@neuraiproject/neurai-rpc 0.7.0 → 0.9.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
@@ -1,3 +1,14 @@
1
+ # 0.9.0
2
+
3
+ - Follow the node's RBF removal (no-RBF sequence rule): drop `bumpfee` from the method catalog, drop the `replaceable` argument from `sendtoaddress` / `sendfromaddress` / `sendmany` and the `bip125-replaceable` field from `gettransaction` / `listtransactions` / `listsinceblock`, and document the allowed `createrawtransaction` sequences.
4
+ - Sync `docs.json` with the `help` output of a node built from Neurai `c665ba3`. New methods in the catalog: NIP-048 reward plans (`getdistributionplan`, `getdistributionproof`, `getdistributionbatches`, `verifydistribution`, `createdistributionbatch`, `getsnapshotannouncement`, `replaysnapshot`, `getsnapshotrecipients`), `getchannelmessages`, the DEPIN transfer state (`opendepin`, `closedepin`, `sealdepin`), the privacy pool reads (`getprivacypoolinfo`, `getprivacypoolupdates`) and NIP-047 silent payments (`getsilentpaymenttweaks`, `getsilentpaymenttweaksrange`, `getsilentpaymentindexinfo` and the wallet calls). 24 existing entries refreshed. The rewritten `depin*` contracts and the `validateaddress` AuthScript fields are kept.
5
+
6
+ # 0.8.0
7
+
8
+ - Add RPC 5 messaging requests, sequence cursors, response types and exact pool/instance routing.
9
+ - Replace removed local signers with depinsignrpc in the catalog; keep wallet helpers out of relay whitelists.
10
+ - Update messaging examples and migration guidance for Legacy/ECDSA and ECIES 2.
11
+
1
12
  # Changelog
2
13
 
3
14
  All notable changes to this project will be documented in this file.
package/DEPIN_EXAMPLES.md CHANGED
@@ -1,127 +1,45 @@
1
- # DePIN protocol 2 examples
2
-
3
- All calls use the normal authenticated HTTP JSON-RPC endpoint.
4
-
5
- ```js
6
- import { getRPC, methods } from "@neuraiproject/neurai-rpc";
7
-
8
- const rpc = getRPC("username", "password", "http://127.0.0.1:19001");
9
- const address = "NXholder...";
10
- const token = "&FRANCE/GENERAL";
11
- ```
12
-
13
- ## Pool information
14
-
15
- ```js
16
- const info = await rpc(methods.depingetmsginfo, []);
17
- const stats = await rpc(methods.depinpoolstats, []);
18
- ```
19
-
20
- Pin `info.depinpoolpkey` on first use. Use it to verify pool signatures and to
21
- encrypt envelopes submitted through `depinsubmitmsg`.
22
-
23
- ## Send with the local wallet
24
-
25
- ```js
26
- const result = await rpc(methods.depinsendmsg, [
27
- token,
28
- "Hello team!",
29
- "NXsender...",
30
- ]);
31
- ```
32
-
33
- `fromaddress` must belong to the node wallet. For a non-custodial remote
34
- client, prepare and sign the message client-side, encrypt its serialized form
35
- for `depingetmsginfo.depinpoolpkey`, and call:
36
-
37
- ```js
38
- await rpc(methods.depinsubmitmsg, [{
39
- sender: "NXsender...",
40
- encrypted: "<ECIES envelope hex>",
41
- }]);
42
- ```
43
-
44
- ## Obtain a receive challenge
45
-
46
- ```js
47
- const requestProof = await rpc(methods.depinsignrequest, [
48
- address,
49
- token,
50
- "receive",
51
- ]);
52
-
53
- const challengeReply = await rpc(methods.depinchallenge, [
54
- token,
55
- address,
56
- requestProof.timestamp,
57
- requestProof.signature,
58
- "receive",
59
- ]);
60
-
61
- // Verify challengeReply.poolsig against the pinned pool key first.
62
- const challengeBody = await rpc(methods.depindecrypt, [
63
- address,
64
- challengeReply.encrypted,
65
- ]);
66
-
67
- const challengeProof = await rpc(methods.depinsignchallenge, [
68
- address,
69
- token,
70
- challengeBody.challenge,
71
- "receive",
72
- ]);
73
- ```
74
-
75
- ## Receive messages
76
-
77
- ```js
78
- const encryptedPage = await rpc(methods.depinreceivemsg, [
79
- token,
80
- address,
81
- challengeBody.challenge,
82
- challengeProof.signature,
83
- 0,
84
- "",
85
- 50,
86
- ]);
87
-
88
- // Verify encryptedPage.poolsig first.
89
- const page = await rpc(methods.depindecrypt, [address, encryptedPage.encrypted]);
90
- console.log(page.messages);
91
- ```
92
-
93
- The decrypted response can contain `next_challenge`. Sign it for the next page
94
- instead of requesting a new challenge.
95
-
96
- ## List sections
97
-
98
- ```js
99
- const publicSections = await rpc(methods.depinlistsections, []);
100
-
101
- const encryptedSections = await rpc(methods.depinlistsections, [
102
- address,
103
- token,
104
- challengeBody.challenge,
105
- challengeProof.signature,
106
- ]);
107
- ```
108
-
109
- Challenges are single-use. Obtain a fresh one if a previous call consumed it.
110
-
111
- ## Clear messages as an owner
112
-
113
- Repeat the challenge flow with type `admin`, then call:
114
-
115
- ```js
116
- await rpc(methods.depinclearmsg, [
117
- token,
118
- "NXowner...",
119
- adminChallenge,
120
- adminSignature,
121
- "all",
122
- ]);
123
- ```
124
-
125
- Use an empty scope for the configured pool root. Omit the final mode to remove
126
- expired messages, use `"all"` for every message, or pass an age in hours. The
127
- challenge must have been issued for exactly the same scope.
1
+ # DePIN RPC 5 examples
2
+
3
+ The messaging SDK implements the binary signing contract. A generic transport call alone does not authenticate a pool reply.
4
+
5
+ ```js
6
+ import {getRPC} from '@neuraiproject/neurai-rpc';
7
+ import {getDepinPoolInfo, createSoftwareIdentity, buildDepinMessageForPool,
8
+ submitDepinMessage, requestDepinChallenge, receiveDepinMessages, callDepinRpc}
9
+ from '@neuraiproject/neurai-depin-msg';
10
+
11
+ const rpc = {call: getRPC(user, password, endpoint)};
12
+ const pool = await getDepinPoolInfo({rpc, serviceId: endpoint, network: 'test',
13
+ trust: storedPin ? {mode: 'pinned', pin: storedPin} : {mode: 'tofu'}});
14
+ const identity = await createSoftwareIdentity({privateKey: wif, network: 'test', address});
15
+ let context = pool.context;
16
+ const built = await buildDepinMessageForPool({rpc, context, identity, network: 'test',
17
+ token: '&GROUP/CHAT', poolRoot: pool.info.token, maxRecipients: pool.info.maxrecipients,
18
+ maxMessageBytes: pool.info.maxmessagesize, messageType: 'group', message: 'Hello',
19
+ timestamp: Math.floor(Date.now()/1000)});
20
+ context = built.context;
21
+ await submitDepinMessage({rpc, context, identity, messageHex: built.hex});
22
+ const issued = await requestDepinChallenge({rpc, context, identity, token: '&GROUP/CHAT'});
23
+ const page = await receiveDepinMessages({rpc, context: issued.context, identity,
24
+ token: '&GROUP/CHAT', challenge: issued.challenge, network: 'test', cursor: null, limit: 100});
25
+ context = page.context;
26
+ // Display only entries with ok === true and a non-null plaintext.
27
+ // Continue serially with page.cursor and page.nextChallenge.
28
+ const stats = await callDepinRpc({rpc, context, method: 'depinpoolstats'});
29
+ ```
30
+
31
+ Common request fields are `protocol`, `network`, `pool_pubkey`, `pool_root`, `instance_id`, `membership_revision`, `request_id`, `timestamp_ms`, `token`, `address`, `challenge`, `args`, `signature`. Bootstrap uses only `protocol:5`, `request_id` and `timestamp_ms`.
32
+
33
+ | Method | `args` | Authentication |
34
+ | --- | --- | --- |
35
+ | `depingetmsginfo` | Bootstrap has no `args` | Public, locally bound bootstrap request |
36
+ | `depinpoolstats`, `depinmcpstatus` | `{}` | Public, root token and blank auth fields |
37
+ | `depingetancestorrecipients` | `{max_results?, stop_at?}` | Public, queried token |
38
+ | `depinchallenge` | `{type:'receive'}` or `{type:'admin'}` | Timestamped signature, empty challenge |
39
+ | `depinreceiveseq` | `{cursor:null, limit:100, from_timestamp:0}` | Receive challenge and full signature |
40
+ | `depinreceivemsg` | `{timestamp?, after_hash?, limit?}` | Receive challenge and full signature |
41
+ | `depinlistsections` | `{}` | Public/root or addressed receive challenge |
42
+ | `depinsubmitmsg` | `{encrypted:outerEciesHex}` | Timestamped signature; token stays empty outside ECIES |
43
+ | `depinclearmsg` | `{mode:'expired'}`, `{mode:'all'}` or `{mode:'hours',hours:n}` | Admin challenge and full signature |
44
+
45
+ There is no positional messaging fallback. Clock correction comes only from a verified bootstrap. A changed membership revision invalidates cached nonces; refresh recipients and renew before continuing. Keep cursors exact (`number` or `bigint`, never rounded) and preserve them across membership changes while the stream is unchanged.
@@ -1,104 +1,30 @@
1
- # Neurai DePIN protocol 2 integration guide
1
+ # Integrating DePIN RPC 5
2
2
 
3
- ## Architecture
3
+ Use neurai-depin-msg 4.x for authentication, encryption and message validation; neurai-rpc 0.8.x provides HTTP transport, exact numeric JSON and the updated catalog. [Runnable composition examples](DEPIN_EXAMPLES.md) describe the request arguments.
4
4
 
5
- DePIN protocol 2 is served through Neurai's standard authenticated HTTP
6
- JSON-RPC interface: port `19001` on mainnet and `19101` on testnet. There is no
7
- separate TCP gateway. Applications use `getRPC` for every DePIN operation.
5
+ 1. Bootstrap with a fresh request ID. Bind the reply to the local request hash and expected genesis, then verify the pool key/root under explicit pinning or TOFU policy. Never silently re-pin.
6
+ 2. Keep the verified instance and membership revision. Sign the full method, arguments and context for every addressed operation, including submit and challenge issuance.
7
+ 3. Verify each response's request hash, service identity, confidentiality kind, membership metadata and signature before parsing or decrypting it.
8
+ 4. Resolve recipient addresses and keys from a verified directory. Preserve exact destination identities: Legacy and ECDSA addresses sharing one key are different permissions. Use typed recipients for ECIES 2. A directory signature does not independently prove asset ownership.
9
+ 5. Use admission-sequence cursors, retaining all six fields and exact integer values. Persisting a cursor also requires retaining its corresponding local history. A membership change does not itself reset the stream.
10
+ 6. On a verified `membership_stale`, refresh the directory and renew every cached receive/admin challenge for the old pool revision. Re-encrypt and re-sign an affected send. Bound retries; never automatically replay an ambiguous submit or clear result.
11
+ 7. A restart changes the instance. Bootstrap again under the existing pin. A new stream requires restarting pagination with hash deduplication.
12
+ 8. Handle transport errors separately from signed operation errors. Keep node `error.data` intact; do not manufacture a signed wrapper in a proxy.
8
13
 
9
- ## Roles
14
+ ## Relay requirements
10
15
 
11
- - The service node owns a dedicated wallet key used as the pool key. Its
12
- public key is published by `depingetmsginfo`.
13
- - A holder address must have its public key revealed on chain before the node
14
- can encrypt responses for it.
15
- - Clients pin the pool public key on first use, verify `poolsig` on replies,
16
- and encrypt `depinsubmitmsg` envelopes for that key.
17
- - `depinsignrequest`, `depinsignchallenge`, and `depindecrypt` are convenience
18
- RPCs for keys held by the local node wallet. External wallets implement the
19
- same signing and ECIES operations client-side.
16
+ Forward one complete request object unchanged. Expose `depinreceiveseq` and the other nine public messaging RPCs. Never expose `depinsignrpc` or local wallet decryption/sending helpers. Do not cache any request-bound response, including public bootstrap/directory/sections: the response contains a unique request hash and the live pool signature/context.
20
17
 
21
- ## Challenge authentication
18
+ When several node backends are configured, route private requests to the matching genesis, pool key, root and instance. An unrelated healthy node cannot replace that destination. Discovery metadata is advisory; the client still verifies the final response. Do not broadcast private requests or retry writes during failover.
22
19
 
23
- Authenticated reads use type `receive`; destructive cleanup uses type
24
- `admin`.
20
+ Use a lossless parser/serializer for sequence numbers. Reject duplicate JSON keys and numeric-object impersonation. Preserve invalid lexical numeric tokens so the node can reject them rather than normalizing a signed request silently.
25
21
 
26
- 1. Sign `DEPIN-REQ|<type>|<token>|<address>|<unix_time_ms>`.
27
- 2. Call `depinchallenge(token, address, timestamp, signature, type)`.
28
- 3. Verify the response's `poolsig` and decrypt its `encrypted` field.
29
- 4. Sign `DEPIN-GET|<token>|<address>|<nonce>` for reads or
30
- `DEPIN-CLEAR|<token>|<address>|<nonce>` for cleanup.
31
- 5. Pass the nonce and signature to the protected RPC.
22
+ HTTP and WSS need the same checks. The wallet service exposes `depin.receive_seq` as the WSS alias of `depinreceiveseq`; WSS node errors carry `node_code` and `data` inside the transport error. A valid node RPC response remains opaque to the relay.
32
23
 
33
- Request signatures are time-bounded and replay-protected. Challenges are
34
- bound to type, token/scope, and address; they expire and are consumed by their
35
- first successful use. Read responses can include `next_challenge` to avoid
36
- another challenge-request round trip.
24
+ ## Scope and migration
37
25
 
38
- ## Messaging RPCs
26
+ The protocol accepts canonical Legacy and strict ECDSA v3 addresses. PQ encryption/key publication is deferred. ESP32 authentication firmware and its separate library require a later migration; do not reuse old DEPIN-REQ/GET/CLEAR authentication strings.
39
27
 
40
- Public and diagnostic:
28
+ Canonical Legacy ECIES 1 history is retained. RPC 2/3/4 authentication is rejected. Noncanonical recipient ordering emitted by some older SDK versions is also rejected by the current strict parser. ECIES 2 adds typed identities for mixed/ECDSA recipients; state format 2 and cursor format 1 do not change with RPC 5.
41
29
 
42
- - `depingetmsginfo()` publishes protocol configuration and the pool key.
43
- - `depinpoolstats()` returns pool statistics.
44
- - `depinmcpstatus()` returns MCP worker state.
45
- - `depinlistsections()` returns public section names.
46
- - `depingetancestorrecipients(token, max_results?, stop_at?)` resolves active
47
- holders with revealed public keys.
48
-
49
- Wallet-backed local operations:
50
-
51
- - `depinsendmsg(token, message, fromaddress)` signs, encrypts, and stores a
52
- message in the local pool.
53
- - `depingetmsg(token, fromaddress?)` decrypts local-pool messages.
54
- - `depinpoolpkey()` derives the pool key from the service wallet.
55
- - `depinsignrequest`, `depinsignchallenge`, and `depindecrypt` assist scripts.
56
-
57
- Remote and non-custodial operations:
58
-
59
- - `depinsubmitmsg({sender, encrypted})` accepts a signed message wrapped in an
60
- ECIES envelope for the pool key. Bare serialized hex is invalid.
61
- - `depinreceivemsg(token, address, challenge, signature, timestamp?,
62
- after_hash?, limit?)` returns an encrypted, pool-signed page.
63
- - `depinlistsections(address, scope, challenge, signature)` returns encrypted
64
- personal access and counters for the selected subtree.
65
- - `depinclearmsg(scope, address, challenge, signature, mode?)` performs an
66
- owner-authorized purge. Omit mode for expired messages, use `"all"` for all
67
- messages, or pass a numeric age in hours.
68
-
69
- `depingetpoolcontent` was removed because it exposed pool-wide metadata
70
- without an identity to authenticate.
71
-
72
- ## DePIN asset RPCs
73
-
74
- - `checkdepinvalidity(asset_name, address)`
75
- - `listdepinholders(asset_name)`
76
- - `listdepinaddresses(asset_name, count?, start?)`
77
- - `freezedepin(asset_name, address, change_address?)`
78
- - `unfreezedepin(asset_name, address, change_address?)`
79
- - `selfrevokedepin(asset_name)`
80
-
81
- Wallet-changing methods require an enabled wallet. Chain-wide holder queries
82
- require the indexes specified by the node's RPC help.
83
-
84
- ## JavaScript client
85
-
86
- ```js
87
- import { getRPC, methods } from "@neuraiproject/neurai-rpc";
88
-
89
- const rpc = getRPC("rpcuser", "rpcpassword", "http://127.0.0.1:19001");
90
- const info = await rpc(methods.depingetmsginfo, []);
91
- ```
92
-
93
- The library transports JSON-RPC and exposes current method names. It does not
94
- hold private keys or silently trust pool keys. See
95
- [DEPIN_EXAMPLES.md](./DEPIN_EXAMPLES.md) for the wallet-assisted sequence.
96
-
97
- ## Migration from protocol 1
98
-
99
- - Replace imports from `@neuraiproject/neurai-rpc/depin` with the package root.
100
- - Replace `getDePinRPC({host, port}, ...)` with `getRPC(user, password, URL)`.
101
- - Remove DePIN host/port arguments and configuration fields.
102
- - Update protected calls to the signed challenge flow.
103
- - Replace bare `depinsubmitmsg` payloads with encrypted envelope objects.
104
- - Remove calls to `depingetpoolcontent`.
30
+ The RPC method catalog includes local wallet/admin commands. Use an explicit whitelist for a public service rather than exporting the whole catalog. Publishing packages or deploying services is a separate operator action.
package/README.md CHANGED
@@ -1,137 +1,53 @@
1
1
  # neurai-rpc
2
2
 
3
- JavaScript/TypeScript client for the Neurai JSON-RPC API.
4
-
5
- ## Endpoints
6
-
7
- - Mainnet node: `http://127.0.0.1:19001`
8
- - Testnet node: `http://127.0.0.1:19101`
9
- - Hosted mainnet: `https://rpc-main.neurai.org/rpc`
10
- - Hosted testnet: `https://rpc-testnet.neurai.org/rpc`
11
-
12
- DePIN protocol 2 uses the same authenticated HTTP JSON-RPC endpoint. The old
13
- raw-TCP DePIN gateway and its dedicated port no longer exist.
14
-
15
- ## Install
16
-
17
- ```sh
18
- npm install @neuraiproject/neurai-rpc
19
- ```
20
-
21
- ## Usage
3
+ HTTP JSON-RPC transport and method catalog for Neurai, including **DePIN RPC 5**.
22
4
 
23
5
  ```js
24
- import { getRPC, methods } from "@neuraiproject/neurai-rpc";
25
-
26
- const rpc = getRPC("username", "password", "http://127.0.0.1:19001");
6
+ import {getRPC, methods, assertRpcGenesis, TESTNET_GENESIS_HASH} from '@neuraiproject/neurai-rpc';
7
+ const rpc = getRPC(username, password, endpoint);
8
+ await assertRpcGenesis(rpc, TESTNET_GENESIS_HASH);
27
9
  const height = await rpc(methods.getblockcount, []);
28
- console.log(height);
29
10
  ```
30
11
 
31
- CommonJS uses `const { getRPC, methods } = require("@neuraiproject/neurai-rpc")`.
32
- `getRPC` resolves with the JSON-RPC `result` and rejects HTTP failures and
33
- JSON-RPC error objects, including errors returned with HTTP status 200.
12
+ The transport supports Node 18+ and browser `fetch`. JSON-RPC errors reject even when the node returns HTTP 200. Error objects retain the node's numeric code, message and `data`; HTTP/network failures remain distinguishable. Never put wallet secrets in a public proxy request.
34
13
 
35
- ## DePIN protocol 2
14
+ ## Exact numbers
36
15
 
37
- Use the normal `getRPC` client for every DePIN command:
16
+ `parseRpcJson` keeps unsafe response numeric tokens as decimal strings for compatibility with chain/amount APIs. `stringifyRpcJson` emits `bigint` and `rpcNumber(decimalText)` as exact JSON numbers, and rejects unsafe JavaScript numeric parameters.
38
17
 
39
18
  ```js
40
- const info = await rpc(methods.depingetmsginfo, []);
41
- const stats = await rpc(methods.depinpoolstats, []);
42
-
43
- const sent = await rpc(methods.depinsendmsg, [
44
- "&FRANCE/GENERAL",
45
- "Hello team!",
46
- "NXsender...",
47
- ]);
19
+ import {rpcNumber, stringifyRpcJson} from '@neuraiproject/neurai-rpc';
20
+ await rpc('sendtoaddress', [address, rpcNumber('0.12345678')]); // Local wallet RPC only.
21
+ console.log(stringifyRpcJson({after_seq: 9007199254740993n}));
48
22
  ```
49
23
 
50
- Authenticated reads and administrative purges use signed, single-use
51
- challenges. A wallet-backed flow uses these commands in order:
52
-
53
- 1. `depinsignrequest(address, token, type)`
54
- 2. `depinchallenge(token, address, timestamp, signature, type)`
55
- 3. `depindecrypt(address, encrypted)` to recover the challenge
56
- 4. `depinsignchallenge(address, token, challenge, type)`
57
- 5. `depinreceivemsg`, `depinlistsections`, or `depinclearmsg`
58
- 6. Verify `poolsig`, then decrypt the encrypted response
59
-
60
- See [DEPIN_EXAMPLES.md](./DEPIN_EXAMPLES.md) for call sequences and
61
- [DEPIN_IMPLEMENTATION_GUIDE_EN.md](./DEPIN_IMPLEMENTATION_GUIDE_EN.md) for the
62
- protocol details.
63
-
64
- ### Method changes
24
+ ## DePIN RPC 5
65
25
 
66
- Added:
26
+ Use `@neuraiproject/neurai-depin-msg` 4.x to build and authenticate requests/replies. This transport does not sign, decrypt or authenticate `poolsig` on the application's behalf.
67
27
 
68
- - `depinchallenge`
69
- - `depinsignrequest` (wallet helper)
70
- - `depinsignchallenge` (wallet helper)
71
- - `depindecrypt` (wallet helper)
72
- - `getibdstatus` (header synchronization diagnostics)
28
+ All ten remote messaging methods take exactly one request object (`[request]` or named `{request}`): bootstrap, stats, MCP status, challenge, directory, sections, sequence/timestamp reads, submission and clear. `depinreceiveseq` is the default read path in the messaging SDK. Each addressed operation signs all parameters, target chain/pool/instance, membership revision and a fresh request ID. No RPC 2/3/4 fallback is provided.
73
29
 
74
- Changed:
75
-
76
- - `depinsendmsg(token, message, fromaddress)` is local; host/port parameters
77
- were removed.
78
- - `depinreceivemsg` now requires a receive challenge and signature.
79
- - `depinclearmsg` now requires an admin challenge and signature.
80
- - Address mode in `depinlistsections` now requires scope, challenge, and
81
- signature.
82
- - `depinsubmitmsg` accepts only an encrypted envelope object.
83
- - `depingetmsg(token, fromaddress?)` is local-wallet only.
84
-
85
- Removed:
86
-
87
- - `depingetpoolcontent`
88
- - `@neuraiproject/neurai-rpc/depin` and `getDePinRPC`, which implemented the
89
- retired TCP transport
90
-
91
- ## Compatibility
92
-
93
- - DePIN protocol 2 methods require Neurai node 2.0.0 or later.
94
- - `getibdstatus` requires a node from August 2026 or later.
95
- - `createrawtransaction` with `refinputs` requires a node from April 2026 or
96
- later.
97
- - `dumpextkeypq` and `exportxpqpub` require PQ wallet support.
98
- - Wallet-only commands are unavailable when the wallet is disabled.
99
-
100
- ## Method catalog
101
-
102
- `methods` exposes the supported command names with TypeScript declarations:
30
+ Bootstrap is also request-bound:
103
31
 
104
32
  ```js
105
- await rpc(methods.getibdstatus, []);
106
- await rpc(methods.checkdepinvalidity, ["&FRANCE", "NXaddress..."]);
33
+ const response = await rpc(methods.depingetmsginfo, [{
34
+ protocol: 5,
35
+ request_id: random32ByteLowercaseHex,
36
+ timestamp_ms: Date.now(),
37
+ }]);
38
+ // Verify response identity and signature with the SDK before using its contents.
107
39
  ```
108
40
 
109
- Generated command documentation is in
110
- [neurai_methods.md](./neurai_methods.md).
111
-
112
- ## Links
113
-
114
- - [GitHub repository](https://github.com/neuraiproject/neurai-rpc)
115
- - [NPM package](https://www.npmjs.com/package/@neuraiproject/neurai-rpc)
41
+ Local `depinsignrpc(method, request)` replaces the removed `depinsignrequest`, `depinsignchallenge` and `depinsignreadseq` helpers. It belongs only on an unlocked local signing wallet. `depindecrypt`, `depinsendmsg`, `depingetmsg` and `depinpoolpkey` also remain local helpers and must not be publicly exposed merely because they appear in the node catalog.
116
42
 
117
- ### Exact numeric values
43
+ Legacy and strict ECDSA v3 identities are supported by RPC 5. PQ messaging remains outside this contract. A signature over a directory is the pool's statement, not independent proof of asset ownership.
118
44
 
119
- RPC responses are parsed from their original JSON text. Safe numbers retain
120
- `number` compatibility; numeric tokens that would lose digits (large raw
121
- integers or high-precision decimals) are returned as strings. Normalize monetary
122
- fields to bigint/decimal text in your application, never with parseFloat.
45
+ See [examples](DEPIN_EXAMPLES.md) and [integration guide](DEPIN_IMPLEMENTATION_GUIDE_EN.md). The package exports request/response/cursor types, `DEPIN_REMOTE_METHODS`, `getDepinRequest` and `createDepinNodeRouter`. The router performs advisory pool/instance discovery, routes a private request only to its exact healthy destination and never broadcasts, rewrites or automatically replays a write. Clients still verify the final signed response.
123
46
 
124
- For request parameters use bigint for exact integer JSON tokens, or
125
- `rpcNumber('100000000.00000001')` for an exact decimal JSON token. Ordinary
126
- strings remain quoted strings: use the representation required by the RPC
127
- method. Unsafe integer numbers, NaN and Infinity are rejected. No global
128
- BigInt.prototype mutation is performed. `parseRpcJson` and `stringifyRpcJson`
129
- are exported for callers implementing their own transport.
130
-
131
- ## Verify the chain before using a testnet RPC
47
+ ```sh
48
+ npm run create-docs
49
+ npm run build
50
+ npm test -- --runInBand
51
+ ```
132
52
 
133
- `TESTNET_GENESIS_HASH` identifies the reset testnet. Call
134
- `await assertRpcGenesis(rpc, TESTNET_GENESIS_HASH)` after constructing an RPC
135
- client and before reading balances or building transactions. The port and
136
- `getblockchaininfo.chain` label alone do not distinguish the previous testnet.
137
- `MAINNET_GENESIS_HASH` is also exported for mainnet clients.
53
+ Integration tests requiring a live node are separate from the offline suite. The method catalog is generated from `docs.json`; it includes both public and local wallet/admin methods, so it is not a proxy whitelist.
package/depin.ts ADDED
@@ -0,0 +1,144 @@
1
+ /** Transport types only. Build and verify signatures with neurai-depin-msg. */
2
+ export const DEPIN_RPC_PROTOCOL = 5 as const;
3
+ export const DEPIN_REMOTE_METHODS = Object.freeze([
4
+ 'depingetmsginfo',
5
+ 'depinpoolstats',
6
+ 'depinmcpstatus',
7
+ 'depinchallenge',
8
+ 'depinreceivemsg',
9
+ 'depinreceiveseq',
10
+ 'depinlistsections',
11
+ 'depinclearmsg',
12
+ 'depinsubmitmsg',
13
+ 'depingetancestorrecipients',
14
+ ] as const);
15
+ export type DepinRemoteMethod = (typeof DEPIN_REMOTE_METHODS)[number];
16
+ export interface DepinBootstrapRequest {
17
+ protocol: 5;
18
+ request_id: string;
19
+ timestamp_ms: number | bigint;
20
+ }
21
+ export interface DepinSequenceCursor {
22
+ version: 1;
23
+ stream_id: string;
24
+ after_seq: number | bigint;
25
+ scope: string;
26
+ address: string;
27
+ from_timestamp: number | bigint;
28
+ }
29
+ export interface DepinRpcRequest extends DepinBootstrapRequest {
30
+ network: string;
31
+ pool_pubkey: string;
32
+ pool_root: string;
33
+ instance_id: string;
34
+ membership_revision: string;
35
+ token: string;
36
+ address: string;
37
+ challenge: string;
38
+ args: Record<string, unknown>;
39
+ signature: string;
40
+ }
41
+ export type DepinRpcParams = [DepinBootstrapRequest | DepinRpcRequest] | { request: DepinBootstrapRequest | DepinRpcRequest };
42
+ export interface DepinRpcResponse {
43
+ protocol: 5;
44
+ network: string;
45
+ pool_pubkey: string;
46
+ pool_root: string;
47
+ instance_id: string;
48
+ membership_revision: string;
49
+ membership_height: number;
50
+ membership_blockhash: string;
51
+ request_hash: string;
52
+ body_kind: 0 | 1;
53
+ body?: string;
54
+ encrypted?: string;
55
+ poolsig: string;
56
+ }
57
+ export function isDepinRemoteMethod(method: string): method is DepinRemoteMethod {
58
+ return (DEPIN_REMOTE_METHODS as readonly string[]).includes(method);
59
+ }
60
+ /** Keep every signed byte intact. The node performs canonical validation. */
61
+ export function getDepinRequest(params: unknown): DepinBootstrapRequest | DepinRpcRequest {
62
+ const request =
63
+ Array.isArray(params) && params.length === 1
64
+ ? params[0]
65
+ : params && typeof params === 'object' && Object.keys(params).length === 1
66
+ ? (params as any).request
67
+ : null;
68
+ const protocol = request?.protocol;
69
+ // HTTP services can parse numeric JSON tokens as genuine LosslessNumbers.
70
+ if (
71
+ !request ||
72
+ typeof request !== 'object' ||
73
+ Array.isArray(request) ||
74
+ !(
75
+ protocol === 5 ||
76
+ (protocol?.isLosslessNumber === true &&
77
+ protocol.value === '5' &&
78
+ typeof protocol.toString === 'function' &&
79
+ protocol.toString() === '5')
80
+ )
81
+ ) {
82
+ throw Object.assign(new Error('DePIN protocol 5 requires one request object'), {
83
+ code: -8,
84
+ data: { depin_error: 'unsupported_protocol', expected_protocol: 5 },
85
+ });
86
+ }
87
+ return request;
88
+ }
89
+
90
+ type RpcNode = { rpc: (method: string, params: any) => Promise<any> };
91
+ /** Route signed requests to their exact pool/instance, with no request rewriting.
92
+ * Discovery is advisory routing metadata; the client verifies the final reply.
93
+ * No private request is broadcast and no write is retried by this router.
94
+ */
95
+ export function createDepinNodeRouter<T extends RpcNode>(healthyNodes: () => T[], randomId: () => string) {
96
+ const identities = new WeakMap<T, { network: string; pool_pubkey: string; pool_root: string; instance_id: string }>();
97
+ const pending = new WeakMap<T, Promise<void>>();
98
+ const discoveredAt = new WeakMap<T, number>();
99
+ async function discover(node: T) {
100
+ let promise = pending.get(node);
101
+ if (!promise && Date.now() - (discoveredAt.get(node) ?? 0) < 1000) return;
102
+ if (!promise) {
103
+ discoveredAt.set(node, Date.now());
104
+ promise = (async () => {
105
+ const reply = await node.rpc('depingetmsginfo', [{ protocol: 5, request_id: randomId(), timestamp_ms: Date.now() }]);
106
+ if (
107
+ reply?.protocol !== 5 ||
108
+ typeof reply.network !== 'string' ||
109
+ typeof reply.pool_pubkey !== 'string' ||
110
+ typeof reply.pool_root !== 'string' ||
111
+ typeof reply.instance_id !== 'string'
112
+ )
113
+ throw new Error('Node has no RPC 5 pool identity');
114
+ identities.set(node, reply);
115
+ })().finally(() => pending.delete(node));
116
+ pending.set(node, promise);
117
+ }
118
+ await promise;
119
+ }
120
+ return async function route(method: string, params: unknown): Promise<T> {
121
+ const request = getDepinRequest(params);
122
+ const nodes = healthyNodes();
123
+ if (!nodes.length) throw new Error('No healthy RPC node');
124
+ if (method === 'depingetmsginfo') return nodes[0];
125
+ const target = request as DepinRpcRequest;
126
+ const matches = (node: T) => {
127
+ const identity = identities.get(node);
128
+ return (
129
+ identity && ['network', 'pool_pubkey', 'pool_root', 'instance_id'].every((key) => (identity as any)[key] === (target as any)[key])
130
+ );
131
+ };
132
+ let found = nodes.find(matches);
133
+ if (found) return found;
134
+ // One discovery per healthy node, coalesced across concurrent requests.
135
+ await Promise.all(nodes.map((node) => discover(node).catch(() => identities.delete(node))));
136
+ found = nodes.find(matches);
137
+ if (!found)
138
+ throw Object.assign(new Error('DePIN service_mismatch: target pool or instance is unavailable; refresh bootstrap'), {
139
+ code: -32600,
140
+ data: { depin_error: 'service_mismatch', expected_protocol: 5 },
141
+ });
142
+ return found;
143
+ };
144
+ }