@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 CHANGED
@@ -5,18 +5,97 @@ All notable changes to this project will be documented in this file.
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6
6
  and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
 
8
+ ## [0.5.0] - 2026-08-01
9
+
10
+ ### Breaking — DePIN client rewritten for the gateway's real protocol
11
+
12
+ The DePIN messaging gateway (port 19002) speaks a raw TCP line protocol, not
13
+ HTTP. The previous `fetch`-based client could never talk to a real node, so
14
+ the client was rewritten:
15
+
16
+ - **Transport**: raw TCP via `node:net` — one request line terminated by `\n`
17
+ per connection, response read up to `\n`, 30 s timeout (matches the node's
18
+ `DEPIN_SOCKET_TIMEOUT`), safe handling of fragmented and multibyte
19
+ responses.
20
+ - **Node.js-only entry**: the DePIN client moved to the subpath
21
+ `@neuraiproject/neurai-rpc/depin`, and is no longer re-exported from the
22
+ package root, which stays free of Node built-ins and browser-safe.
23
+ Migrate imports:
24
+ `import { getDePinRPC } from "@neuraiproject/neurai-rpc/depin"`.
25
+ - **Constructor**: `getDePinRPC({ host, port }, authOptions?)` — URL strings
26
+ are rejected. Auth options are now optional: without them the client serves
27
+ the gateway's unauthenticated methods and fails clearly on authenticated
28
+ ones.
29
+ - **Correct per-method authentication** (the old client applied one generic
30
+ flow to every method, which the gateway rejects):
31
+ - `depinsendmsg` — SEND challenge, signs `DEPIN-SEND|token|address|challenge`,
32
+ appends challenge/signature (gateway validates and trims them).
33
+ - `depinclearmsg` — ADMIN challenge (owner only), signs
34
+ `DEPIN-CLEAR|token|address|challenge`, sends
35
+ `[mode, (scope,) address, challenge, signature]`; with a scope the
36
+ challenge is requested for that scope token.
37
+ - RECEIVE challenges now sign `DEPIN-GET|…` (the old `DEPIN-RECEIVE|…` was
38
+ never accepted by the node).
39
+ - Unauthenticated gateway methods (`depinreceivemsg`, `depinsubmitmsg`,
40
+ `depingetmsginfo`, `depingetpoolcontent`, `depinpoolstats`,
41
+ `depinmcpstatus`, `depinlistsections`, `depinpoolpkey`) are sent with
42
+ their params untouched.
43
+ - `depingetmsg` over the gateway is rejected with a clear error: it is
44
+ blocked by a node-side bug (the gateway reads `fromaddress` from
45
+ `params[3]`, where this method carries it at index 1 or 2). Use
46
+ `depinreceivemsg` or the standard RPC port.
47
+ - Challenges are single-use on the node (the nonce is consumed on
48
+ validation), so the client requests a fresh challenge for every
49
+ authenticated call — never cached or reused — with one automatic retry
50
+ (new nonce) on expiration.
51
+ - `DePinAuthOptions.mode` is only honored by `requestDePinChallenge()`
52
+ (`"SEND" | "RECEIVE" | "ADMIN"`); `getDePinRPC` derives the challenge type
53
+ per method and rejects a conflicting override.
54
+
55
+ ### Added
56
+
57
+ - New RPC methods in the catalog (node from July 2026, except where noted):
58
+ - `depinreceivemsg` - Retrieve pool messages with pagination (`after_hash`, `limit`)
59
+ - `depingetancestorrecipients` - Active holders of a DEPIN branch with revealed pubkeys
60
+ - `depinlistsections` - Hierarchical DePIN sections
61
+ - `depinpoolpkey` - DePIN pool public key
62
+ - `dumpextkeypq` - Master post-quantum extended private key (PQ wallet build)
63
+ - `exportxpqpub` - Batch of ML-DSA-44 public keys (PQ wallet build)
64
+ - Node compatibility notes in the README.
65
+
66
+ ### Fixed
67
+
68
+ - `getRPC` now rejects JSON-RPC errors that arrive with HTTP 200 (previously
69
+ it resolved `undefined`, silently swallowing the error object).
70
+
71
+ ### Changed
72
+
73
+ - `docs.json` fully re-synchronized against a node at today's HEAD: 61
74
+ existing entries refreshed, including `depinclearmsg` (new `scope`
75
+ parameter), `createrawtransaction` (new `refinputs` parameter, NIP-014 v3
76
+ transactions, node from April 2026) and `getaddressdeltas` (wildcard `*`
77
+ asset name).
78
+ - Build switched from parcel to tsup with two entries (`.` and `./depin`),
79
+ each shipping ESM (`.mjs`), CJS (`.cjs`) and type declarations; `exports`
80
+ map rewritten with `types`/`import`/`require` conditions per entry.
81
+ - Dropped the now-unused parcel toolchain and `buffer` polyfill from
82
+ devDependencies and pinned esbuild to a patched version via `overrides` —
83
+ `npm audit` reports 0 vulnerabilities.
84
+ - `files` whitelist added to `package.json` (internal working notes and tests
85
+ are no longer published).
86
+ - Fixed the `create-docs` npm script (`node createDocs.mjs`).
87
+
8
88
  ## [0.4.6] - 2025-12-10
9
89
 
10
90
  ### Fixed
11
- - **IMPORTANT**: Removed an incorrect restriction that required DePIN assets to start with `&`.
12
- - The Neurai DePIN system can operate with **any asset** on the blockchain.
13
- - Documentation updated in `docs.json`, `docs.ts`, `DEPIN_IMPLEMENTATION_GUIDE.md`, and `neurai_methods.md`.
14
- - Examples that showed tokens requiring the `&` prefix were corrected.
15
- - Affected commands: `checkdepinvalidity`, `listdepinholders`, `freezedepin`, `unfreezedepin`, `selfrevokedepin`.
91
+ - Clarified the DePIN documentation to distinguish between:
92
+ - the messaging token configured in `depintoken`, which can be any asset
93
+ - the dedicated DePIN asset type used by asset-management RPCs, which uses the `&` prefix in current core
94
+ - Corrected examples for the dedicated DePIN asset-management RPCs.
16
95
 
17
96
  ### Changed
18
- - Updated owner token example from `&ASSET!` to `ASSET!` in the documentation.
19
- - Updated the technical implementation guide (`DEPIN_IMPLEMENTATION_GUIDE.md`) to reflect that any asset can be used.
97
+ - Documented the dedicated DePIN asset behavior for package consumers as enabled on mainnet and testnet, with `units=0` on issue/reissue.
98
+ - Added missing RPC documentation for `listdepinaddresses` and `listpqaddresses`.
20
99
 
21
100
  ## [0.4.5] - 2025-12-09
22
101
 
@@ -78,28 +157,31 @@ See repository commits for the full history of changes.
78
157
 
79
158
  ### From 0.4.5 to 0.4.6
80
159
 
81
- **IMPORTANT**: If you were validating that DePIN tokens start with `&` in your code:
160
+ **IMPORTANT**: Distinguish between DePIN messaging tokens and dedicated DePIN assets:
82
161
 
83
- ❌ **Incorrect (old code):**
162
+ ❌ **Incorrect (treating them as the same thing):**
84
163
  ```javascript
85
- if (!token.startsWith('&')) {
86
- throw new Error('Token must start with &');
87
- }
164
+ const token = 'FRANCE';
165
+ await rpc('checkdepinvalidity', [token, address]);
88
166
  ```
89
167
 
90
168
  ✅ **Correct (0.4.6+):**
91
169
  ```javascript
92
- // DePIN tokens can be any asset on the blockchain
93
- // Do not validate by prefix; use checkdepinvalidity instead
94
- const validity = await rpc('checkdepinvalidity', [token, address]);
170
+ const messagingToken = 'FRANCE';
171
+ const depinAsset = '&FRANCE';
172
+
173
+ // Messaging token for depinmsg can be any asset.
174
+ // Dedicated DePIN asset-management commands use the &-prefixed DePIN asset type.
175
+ const validity = await rpc('checkdepinvalidity', [depinAsset, address]);
95
176
  if (!validity.has_asset || validity.valid === 0) {
96
- throw new Error('Invalid DePIN token for this address');
177
+ throw new Error('Invalid DePIN asset for this address');
97
178
  }
98
179
  ```
99
180
 
100
181
  **Updated examples:**
101
- - `&FRANCE` → may be `FRANCE`, `&FRANCE`, or any other asset
102
- - Owner token: `&ASSET!` → `ASSET!` (no mandatory prefix)
182
+ - Messaging token: `FRANCE` can still be any asset
183
+ - Dedicated DePIN asset: `&FRANCE`
184
+ - Owner token for a dedicated DePIN asset: `&FRANCE!`
103
185
 
104
186
  ### Node configuration
105
187
 
@@ -108,14 +190,15 @@ Ensure the following in `neurai.conf`:
108
190
  ```ini
109
191
  # DePIN Messaging
110
192
  depinmsg=1
111
- depintoken=YOUR_TOKEN_HERE # Any valid asset
193
+ depintoken=YOUR_TOKEN_HERE # Messaging token, can be any valid asset
112
194
  depinport=19002
113
195
  depinmaxmessagesize=1024
114
196
  depinmessageexpiry=168
115
197
  depinmaxpoolsize=100
116
198
 
117
- # Asset Index (required for listdepinholders)
199
+ # Asset indexes (required for listdepinholders/listdepinaddresses)
118
200
  assetindex=1
201
+ pubkeyindex=1
119
202
  ```
120
203
 
121
204
  ---
package/DEPIN_EXAMPLES.md CHANGED
@@ -1,271 +1,199 @@
1
1
  # DePIN RPC Examples
2
2
 
3
- This file demonstrates how to use the DePIN messaging functionality in neurai-rpc.
3
+ Practical examples for the DePIN messaging client in
4
+ `@neuraiproject/neurai-rpc`.
5
+
6
+ > **Node.js only.** The DePIN gateway (default port 19002) speaks a raw TCP
7
+ > line protocol — not HTTP — so this client uses `node:net` sockets and lives
8
+ > in its own package entry. Browsers cannot open raw TCP connections; from a
9
+ > browser, talk to the node's standard HTTP RPC port instead (see
10
+ > `DEPIN_IMPLEMENTATION_GUIDE_EN.md` §4), or put an HTTP/WebSocket proxy in
11
+ > front of the gateway.
4
12
 
5
13
  ## Basic Setup
6
14
 
7
15
  ```javascript
8
- import { getDePinRPC } from "@neuraiproject/neurai-rpc";
9
-
10
- // You need a function that can sign messages with your Neurai address
11
- // This example uses neurai-cli via the standard RPC
12
16
  import { getRPC, methods } from "@neuraiproject/neurai-rpc";
17
+ import { getDePinRPC } from "@neuraiproject/neurai-rpc/depin";
13
18
 
19
+ // Standard RPC (HTTP) — works in Node.js and browsers
14
20
  const standardRpc = getRPC("user", "password", "http://localhost:19001");
15
21
 
16
- async function signMessage(message) {
17
- // Sign using neurai-cli via RPC
18
- return await standardRpc(methods.signmessage, ["NXyouraddress...", message]);
19
- }
22
+ // DePIN gateway (raw TCP) — Node.js only
23
+ const depinRpc = getDePinRPC(
24
+ { host: "127.0.0.1", port: 19002 },
25
+ {
26
+ token: "&FRANCE",
27
+ address: "NXyouraddress...",
28
+ signMessage: async (message) => {
29
+ // Sign with the standard RPC (wallet must hold the address key),
30
+ // or with any other wallet integration that returns base64.
31
+ return await standardRpc(methods.signmessage, [
32
+ "NXyouraddress...",
33
+ message,
34
+ ]);
35
+ },
36
+ }
37
+ );
38
+ ```
39
+
40
+ The second argument is optional: without auth options the client can still
41
+ call every gateway method that the server serves without authentication
42
+ (`depinreceivemsg`, `depinsubmitmsg`, `depingetmsginfo`, `depingetpoolcontent`,
43
+ `depinpoolstats`, `depinmcpstatus`, `depinlistsections`, `depinpoolpkey`).
20
44
 
21
- // Create DePIN RPC client
22
- const depinRpc = getDePinRPC("http://localhost:19002", {
23
- token: "MYTOKEN",
24
- address: "NXyouraddress...",
25
- signMessage: signMessage,
26
- mode: "SEND"
27
- });
45
+ ```javascript
46
+ const publicRpc = getDePinRPC({ host: "127.0.0.1", port: 19002 });
47
+ const info = await publicRpc("depingetmsginfo", []);
28
48
  ```
29
49
 
30
50
  ## Example 1: Send a DePIN Message
31
51
 
52
+ `depinsendmsg` needs a SEND challenge. The client requests it, signs
53
+ `DEPIN-SEND|token|address|challenge` with your `signMessage`, appends
54
+ challenge and signature where the gateway expects them, and retries once
55
+ automatically if the challenge expired.
56
+
32
57
  ```javascript
33
- import { getDePinRPC } from "@neuraiproject/neurai-rpc";
34
-
35
- async function sendDePinMessage() {
36
- const depinRpc = getDePinRPC("http://localhost:19002", {
37
- token: "MYTOKEN",
38
- address: "NXsenderAddress...",
39
- signMessage: async (msg) => {
40
- // Use your signing method
41
- return await yourWallet.signMessage(msg);
42
- },
43
- mode: "SEND"
44
- });
45
-
46
- try {
47
- const result = await depinRpc("depinsendmsg", [
48
- "MYTOKEN", // token
49
- "localhost", // server (use "localhost" for local pool)
50
- "Hello DePIN!", // message
51
- "NXsenderAddress..." // from address
52
- ]);
53
-
54
- console.log("Message sent successfully:", result);
55
- } catch (error) {
56
- console.error("Failed to send message:", error);
57
- }
58
- }
58
+ const result = await depinRpc("depinsendmsg", [
59
+ "&FRANCE", // token
60
+ "192.168.1.100:19002", // destination gateway ip[:port]
61
+ "Hello team!", // message
62
+ "NXyouraddress...", // fromaddress — must be the authenticated address
63
+ ]);
64
+ console.log(result);
59
65
  ```
60
66
 
61
- ## Example 2: Retrieve DePIN Messages
67
+ If you omit `fromaddress` (3 params), the client fills it in with the
68
+ authenticated address.
69
+
70
+ ## Example 2: Retrieve Messages with Pagination
71
+
72
+ `depinreceivemsg` is served without authentication and supports pagination
73
+ (node from July 2026+):
62
74
 
63
75
  ```javascript
64
- import { getDePinRPC } from "@neuraiproject/neurai-rpc";
65
-
66
- async function getDePinMessages() {
67
- const depinRpc = getDePinRPC("http://localhost:19002", {
68
- token: "MYTOKEN",
69
- address: "NXreceiverAddress...",
70
- signMessage: async (msg) => {
71
- return await yourWallet.signMessage(msg);
72
- },
73
- mode: "RECEIVE"
74
- });
75
-
76
- try {
77
- const messages = await depinRpc("depingetmsg", [
78
- "MYTOKEN", // token
79
- "localhost", // server or address
80
- "NXreceiverAddress..." // your address
81
- ]);
82
-
83
- console.log("Received messages:", messages);
84
-
85
- messages.forEach(msg => {
86
- console.log(`From: ${msg.sender}`);
87
- console.log(`Message: ${msg.message}`);
88
- console.log(`Time: ${new Date(msg.timestamp * 1000).toLocaleString()}`);
89
- });
90
- } catch (error) {
91
- console.error("Failed to get messages:", error);
92
- }
76
+ // Everything for the address
77
+ const all = await depinRpc("depinreceivemsg", ["&FRANCE", "NXyouraddress..."]);
78
+
79
+ // Pages of 50, resuming after the last received hash
80
+ let afterHash = "";
81
+ while (true) {
82
+ const page = await depinRpc("depinreceivemsg", [
83
+ "&FRANCE",
84
+ "NXyouraddress...",
85
+ 0, // timestamp filter (0 = no filter)
86
+ afterHash, // "" starts from the beginning
87
+ 50, // limit
88
+ ]);
89
+ if (!page || page.length === 0) break;
90
+ process(page);
91
+ afterHash = page[page.length - 1].hash;
93
92
  }
94
93
  ```
95
94
 
96
- ## Example 3: Submit Pre-encrypted Message
95
+ > `depingetmsg` over the gateway is currently blocked by a node-side bug and
96
+ > the client rejects it with a clear error. Use `depinreceivemsg` (above), or
97
+ > call `depingetmsg` through the standard RPC port:
98
+ > `standardRpc(methods.depingetmsg, ["&FRANCE"])`.
99
+
100
+ ## Example 3: Submit a Pre-encrypted Message
97
101
 
98
102
  ```javascript
99
- import { getDePinRPC } from "@neuraiproject/neurai-rpc";
100
-
101
- async function submitPreEncryptedMessage() {
102
- const depinRpc = getDePinRPC("http://localhost:19002", {
103
- token: "MYTOKEN",
104
- address: "NXsenderAddress...",
105
- signMessage: async (msg) => {
106
- return await yourWallet.signMessage(msg);
107
- },
108
- mode: "SEND"
109
- });
110
-
111
- try {
112
- // Assume you have a pre-encrypted and signed message in hex format
113
- const hexMessage = "0a1b2c3d..."; // Your encrypted message hex
114
-
115
- const result = await depinRpc("depinsubmitmsg", [hexMessage]);
116
-
117
- console.log("Pre-encrypted message submitted:", result);
118
- } catch (error) {
119
- console.error("Failed to submit message:", error);
120
- }
121
- }
103
+ const result = await depinRpc("depinsubmitmsg", [
104
+ "48656c6c6f...", // hex-encoded encrypted message
105
+ ]);
122
106
  ```
123
107
 
124
- ## Example 4: Using with Browser Wallet
108
+ ## Example 4: Clear Messages (ADMIN, owner only)
109
+
110
+ `depinclearmsg` over the gateway requires an ADMIN challenge signed as
111
+ `DEPIN-CLEAR|token|address|challenge` by an owner of the token (or of an
112
+ ancestor). The client inserts your address into the parameters the way the
113
+ gateway expects — you only pass the mode and optional scope:
125
114
 
126
115
  ```javascript
127
- import { getDePinRPC } from "@neuraiproject/neurai-rpc";
116
+ // Remove expired messages
117
+ await depinRpc("depinclearmsg", []);
128
118
 
129
- // Example with a hypothetical browser wallet extension
130
- async function useBrowserWallet() {
131
- // Check if wallet is available
132
- if (!window.neuraiWallet) {
133
- throw new Error("Neurai wallet extension not found");
134
- }
119
+ // Remove ALL messages
120
+ await depinRpc("depinclearmsg", ["all"]);
135
121
 
136
- // Request wallet connection
137
- const accounts = await window.neuraiWallet.connect();
138
- const address = accounts[0];
139
-
140
- // Create DePIN RPC client with wallet signing
141
- const depinRpc = getDePinRPC("http://localhost:19002", {
142
- token: "MYTOKEN",
143
- address: address,
144
- signMessage: async (msg) => {
145
- // Use wallet extension to sign
146
- return await window.neuraiWallet.signMessage(address, msg);
147
- },
148
- mode: "SEND"
149
- });
150
-
151
- // Send message
152
- const result = await depinRpc("depinsendmsg", [
153
- "MYTOKEN",
154
- "localhost",
155
- "Hello from browser!",
156
- address
157
- ]);
122
+ // Remove messages older than 7 days
123
+ await depinRpc("depinclearmsg", [168]);
158
124
 
159
- console.log("Message sent:", result);
160
- }
125
+ // Restrict the purge to one section's subtree — the ADMIN challenge is
126
+ // requested for that scope automatically
127
+ await depinRpc("depinclearmsg", ["all", "&FRANCE/GENERAL"]);
161
128
  ```
162
129
 
163
- ## Example 5: Manual Challenge Handling
130
+ ## Example 5: Sections and Branch Holders
164
131
 
165
132
  ```javascript
166
- import { requestDePinChallenge } from "@neuraiproject/neurai-rpc";
167
-
168
- async function manualChallengeFlow() {
169
- // Request a challenge manually
170
- const challengeData = await requestDePinChallenge("http://localhost:19002", {
171
- token: "MYTOKEN",
172
- address: "NXyourAddress...",
173
- signMessage: async () => "", // Not used in requestChallenge
174
- mode: "SEND"
175
- });
176
-
177
- console.log("Challenge:", challengeData.challenge);
178
- console.log("Expires in:", challengeData.timeout, "seconds");
179
- console.log("Message to sign:", challengeData.messageToSign);
180
-
181
- // Now you can sign this message manually
182
- const signature = await yourSigningFunction(challengeData.messageToSign);
183
-
184
- console.log("Signature:", signature);
185
- }
133
+ // Section names (full address mode needs the standard RPC port)
134
+ const sections = await depinRpc("depinlistsections", []);
135
+
136
+ // Active holders of a branch with their revealed pubkeys (standard RPC port)
137
+ const holders = await standardRpc(methods.depingetancestorrecipients, [
138
+ "&FRANCE/PARIS",
139
+ ]);
186
140
  ```
187
141
 
188
- ## Example 6: Error Handling
142
+ ## Example 6: Manual Challenge Handling
189
143
 
190
144
  ```javascript
191
- import { getDePinRPC } from "@neuraiproject/neurai-rpc";
192
-
193
- async function robustDePinCall() {
194
- const depinRpc = getDePinRPC("http://localhost:19002", {
195
- token: "MYTOKEN",
196
- address: "NXyourAddress...",
197
- signMessage: async (msg) => {
198
- try {
199
- return await yourWallet.signMessage(msg);
200
- } catch (error) {
201
- throw new Error(`Signing failed: ${error.message}`);
202
- }
203
- },
204
- mode: "SEND"
205
- });
206
-
207
- try {
208
- const result = await depinRpc("depinsendmsg", [
209
- "MYTOKEN",
210
- "localhost",
211
- "Test message",
212
- "NXyourAddress..."
213
- ]);
214
-
215
- return { success: true, result };
216
- } catch (error) {
217
- // Handle different error types
218
- if (error.type === 'DePinRequestError') {
219
- console.error("DePIN request failed:", error.error);
220
- console.error("Description:", error.description);
221
- } else if (error.error?.message?.includes('challenge')) {
222
- console.error("Challenge error:", error.error.message);
223
- } else if (error.error?.message?.includes('signature')) {
224
- console.error("Signature verification failed");
225
- } else {
226
- console.error("Unknown error:", error);
227
- }
228
-
229
- return { success: false, error: error.error };
145
+ import { requestDePinChallenge } from "@neuraiproject/neurai-rpc/depin";
146
+
147
+ const challengeData = await requestDePinChallenge(
148
+ { host: "127.0.0.1", port: 19002 },
149
+ {
150
+ token: "&FRANCE",
151
+ address: "NXyouraddress...",
152
+ signMessage: async (m) => "unused-here",
153
+ mode: "SEND", // "SEND" | "RECEIVE" | "ADMIN" (default "RECEIVE")
230
154
  }
231
- }
155
+ );
156
+
157
+ console.log(challengeData.challenge); // random challenge from the server
158
+ console.log(challengeData.timeout); // seconds until it expires
159
+ console.log(challengeData.messageToSign); // e.g. "DEPIN-SEND|&FRANCE|NX...|abc123"
232
160
  ```
233
161
 
234
- ## Example 7: Connecting to Remote DePIN Node
162
+ Note: `mode` is only honored here. `getDePinRPC` derives the challenge type
163
+ from the method being called and rejects a conflicting `mode` in its auth
164
+ options.
235
165
 
236
- ```javascript
237
- import { getDePinRPC } from "@neuraiproject/neurai-rpc";
238
-
239
- async function connectToRemoteNode() {
240
- const depinRpc = getDePinRPC("http://remote-node.example.com:19002", {
241
- token: "MYTOKEN",
242
- address: "NXyourAddress...",
243
- signMessage: async (msg) => {
244
- return await yourWallet.signMessage(msg);
245
- },
246
- mode: "SEND"
247
- });
248
-
249
- // The library handles challenge/response automatically
250
- const result = await depinRpc("depinsendmsg", [
251
- "MYTOKEN",
252
- "remote-node.example.com:19002",
253
- "Hello remote node!",
254
- "NXyourAddress..."
255
- ]);
166
+ ## Example 7: Error Handling
256
167
 
257
- console.log("Sent to remote node:", result);
168
+ ```javascript
169
+ try {
170
+ await depinRpc("depinsendmsg", ["&FRANCE", "10.0.0.1", "hi", "NXaddr..."]);
171
+ } catch (e) {
172
+ if (e.type === "DePinRequestError") {
173
+ // Transport problem: gateway unreachable, timeout, connection closed…
174
+ console.error("Transport:", e.error);
175
+ } else if (e.error) {
176
+ // JSON-RPC error from the gateway/node
177
+ console.error("RPC:", e.description);
178
+ }
258
179
  }
259
180
  ```
260
181
 
261
- ## Notes
262
-
263
- 1. **Challenge Expiry**: Challenges expire after 60 seconds. The library automatically handles expiry and retries with a new challenge.
182
+ The client raises a clear error, without touching the network, when:
264
183
 
265
- 2. **Signature Format**: The signature must be in base64 format as returned by Neurai's `signmessage` RPC command.
184
+ - the target is not `{ host, port }` (URL strings are rejected),
185
+ - an authenticated method is called on a client built without auth options,
186
+ - `depingetmsg` is attempted over the gateway (node-side bug, see README),
187
+ - `fromaddress` in `depinsendmsg` differs from the authenticated address.
266
188
 
267
- 3. **Mode Selection**: Use `mode: "SEND"` for `depinsendmsg` and `depinsubmitmsg`, and `mode: "RECEIVE"` for `depingetmsg`.
268
-
269
- 4. **Port**: DePIN messaging uses port 19002 by default (configurable via `-depinmsgport`).
189
+ ## Notes
270
190
 
271
- 5. **Token Requirement**: You must hold the specified DePIN token to send or receive messages.
191
+ - One TCP connection per request; the request is a single line terminated by
192
+ `\n` and the response is read up to the first `\n` (30 s timeout, matching
193
+ the node's `DEPIN_SOCKET_TIMEOUT`).
194
+ - Challenges are single-use — the node consumes the nonce when it validates
195
+ it — so the client requests a fresh challenge for every authenticated call;
196
+ an expired-challenge error triggers one automatic retry (with a new nonce).
197
+ - The messaging token (`-depinmsgtoken`) must be a dedicated `&ASSET` DePIN
198
+ asset (soulbound, `units=0`), currently testnet/regtest only in the node —
199
+ the same type the DePIN asset RPCs operate on.