@neuraiproject/neurai-rpc 0.4.7 → 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 +80 -0
- package/DEPIN_EXAMPLES.md +148 -220
- package/DEPIN_IMPLEMENTATION_GUIDE_EN.md +239 -70
- package/README.md +98 -46
- 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 +5251 -4941
- package/dist/{types.d.ts → index.d.cts} +10 -63
- package/dist/index.d.ts +200 -0
- package/dist/index.mjs +5224 -4933
- package/docs.json +140 -134
- package/docs.ts +512 -64
- package/index.ts +13 -9
- package/neurai_methods.md +482 -64
- 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,15 +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
28
|
There are two related but different concepts in the current DePIN stack:
|
|
25
29
|
|
|
26
|
-
- **DePIN messaging token:** the asset configured in `
|
|
27
|
-
- **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
|
|
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`.
|
|
28
32
|
|
|
29
33
|
---
|
|
30
34
|
|
|
@@ -47,12 +51,12 @@ checkdepinvalidity(asset_name: string, address: string): Promise<{
|
|
|
47
51
|
|
|
48
52
|
**Example:**
|
|
49
53
|
```javascript
|
|
50
|
-
const rpc = getRPC('http://127.0.0.1:
|
|
54
|
+
const rpc = getRPC('username', 'password', 'http://127.0.0.1:19001');
|
|
51
55
|
const result = await rpc('checkdepinvalidity', ['&FRANCE', 'NXabcd...']);
|
|
52
56
|
// Returns: { has_asset: true, amount: 1, valid: 1, blocked: false }
|
|
53
57
|
```
|
|
54
58
|
|
|
55
|
-
**Port:**
|
|
59
|
+
**Port:** standard RPC (19001 mainnet / 19101 testnet)
|
|
56
60
|
**Requires Wallet:** No
|
|
57
61
|
|
|
58
62
|
---
|
|
@@ -78,7 +82,7 @@ const holders = await rpc('listdepinholders', ['&FRANCE']);
|
|
|
78
82
|
// ]
|
|
79
83
|
```
|
|
80
84
|
|
|
81
|
-
**Port:**
|
|
85
|
+
**Port:** standard RPC (19001 mainnet / 19101 testnet)
|
|
82
86
|
**Requires:** `-assetindex` enabled on the node
|
|
83
87
|
|
|
84
88
|
---
|
|
@@ -104,7 +108,7 @@ const recipients = await rpc('listdepinaddresses', ['&FRANCE']);
|
|
|
104
108
|
// ]
|
|
105
109
|
```
|
|
106
110
|
|
|
107
|
-
**Port:**
|
|
111
|
+
**Port:** standard RPC (19001 mainnet / 19101 testnet)
|
|
108
112
|
**Requires:** `-assetindex` and `-pubkeyindex` enabled on the node
|
|
109
113
|
|
|
110
114
|
---
|
|
@@ -127,7 +131,7 @@ const txid = await rpc('freezedepin', ['&FRANCE', 'NXmalicious...']);
|
|
|
127
131
|
// Returns: "a1b2c3d4e5f6..." (transaction ID)
|
|
128
132
|
```
|
|
129
133
|
|
|
130
|
-
**Port:**
|
|
134
|
+
**Port:** standard RPC (19001 mainnet / 19101 testnet)
|
|
131
135
|
**Requires:** Owner token `&FRANCE!` in the wallet
|
|
132
136
|
|
|
133
137
|
---
|
|
@@ -144,7 +148,7 @@ unfreezedepin(
|
|
|
144
148
|
): Promise<string> // txid
|
|
145
149
|
```
|
|
146
150
|
|
|
147
|
-
**Port:**
|
|
151
|
+
**Port:** standard RPC (19001 mainnet / 19101 testnet)
|
|
148
152
|
**Requires:** Owner token `ASSET!` in the wallet
|
|
149
153
|
|
|
150
154
|
---
|
|
@@ -162,7 +166,7 @@ selfrevokedepin(asset_name: string): Promise<string> // txid
|
|
|
162
166
|
const txid = await rpc('selfrevokedepin', ['&FRANCE']);
|
|
163
167
|
```
|
|
164
168
|
|
|
165
|
-
**Port:**
|
|
169
|
+
**Port:** standard RPC (19001 mainnet / 19101 testnet)
|
|
166
170
|
**Requires Wallet:** Yes (the wallet must hold the asset)
|
|
167
171
|
|
|
168
172
|
---
|
|
@@ -195,7 +199,7 @@ depingetmsginfo(): Promise<{
|
|
|
195
199
|
const info = await rpc('depingetmsginfo', []);
|
|
196
200
|
// Returns: {
|
|
197
201
|
// enabled: true,
|
|
198
|
-
// token: "FRANCE",
|
|
202
|
+
// token: "&FRANCE",
|
|
199
203
|
// port: 19002,
|
|
200
204
|
// maxmessagesize: 1024,
|
|
201
205
|
// messages: 42,
|
|
@@ -203,7 +207,7 @@ const info = await rpc('depingetmsginfo', []);
|
|
|
203
207
|
// }
|
|
204
208
|
```
|
|
205
209
|
|
|
206
|
-
**Port:**
|
|
210
|
+
**Port:** standard RPC (19001 mainnet / 19101 testnet)
|
|
207
211
|
|
|
208
212
|
---
|
|
209
213
|
|
|
@@ -230,14 +234,15 @@ depinsendmsg(
|
|
|
230
234
|
1. Client connects to remote gateway on port 19002
|
|
231
235
|
2. Requests challenge: `AUTH|TOKEN|ADDRESS|SEND`
|
|
232
236
|
3. Gateway responds: `CHALLENGE|<challenge>|<timeout>`
|
|
233
|
-
4. Client signs
|
|
234
|
-
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)
|
|
235
240
|
6. Gateway validates and distributes the message
|
|
236
241
|
|
|
237
242
|
**Example:**
|
|
238
243
|
```javascript
|
|
239
244
|
const result = await rpc('depinsendmsg', [
|
|
240
|
-
'FRANCE',
|
|
245
|
+
'&FRANCE',
|
|
241
246
|
'192.168.1.100:19002',
|
|
242
247
|
'Hello team!',
|
|
243
248
|
'NXsender...'
|
|
@@ -245,7 +250,7 @@ const result = await rpc('depinsendmsg', [
|
|
|
245
250
|
// Returns: { result: "success", hash: "abc123...", recipients: 5, timestamp: 1702123456 }
|
|
246
251
|
```
|
|
247
252
|
|
|
248
|
-
**Port:**
|
|
253
|
+
**Port:** standard RPC (19001/19101); the node connects out to the remote gateway on TCP 19002
|
|
249
254
|
**Encryption:** ECIES (ECDH + AES-256-CBC + HMAC-SHA256)
|
|
250
255
|
|
|
251
256
|
---
|
|
@@ -308,36 +313,40 @@ depingetmsg(
|
|
|
308
313
|
|
|
309
314
|
1. **Local - all addresses:**
|
|
310
315
|
```javascript
|
|
311
|
-
const messages = await rpc('depingetmsg', ['FRANCE']);
|
|
316
|
+
const messages = await rpc('depingetmsg', ['&FRANCE']);
|
|
312
317
|
```
|
|
313
318
|
|
|
314
319
|
2. **Local - specific address:**
|
|
315
320
|
```javascript
|
|
316
|
-
const messages = await rpc('depingetmsg', ['FRANCE', 'NXyouraddr...']);
|
|
321
|
+
const messages = await rpc('depingetmsg', ['&FRANCE', 'NXyouraddr...']);
|
|
317
322
|
```
|
|
318
323
|
|
|
319
324
|
3. **Remote - IP without port:**
|
|
320
325
|
```javascript
|
|
321
|
-
const messages = await rpc('depingetmsg', ['FRANCE', '192.168.1.78']);
|
|
326
|
+
const messages = await rpc('depingetmsg', ['&FRANCE', '192.168.1.78']);
|
|
322
327
|
```
|
|
323
328
|
|
|
324
329
|
4. **Remote - IP with port:**
|
|
325
330
|
```javascript
|
|
326
|
-
const messages = await rpc('depingetmsg', ['FRANCE', '192.168.1.78:19002']);
|
|
331
|
+
const messages = await rpc('depingetmsg', ['&FRANCE', '192.168.1.78:19002']);
|
|
327
332
|
```
|
|
328
333
|
|
|
329
334
|
5. **Remote - with specific address:**
|
|
330
335
|
```javascript
|
|
331
336
|
const messages = await rpc('depingetmsg', [
|
|
332
|
-
'FRANCE',
|
|
337
|
+
'&FRANCE',
|
|
333
338
|
'192.168.1.78:19002',
|
|
334
339
|
'NXyouraddr...'
|
|
335
340
|
]);
|
|
336
341
|
```
|
|
337
342
|
|
|
338
|
-
**Port:**
|
|
343
|
+
**Port:** standard RPC (19001/19101) for local queries; remote queries reach the remote gateway on TCP 19002
|
|
339
344
|
**Decryption:** Automatic using the wallet's private keys
|
|
340
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
|
+
|
|
341
350
|
---
|
|
342
351
|
|
|
343
352
|
#### **depinclearmsg**
|
|
@@ -345,7 +354,10 @@ Removes messages from the DePIN messaging pool.
|
|
|
345
354
|
|
|
346
355
|
**Signature:**
|
|
347
356
|
```typescript
|
|
348
|
-
depinclearmsg(
|
|
357
|
+
depinclearmsg(
|
|
358
|
+
mode?: 'all' | number,
|
|
359
|
+
scope?: string // section token, e.g. "&TOKEN/GENERAL"
|
|
360
|
+
): Promise<{
|
|
349
361
|
removed: number;
|
|
350
362
|
remaining: number;
|
|
351
363
|
}>
|
|
@@ -355,6 +367,9 @@ depinclearmsg(mode?: 'all' | number): Promise<{
|
|
|
355
367
|
- No parameters: Remove only expired messages (default)
|
|
356
368
|
- `"all"`: Remove ALL messages from the pool
|
|
357
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)
|
|
358
373
|
|
|
359
374
|
**Examples:**
|
|
360
375
|
```javascript
|
|
@@ -366,9 +381,12 @@ const result = await rpc('depinclearmsg', ['all']);
|
|
|
366
381
|
|
|
367
382
|
// Remove older than 7 days
|
|
368
383
|
const result = await rpc('depinclearmsg', [168]);
|
|
384
|
+
|
|
385
|
+
// Remove everything in one section only
|
|
386
|
+
const result = await rpc('depinclearmsg', ['all', '&FRANCE/GENERAL']);
|
|
369
387
|
```
|
|
370
388
|
|
|
371
|
-
**Port:**
|
|
389
|
+
**Port:** standard RPC (19001/19101); over the gateway (19002) it requires an ADMIN challenge — see §3.2
|
|
372
390
|
|
|
373
391
|
---
|
|
374
392
|
|
|
@@ -416,7 +434,7 @@ const pool = await rpc('depingetpoolcontent', ['raw']);
|
|
|
416
434
|
const pool = await rpc('depingetpoolcontent', [false, 'NXsender...']);
|
|
417
435
|
```
|
|
418
436
|
|
|
419
|
-
**Port:**
|
|
437
|
+
**Port:** standard RPC (19001 mainnet / 19101 testnet)
|
|
420
438
|
**Note:** Recipient filtering does not work with ECIES shared encryption
|
|
421
439
|
|
|
422
440
|
---
|
|
@@ -451,7 +469,108 @@ depinpoolstats(): Promise<{
|
|
|
451
469
|
const stats = await rpc('depinpoolstats', []);
|
|
452
470
|
```
|
|
453
471
|
|
|
454
|
-
**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)
|
|
455
574
|
|
|
456
575
|
---
|
|
457
576
|
|
|
@@ -494,7 +613,7 @@ const status = await rpc('depinmcpstatus', []);
|
|
|
494
613
|
// }
|
|
495
614
|
```
|
|
496
615
|
|
|
497
|
-
**Port:**
|
|
616
|
+
**Port:** standard RPC (19001 mainnet / 19101 testnet)
|
|
498
617
|
**Note:** The MCP worker processes AI commands sent through the DePIN messaging system
|
|
499
618
|
|
|
500
619
|
---
|
|
@@ -532,40 +651,60 @@ The system uses ECIES (Elliptic Curve Integrated Encryption Scheme) with the fol
|
|
|
532
651
|
5. Decrypt: plaintext = AES-256-CBC-decrypt(ciphertext, encryption_key, iv)
|
|
533
652
|
```
|
|
534
653
|
|
|
535
|
-
### 3.2 Challenge/Response Authentication
|
|
654
|
+
### 3.2 Gateway Transport and Challenge/Response Authentication
|
|
536
655
|
|
|
537
|
-
|
|
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.
|
|
538
660
|
|
|
539
661
|
**Protocol:**
|
|
540
662
|
```
|
|
541
|
-
Client → Server: AUTH|<token>|<address>|<mode
|
|
542
|
-
mode = SEND | RECEIVE
|
|
543
|
-
|
|
544
|
-
Server → Client: CHALLENGE|<random_challenge>|<timeout_seconds
|
|
545
|
-
|
|
546
|
-
Client:
|
|
547
|
-
|
|
548
|
-
|
|
549
|
-
|
|
550
|
-
|
|
551
|
-
|
|
552
|
-
|
|
553
|
-
|
|
554
|
-
|
|
555
|
-
|
|
556
|
-
|
|
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
|
|
557
684
|
```
|
|
558
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
|
+
|
|
559
691
|
---
|
|
560
692
|
|
|
561
693
|
## 4. Wallet Web Implementation
|
|
562
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
|
+
|
|
563
702
|
### 4.1 Recommended DePINClient Class
|
|
564
703
|
|
|
565
704
|
```typescript
|
|
566
705
|
class DePINClient {
|
|
567
706
|
private rpcUrl: string;
|
|
568
|
-
private rpcPort: number =
|
|
707
|
+
private rpcPort: number = 19001;
|
|
569
708
|
private depinPort: number = 19002;
|
|
570
709
|
private username: string;
|
|
571
710
|
private password: string;
|
|
@@ -578,13 +717,13 @@ class DePINClient {
|
|
|
578
717
|
password: string;
|
|
579
718
|
}) {
|
|
580
719
|
this.rpcUrl = `http://${config.host}`;
|
|
581
|
-
this.rpcPort = config.rpcPort ||
|
|
720
|
+
this.rpcPort = config.rpcPort || 19001;
|
|
582
721
|
this.depinPort = config.depinPort || 19002;
|
|
583
722
|
this.username = config.username;
|
|
584
723
|
this.password = config.password;
|
|
585
724
|
}
|
|
586
725
|
|
|
587
|
-
// Standard RPC operations (port
|
|
726
|
+
// Standard RPC operations (standard RPC port)
|
|
588
727
|
async checkValidity(asset: string, address: string) {
|
|
589
728
|
return this.callRPC('checkdepinvalidity', [asset, address]);
|
|
590
729
|
}
|
|
@@ -602,7 +741,7 @@ class DePINClient {
|
|
|
602
741
|
return this.callRPC('depinpoolstats', []);
|
|
603
742
|
}
|
|
604
743
|
|
|
605
|
-
// Messaging operations (
|
|
744
|
+
// Messaging operations (the local node opens the TCP gateway connection)
|
|
606
745
|
async sendMessage(
|
|
607
746
|
token: string,
|
|
608
747
|
remoteHost: string,
|
|
@@ -754,7 +893,7 @@ async function verifyTokenOwnership(address: string, token: string) {
|
|
|
754
893
|
}
|
|
755
894
|
```
|
|
756
895
|
|
|
757
|
-
**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.
|
|
758
897
|
|
|
759
898
|
### 5.2 Key Management
|
|
760
899
|
|
|
@@ -799,17 +938,19 @@ To enable DePIN on the node:
|
|
|
799
938
|
# RPC Configuration
|
|
800
939
|
rpcuser=yourusername
|
|
801
940
|
rpcpassword=yourpassword
|
|
802
|
-
rpcport=
|
|
941
|
+
rpcport=19001 # 19101 on testnet
|
|
803
942
|
rpcallowip=127.0.0.1
|
|
804
943
|
rpcallowip=192.168.1.0/24
|
|
805
944
|
|
|
806
945
|
# DePIN Messaging
|
|
807
946
|
depinmsg=1
|
|
808
|
-
|
|
809
|
-
|
|
810
|
-
|
|
811
|
-
|
|
812
|
-
|
|
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
|
|
813
954
|
|
|
814
955
|
# Asset indexes (required for DePIN holder and pubkey discovery)
|
|
815
956
|
assetindex=1
|
|
@@ -820,16 +961,17 @@ pubkeyindex=1
|
|
|
820
961
|
|
|
821
962
|
# MCP/AI Worker (optional)
|
|
822
963
|
depinmcp=1
|
|
823
|
-
depinmcpurl=http://localhost:
|
|
824
|
-
|
|
825
|
-
|
|
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
|
|
826
968
|
```
|
|
827
969
|
|
|
828
970
|
### 6.2 Ports to Open
|
|
829
971
|
|
|
830
972
|
In your firewall/router:
|
|
831
|
-
- **
|
|
832
|
-
- **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`)
|
|
833
975
|
|
|
834
976
|
---
|
|
835
977
|
|
|
@@ -872,7 +1014,7 @@ async function testMessaging() {
|
|
|
872
1014
|
|
|
873
1015
|
// Send message
|
|
874
1016
|
const result = await client.sendMessage(
|
|
875
|
-
'FRANCE',
|
|
1017
|
+
'&FRANCE',
|
|
876
1018
|
'192.168.1.100:19002',
|
|
877
1019
|
'Test message',
|
|
878
1020
|
'NXyouraddr...'
|
|
@@ -880,7 +1022,7 @@ async function testMessaging() {
|
|
|
880
1022
|
console.log('Message sent:', result);
|
|
881
1023
|
|
|
882
1024
|
// Retrieve messages
|
|
883
|
-
const messages = await client.getMessages('FRANCE', 'NXyouraddr...');
|
|
1025
|
+
const messages = await client.getMessages('&FRANCE', 'NXyouraddr...');
|
|
884
1026
|
console.log('Messages:', messages);
|
|
885
1027
|
}
|
|
886
1028
|
```
|
|
@@ -905,7 +1047,8 @@ async function testMessaging() {
|
|
|
905
1047
|
Enable detailed logs in `neurai.conf`:
|
|
906
1048
|
|
|
907
1049
|
```ini
|
|
908
|
-
debug=
|
|
1050
|
+
debug=net # the DePIN gateway logs under the net category
|
|
1051
|
+
debug=mempool # the DePIN message pool logs under mempool
|
|
909
1052
|
debug=rpc
|
|
910
1053
|
```
|
|
911
1054
|
|
|
@@ -914,7 +1057,7 @@ debug=rpc
|
|
|
914
1057
|
## 9. References
|
|
915
1058
|
|
|
916
1059
|
- **Repository:** https://github.com/NeuraiProject/neurai-rpc
|
|
917
|
-
- **Version:** 0.
|
|
1060
|
+
- **Version:** 0.5.0
|
|
918
1061
|
- **RPC Documentation:** See `neurai_methods.md`
|
|
919
1062
|
- **DePIN source code:** `Neurai/src/rpc/messages.cpp`, `Neurai/src/rpc/assets.cpp`
|
|
920
1063
|
- **ECIES specification:** `Neurai/src/depinecies.cpp`
|
|
@@ -923,6 +1066,32 @@ debug=rpc
|
|
|
923
1066
|
|
|
924
1067
|
## 10. Changelog
|
|
925
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
|
+
|
|
926
1095
|
### v0.4.5 (December 2025)
|
|
927
1096
|
|
|
928
1097
|
**New commands added:**
|