@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
|
@@ -2,10 +2,14 @@
|
|
|
2
2
|
|
|
3
3
|
## Change Summary
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
5
|
+
This guide covers the RPC commands of Neurai's DePIN (Decentralized Physical
|
|
6
|
+
Infrastructure Networks) system — asset management, encrypted messaging and
|
|
7
|
+
AI/MCP monitoring — and the library's DePIN client. As of 0.5.0 the client
|
|
8
|
+
speaks the gateway's real raw-TCP line protocol from the Node.js-only entry
|
|
9
|
+
`@neuraiproject/neurai-rpc/depin` (see §3.2 and the changelog in §10).
|
|
10
|
+
|
|
11
|
+
**Version:** 0.5.0
|
|
12
|
+
**Date:** August 2026
|
|
9
13
|
**Branch:** master
|
|
10
14
|
|
|
11
15
|
---
|
|
@@ -16,16 +20,15 @@ Thirteen new RPC commands have been added for Neurai's DePIN (Decentralized Phys
|
|
|
16
20
|
|
|
17
21
|
The DePIN system uses two distinct ports for different operations:
|
|
18
22
|
|
|
19
|
-
- **
|
|
20
|
-
- **Port 19002** (DePIN
|
|
23
|
+
- **Ports 19001 (mainnet) / 19101 (testnet)** (standard RPC, HTTP): Asset management commands and queries
|
|
24
|
+
- **Port 19002** (DePIN gateway, raw TCP): Encrypted messaging and P2P operations (default of `-depinmsgport`, same on every network)
|
|
21
25
|
|
|
22
26
|
### 1.2 DePIN Asset Types
|
|
23
27
|
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
-
|
|
27
|
-
-
|
|
28
|
-
- Require the owner token `ASSET!` for administration operations
|
|
28
|
+
There are two related but different concepts in the current DePIN stack:
|
|
29
|
+
|
|
30
|
+
- **DePIN messaging token:** the DEPIN asset configured in `depinmsgtoken` for gateway messaging. It must start with `&` (e.g. `&FRANCE`); sections like `&FRANCE/GENERAL` scope hierarchical pools.
|
|
31
|
+
- **Dedicated DePIN asset type:** a newer asset class used by the asset-management RPCs (`checkdepinvalidity`, `listdepinholders`, `freezedepin`, `unfreezedepin`, `selfrevokedepin`). These assets use the `&` prefix, are soulbound, are currently enabled on **testnet and regtest only** in the node, require the owner token `&ASSET!`, and must be issued and reissued with `units=0`.
|
|
29
32
|
|
|
30
33
|
---
|
|
31
34
|
|
|
@@ -48,12 +51,12 @@ checkdepinvalidity(asset_name: string, address: string): Promise<{
|
|
|
48
51
|
|
|
49
52
|
**Example:**
|
|
50
53
|
```javascript
|
|
51
|
-
const rpc = getRPC('http://127.0.0.1:
|
|
52
|
-
const result = await rpc('checkdepinvalidity', ['FRANCE', 'NXabcd...']);
|
|
54
|
+
const rpc = getRPC('username', 'password', 'http://127.0.0.1:19001');
|
|
55
|
+
const result = await rpc('checkdepinvalidity', ['&FRANCE', 'NXabcd...']);
|
|
53
56
|
// Returns: { has_asset: true, amount: 1, valid: 1, blocked: false }
|
|
54
57
|
```
|
|
55
58
|
|
|
56
|
-
**Port:**
|
|
59
|
+
**Port:** standard RPC (19001 mainnet / 19101 testnet)
|
|
57
60
|
**Requires Wallet:** No
|
|
58
61
|
|
|
59
62
|
---
|
|
@@ -72,18 +75,44 @@ listdepinholders(asset_name: string): Promise<Array<{
|
|
|
72
75
|
|
|
73
76
|
**Example:**
|
|
74
77
|
```javascript
|
|
75
|
-
const holders = await rpc('listdepinholders', ['FRANCE']);
|
|
78
|
+
const holders = await rpc('listdepinholders', ['&FRANCE']);
|
|
76
79
|
// Returns: [
|
|
77
80
|
// { address: 'NXabc...', amount: 1, valid: 1 },
|
|
78
81
|
// { address: 'NXdef...', amount: 1, valid: 0 }
|
|
79
82
|
// ]
|
|
80
83
|
```
|
|
81
84
|
|
|
82
|
-
**Port:**
|
|
85
|
+
**Port:** standard RPC (19001 mainnet / 19101 testnet)
|
|
83
86
|
**Requires:** `-assetindex` enabled on the node
|
|
84
87
|
|
|
85
88
|
---
|
|
86
89
|
|
|
90
|
+
#### **listdepinaddresses**
|
|
91
|
+
Lists addresses that own an asset and have already revealed a public key on-chain.
|
|
92
|
+
This is useful when discovering recipients for DePIN messaging.
|
|
93
|
+
|
|
94
|
+
**Signature:**
|
|
95
|
+
```typescript
|
|
96
|
+
listdepinaddresses(asset_name: string, count?: number, start?: number): Promise<Array<{
|
|
97
|
+
address: string;
|
|
98
|
+
pubkey: string;
|
|
99
|
+
}>>
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
**Example:**
|
|
103
|
+
```javascript
|
|
104
|
+
const recipients = await rpc('listdepinaddresses', ['&FRANCE']);
|
|
105
|
+
// Returns: [
|
|
106
|
+
// { address: 'NXabc...', pubkey: '02ab...' },
|
|
107
|
+
// { address: 'NXdef...', pubkey: '03cd...' }
|
|
108
|
+
// ]
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
**Port:** standard RPC (19001 mainnet / 19101 testnet)
|
|
112
|
+
**Requires:** `-assetindex` and `-pubkeyindex` enabled on the node
|
|
113
|
+
|
|
114
|
+
---
|
|
115
|
+
|
|
87
116
|
#### **freezedepin**
|
|
88
117
|
Freezes a DePIN asset for a specific address (owner only).
|
|
89
118
|
|
|
@@ -98,12 +127,12 @@ freezedepin(
|
|
|
98
127
|
|
|
99
128
|
**Example:**
|
|
100
129
|
```javascript
|
|
101
|
-
const txid = await rpc('freezedepin', ['FRANCE', 'NXmalicious...']);
|
|
130
|
+
const txid = await rpc('freezedepin', ['&FRANCE', 'NXmalicious...']);
|
|
102
131
|
// Returns: "a1b2c3d4e5f6..." (transaction ID)
|
|
103
132
|
```
|
|
104
133
|
|
|
105
|
-
**Port:**
|
|
106
|
-
**Requires:** Owner token
|
|
134
|
+
**Port:** standard RPC (19001 mainnet / 19101 testnet)
|
|
135
|
+
**Requires:** Owner token `&FRANCE!` in the wallet
|
|
107
136
|
|
|
108
137
|
---
|
|
109
138
|
|
|
@@ -119,7 +148,7 @@ unfreezedepin(
|
|
|
119
148
|
): Promise<string> // txid
|
|
120
149
|
```
|
|
121
150
|
|
|
122
|
-
**Port:**
|
|
151
|
+
**Port:** standard RPC (19001 mainnet / 19101 testnet)
|
|
123
152
|
**Requires:** Owner token `ASSET!` in the wallet
|
|
124
153
|
|
|
125
154
|
---
|
|
@@ -134,10 +163,10 @@ selfrevokedepin(asset_name: string): Promise<string> // txid
|
|
|
134
163
|
|
|
135
164
|
**Example:**
|
|
136
165
|
```javascript
|
|
137
|
-
const txid = await rpc('selfrevokedepin', ['FRANCE']);
|
|
166
|
+
const txid = await rpc('selfrevokedepin', ['&FRANCE']);
|
|
138
167
|
```
|
|
139
168
|
|
|
140
|
-
**Port:**
|
|
169
|
+
**Port:** standard RPC (19001 mainnet / 19101 testnet)
|
|
141
170
|
**Requires Wallet:** Yes (the wallet must hold the asset)
|
|
142
171
|
|
|
143
172
|
---
|
|
@@ -170,7 +199,7 @@ depingetmsginfo(): Promise<{
|
|
|
170
199
|
const info = await rpc('depingetmsginfo', []);
|
|
171
200
|
// Returns: {
|
|
172
201
|
// enabled: true,
|
|
173
|
-
// token: "FRANCE",
|
|
202
|
+
// token: "&FRANCE",
|
|
174
203
|
// port: 19002,
|
|
175
204
|
// maxmessagesize: 1024,
|
|
176
205
|
// messages: 42,
|
|
@@ -178,7 +207,7 @@ const info = await rpc('depingetmsginfo', []);
|
|
|
178
207
|
// }
|
|
179
208
|
```
|
|
180
209
|
|
|
181
|
-
**Port:**
|
|
210
|
+
**Port:** standard RPC (19001 mainnet / 19101 testnet)
|
|
182
211
|
|
|
183
212
|
---
|
|
184
213
|
|
|
@@ -205,14 +234,15 @@ depinsendmsg(
|
|
|
205
234
|
1. Client connects to remote gateway on port 19002
|
|
206
235
|
2. Requests challenge: `AUTH|TOKEN|ADDRESS|SEND`
|
|
207
236
|
3. Gateway responds: `CHALLENGE|<challenge>|<timeout>`
|
|
208
|
-
4. Client signs
|
|
209
|
-
5. Client sends
|
|
237
|
+
4. Client signs `DEPIN-SEND|token|address|challenge` with its private key
|
|
238
|
+
5. Client sends the JSON-RPC request with challenge and signature appended
|
|
239
|
+
to the params — the gateway validates and trims them (see §3.2)
|
|
210
240
|
6. Gateway validates and distributes the message
|
|
211
241
|
|
|
212
242
|
**Example:**
|
|
213
243
|
```javascript
|
|
214
244
|
const result = await rpc('depinsendmsg', [
|
|
215
|
-
'FRANCE',
|
|
245
|
+
'&FRANCE',
|
|
216
246
|
'192.168.1.100:19002',
|
|
217
247
|
'Hello team!',
|
|
218
248
|
'NXsender...'
|
|
@@ -220,7 +250,7 @@ const result = await rpc('depinsendmsg', [
|
|
|
220
250
|
// Returns: { result: "success", hash: "abc123...", recipients: 5, timestamp: 1702123456 }
|
|
221
251
|
```
|
|
222
252
|
|
|
223
|
-
**Port:**
|
|
253
|
+
**Port:** standard RPC (19001/19101); the node connects out to the remote gateway on TCP 19002
|
|
224
254
|
**Encryption:** ECIES (ECDH + AES-256-CBC + HMAC-SHA256)
|
|
225
255
|
|
|
226
256
|
---
|
|
@@ -283,36 +313,40 @@ depingetmsg(
|
|
|
283
313
|
|
|
284
314
|
1. **Local - all addresses:**
|
|
285
315
|
```javascript
|
|
286
|
-
const messages = await rpc('depingetmsg', ['FRANCE']);
|
|
316
|
+
const messages = await rpc('depingetmsg', ['&FRANCE']);
|
|
287
317
|
```
|
|
288
318
|
|
|
289
319
|
2. **Local - specific address:**
|
|
290
320
|
```javascript
|
|
291
|
-
const messages = await rpc('depingetmsg', ['FRANCE', 'NXyouraddr...']);
|
|
321
|
+
const messages = await rpc('depingetmsg', ['&FRANCE', 'NXyouraddr...']);
|
|
292
322
|
```
|
|
293
323
|
|
|
294
324
|
3. **Remote - IP without port:**
|
|
295
325
|
```javascript
|
|
296
|
-
const messages = await rpc('depingetmsg', ['FRANCE', '192.168.1.78']);
|
|
326
|
+
const messages = await rpc('depingetmsg', ['&FRANCE', '192.168.1.78']);
|
|
297
327
|
```
|
|
298
328
|
|
|
299
329
|
4. **Remote - IP with port:**
|
|
300
330
|
```javascript
|
|
301
|
-
const messages = await rpc('depingetmsg', ['FRANCE', '192.168.1.78:19002']);
|
|
331
|
+
const messages = await rpc('depingetmsg', ['&FRANCE', '192.168.1.78:19002']);
|
|
302
332
|
```
|
|
303
333
|
|
|
304
334
|
5. **Remote - with specific address:**
|
|
305
335
|
```javascript
|
|
306
336
|
const messages = await rpc('depingetmsg', [
|
|
307
|
-
'FRANCE',
|
|
337
|
+
'&FRANCE',
|
|
308
338
|
'192.168.1.78:19002',
|
|
309
339
|
'NXyouraddr...'
|
|
310
340
|
]);
|
|
311
341
|
```
|
|
312
342
|
|
|
313
|
-
**Port:**
|
|
343
|
+
**Port:** standard RPC (19001/19101) for local queries; remote queries reach the remote gateway on TCP 19002
|
|
314
344
|
**Decryption:** Automatic using the wallet's private keys
|
|
315
345
|
|
|
346
|
+
> **Gateway note:** calling `depingetmsg` directly against the TCP gateway
|
|
347
|
+
> (port 19002) is currently blocked by a node-side parameter bug — see §3.2.
|
|
348
|
+
> Through the standard RPC port (shown above) it works normally.
|
|
349
|
+
|
|
316
350
|
---
|
|
317
351
|
|
|
318
352
|
#### **depinclearmsg**
|
|
@@ -320,7 +354,10 @@ Removes messages from the DePIN messaging pool.
|
|
|
320
354
|
|
|
321
355
|
**Signature:**
|
|
322
356
|
```typescript
|
|
323
|
-
depinclearmsg(
|
|
357
|
+
depinclearmsg(
|
|
358
|
+
mode?: 'all' | number,
|
|
359
|
+
scope?: string // section token, e.g. "&TOKEN/GENERAL"
|
|
360
|
+
): Promise<{
|
|
324
361
|
removed: number;
|
|
325
362
|
remaining: number;
|
|
326
363
|
}>
|
|
@@ -330,6 +367,9 @@ depinclearmsg(mode?: 'all' | number): Promise<{
|
|
|
330
367
|
- No parameters: Remove only expired messages (default)
|
|
331
368
|
- `"all"`: Remove ALL messages from the pool
|
|
332
369
|
- `<hours>`: Remove messages older than the specified hours
|
|
370
|
+
- With `scope`: restrict the purge to one section's subtree (owner of the
|
|
371
|
+
section or of an ancestor required over the gateway; purging a subtree
|
|
372
|
+
never touches parents or siblings)
|
|
333
373
|
|
|
334
374
|
**Examples:**
|
|
335
375
|
```javascript
|
|
@@ -341,9 +381,12 @@ const result = await rpc('depinclearmsg', ['all']);
|
|
|
341
381
|
|
|
342
382
|
// Remove older than 7 days
|
|
343
383
|
const result = await rpc('depinclearmsg', [168]);
|
|
384
|
+
|
|
385
|
+
// Remove everything in one section only
|
|
386
|
+
const result = await rpc('depinclearmsg', ['all', '&FRANCE/GENERAL']);
|
|
344
387
|
```
|
|
345
388
|
|
|
346
|
-
**Port:**
|
|
389
|
+
**Port:** standard RPC (19001/19101); over the gateway (19002) it requires an ADMIN challenge — see §3.2
|
|
347
390
|
|
|
348
391
|
---
|
|
349
392
|
|
|
@@ -391,7 +434,7 @@ const pool = await rpc('depingetpoolcontent', ['raw']);
|
|
|
391
434
|
const pool = await rpc('depingetpoolcontent', [false, 'NXsender...']);
|
|
392
435
|
```
|
|
393
436
|
|
|
394
|
-
**Port:**
|
|
437
|
+
**Port:** standard RPC (19001 mainnet / 19101 testnet)
|
|
395
438
|
**Note:** Recipient filtering does not work with ECIES shared encryption
|
|
396
439
|
|
|
397
440
|
---
|
|
@@ -426,7 +469,108 @@ depinpoolstats(): Promise<{
|
|
|
426
469
|
const stats = await rpc('depinpoolstats', []);
|
|
427
470
|
```
|
|
428
471
|
|
|
429
|
-
**Port:**
|
|
472
|
+
**Port:** standard RPC (19001 mainnet / 19101 testnet)
|
|
473
|
+
|
|
474
|
+
---
|
|
475
|
+
|
|
476
|
+
#### **depinreceivemsg**
|
|
477
|
+
Retrieves DePIN messages from the pool with optional pagination. If the
|
|
478
|
+
server has a DePIN pool key and the requester's address has a revealed
|
|
479
|
+
public key, the response is fully encrypted using the privacy layer.
|
|
480
|
+
|
|
481
|
+
**Signature:**
|
|
482
|
+
```typescript
|
|
483
|
+
depinreceivemsg(
|
|
484
|
+
token: string,
|
|
485
|
+
address: string,
|
|
486
|
+
timestamp?: number, // only messages with timestamp >= (timestamp-1)
|
|
487
|
+
after_hash?: string, // hash of last received message, "" = from beginning
|
|
488
|
+
limit?: number // max messages, 0/omitted = all
|
|
489
|
+
): Promise<Array<object> | object>
|
|
490
|
+
```
|
|
491
|
+
|
|
492
|
+
**Examples:**
|
|
493
|
+
```javascript
|
|
494
|
+
// Everything for one address
|
|
495
|
+
const msgs = await rpc('depinreceivemsg', ['&FRANCE', 'NXyouraddr...']);
|
|
496
|
+
|
|
497
|
+
// Paginated: 50 messages after a known hash
|
|
498
|
+
const page = await rpc('depinreceivemsg', [
|
|
499
|
+
'&FRANCE', 'NXyouraddr...', 0, 'abcdef123...', 50,
|
|
500
|
+
]);
|
|
501
|
+
```
|
|
502
|
+
|
|
503
|
+
**Port:** standard RPC (19001/19101) and 19002 (served without auth by the gateway)
|
|
504
|
+
**Node:** requires July 2026+ for `after_hash`/`limit` pagination
|
|
505
|
+
|
|
506
|
+
---
|
|
507
|
+
|
|
508
|
+
#### **depingetancestorrecipients**
|
|
509
|
+
Lists the active holders of a DEPIN branch: the deduplicated union of the
|
|
510
|
+
holders of the given token and of every one of its `/`-separated ancestors,
|
|
511
|
+
each with the public key revealed on chain. Active means: positive balance,
|
|
512
|
+
public key revealed, and not blocked by an owner freeze or self-revocation.
|
|
513
|
+
|
|
514
|
+
**Signature:**
|
|
515
|
+
```typescript
|
|
516
|
+
depingetancestorrecipients(
|
|
517
|
+
token: string,
|
|
518
|
+
max_results?: number,
|
|
519
|
+
stop_at?: string // ancestor at which to stop climbing
|
|
520
|
+
): Promise<object>
|
|
521
|
+
```
|
|
522
|
+
|
|
523
|
+
**Example:**
|
|
524
|
+
```javascript
|
|
525
|
+
const holders = await rpc('depingetancestorrecipients', ['&FRANCE/PARIS']);
|
|
526
|
+
```
|
|
527
|
+
|
|
528
|
+
**Port:** standard RPC (19001 mainnet / 19101 testnet)
|
|
529
|
+
**Node:** requires July 2026+
|
|
530
|
+
|
|
531
|
+
---
|
|
532
|
+
|
|
533
|
+
#### **depinlistsections**
|
|
534
|
+
Lists the hierarchical DePIN sections known to the wallet. With an address it
|
|
535
|
+
also reports access and per-section message counters — that mode requires the
|
|
536
|
+
standard RPC port (over the gateway only section names are served).
|
|
537
|
+
|
|
538
|
+
**Signature:**
|
|
539
|
+
```typescript
|
|
540
|
+
depinlistsections(address?: string): Promise<object>
|
|
541
|
+
```
|
|
542
|
+
|
|
543
|
+
**Example:**
|
|
544
|
+
```javascript
|
|
545
|
+
const sections = await rpc('depinlistsections', []);
|
|
546
|
+
const mine = await rpc('depinlistsections', ['NXyouraddr...']);
|
|
547
|
+
```
|
|
548
|
+
|
|
549
|
+
**Port:** standard RPC (19001/19101) (names also on 19002)
|
|
550
|
+
**Node:** requires July 2026+
|
|
551
|
+
|
|
552
|
+
---
|
|
553
|
+
|
|
554
|
+
#### **depinpoolpkey**
|
|
555
|
+
Returns the public key of the DePIN pool address from the internal wallet
|
|
556
|
+
(wallet must be loaded and unlocked at node startup). Derivation paths:
|
|
557
|
+
mainnet `m/44'/0'/200'/0/0`, testnet `m/44'/0'/200'/1/0`.
|
|
558
|
+
|
|
559
|
+
**Signature:**
|
|
560
|
+
```typescript
|
|
561
|
+
depinpoolpkey(): Promise<{
|
|
562
|
+
pubkey: string;
|
|
563
|
+
address: string;
|
|
564
|
+
path: string;
|
|
565
|
+
}>
|
|
566
|
+
```
|
|
567
|
+
|
|
568
|
+
**Example:**
|
|
569
|
+
```javascript
|
|
570
|
+
const poolKey = await rpc('depinpoolpkey', []);
|
|
571
|
+
```
|
|
572
|
+
|
|
573
|
+
**Port:** standard RPC (19001/19101) and 19002 (served without auth by the gateway)
|
|
430
574
|
|
|
431
575
|
---
|
|
432
576
|
|
|
@@ -469,7 +613,7 @@ const status = await rpc('depinmcpstatus', []);
|
|
|
469
613
|
// }
|
|
470
614
|
```
|
|
471
615
|
|
|
472
|
-
**Port:**
|
|
616
|
+
**Port:** standard RPC (19001 mainnet / 19101 testnet)
|
|
473
617
|
**Note:** The MCP worker processes AI commands sent through the DePIN messaging system
|
|
474
618
|
|
|
475
619
|
---
|
|
@@ -507,40 +651,60 @@ The system uses ECIES (Elliptic Curve Integrated Encryption Scheme) with the fol
|
|
|
507
651
|
5. Decrypt: plaintext = AES-256-CBC-decrypt(ciphertext, encryption_key, iv)
|
|
508
652
|
```
|
|
509
653
|
|
|
510
|
-
### 3.2 Challenge/Response Authentication
|
|
654
|
+
### 3.2 Gateway Transport and Challenge/Response Authentication
|
|
511
655
|
|
|
512
|
-
|
|
656
|
+
The gateway (default port 19002) speaks a **raw TCP line protocol, not HTTP**:
|
|
657
|
+
each connection carries exactly one request line terminated by `\n` and
|
|
658
|
+
receives one response line back. A request line is either a protocol command
|
|
659
|
+
(`PING`, `INFO`, `AUTH|...`) or a serialized JSON-RPC object.
|
|
513
660
|
|
|
514
661
|
**Protocol:**
|
|
515
662
|
```
|
|
516
|
-
Client → Server: AUTH|<token>|<address>|<mode
|
|
517
|
-
mode = SEND | RECEIVE
|
|
518
|
-
|
|
519
|
-
Server → Client: CHALLENGE|<random_challenge>|<timeout_seconds
|
|
520
|
-
|
|
521
|
-
Client:
|
|
522
|
-
|
|
523
|
-
|
|
524
|
-
|
|
525
|
-
|
|
526
|
-
|
|
527
|
-
|
|
528
|
-
|
|
529
|
-
|
|
530
|
-
|
|
531
|
-
|
|
663
|
+
Client → Server: AUTH|<token>|<address>|<mode>\n
|
|
664
|
+
mode = SEND | RECEIVE | ADMIN
|
|
665
|
+
|
|
666
|
+
Server → Client: CHALLENGE|<random_challenge>|<timeout_seconds>\n
|
|
667
|
+
|
|
668
|
+
Client signs the mode-specific message with the address key:
|
|
669
|
+
SEND → "DEPIN-SEND|<token>|<address>|<challenge>" (depinsendmsg)
|
|
670
|
+
RECEIVE → "DEPIN-GET|<token>|<address>|<challenge>"
|
|
671
|
+
ADMIN → "DEPIN-CLEAR|<token>|<address>|<challenge>" (depinclearmsg, owner only)
|
|
672
|
+
|
|
673
|
+
Client → Server (new connection): {"jsonrpc":"2.0","id":...,"method":...,"params":[...]}\n
|
|
674
|
+
Challenge and signature placement depends on the method:
|
|
675
|
+
- depinsendmsg: [token, ip, message, fromaddress, (port), challenge, signature]
|
|
676
|
+
(the gateway validates and trims the last two)
|
|
677
|
+
- depinclearmsg: [mode, address, challenge, signature] or
|
|
678
|
+
[mode, scope, address, challenge, signature]
|
|
679
|
+
- depinreceivemsg, depinsubmitmsg, depingetmsginfo, depingetpoolcontent,
|
|
680
|
+
depinpoolstats, depinmcpstatus, depinlistsections, depinpoolpkey:
|
|
681
|
+
params untouched — the gateway serves them without auth
|
|
682
|
+
|
|
683
|
+
Server → Client: JSON-RPC response line
|
|
532
684
|
```
|
|
533
685
|
|
|
686
|
+
Note: `depingetmsg` over the gateway is currently blocked by a node-side bug
|
|
687
|
+
(the gateway reads `fromaddress` from `params[3]`, where this method carries
|
|
688
|
+
it at index 1 or 2 and accepts at most 3 arguments). Use `depinreceivemsg`
|
|
689
|
+
over the gateway, or `depingetmsg` through the standard RPC port.
|
|
690
|
+
|
|
534
691
|
---
|
|
535
692
|
|
|
536
693
|
## 4. Wallet Web Implementation
|
|
537
694
|
|
|
695
|
+
> **Transport note:** the class below talks to the node's **standard HTTP RPC
|
|
696
|
+
> port** with Basic auth, which works from a browser and is the right choice
|
|
697
|
+
> for wallet web apps (for `depinsendmsg` the local node opens the TCP
|
|
698
|
+
> connection to the remote gateway itself). Direct access to the DePIN
|
|
699
|
+
> gateway (TCP 19002) is only possible from Node.js — use
|
|
700
|
+
> `import { getDePinRPC } from "@neuraiproject/neurai-rpc/depin"` for that.
|
|
701
|
+
|
|
538
702
|
### 4.1 Recommended DePINClient Class
|
|
539
703
|
|
|
540
704
|
```typescript
|
|
541
705
|
class DePINClient {
|
|
542
706
|
private rpcUrl: string;
|
|
543
|
-
private rpcPort: number =
|
|
707
|
+
private rpcPort: number = 19001;
|
|
544
708
|
private depinPort: number = 19002;
|
|
545
709
|
private username: string;
|
|
546
710
|
private password: string;
|
|
@@ -553,13 +717,13 @@ class DePINClient {
|
|
|
553
717
|
password: string;
|
|
554
718
|
}) {
|
|
555
719
|
this.rpcUrl = `http://${config.host}`;
|
|
556
|
-
this.rpcPort = config.rpcPort ||
|
|
720
|
+
this.rpcPort = config.rpcPort || 19001;
|
|
557
721
|
this.depinPort = config.depinPort || 19002;
|
|
558
722
|
this.username = config.username;
|
|
559
723
|
this.password = config.password;
|
|
560
724
|
}
|
|
561
725
|
|
|
562
|
-
// Standard RPC operations (port
|
|
726
|
+
// Standard RPC operations (standard RPC port)
|
|
563
727
|
async checkValidity(asset: string, address: string) {
|
|
564
728
|
return this.callRPC('checkdepinvalidity', [asset, address]);
|
|
565
729
|
}
|
|
@@ -577,7 +741,7 @@ class DePINClient {
|
|
|
577
741
|
return this.callRPC('depinpoolstats', []);
|
|
578
742
|
}
|
|
579
743
|
|
|
580
|
-
// Messaging operations (
|
|
744
|
+
// Messaging operations (the local node opens the TCP gateway connection)
|
|
581
745
|
async sendMessage(
|
|
582
746
|
token: string,
|
|
583
747
|
remoteHost: string,
|
|
@@ -729,7 +893,7 @@ async function verifyTokenOwnership(address: string, token: string) {
|
|
|
729
893
|
}
|
|
730
894
|
```
|
|
731
895
|
|
|
732
|
-
**Note:**
|
|
896
|
+
**Note:** Both DePIN messaging and the asset-management RPCs use the dedicated `&ASSET` DEPIN asset type — `-depinmsgtoken` must start with `&`, and DEPIN assets are currently testnet/regtest only.
|
|
733
897
|
|
|
734
898
|
### 5.2 Key Management
|
|
735
899
|
|
|
@@ -774,33 +938,40 @@ To enable DePIN on the node:
|
|
|
774
938
|
# RPC Configuration
|
|
775
939
|
rpcuser=yourusername
|
|
776
940
|
rpcpassword=yourpassword
|
|
777
|
-
rpcport=
|
|
941
|
+
rpcport=19001 # 19101 on testnet
|
|
778
942
|
rpcallowip=127.0.0.1
|
|
779
943
|
rpcallowip=192.168.1.0/24
|
|
780
944
|
|
|
781
945
|
# DePIN Messaging
|
|
782
946
|
depinmsg=1
|
|
783
|
-
|
|
784
|
-
|
|
785
|
-
|
|
786
|
-
|
|
787
|
-
|
|
788
|
-
|
|
789
|
-
#
|
|
947
|
+
depinmsgtoken=&FRANCE # must start with '&' (DEPIN assets: testnet/regtest only)
|
|
948
|
+
depinmsgport=19002
|
|
949
|
+
depinmsgbind=0.0.0.0 # use 127.0.0.1 for local-only
|
|
950
|
+
depinmsgsize=1024 # max message size in bytes (default 1024)
|
|
951
|
+
depinmsgexpire=168 # message expiry in hours (default 168 = 7 days)
|
|
952
|
+
depinpoolsize=100 # max pool size in MB (default 100)
|
|
953
|
+
depinpoolpersist=0 # save/load the pool across restarts
|
|
954
|
+
|
|
955
|
+
# Asset indexes (required for DePIN holder and pubkey discovery)
|
|
790
956
|
assetindex=1
|
|
957
|
+
pubkeyindex=1
|
|
958
|
+
|
|
959
|
+
# Dedicated DePIN assets are issued separately via the standard asset RPCs
|
|
960
|
+
# Example on testnet: issue "&FRANCE" 1 "to_address" "change_address" 0 true
|
|
791
961
|
|
|
792
962
|
# MCP/AI Worker (optional)
|
|
793
963
|
depinmcp=1
|
|
794
|
-
depinmcpurl=http://localhost:
|
|
795
|
-
|
|
796
|
-
|
|
964
|
+
depinmcpurl=http://localhost:1234 # MCP server (default http://localhost:1234)
|
|
965
|
+
depinmcpendpoint=/v1/chat/completions
|
|
966
|
+
depinmcpaddress=NXbotaddress # required: address that signs bot responses
|
|
967
|
+
depinmcpkey=/ai # command prefix that triggers the AI
|
|
797
968
|
```
|
|
798
969
|
|
|
799
970
|
### 6.2 Ports to Open
|
|
800
971
|
|
|
801
972
|
In your firewall/router:
|
|
802
|
-
- **
|
|
803
|
-
- **19002**: DePIN Messaging (public if you want to receive messages)
|
|
973
|
+
- **19001** (mainnet) / **19101** (testnet): standard RPC (only localhost or trusted IPs)
|
|
974
|
+
- **19002**: DePIN Messaging gateway, raw TCP (public if you want to receive messages; configurable with `-depinmsgport`)
|
|
804
975
|
|
|
805
976
|
---
|
|
806
977
|
|
|
@@ -838,12 +1009,12 @@ async function testMessaging() {
|
|
|
838
1009
|
});
|
|
839
1010
|
|
|
840
1011
|
// Verify token
|
|
841
|
-
const validity = await client.checkValidity('FRANCE', 'NXyouraddr...');
|
|
1012
|
+
const validity = await client.checkValidity('&FRANCE', 'NXyouraddr...');
|
|
842
1013
|
console.log('Token validity:', validity);
|
|
843
1014
|
|
|
844
1015
|
// Send message
|
|
845
1016
|
const result = await client.sendMessage(
|
|
846
|
-
'FRANCE',
|
|
1017
|
+
'&FRANCE',
|
|
847
1018
|
'192.168.1.100:19002',
|
|
848
1019
|
'Test message',
|
|
849
1020
|
'NXyouraddr...'
|
|
@@ -851,7 +1022,7 @@ async function testMessaging() {
|
|
|
851
1022
|
console.log('Message sent:', result);
|
|
852
1023
|
|
|
853
1024
|
// Retrieve messages
|
|
854
|
-
const messages = await client.getMessages('FRANCE', 'NXyouraddr...');
|
|
1025
|
+
const messages = await client.getMessages('&FRANCE', 'NXyouraddr...');
|
|
855
1026
|
console.log('Messages:', messages);
|
|
856
1027
|
}
|
|
857
1028
|
```
|
|
@@ -876,7 +1047,8 @@ async function testMessaging() {
|
|
|
876
1047
|
Enable detailed logs in `neurai.conf`:
|
|
877
1048
|
|
|
878
1049
|
```ini
|
|
879
|
-
debug=
|
|
1050
|
+
debug=net # the DePIN gateway logs under the net category
|
|
1051
|
+
debug=mempool # the DePIN message pool logs under mempool
|
|
880
1052
|
debug=rpc
|
|
881
1053
|
```
|
|
882
1054
|
|
|
@@ -885,7 +1057,7 @@ debug=rpc
|
|
|
885
1057
|
## 9. References
|
|
886
1058
|
|
|
887
1059
|
- **Repository:** https://github.com/NeuraiProject/neurai-rpc
|
|
888
|
-
- **Version:** 0.
|
|
1060
|
+
- **Version:** 0.5.0
|
|
889
1061
|
- **RPC Documentation:** See `neurai_methods.md`
|
|
890
1062
|
- **DePIN source code:** `Neurai/src/rpc/messages.cpp`, `Neurai/src/rpc/assets.cpp`
|
|
891
1063
|
- **ECIES specification:** `Neurai/src/depinecies.cpp`
|
|
@@ -894,6 +1066,32 @@ debug=rpc
|
|
|
894
1066
|
|
|
895
1067
|
## 10. Changelog
|
|
896
1068
|
|
|
1069
|
+
### v0.5.0 (August 2026)
|
|
1070
|
+
|
|
1071
|
+
**Library breaking change:**
|
|
1072
|
+
- The DePIN client now speaks the gateway's real raw-TCP line protocol
|
|
1073
|
+
(it previously used HTTP, which the gateway never supported) and moved to
|
|
1074
|
+
the Node.js-only entry `@neuraiproject/neurai-rpc/depin` with a
|
|
1075
|
+
`{ host, port }` constructor.
|
|
1076
|
+
- Per-method authentication: `DEPIN-SEND|`/`DEPIN-GET|`/`DEPIN-CLEAR|` sign
|
|
1077
|
+
formats, ADMIN challenges for `depinclearmsg`, and no auth appended to the
|
|
1078
|
+
gateway's unauthenticated methods.
|
|
1079
|
+
|
|
1080
|
+
**Documentation corrections:**
|
|
1081
|
+
- Real Neurai ports throughout (standard RPC 19001/19101 — 8766 was
|
|
1082
|
+
Ravencoin's), real `-depinmsg*`/`-depinmcp*` option names in §6, `debug=net`
|
|
1083
|
+
instead of the nonexistent `depin` category, the obsolete `SUBMIT|` step
|
|
1084
|
+
replaced by the real JSON-RPC flow, and the `&` messaging-token requirement
|
|
1085
|
+
(DEPIN assets are testnet/regtest only in the current node).
|
|
1086
|
+
|
|
1087
|
+
**New commands documented:**
|
|
1088
|
+
- `depinreceivemsg` - Pool retrieval with pagination
|
|
1089
|
+
- `depingetancestorrecipients` - Active holders of a DEPIN branch
|
|
1090
|
+
- `depinlistsections` - Hierarchical sections
|
|
1091
|
+
- `depinpoolpkey` - Pool public key
|
|
1092
|
+
- `depinclearmsg` scope parameter
|
|
1093
|
+
- `dumpextkeypq` / `exportxpqpub` - Post-quantum wallet (see neurai_methods.md)
|
|
1094
|
+
|
|
897
1095
|
### v0.4.5 (December 2025)
|
|
898
1096
|
|
|
899
1097
|
**New commands added:**
|