@neuraiproject/neurai-rpc 0.4.7 → 0.5.1

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,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
- - **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
28
  There are two related but different concepts in the current DePIN stack:
25
29
 
26
- - **DePIN messaging token:** the asset configured in `depintoken` for gateway messaging. This can be any asset.
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 documented here as enabled for mainnet and testnet, require the owner token `&ASSET!`, and must be issued and reissued with `units=0`.
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:8766', 'username', 'password');
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:** 8766
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:** 8766
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:** 8766
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:** 8766
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:** 8766
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:** 8766
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:** 8766
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 the challenge with its private key
234
- 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)
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:** 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
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:** 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
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(mode?: 'all' | number): Promise<{
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:** 8766
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:** 8766
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:** 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)
455
574
 
456
575
  ---
457
576
 
@@ -494,7 +613,7 @@ const status = await rpc('depinmcpstatus', []);
494
613
  // }
495
614
  ```
496
615
 
497
- **Port:** 8766
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
- 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.
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
- 1. Sign challenge: signature = sign(sha256(challenge), privkey)
548
- 2. Prepare encrypted message
549
-
550
- Client → Server: SUBMIT|<signature>|<hex_encrypted_message>
551
-
552
- Server:
553
- 1. Verify signature with address pubkey
554
- 2. Verify token ownership
555
- 3. Validate and store message
556
- 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
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 = 8766;
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 || 8766;
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 8766)
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 (port 19002 for sending)
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:** For DePIN messaging, the token can be any asset. For the dedicated DePIN asset-management RPCs, use the `&ASSET` asset type.
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=8766
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
- depintoken=FRANCE
809
- depinport=19002
810
- depinmaxmessagesize=1024
811
- depinmessageexpiry=168 # 7 days in hours
812
- depinmaxpoolsize=100 # MB
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:8080
824
- depinmcpmodel=claude-3-sonnet
825
- 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
826
968
  ```
827
969
 
828
970
  ### 6.2 Ports to Open
829
971
 
830
972
  In your firewall/router:
831
- - **8766**: RPC (only localhost or trusted IPs)
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=depin
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.4.5
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:**