@neuraiproject/neurai-rpc 0.4.6 → 0.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +103 -20
- package/DEPIN_EXAMPLES.md +148 -220
- package/DEPIN_IMPLEMENTATION_GUIDE_EN.md +278 -80
- package/README.md +106 -40
- package/depin.ts +465 -214
- package/dist/depin.cjs +305 -0
- package/dist/depin.d.cts +96 -0
- package/dist/depin.d.ts +96 -0
- package/dist/depin.mjs +280 -0
- package/dist/index.cjs +5241 -4892
- package/dist/{types.d.ts → index.d.cts} +12 -63
- package/dist/index.d.ts +200 -0
- package/dist/index.mjs +5214 -4884
- package/docs.json +140 -132
- package/docs.ts +544 -43
- package/index.ts +13 -9
- package/neurai_methods.md +504 -43
- package/package.json +39 -11
- package/createDocs.mjs +0 -61
- package/dist/index.cjs.map +0 -1
- package/dist/index.mjs.map +0 -1
- package/dist/types.d.ts.map +0 -1
- package/test-depin.ts +0 -187
- package/test.js +0 -56
- package/tsconfig.json +0 -26
package/CHANGELOG.md
CHANGED
|
@@ -5,18 +5,97 @@ All notable changes to this project will be documented in this file.
|
|
|
5
5
|
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
|
|
6
6
|
and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
7
|
|
|
8
|
+
## [0.5.0] - 2026-08-01
|
|
9
|
+
|
|
10
|
+
### Breaking — DePIN client rewritten for the gateway's real protocol
|
|
11
|
+
|
|
12
|
+
The DePIN messaging gateway (port 19002) speaks a raw TCP line protocol, not
|
|
13
|
+
HTTP. The previous `fetch`-based client could never talk to a real node, so
|
|
14
|
+
the client was rewritten:
|
|
15
|
+
|
|
16
|
+
- **Transport**: raw TCP via `node:net` — one request line terminated by `\n`
|
|
17
|
+
per connection, response read up to `\n`, 30 s timeout (matches the node's
|
|
18
|
+
`DEPIN_SOCKET_TIMEOUT`), safe handling of fragmented and multibyte
|
|
19
|
+
responses.
|
|
20
|
+
- **Node.js-only entry**: the DePIN client moved to the subpath
|
|
21
|
+
`@neuraiproject/neurai-rpc/depin`, and is no longer re-exported from the
|
|
22
|
+
package root, which stays free of Node built-ins and browser-safe.
|
|
23
|
+
Migrate imports:
|
|
24
|
+
`import { getDePinRPC } from "@neuraiproject/neurai-rpc/depin"`.
|
|
25
|
+
- **Constructor**: `getDePinRPC({ host, port }, authOptions?)` — URL strings
|
|
26
|
+
are rejected. Auth options are now optional: without them the client serves
|
|
27
|
+
the gateway's unauthenticated methods and fails clearly on authenticated
|
|
28
|
+
ones.
|
|
29
|
+
- **Correct per-method authentication** (the old client applied one generic
|
|
30
|
+
flow to every method, which the gateway rejects):
|
|
31
|
+
- `depinsendmsg` — SEND challenge, signs `DEPIN-SEND|token|address|challenge`,
|
|
32
|
+
appends challenge/signature (gateway validates and trims them).
|
|
33
|
+
- `depinclearmsg` — ADMIN challenge (owner only), signs
|
|
34
|
+
`DEPIN-CLEAR|token|address|challenge`, sends
|
|
35
|
+
`[mode, (scope,) address, challenge, signature]`; with a scope the
|
|
36
|
+
challenge is requested for that scope token.
|
|
37
|
+
- RECEIVE challenges now sign `DEPIN-GET|…` (the old `DEPIN-RECEIVE|…` was
|
|
38
|
+
never accepted by the node).
|
|
39
|
+
- Unauthenticated gateway methods (`depinreceivemsg`, `depinsubmitmsg`,
|
|
40
|
+
`depingetmsginfo`, `depingetpoolcontent`, `depinpoolstats`,
|
|
41
|
+
`depinmcpstatus`, `depinlistsections`, `depinpoolpkey`) are sent with
|
|
42
|
+
their params untouched.
|
|
43
|
+
- `depingetmsg` over the gateway is rejected with a clear error: it is
|
|
44
|
+
blocked by a node-side bug (the gateway reads `fromaddress` from
|
|
45
|
+
`params[3]`, where this method carries it at index 1 or 2). Use
|
|
46
|
+
`depinreceivemsg` or the standard RPC port.
|
|
47
|
+
- Challenges are single-use on the node (the nonce is consumed on
|
|
48
|
+
validation), so the client requests a fresh challenge for every
|
|
49
|
+
authenticated call — never cached or reused — with one automatic retry
|
|
50
|
+
(new nonce) on expiration.
|
|
51
|
+
- `DePinAuthOptions.mode` is only honored by `requestDePinChallenge()`
|
|
52
|
+
(`"SEND" | "RECEIVE" | "ADMIN"`); `getDePinRPC` derives the challenge type
|
|
53
|
+
per method and rejects a conflicting override.
|
|
54
|
+
|
|
55
|
+
### Added
|
|
56
|
+
|
|
57
|
+
- New RPC methods in the catalog (node from July 2026, except where noted):
|
|
58
|
+
- `depinreceivemsg` - Retrieve pool messages with pagination (`after_hash`, `limit`)
|
|
59
|
+
- `depingetancestorrecipients` - Active holders of a DEPIN branch with revealed pubkeys
|
|
60
|
+
- `depinlistsections` - Hierarchical DePIN sections
|
|
61
|
+
- `depinpoolpkey` - DePIN pool public key
|
|
62
|
+
- `dumpextkeypq` - Master post-quantum extended private key (PQ wallet build)
|
|
63
|
+
- `exportxpqpub` - Batch of ML-DSA-44 public keys (PQ wallet build)
|
|
64
|
+
- Node compatibility notes in the README.
|
|
65
|
+
|
|
66
|
+
### Fixed
|
|
67
|
+
|
|
68
|
+
- `getRPC` now rejects JSON-RPC errors that arrive with HTTP 200 (previously
|
|
69
|
+
it resolved `undefined`, silently swallowing the error object).
|
|
70
|
+
|
|
71
|
+
### Changed
|
|
72
|
+
|
|
73
|
+
- `docs.json` fully re-synchronized against a node at today's HEAD: 61
|
|
74
|
+
existing entries refreshed, including `depinclearmsg` (new `scope`
|
|
75
|
+
parameter), `createrawtransaction` (new `refinputs` parameter, NIP-014 v3
|
|
76
|
+
transactions, node from April 2026) and `getaddressdeltas` (wildcard `*`
|
|
77
|
+
asset name).
|
|
78
|
+
- Build switched from parcel to tsup with two entries (`.` and `./depin`),
|
|
79
|
+
each shipping ESM (`.mjs`), CJS (`.cjs`) and type declarations; `exports`
|
|
80
|
+
map rewritten with `types`/`import`/`require` conditions per entry.
|
|
81
|
+
- Dropped the now-unused parcel toolchain and `buffer` polyfill from
|
|
82
|
+
devDependencies and pinned esbuild to a patched version via `overrides` —
|
|
83
|
+
`npm audit` reports 0 vulnerabilities.
|
|
84
|
+
- `files` whitelist added to `package.json` (internal working notes and tests
|
|
85
|
+
are no longer published).
|
|
86
|
+
- Fixed the `create-docs` npm script (`node createDocs.mjs`).
|
|
87
|
+
|
|
8
88
|
## [0.4.6] - 2025-12-10
|
|
9
89
|
|
|
10
90
|
### Fixed
|
|
11
|
-
-
|
|
12
|
-
-
|
|
13
|
-
-
|
|
14
|
-
|
|
15
|
-
- Affected commands: `checkdepinvalidity`, `listdepinholders`, `freezedepin`, `unfreezedepin`, `selfrevokedepin`.
|
|
91
|
+
- Clarified the DePIN documentation to distinguish between:
|
|
92
|
+
- the messaging token configured in `depintoken`, which can be any asset
|
|
93
|
+
- the dedicated DePIN asset type used by asset-management RPCs, which uses the `&` prefix in current core
|
|
94
|
+
- Corrected examples for the dedicated DePIN asset-management RPCs.
|
|
16
95
|
|
|
17
96
|
### Changed
|
|
18
|
-
-
|
|
19
|
-
-
|
|
97
|
+
- Documented the dedicated DePIN asset behavior for package consumers as enabled on mainnet and testnet, with `units=0` on issue/reissue.
|
|
98
|
+
- Added missing RPC documentation for `listdepinaddresses` and `listpqaddresses`.
|
|
20
99
|
|
|
21
100
|
## [0.4.5] - 2025-12-09
|
|
22
101
|
|
|
@@ -78,28 +157,31 @@ See repository commits for the full history of changes.
|
|
|
78
157
|
|
|
79
158
|
### From 0.4.5 to 0.4.6
|
|
80
159
|
|
|
81
|
-
**IMPORTANT**:
|
|
160
|
+
**IMPORTANT**: Distinguish between DePIN messaging tokens and dedicated DePIN assets:
|
|
82
161
|
|
|
83
|
-
❌ **Incorrect (
|
|
162
|
+
❌ **Incorrect (treating them as the same thing):**
|
|
84
163
|
```javascript
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
}
|
|
164
|
+
const token = 'FRANCE';
|
|
165
|
+
await rpc('checkdepinvalidity', [token, address]);
|
|
88
166
|
```
|
|
89
167
|
|
|
90
168
|
✅ **Correct (0.4.6+):**
|
|
91
169
|
```javascript
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
170
|
+
const messagingToken = 'FRANCE';
|
|
171
|
+
const depinAsset = '&FRANCE';
|
|
172
|
+
|
|
173
|
+
// Messaging token for depinmsg can be any asset.
|
|
174
|
+
// Dedicated DePIN asset-management commands use the &-prefixed DePIN asset type.
|
|
175
|
+
const validity = await rpc('checkdepinvalidity', [depinAsset, address]);
|
|
95
176
|
if (!validity.has_asset || validity.valid === 0) {
|
|
96
|
-
throw new Error('Invalid DePIN
|
|
177
|
+
throw new Error('Invalid DePIN asset for this address');
|
|
97
178
|
}
|
|
98
179
|
```
|
|
99
180
|
|
|
100
181
|
**Updated examples:**
|
|
101
|
-
-
|
|
102
|
-
-
|
|
182
|
+
- Messaging token: `FRANCE` can still be any asset
|
|
183
|
+
- Dedicated DePIN asset: `&FRANCE`
|
|
184
|
+
- Owner token for a dedicated DePIN asset: `&FRANCE!`
|
|
103
185
|
|
|
104
186
|
### Node configuration
|
|
105
187
|
|
|
@@ -108,14 +190,15 @@ Ensure the following in `neurai.conf`:
|
|
|
108
190
|
```ini
|
|
109
191
|
# DePIN Messaging
|
|
110
192
|
depinmsg=1
|
|
111
|
-
depintoken=YOUR_TOKEN_HERE #
|
|
193
|
+
depintoken=YOUR_TOKEN_HERE # Messaging token, can be any valid asset
|
|
112
194
|
depinport=19002
|
|
113
195
|
depinmaxmessagesize=1024
|
|
114
196
|
depinmessageexpiry=168
|
|
115
197
|
depinmaxpoolsize=100
|
|
116
198
|
|
|
117
|
-
# Asset
|
|
199
|
+
# Asset indexes (required for listdepinholders/listdepinaddresses)
|
|
118
200
|
assetindex=1
|
|
201
|
+
pubkeyindex=1
|
|
119
202
|
```
|
|
120
203
|
|
|
121
204
|
---
|
package/DEPIN_EXAMPLES.md
CHANGED
|
@@ -1,271 +1,199 @@
|
|
|
1
1
|
# DePIN RPC Examples
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Practical examples for the DePIN messaging client in
|
|
4
|
+
`@neuraiproject/neurai-rpc`.
|
|
5
|
+
|
|
6
|
+
> **Node.js only.** The DePIN gateway (default port 19002) speaks a raw TCP
|
|
7
|
+
> line protocol — not HTTP — so this client uses `node:net` sockets and lives
|
|
8
|
+
> in its own package entry. Browsers cannot open raw TCP connections; from a
|
|
9
|
+
> browser, talk to the node's standard HTTP RPC port instead (see
|
|
10
|
+
> `DEPIN_IMPLEMENTATION_GUIDE_EN.md` §4), or put an HTTP/WebSocket proxy in
|
|
11
|
+
> front of the gateway.
|
|
4
12
|
|
|
5
13
|
## Basic Setup
|
|
6
14
|
|
|
7
15
|
```javascript
|
|
8
|
-
import { getDePinRPC } from "@neuraiproject/neurai-rpc";
|
|
9
|
-
|
|
10
|
-
// You need a function that can sign messages with your Neurai address
|
|
11
|
-
// This example uses neurai-cli via the standard RPC
|
|
12
16
|
import { getRPC, methods } from "@neuraiproject/neurai-rpc";
|
|
17
|
+
import { getDePinRPC } from "@neuraiproject/neurai-rpc/depin";
|
|
13
18
|
|
|
19
|
+
// Standard RPC (HTTP) — works in Node.js and browsers
|
|
14
20
|
const standardRpc = getRPC("user", "password", "http://localhost:19001");
|
|
15
21
|
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
22
|
+
// DePIN gateway (raw TCP) — Node.js only
|
|
23
|
+
const depinRpc = getDePinRPC(
|
|
24
|
+
{ host: "127.0.0.1", port: 19002 },
|
|
25
|
+
{
|
|
26
|
+
token: "&FRANCE",
|
|
27
|
+
address: "NXyouraddress...",
|
|
28
|
+
signMessage: async (message) => {
|
|
29
|
+
// Sign with the standard RPC (wallet must hold the address key),
|
|
30
|
+
// or with any other wallet integration that returns base64.
|
|
31
|
+
return await standardRpc(methods.signmessage, [
|
|
32
|
+
"NXyouraddress...",
|
|
33
|
+
message,
|
|
34
|
+
]);
|
|
35
|
+
},
|
|
36
|
+
}
|
|
37
|
+
);
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
The second argument is optional: without auth options the client can still
|
|
41
|
+
call every gateway method that the server serves without authentication
|
|
42
|
+
(`depinreceivemsg`, `depinsubmitmsg`, `depingetmsginfo`, `depingetpoolcontent`,
|
|
43
|
+
`depinpoolstats`, `depinmcpstatus`, `depinlistsections`, `depinpoolpkey`).
|
|
20
44
|
|
|
21
|
-
|
|
22
|
-
const
|
|
23
|
-
|
|
24
|
-
address: "NXyouraddress...",
|
|
25
|
-
signMessage: signMessage,
|
|
26
|
-
mode: "SEND"
|
|
27
|
-
});
|
|
45
|
+
```javascript
|
|
46
|
+
const publicRpc = getDePinRPC({ host: "127.0.0.1", port: 19002 });
|
|
47
|
+
const info = await publicRpc("depingetmsginfo", []);
|
|
28
48
|
```
|
|
29
49
|
|
|
30
50
|
## Example 1: Send a DePIN Message
|
|
31
51
|
|
|
52
|
+
`depinsendmsg` needs a SEND challenge. The client requests it, signs
|
|
53
|
+
`DEPIN-SEND|token|address|challenge` with your `signMessage`, appends
|
|
54
|
+
challenge and signature where the gateway expects them, and retries once
|
|
55
|
+
automatically if the challenge expired.
|
|
56
|
+
|
|
32
57
|
```javascript
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
// Use your signing method
|
|
41
|
-
return await yourWallet.signMessage(msg);
|
|
42
|
-
},
|
|
43
|
-
mode: "SEND"
|
|
44
|
-
});
|
|
45
|
-
|
|
46
|
-
try {
|
|
47
|
-
const result = await depinRpc("depinsendmsg", [
|
|
48
|
-
"MYTOKEN", // token
|
|
49
|
-
"localhost", // server (use "localhost" for local pool)
|
|
50
|
-
"Hello DePIN!", // message
|
|
51
|
-
"NXsenderAddress..." // from address
|
|
52
|
-
]);
|
|
53
|
-
|
|
54
|
-
console.log("Message sent successfully:", result);
|
|
55
|
-
} catch (error) {
|
|
56
|
-
console.error("Failed to send message:", error);
|
|
57
|
-
}
|
|
58
|
-
}
|
|
58
|
+
const result = await depinRpc("depinsendmsg", [
|
|
59
|
+
"&FRANCE", // token
|
|
60
|
+
"192.168.1.100:19002", // destination gateway ip[:port]
|
|
61
|
+
"Hello team!", // message
|
|
62
|
+
"NXyouraddress...", // fromaddress — must be the authenticated address
|
|
63
|
+
]);
|
|
64
|
+
console.log(result);
|
|
59
65
|
```
|
|
60
66
|
|
|
61
|
-
|
|
67
|
+
If you omit `fromaddress` (3 params), the client fills it in with the
|
|
68
|
+
authenticated address.
|
|
69
|
+
|
|
70
|
+
## Example 2: Retrieve Messages with Pagination
|
|
71
|
+
|
|
72
|
+
`depinreceivemsg` is served without authentication and supports pagination
|
|
73
|
+
(node from July 2026+):
|
|
62
74
|
|
|
63
75
|
```javascript
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
"NXreceiverAddress..." // your address
|
|
81
|
-
]);
|
|
82
|
-
|
|
83
|
-
console.log("Received messages:", messages);
|
|
84
|
-
|
|
85
|
-
messages.forEach(msg => {
|
|
86
|
-
console.log(`From: ${msg.sender}`);
|
|
87
|
-
console.log(`Message: ${msg.message}`);
|
|
88
|
-
console.log(`Time: ${new Date(msg.timestamp * 1000).toLocaleString()}`);
|
|
89
|
-
});
|
|
90
|
-
} catch (error) {
|
|
91
|
-
console.error("Failed to get messages:", error);
|
|
92
|
-
}
|
|
76
|
+
// Everything for the address
|
|
77
|
+
const all = await depinRpc("depinreceivemsg", ["&FRANCE", "NXyouraddress..."]);
|
|
78
|
+
|
|
79
|
+
// Pages of 50, resuming after the last received hash
|
|
80
|
+
let afterHash = "";
|
|
81
|
+
while (true) {
|
|
82
|
+
const page = await depinRpc("depinreceivemsg", [
|
|
83
|
+
"&FRANCE",
|
|
84
|
+
"NXyouraddress...",
|
|
85
|
+
0, // timestamp filter (0 = no filter)
|
|
86
|
+
afterHash, // "" starts from the beginning
|
|
87
|
+
50, // limit
|
|
88
|
+
]);
|
|
89
|
+
if (!page || page.length === 0) break;
|
|
90
|
+
process(page);
|
|
91
|
+
afterHash = page[page.length - 1].hash;
|
|
93
92
|
}
|
|
94
93
|
```
|
|
95
94
|
|
|
96
|
-
|
|
95
|
+
> `depingetmsg` over the gateway is currently blocked by a node-side bug and
|
|
96
|
+
> the client rejects it with a clear error. Use `depinreceivemsg` (above), or
|
|
97
|
+
> call `depingetmsg` through the standard RPC port:
|
|
98
|
+
> `standardRpc(methods.depingetmsg, ["&FRANCE"])`.
|
|
99
|
+
|
|
100
|
+
## Example 3: Submit a Pre-encrypted Message
|
|
97
101
|
|
|
98
102
|
```javascript
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
const depinRpc = getDePinRPC("http://localhost:19002", {
|
|
103
|
-
token: "MYTOKEN",
|
|
104
|
-
address: "NXsenderAddress...",
|
|
105
|
-
signMessage: async (msg) => {
|
|
106
|
-
return await yourWallet.signMessage(msg);
|
|
107
|
-
},
|
|
108
|
-
mode: "SEND"
|
|
109
|
-
});
|
|
110
|
-
|
|
111
|
-
try {
|
|
112
|
-
// Assume you have a pre-encrypted and signed message in hex format
|
|
113
|
-
const hexMessage = "0a1b2c3d..."; // Your encrypted message hex
|
|
114
|
-
|
|
115
|
-
const result = await depinRpc("depinsubmitmsg", [hexMessage]);
|
|
116
|
-
|
|
117
|
-
console.log("Pre-encrypted message submitted:", result);
|
|
118
|
-
} catch (error) {
|
|
119
|
-
console.error("Failed to submit message:", error);
|
|
120
|
-
}
|
|
121
|
-
}
|
|
103
|
+
const result = await depinRpc("depinsubmitmsg", [
|
|
104
|
+
"48656c6c6f...", // hex-encoded encrypted message
|
|
105
|
+
]);
|
|
122
106
|
```
|
|
123
107
|
|
|
124
|
-
## Example 4:
|
|
108
|
+
## Example 4: Clear Messages (ADMIN, owner only)
|
|
109
|
+
|
|
110
|
+
`depinclearmsg` over the gateway requires an ADMIN challenge signed as
|
|
111
|
+
`DEPIN-CLEAR|token|address|challenge` by an owner of the token (or of an
|
|
112
|
+
ancestor). The client inserts your address into the parameters the way the
|
|
113
|
+
gateway expects — you only pass the mode and optional scope:
|
|
125
114
|
|
|
126
115
|
```javascript
|
|
127
|
-
|
|
116
|
+
// Remove expired messages
|
|
117
|
+
await depinRpc("depinclearmsg", []);
|
|
128
118
|
|
|
129
|
-
//
|
|
130
|
-
|
|
131
|
-
// Check if wallet is available
|
|
132
|
-
if (!window.neuraiWallet) {
|
|
133
|
-
throw new Error("Neurai wallet extension not found");
|
|
134
|
-
}
|
|
119
|
+
// Remove ALL messages
|
|
120
|
+
await depinRpc("depinclearmsg", ["all"]);
|
|
135
121
|
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
const address = accounts[0];
|
|
139
|
-
|
|
140
|
-
// Create DePIN RPC client with wallet signing
|
|
141
|
-
const depinRpc = getDePinRPC("http://localhost:19002", {
|
|
142
|
-
token: "MYTOKEN",
|
|
143
|
-
address: address,
|
|
144
|
-
signMessage: async (msg) => {
|
|
145
|
-
// Use wallet extension to sign
|
|
146
|
-
return await window.neuraiWallet.signMessage(address, msg);
|
|
147
|
-
},
|
|
148
|
-
mode: "SEND"
|
|
149
|
-
});
|
|
150
|
-
|
|
151
|
-
// Send message
|
|
152
|
-
const result = await depinRpc("depinsendmsg", [
|
|
153
|
-
"MYTOKEN",
|
|
154
|
-
"localhost",
|
|
155
|
-
"Hello from browser!",
|
|
156
|
-
address
|
|
157
|
-
]);
|
|
122
|
+
// Remove messages older than 7 days
|
|
123
|
+
await depinRpc("depinclearmsg", [168]);
|
|
158
124
|
|
|
159
|
-
|
|
160
|
-
|
|
125
|
+
// Restrict the purge to one section's subtree — the ADMIN challenge is
|
|
126
|
+
// requested for that scope automatically
|
|
127
|
+
await depinRpc("depinclearmsg", ["all", "&FRANCE/GENERAL"]);
|
|
161
128
|
```
|
|
162
129
|
|
|
163
|
-
## Example 5:
|
|
130
|
+
## Example 5: Sections and Branch Holders
|
|
164
131
|
|
|
165
132
|
```javascript
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
signMessage: async () => "", // Not used in requestChallenge
|
|
174
|
-
mode: "SEND"
|
|
175
|
-
});
|
|
176
|
-
|
|
177
|
-
console.log("Challenge:", challengeData.challenge);
|
|
178
|
-
console.log("Expires in:", challengeData.timeout, "seconds");
|
|
179
|
-
console.log("Message to sign:", challengeData.messageToSign);
|
|
180
|
-
|
|
181
|
-
// Now you can sign this message manually
|
|
182
|
-
const signature = await yourSigningFunction(challengeData.messageToSign);
|
|
183
|
-
|
|
184
|
-
console.log("Signature:", signature);
|
|
185
|
-
}
|
|
133
|
+
// Section names (full address mode needs the standard RPC port)
|
|
134
|
+
const sections = await depinRpc("depinlistsections", []);
|
|
135
|
+
|
|
136
|
+
// Active holders of a branch with their revealed pubkeys (standard RPC port)
|
|
137
|
+
const holders = await standardRpc(methods.depingetancestorrecipients, [
|
|
138
|
+
"&FRANCE/PARIS",
|
|
139
|
+
]);
|
|
186
140
|
```
|
|
187
141
|
|
|
188
|
-
## Example 6:
|
|
142
|
+
## Example 6: Manual Challenge Handling
|
|
189
143
|
|
|
190
144
|
```javascript
|
|
191
|
-
import {
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
} catch (error) {
|
|
201
|
-
throw new Error(`Signing failed: ${error.message}`);
|
|
202
|
-
}
|
|
203
|
-
},
|
|
204
|
-
mode: "SEND"
|
|
205
|
-
});
|
|
206
|
-
|
|
207
|
-
try {
|
|
208
|
-
const result = await depinRpc("depinsendmsg", [
|
|
209
|
-
"MYTOKEN",
|
|
210
|
-
"localhost",
|
|
211
|
-
"Test message",
|
|
212
|
-
"NXyourAddress..."
|
|
213
|
-
]);
|
|
214
|
-
|
|
215
|
-
return { success: true, result };
|
|
216
|
-
} catch (error) {
|
|
217
|
-
// Handle different error types
|
|
218
|
-
if (error.type === 'DePinRequestError') {
|
|
219
|
-
console.error("DePIN request failed:", error.error);
|
|
220
|
-
console.error("Description:", error.description);
|
|
221
|
-
} else if (error.error?.message?.includes('challenge')) {
|
|
222
|
-
console.error("Challenge error:", error.error.message);
|
|
223
|
-
} else if (error.error?.message?.includes('signature')) {
|
|
224
|
-
console.error("Signature verification failed");
|
|
225
|
-
} else {
|
|
226
|
-
console.error("Unknown error:", error);
|
|
227
|
-
}
|
|
228
|
-
|
|
229
|
-
return { success: false, error: error.error };
|
|
145
|
+
import { requestDePinChallenge } from "@neuraiproject/neurai-rpc/depin";
|
|
146
|
+
|
|
147
|
+
const challengeData = await requestDePinChallenge(
|
|
148
|
+
{ host: "127.0.0.1", port: 19002 },
|
|
149
|
+
{
|
|
150
|
+
token: "&FRANCE",
|
|
151
|
+
address: "NXyouraddress...",
|
|
152
|
+
signMessage: async (m) => "unused-here",
|
|
153
|
+
mode: "SEND", // "SEND" | "RECEIVE" | "ADMIN" (default "RECEIVE")
|
|
230
154
|
}
|
|
231
|
-
|
|
155
|
+
);
|
|
156
|
+
|
|
157
|
+
console.log(challengeData.challenge); // random challenge from the server
|
|
158
|
+
console.log(challengeData.timeout); // seconds until it expires
|
|
159
|
+
console.log(challengeData.messageToSign); // e.g. "DEPIN-SEND|&FRANCE|NX...|abc123"
|
|
232
160
|
```
|
|
233
161
|
|
|
234
|
-
|
|
162
|
+
Note: `mode` is only honored here. `getDePinRPC` derives the challenge type
|
|
163
|
+
from the method being called and rejects a conflicting `mode` in its auth
|
|
164
|
+
options.
|
|
235
165
|
|
|
236
|
-
|
|
237
|
-
import { getDePinRPC } from "@neuraiproject/neurai-rpc";
|
|
238
|
-
|
|
239
|
-
async function connectToRemoteNode() {
|
|
240
|
-
const depinRpc = getDePinRPC("http://remote-node.example.com:19002", {
|
|
241
|
-
token: "MYTOKEN",
|
|
242
|
-
address: "NXyourAddress...",
|
|
243
|
-
signMessage: async (msg) => {
|
|
244
|
-
return await yourWallet.signMessage(msg);
|
|
245
|
-
},
|
|
246
|
-
mode: "SEND"
|
|
247
|
-
});
|
|
248
|
-
|
|
249
|
-
// The library handles challenge/response automatically
|
|
250
|
-
const result = await depinRpc("depinsendmsg", [
|
|
251
|
-
"MYTOKEN",
|
|
252
|
-
"remote-node.example.com:19002",
|
|
253
|
-
"Hello remote node!",
|
|
254
|
-
"NXyourAddress..."
|
|
255
|
-
]);
|
|
166
|
+
## Example 7: Error Handling
|
|
256
167
|
|
|
257
|
-
|
|
168
|
+
```javascript
|
|
169
|
+
try {
|
|
170
|
+
await depinRpc("depinsendmsg", ["&FRANCE", "10.0.0.1", "hi", "NXaddr..."]);
|
|
171
|
+
} catch (e) {
|
|
172
|
+
if (e.type === "DePinRequestError") {
|
|
173
|
+
// Transport problem: gateway unreachable, timeout, connection closed…
|
|
174
|
+
console.error("Transport:", e.error);
|
|
175
|
+
} else if (e.error) {
|
|
176
|
+
// JSON-RPC error from the gateway/node
|
|
177
|
+
console.error("RPC:", e.description);
|
|
178
|
+
}
|
|
258
179
|
}
|
|
259
180
|
```
|
|
260
181
|
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
1. **Challenge Expiry**: Challenges expire after 60 seconds. The library automatically handles expiry and retries with a new challenge.
|
|
182
|
+
The client raises a clear error, without touching the network, when:
|
|
264
183
|
|
|
265
|
-
|
|
184
|
+
- the target is not `{ host, port }` (URL strings are rejected),
|
|
185
|
+
- an authenticated method is called on a client built without auth options,
|
|
186
|
+
- `depingetmsg` is attempted over the gateway (node-side bug, see README),
|
|
187
|
+
- `fromaddress` in `depinsendmsg` differs from the authenticated address.
|
|
266
188
|
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
4. **Port**: DePIN messaging uses port 19002 by default (configurable via `-depinmsgport`).
|
|
189
|
+
## Notes
|
|
270
190
|
|
|
271
|
-
|
|
191
|
+
- One TCP connection per request; the request is a single line terminated by
|
|
192
|
+
`\n` and the response is read up to the first `\n` (30 s timeout, matching
|
|
193
|
+
the node's `DEPIN_SOCKET_TIMEOUT`).
|
|
194
|
+
- Challenges are single-use — the node consumes the nonce when it validates
|
|
195
|
+
it — so the client requests a fresh challenge for every authenticated call;
|
|
196
|
+
an expired-challenge error triggers one automatic retry (with a new nonce).
|
|
197
|
+
- The messaging token (`-depinmsgtoken`) must be a dedicated `&ASSET` DePIN
|
|
198
|
+
asset (soulbound, `units=0`), currently testnet/regtest only in the node —
|
|
199
|
+
the same type the DePIN asset RPCs operate on.
|