Skip to content

Commit 4230781

Browse files
RigidityRigidity
committed
Add some basic RPC content
1 parent fc4353c commit 4230781

File tree

11 files changed

+284
-38
lines changed

11 files changed

+284
-38
lines changed

docs/sage/config.md renamed to docs/config.md

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -223,6 +223,9 @@ This file provides a list of wallet objects, each prefixed with `[[wallets]]`. T
223223
For example:
224224

225225
```toml
226+
[defaults]
227+
delta_sync = true
228+
226229
[defaults.change]
227230
mode = "same"
228231

@@ -236,6 +239,10 @@ fingerprint = 1239439275
236239
network = "mainnet"
237240
```
238241

242+
### defaults.delta_sync
243+
244+
Delta sync is enabled by default. During initial sync, the wallet will use a peer to subscribe to each of its p2 puzzle hashes (addresses) and coin ids. If delta sync is enabled, it will start from the previous peak height instead of downloading all of the coins every time. This is an optimization, but it can lead to data loss if a race condition occurs - for example, if a p2 puzzle hash or coin id is inserted into the database but the app is restarted before it finishes syncing it. In the case of lost data, a resync is required.
245+
239246
### defaults.change
240247

241248
The mode can be one of the following:
@@ -287,6 +294,15 @@ This fingerprint is used for internal identification purposes, and is not consid
287294
fingerprint = 1239439275
288295
```
289296

297+
### delta_sync
298+
299+
This is a per-wallet override for `defaults.delta_sync`, although it's not currently exposed to the UI to reduce complexity:
300+
301+
```toml
302+
[[wallets]]
303+
delta_sync = false
304+
```
305+
290306
### change
291307

292308
The same as `defaults.change`, although it would take the following form (after the initial `[[wallets]]` settings):

docs/sage/files.md renamed to docs/files.md

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -21,13 +21,13 @@ The username `Alice` is a placeholder, and must be replaced by your actual usern
2121

2222
## Files
2323

24-
| Name | Description |
25-
| --------------- | -------------------------------------------------------------------------------------------- |
26-
| `config.toml` | The main configuration file used by the app. See [Config](/docs/config). |
27-
| `keys.bin` | A binary encoding of all imported keys. |
28-
| `logs` | Logs emitted by the backend of the app. |
29-
| `networks.toml` | Information about blockchain networks (ie mainnet or testnet11). See [Config](/docs/config). |
30-
| `peers` | Binary files that store previous peer connections. |
31-
| `ssl` | The SSL certificate used for full node connections and the RPC. |
32-
| `wallets` | SQLite databases for each network and key pair. |
33-
| `wallets.toml` | Configuration for each imported wallet. See [Config](/docs/config). |
24+
| Name | Description |
25+
| --------------- | --------------------------------------------------------------------------------------- |
26+
| `config.toml` | The main configuration file used by the app. See [Config](/config). |
27+
| `keys.bin` | A binary encoding of all imported keys. |
28+
| `logs` | Logs emitted by the backend of the app. |
29+
| `networks.toml` | Information about blockchain networks (ie mainnet or testnet11). See [Config](/config). |
30+
| `peers` | Binary files that store previous peer connections. |
31+
| `ssl` | The SSL certificate used for full node connections and the RPC. |
32+
| `wallets` | SQLite databases for each network and key pair. |
33+
| `wallets.toml` | Configuration for each imported wallet. See [Config](/config). |

docs/sage/index.md renamed to docs/index.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
slug: /
2+
slug: /getting-started
33
---
44

55
import Tabs from '@theme/Tabs';

‎docs/rpc/offers.md‎

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
---
2+
slug: /rpc-offers
3+
---
4+
5+
# Offers
6+
7+
## make_offer
8+
9+
**Request**
10+
11+
| Parameter | Type | Required | Description |
12+
| ----------------- | ---------------------------- | -------- | -------------------------------------------------------------- |
13+
| offered_assets | [Assets](./rpc-types#assets) | true | The assets being spent to make the offer. |
14+
| requested_assets | [Assets](./rpc-types#assets) | true | The assets that must be paid to fulfill the offer. |
15+
| fee | [Amount](./rpc-types#amount) | true | The amount of mojos to pay as the fee once the offer is taken. |
16+
| receive_address | string | false | Overrides the address the requested assets will be sent to. |
17+
| expires_at_second | number | false | The seconds since UNIX epoch at which the offer expires. |
18+
| auto_import | boolean | false | Whether the app should import and track the offer's status. |
19+
20+
**Response**
21+
22+
| Parameter | Type | Description |
23+
| --------- | ------ | ----------------------------------------------------------------- |
24+
| offer | string | The bech32m encoded offer string. |
25+
| offer_id | string | An offer id that is compatible with [Dexie](https://dexie.space). |
26+
27+
## take_offer
28+
29+
**Request**
30+
31+
| Parameter | Type | Required | Description |
32+
| ----------- | ---------------------------- | -------- | ----------------------------------------------------------- |
33+
| offer | string | true | The bech32m encoded offer string. |
34+
| fee | [Amount](./rpc-types#amount) | true | The amount of additional mojos to add to the maker's fee. |
35+
| auto_submit | boolean | false | Whether the transaction should be submitted to the mempool. |
36+
37+
**Response**
38+
39+
| Parameter | Type | Description |
40+
| -------------- | ------------------ | ------------------------------------------------------ |
41+
| summary | TransactionSummary | The inputs and outputs in the transaction. |
42+
| spend_bundle | SpendBundle | The spend bundle representing the transaction. |
43+
| transaction_id | string | The hash of the spend bundle submitted to the mempool. |
44+
45+
<!--
46+
#[derive(Debug, Clone, Serialize, Deserialize)]
47+
#[cfg_attr(feature = "tauri", derive(specta::Type))]
48+
pub struct CombineOffers {
49+
pub offers: Vec<String>,
50+
}
51+
52+
#[derive(Debug, Clone, Serialize, Deserialize)]
53+
#[cfg_attr(feature = "tauri", derive(specta::Type))]
54+
pub struct CombineOffersResponse {
55+
pub offer: String,
56+
}
57+
58+
#[derive(Debug, Clone, Serialize, Deserialize)]
59+
#[cfg_attr(feature = "tauri", derive(specta::Type))]
60+
pub struct ViewOffer {
61+
pub offer: String,
62+
}
63+
64+
#[derive(Debug, Clone, Serialize, Deserialize)]
65+
#[cfg_attr(feature = "tauri", derive(specta::Type))]
66+
pub struct ViewOfferResponse {
67+
pub offer: OfferSummary,
68+
}
69+
70+
#[derive(Debug, Clone, Serialize, Deserialize)]
71+
#[cfg_attr(feature = "tauri", derive(specta::Type))]
72+
pub struct ImportOffer {
73+
pub offer: String,
74+
}
75+
76+
#[derive(Debug, Clone, Serialize, Deserialize)]
77+
#[cfg_attr(feature = "tauri", derive(specta::Type))]
78+
pub struct ImportOfferResponse {
79+
pub offer_id: String,
80+
}
81+
82+
#[derive(Debug, Clone, Copy, Serialize, Deserialize)]
83+
#[cfg_attr(feature = "tauri", derive(specta::Type))]
84+
pub struct GetOffers {}
85+
86+
#[derive(Debug, Clone, Serialize, Deserialize)]
87+
#[cfg_attr(feature = "tauri", derive(specta::Type))]
88+
pub struct GetOffersResponse {
89+
pub offers: Vec<OfferRecord>,
90+
}
91+
92+
#[derive(Debug, Clone, Serialize, Deserialize)]
93+
#[cfg_attr(feature = "tauri", derive(specta::Type))]
94+
pub struct GetOffer {
95+
pub offer_id: String,
96+
}
97+
98+
#[derive(Debug, Clone, Serialize, Deserialize)]
99+
#[cfg_attr(feature = "tauri", derive(specta::Type))]
100+
pub struct GetOfferResponse {
101+
pub offer: OfferRecord,
102+
}
103+
104+
#[derive(Debug, Clone, Serialize, Deserialize)]
105+
#[cfg_attr(feature = "tauri", derive(specta::Type))]
106+
pub struct DeleteOffer {
107+
pub offer_id: String,
108+
}
109+
110+
#[derive(Debug, Clone, Copy, Serialize, Deserialize)]
111+
#[cfg_attr(feature = "tauri", derive(specta::Type))]
112+
pub struct DeleteOfferResponse {}
113+
114+
#[derive(Debug, Clone, Serialize, Deserialize)]
115+
#[cfg_attr(feature = "tauri", derive(specta::Type))]
116+
pub struct CancelOffer {
117+
pub offer_id: String,
118+
pub fee: Amount,
119+
#[serde(default)]
120+
pub auto_submit: bool,
121+
}
122+
123+
pub type CancelOfferResponse = TransactionResponse;
124+
125+
#[derive(Debug, Clone, Serialize, Deserialize)]
126+
#[cfg_attr(feature = "tauri", derive(specta::Type))]
127+
pub struct CancelOffers {
128+
pub offer_ids: Vec<String>,
129+
pub fee: Amount,
130+
#[serde(default)]
131+
pub auto_submit: bool,
132+
}
133+
134+
pub type CancelOffersResponse = TransactionResponse;
135+
136+
fn yes() -> bool {
137+
true
138+
} -->

‎docs/rpc/setup.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
---
2+
title: Setup
3+
slug: /rpc-setup
4+
---
5+
6+
# RPC Setup
7+
8+
## GUI
9+
10+
You can run the RPC in the background while the Sage app is open. It runs in the same process as the app rather than as a separate daemon service, so if the app is closed the RPC server will be as well.
11+
12+
The RPC server is off by default. You will need to start it in Settings => Advanced. Optionally, it can also be set to start automatically when the GUI is opened.
13+
14+
![Sage RPC settings](/img/screenshots/rpc.png)
15+
16+
## CLI
17+
18+
The RPC server can be run directly from the command line as well, which is preferable for backend applications running on headless hosts.
19+
20+
You will need to follow the [Prerequisites](https://tauri.app/start/prerequisites/) section of the Tauri docs, and install [Rustup](https://rustup.rs/).
21+
22+
Run the following command, using whichever version number you want to install (it should be the same version as the GUI, if you were running it previously):
23+
24+
```bash
25+
cargo install --git https://github.com/xch-dev/sage --tag v0.11.1 sage-cli
26+
```
27+
28+
Now you can run `sage rpc start` to start the Sage process in the foreground. You can also run RPC commands by passing in their request body like so:
29+
30+
```bash
31+
sage rpc login '{"fingerprint": 2417281}'
32+
```
33+
34+
:::warning
35+
Do not run the command line RPC server at the same time as the GUI. They may overwrite each other's data.
36+
:::
37+
38+
## SSL Certificate
39+
40+
The CLI will load the certificate automatically, but if you want to connect to the RPC server from your own client (for example, in a Node.js app), you can find the SSL certificate on the [Files](/files) page.
41+
42+
Here is an example of how you need to connect:
43+
44+
```js
45+
import axios from "axios";
46+
import { Agent } from "https";
47+
import fs from "fs";
48+
49+
const sageDir = "...";
50+
51+
const agent = new Agent({
52+
rejectUnauthorized: false,
53+
cert: fs.readFileSync(`${sageDir}/ssl/wallet.crt`),
54+
key: fs.readFileSync(`${sageDir}/ssl/wallet.key`),
55+
});
56+
57+
axios
58+
.post("https://localhost:9257/get_sync_status", {}, { httpsAgent: agent })
59+
.then(console.log.bind(console))
60+
.catch(console.error.bind(console));
61+
```
62+
63+
You need to disable server verification with `rejectUnauthorized` and connect using the wallet's certificate and key files. All requests use the `POST` method, and accept and return JSON payloads. The default port is 9257, but it can be configured.

‎docs/rpc/types.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
slug: /rpc-types
3+
---
4+
5+
# Types
6+
7+
## Amount
8+
9+
All amounts in the RPC are represented using mojos, however you can use either a number or a string as needed in the request. If an amount is too large to fit in the maximum safe JavaScript integer (2^53-1), then it will be returned as a string.
10+
11+
## Assets
12+
13+
Represents the assets in the side of an offer.
14+
15+
| Field | Type | Required | Description |
16+
| ----- | -------------------------- | -------- | ------------------------------------------- |
17+
| xch | [Amount](#amount) | true | The amount of XCH involved in the offer. |
18+
| cats | [CatAmount](#cat-amount)[] | true | A list of CAT assets involved in the offer. |
19+
| nfts | string[] | true | A list of NFT ids involved in the offer. |
20+
21+
## CatAmount {#cat-amount}
22+
23+
<!-- #[derive(Debug, Clone, Serialize, Deserialize)]
24+
#[cfg_attr(feature = "tauri", derive(specta::Type))]
25+
pub struct Assets {
26+
pub xch: Amount,
27+
pub cats: Vec<CatAmount>,
28+
pub nfts: Vec<String>,
29+
}
30+
31+
#[derive(Debug, Clone, Serialize, Deserialize)]
32+
#[cfg_attr(feature = "tauri", derive(specta::Type))]
33+
pub struct CatAmount {
34+
pub asset_id: String,
35+
pub amount: Amount,
36+
} -->

‎docs/sage/rpc.md‎

Lines changed: 0 additions & 7 deletions
This file was deleted.

‎docs/sdk/index.md‎

Lines changed: 0 additions & 5 deletions
This file was deleted.

‎docusaurus.config.ts‎

Lines changed: 3 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ const config: Config = {
2222
{
2323
docs: {
2424
sidebarPath: "./sidebars.ts",
25+
routeBasePath: "",
2526
},
2627
theme: {
2728
customCss: "./src/css/custom.css",
@@ -39,15 +40,9 @@ const config: Config = {
3940
items: [
4041
{
4142
type: "docSidebar",
42-
sidebarId: "sageSidebar",
43+
sidebarId: "sidebar",
4344
position: "left",
44-
label: "Sage",
45-
},
46-
{
47-
type: "docSidebar",
48-
sidebarId: "sdkSidebar",
49-
position: "left",
50-
label: "Wallet SDK",
45+
label: "Docs",
5146
},
5247
{
5348
href: "https://github.com/xch-dev/docs",

‎sidebars.ts‎

Lines changed: 13 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,20 @@
11
import type { SidebarsConfig } from "@docusaurus/plugin-content-docs";
22

33
const sidebars: SidebarsConfig = {
4-
sageSidebar: [
5-
{ type: "doc", id: "sage/index" },
6-
{ type: "doc", id: "sage/files" },
7-
{ type: "doc", id: "sage/config" },
8-
{ type: "doc", id: "sage/rpc" },
4+
sidebar: [
5+
{ type: "doc", id: "index" },
6+
{ type: "doc", id: "files" },
7+
{ type: "doc", id: "config" },
8+
{
9+
type: "category",
10+
label: "RPC",
11+
items: [
12+
{ type: "doc", id: "rpc/setup" },
13+
{ type: "doc", id: "rpc/types" },
14+
{ type: "doc", id: "rpc/offers" },
15+
],
16+
},
917
],
10-
sdkSidebar: ["sdk/index"],
1118
};
1219

1320
export default sidebars;

0 commit comments

Comments
 (0)