@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.
@@ -2,10 +2,14 @@
2
2
 
3
3
  ## Change Summary
4
4
 
5
- Thirteen new RPC commands have been added for Neurai's DePIN (Decentralized Physical Infrastructure Networks) system, grouped into three categories: DePIN asset management, encrypted messaging, and AI/MCP monitoring.
6
-
7
- **Version:** 0.4.5
8
- **Date:** December 2025
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
- - **Port 8766** (standard RPC): Asset management commands and queries
20
- - **Port 19002** (DePIN Server): Encrypted messaging and P2P operations
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
- DePIN assets are special tokens that:
25
- - **Can be any asset on the Neurai blockchain** (no specific prefix required)
26
- - Are **soulbound** (non-transferable except by the owner)
27
- - Can be frozen/revoked by the owner or self-revoked by the holder
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:8766', 'username', 'password');
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:** 8766
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:** 8766
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:** 8766
106
- **Requires:** Owner token `FRANCE!` in the wallet
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:** 8766
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:** 8766
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:** 8766
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 the challenge with its private key
209
- 5. Client sends: `SUBMIT|<signature>|<encrypted_message>`
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:** 8766 (RPC), connects to remote node port 19002
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:** 8766 (for local queries), 19002 (for remote queries)
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(mode?: 'all' | number): Promise<{
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:** 8766
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:** 8766
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:** 8766
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:** 8766
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
- For remote operations (depinsendmsg):
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
- 1. Sign challenge: signature = sign(sha256(challenge), privkey)
523
- 2. Prepare encrypted message
524
-
525
- Client → Server: SUBMIT|<signature>|<hex_encrypted_message>
526
-
527
- Server:
528
- 1. Verify signature with address pubkey
529
- 2. Verify token ownership
530
- 3. Validate and store message
531
- 4. Return confirmation
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 = 8766;
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 || 8766;
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 8766)
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 (port 19002 for sending)
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:** The token can be any asset on the Neurai blockchain; no special prefix is required.
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=8766
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
- depintoken=FRANCE
784
- depinport=19002
785
- depinmaxmessagesize=1024
786
- depinmessageexpiry=168 # 7 days in hours
787
- depinmaxpoolsize=100 # MB
788
-
789
- # Asset Index (required for listdepinholders)
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:8080
795
- depinmcpmodel=claude-3-sonnet
796
- depinmcpkey=/ai
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
- - **8766**: RPC (only localhost or trusted IPs)
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=depin
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.4.5
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:**