@neuraiproject/neurai-rpc 0.6.2 → 0.8.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 +17 -0
- package/DEPIN_EXAMPLES.md +45 -127
- package/DEPIN_IMPLEMENTATION_GUIDE_EN.md +19 -93
- package/README.md +29 -105
- package/depin.ts +144 -0
- package/dist/index.cjs +355 -331
- package/dist/index.d.cts +72 -4
- package/dist/index.d.ts +72 -4
- package/dist/index.mjs +346 -331
- package/docs.json +198 -198
- package/docs.ts +1342 -1504
- package/index.ts +54 -34
- package/json.ts +29 -0
- package/neurai_methods.md +743 -872
- package/package.json +4 -2
package/CHANGELOG.md
CHANGED
|
@@ -1,3 +1,9 @@
|
|
|
1
|
+
# 0.8.0
|
|
2
|
+
|
|
3
|
+
- Add RPC 5 messaging requests, sequence cursors, response types and exact pool/instance routing.
|
|
4
|
+
- Replace removed local signers with depinsignrpc in the catalog; keep wallet helpers out of relay whitelists.
|
|
5
|
+
- Update messaging examples and migration guidance for Legacy/ECDSA and ECIES 2.
|
|
6
|
+
|
|
1
7
|
# Changelog
|
|
2
8
|
|
|
3
9
|
All notable changes to this project will be documented in this file.
|
|
@@ -5,6 +11,17 @@ All notable changes to this project will be documented in this file.
|
|
|
5
11
|
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
|
|
6
12
|
and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
13
|
|
|
14
|
+
## [0.7.0] - 2026-09-27
|
|
15
|
+
|
|
16
|
+
### Reset testnet
|
|
17
|
+
|
|
18
|
+
- Export the new testnet and mainnet genesis hashes and `assertRpcGenesis` so
|
|
19
|
+
clients can reject an endpoint from the previous testnet before reading
|
|
20
|
+
balances or sending transactions.
|
|
21
|
+
- Preserve JSON-RPC errors returned with HTTP 200 as rejections.
|
|
22
|
+
- Verify genesis, asset marker and RPC error propagation against a node built
|
|
23
|
+
from Neurai-DePIN commit `0fe5a74943210508ec3be34c78e0f9192b7fefec`.
|
|
24
|
+
|
|
8
25
|
## [0.6.2] - 2026-09-22
|
|
9
26
|
|
|
10
27
|
### Documentation — neurai-key 5 address types
|
package/DEPIN_EXAMPLES.md
CHANGED
|
@@ -1,127 +1,45 @@
|
|
|
1
|
-
# DePIN
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
```js
|
|
6
|
-
import {
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
const
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
}
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
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
|
-
#
|
|
1
|
+
# Integrating DePIN RPC 5
|
|
2
2
|
|
|
3
|
-
|
|
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
|
-
|
|
6
|
-
|
|
7
|
-
|
|
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
|
-
##
|
|
14
|
+
## Relay requirements
|
|
10
15
|
|
|
11
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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,129 +1,53 @@
|
|
|
1
1
|
# neurai-rpc
|
|
2
2
|
|
|
3
|
-
|
|
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 {
|
|
25
|
-
|
|
26
|
-
|
|
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
|
-
|
|
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
|
-
##
|
|
14
|
+
## Exact numbers
|
|
36
15
|
|
|
37
|
-
|
|
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
|
-
|
|
41
|
-
|
|
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
|
-
|
|
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.
|
|
24
|
+
## DePIN RPC 5
|
|
63
25
|
|
|
64
|
-
|
|
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.
|
|
65
27
|
|
|
66
|
-
|
|
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.
|
|
67
29
|
|
|
68
|
-
-
|
|
69
|
-
- `depinsignrequest` (wallet helper)
|
|
70
|
-
- `depinsignchallenge` (wallet helper)
|
|
71
|
-
- `depindecrypt` (wallet helper)
|
|
72
|
-
- `getibdstatus` (header synchronization diagnostics)
|
|
73
|
-
|
|
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.
|
|
106
|
-
|
|
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
|
-
|
|
110
|
-
[neurai_methods.md](./neurai_methods.md).
|
|
111
|
-
|
|
112
|
-
## Links
|
|
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.
|
|
113
42
|
|
|
114
|
-
|
|
115
|
-
- [NPM package](https://www.npmjs.com/package/@neuraiproject/neurai-rpc)
|
|
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.
|
|
116
44
|
|
|
117
|
-
|
|
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.
|
|
118
46
|
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
47
|
+
```sh
|
|
48
|
+
npm run create-docs
|
|
49
|
+
npm run build
|
|
50
|
+
npm test -- --runInBand
|
|
51
|
+
```
|
|
123
52
|
|
|
124
|
-
|
|
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.
|
|
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
|
+
}
|