@neuraiproject/neurai-rpc 0.5.1 → 0.6.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 CHANGED
@@ -5,6 +5,34 @@ 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.6.0] - 2026-08-22
9
+
10
+ ### Breaking — Neurai DePIN protocol 2
11
+
12
+ - Removed the raw-TCP `@neuraiproject/neurai-rpc/depin` entry and
13
+ `getDePinRPC`. DePIN now uses the standard authenticated HTTP JSON-RPC
14
+ endpoint through `getRPC`.
15
+ - Removed the retired `depingetpoolcontent` method.
16
+ - Updated the parameter contracts for `depinsendmsg`, `depingetmsg`,
17
+ `depinsubmitmsg`, `depinreceivemsg`, `depinlistsections`, and
18
+ `depinclearmsg`.
19
+
20
+ ### Added
21
+
22
+ - `depinchallenge`
23
+ - `depinsignrequest`
24
+ - `depinsignchallenge`
25
+ - `depindecrypt`
26
+ - `getibdstatus`
27
+
28
+ ### Documentation
29
+
30
+ - Replaced the dual-transport DePIN documentation and examples with the
31
+ protocol 2 single-RPC-port challenge flow.
32
+
33
+ > Entries below describe the behavior of older releases and are retained as
34
+ > history; their TCP gateway configuration does not apply to 0.6.0 or later.
35
+
8
36
  ## [0.5.0] - 2026-08-01
9
37
 
10
38
  ### Breaking — DePIN client rewritten for the gateway's real protocol
package/DEPIN_EXAMPLES.md CHANGED
@@ -1,199 +1,127 @@
1
- # DePIN RPC Examples
1
+ # DePIN protocol 2 examples
2
2
 
3
- Practical examples for the DePIN messaging client in
4
- `@neuraiproject/neurai-rpc`.
3
+ All calls use the normal authenticated HTTP JSON-RPC endpoint.
5
4
 
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.
12
-
13
- ## Basic Setup
14
-
15
- ```javascript
5
+ ```js
16
6
  import { getRPC, methods } from "@neuraiproject/neurai-rpc";
17
- import { getDePinRPC } from "@neuraiproject/neurai-rpc/depin";
18
-
19
- // Standard RPC (HTTP) — works in Node.js and browsers
20
- const standardRpc = getRPC("user", "password", "http://localhost:19001");
21
-
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
- );
7
+
8
+ const rpc = getRPC("username", "password", "http://127.0.0.1:19001");
9
+ const address = "NXholder...";
10
+ const token = "&FRANCE/GENERAL";
38
11
  ```
39
12
 
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`).
13
+ ## Pool information
44
14
 
45
- ```javascript
46
- const publicRpc = getDePinRPC({ host: "127.0.0.1", port: 19002 });
47
- const info = await publicRpc("depingetmsginfo", []);
15
+ ```js
16
+ const info = await rpc(methods.depingetmsginfo, []);
17
+ const stats = await rpc(methods.depinpoolstats, []);
48
18
  ```
49
19
 
50
- ## Example 1: Send a DePIN Message
20
+ Pin `info.depinpoolpkey` on first use. Use it to verify pool signatures and to
21
+ encrypt envelopes submitted through `depinsubmitmsg`.
51
22
 
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.
23
+ ## Send with the local wallet
56
24
 
57
- ```javascript
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
25
+ ```js
26
+ const result = await rpc(methods.depinsendmsg, [
27
+ token,
28
+ "Hello team!",
29
+ "NXsender...",
63
30
  ]);
64
- console.log(result);
65
- ```
66
-
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+):
74
-
75
- ```javascript
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;
92
- }
93
31
  ```
94
32
 
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"])`.
33
+ `fromaddress` must belong to the node wallet. For a non-custodial remote
34
+ client, prepare and sign the message client-side, encrypt its serialized form
35
+ for `depingetmsginfo.depinpoolpkey`, and call:
99
36
 
100
- ## Example 3: Submit a Pre-encrypted Message
101
-
102
- ```javascript
103
- const result = await depinRpc("depinsubmitmsg", [
104
- "48656c6c6f...", // hex-encoded encrypted message
105
- ]);
37
+ ```js
38
+ await rpc(methods.depinsubmitmsg, [{
39
+ sender: "NXsender...",
40
+ encrypted: "<ECIES envelope hex>",
41
+ }]);
106
42
  ```
107
43
 
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:
44
+ ## Obtain a receive challenge
114
45
 
115
- ```javascript
116
- // Remove expired messages
117
- await depinRpc("depinclearmsg", []);
46
+ ```js
47
+ const requestProof = await rpc(methods.depinsignrequest, [
48
+ address,
49
+ token,
50
+ "receive",
51
+ ]);
118
52
 
119
- // Remove ALL messages
120
- await depinRpc("depinclearmsg", ["all"]);
53
+ const challengeReply = await rpc(methods.depinchallenge, [
54
+ token,
55
+ address,
56
+ requestProof.timestamp,
57
+ requestProof.signature,
58
+ "receive",
59
+ ]);
121
60
 
122
- // Remove messages older than 7 days
123
- await depinRpc("depinclearmsg", [168]);
61
+ // Verify challengeReply.poolsig against the pinned pool key first.
62
+ const challengeBody = await rpc(methods.depindecrypt, [
63
+ address,
64
+ challengeReply.encrypted,
65
+ ]);
124
66
 
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"]);
67
+ const challengeProof = await rpc(methods.depinsignchallenge, [
68
+ address,
69
+ token,
70
+ challengeBody.challenge,
71
+ "receive",
72
+ ]);
128
73
  ```
129
74
 
130
- ## Example 5: Sections and Branch Holders
131
-
132
- ```javascript
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",
75
+ ## Receive messages
76
+
77
+ ```js
78
+ const encryptedPage = await rpc(methods.depinreceivemsg, [
79
+ token,
80
+ address,
81
+ challengeBody.challenge,
82
+ challengeProof.signature,
83
+ 0,
84
+ "",
85
+ 50,
139
86
  ]);
87
+
88
+ // Verify encryptedPage.poolsig first.
89
+ const page = await rpc(methods.depindecrypt, [address, encryptedPage.encrypted]);
90
+ console.log(page.messages);
140
91
  ```
141
92
 
142
- ## Example 6: Manual Challenge Handling
93
+ The decrypted response can contain `next_challenge`. Sign it for the next page
94
+ instead of requesting a new challenge.
143
95
 
144
- ```javascript
145
- import { requestDePinChallenge } from "@neuraiproject/neurai-rpc/depin";
96
+ ## List sections
146
97
 
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")
154
- }
155
- );
98
+ ```js
99
+ const publicSections = await rpc(methods.depinlistsections, []);
156
100
 
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"
101
+ const encryptedSections = await rpc(methods.depinlistsections, [
102
+ address,
103
+ token,
104
+ challengeBody.challenge,
105
+ challengeProof.signature,
106
+ ]);
160
107
  ```
161
108
 
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.
165
-
166
- ## Example 7: Error Handling
167
-
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
- }
179
- }
180
- ```
109
+ Challenges are single-use. Obtain a fresh one if a previous call consumed it.
181
110
 
182
- The client raises a clear error, without touching the network, when:
111
+ ## Clear messages as an owner
183
112
 
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.
113
+ Repeat the challenge flow with type `admin`, then call:
188
114
 
189
- ## Notes
115
+ ```js
116
+ await rpc(methods.depinclearmsg, [
117
+ token,
118
+ "NXowner...",
119
+ adminChallenge,
120
+ adminSignature,
121
+ "all",
122
+ ]);
123
+ ```
190
124
 
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.
125
+ Use an empty scope for the configured pool root. Omit the final mode to remove
126
+ expired messages, use `"all"` for every message, or pass an age in hours. The
127
+ challenge must have been issued for exactly the same scope.