@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 +28 -0
- package/DEPIN_EXAMPLES.md +93 -165
- package/DEPIN_IMPLEMENTATION_GUIDE_EN.md +78 -1099
- package/README.md +74 -389
- package/dist/index.cjs +72 -262
- package/dist/index.d.cts +5 -1
- package/dist/index.d.ts +5 -1
- package/dist/index.mjs +72 -262
- package/docs.json +15 -11
- package/docs.ts +102 -268
- package/index.ts +2 -3
- package/neurai_methods.md +77 -263
- package/package.json +1 -12
- package/depin.ts +0 -545
- package/dist/depin.cjs +0 -305
- package/dist/depin.d.cts +0 -96
- package/dist/depin.d.ts +0 -96
- package/dist/depin.mjs +0 -280
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
|
|
1
|
+
# DePIN protocol 2 examples
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
`@neuraiproject/neurai-rpc`.
|
|
3
|
+
All calls use the normal authenticated HTTP JSON-RPC endpoint.
|
|
5
4
|
|
|
6
|
-
|
|
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
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
const
|
|
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
|
-
|
|
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
|
-
```
|
|
46
|
-
const
|
|
47
|
-
const
|
|
15
|
+
```js
|
|
16
|
+
const info = await rpc(methods.depingetmsginfo, []);
|
|
17
|
+
const stats = await rpc(methods.depinpoolstats, []);
|
|
48
18
|
```
|
|
49
19
|
|
|
50
|
-
|
|
20
|
+
Pin `info.depinpoolpkey` on first use. Use it to verify pool signatures and to
|
|
21
|
+
encrypt envelopes submitted through `depinsubmitmsg`.
|
|
51
22
|
|
|
52
|
-
|
|
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
|
-
```
|
|
58
|
-
const result = await
|
|
59
|
-
|
|
60
|
-
"
|
|
61
|
-
"
|
|
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
|
-
|
|
96
|
-
|
|
97
|
-
|
|
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
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
]);
|
|
37
|
+
```js
|
|
38
|
+
await rpc(methods.depinsubmitmsg, [{
|
|
39
|
+
sender: "NXsender...",
|
|
40
|
+
encrypted: "<ECIES envelope hex>",
|
|
41
|
+
}]);
|
|
106
42
|
```
|
|
107
43
|
|
|
108
|
-
##
|
|
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
|
-
```
|
|
116
|
-
|
|
117
|
-
|
|
46
|
+
```js
|
|
47
|
+
const requestProof = await rpc(methods.depinsignrequest, [
|
|
48
|
+
address,
|
|
49
|
+
token,
|
|
50
|
+
"receive",
|
|
51
|
+
]);
|
|
118
52
|
|
|
119
|
-
|
|
120
|
-
|
|
53
|
+
const challengeReply = await rpc(methods.depinchallenge, [
|
|
54
|
+
token,
|
|
55
|
+
address,
|
|
56
|
+
requestProof.timestamp,
|
|
57
|
+
requestProof.signature,
|
|
58
|
+
"receive",
|
|
59
|
+
]);
|
|
121
60
|
|
|
122
|
-
//
|
|
123
|
-
await
|
|
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
|
-
|
|
126
|
-
|
|
127
|
-
|
|
67
|
+
const challengeProof = await rpc(methods.depinsignchallenge, [
|
|
68
|
+
address,
|
|
69
|
+
token,
|
|
70
|
+
challengeBody.challenge,
|
|
71
|
+
"receive",
|
|
72
|
+
]);
|
|
128
73
|
```
|
|
129
74
|
|
|
130
|
-
##
|
|
131
|
-
|
|
132
|
-
```
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
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
|
-
|
|
93
|
+
The decrypted response can contain `next_challenge`. Sign it for the next page
|
|
94
|
+
instead of requesting a new challenge.
|
|
143
95
|
|
|
144
|
-
|
|
145
|
-
import { requestDePinChallenge } from "@neuraiproject/neurai-rpc/depin";
|
|
96
|
+
## List sections
|
|
146
97
|
|
|
147
|
-
|
|
148
|
-
|
|
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
|
-
|
|
158
|
-
|
|
159
|
-
|
|
101
|
+
const encryptedSections = await rpc(methods.depinlistsections, [
|
|
102
|
+
address,
|
|
103
|
+
token,
|
|
104
|
+
challengeBody.challenge,
|
|
105
|
+
challengeProof.signature,
|
|
106
|
+
]);
|
|
160
107
|
```
|
|
161
108
|
|
|
162
|
-
|
|
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
|
-
|
|
111
|
+
## Clear messages as an owner
|
|
183
112
|
|
|
184
|
-
|
|
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
|
-
|
|
115
|
+
```js
|
|
116
|
+
await rpc(methods.depinclearmsg, [
|
|
117
|
+
token,
|
|
118
|
+
"NXowner...",
|
|
119
|
+
adminChallenge,
|
|
120
|
+
adminSignature,
|
|
121
|
+
"all",
|
|
122
|
+
]);
|
|
123
|
+
```
|
|
190
124
|
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
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.
|