@neuraiproject/neurai-rpc 0.9.0 → 0.10.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 +8 -0
- package/DEPIN_EXAMPLES.md +2 -2
- package/DEPIN_IMPLEMENTATION_GUIDE_EN.md +4 -4
- package/README.md +6 -6
- package/depin.ts +12 -12
- package/dist/index.cjs +172 -210
- package/dist/index.d.cts +5 -4
- package/dist/index.d.ts +5 -4
- package/dist/index.mjs +172 -210
- package/docs.json +76 -75
- package/docs.ts +165 -201
- package/index.ts +2 -2
- package/neurai_methods.md +161 -200
- package/package.json +2 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,3 +1,11 @@
|
|
|
1
|
+
## 0.10.0
|
|
2
|
+
|
|
3
|
+
DePIN transport now requires RPC protocol 6. Upgrade the messaging client to 5.x and the proxy together. Signed requests target a single pool instance. Clients must verify format-3 envelopes using their network and message or transport context.
|
|
4
|
+
|
|
5
|
+
# 0.9.1
|
|
6
|
+
|
|
7
|
+
- Testnet reset of 2026-11-05: `TESTNET_GENESIS_HASH` is now `000000c710413a4265a996d30c86043aedef6a563900f1bc43fea61d5b2dc77d`, so `assertRpcGenesis(rpc, TESTNET_GENESIS_HASH)` rejects a node of the previous testnet. The client and the method catalog are unchanged.
|
|
8
|
+
|
|
1
9
|
# 0.9.0
|
|
2
10
|
|
|
3
11
|
- 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.
|
package/DEPIN_EXAMPLES.md
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
# DePIN RPC
|
|
1
|
+
# DePIN RPC 6 examples
|
|
2
2
|
|
|
3
3
|
The messaging SDK implements the binary signing contract. A generic transport call alone does not authenticate a pool reply.
|
|
4
4
|
|
|
@@ -28,7 +28,7 @@ context = page.context;
|
|
|
28
28
|
const stats = await callDepinRpc({rpc, context, method: 'depinpoolstats'});
|
|
29
29
|
```
|
|
30
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:
|
|
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:6`, `request_id` and `timestamp_ms`.
|
|
32
32
|
|
|
33
33
|
| Method | `args` | Authentication |
|
|
34
34
|
| --- | --- | --- |
|
|
@@ -1,11 +1,11 @@
|
|
|
1
|
-
# Integrating DePIN RPC
|
|
1
|
+
# Integrating DePIN RPC 6
|
|
2
2
|
|
|
3
|
-
Use neurai-depin-msg
|
|
3
|
+
Use neurai-depin-msg 5.x for authentication, encryption and message validation; neurai-rpc 0.10.x provides HTTP transport, exact numeric JSON and the updated catalog. [Runnable composition examples](DEPIN_EXAMPLES.md) describe the request arguments.
|
|
4
4
|
|
|
5
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
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
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
|
|
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 3. A directory signature does not independently prove asset ownership.
|
|
9
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
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
11
|
7. A restart changes the instance. Bootstrap again under the existing pin. A new stream requires restarting pagination with hash deduplication.
|
|
@@ -25,6 +25,6 @@ HTTP and WSS need the same checks. The wallet service exposes `depin.receive_seq
|
|
|
25
25
|
|
|
26
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.
|
|
27
27
|
|
|
28
|
-
|
|
28
|
+
The current reader requires a format-3 envelope. RPC 2/3/4/5 authentication is rejected. Noncanonical recipient ordering emitted by some older SDK versions is also rejected by the current strict parser. ECIES 3 adds typed identities for mixed/ECDSA recipients; state format 2 and cursor format 1 do not change with RPC 6.
|
|
29
29
|
|
|
30
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,6 +1,6 @@
|
|
|
1
1
|
# neurai-rpc
|
|
2
2
|
|
|
3
|
-
HTTP JSON-RPC transport and method catalog for Neurai, including **DePIN RPC
|
|
3
|
+
HTTP JSON-RPC transport and method catalog for Neurai, including **DePIN RPC 6**.
|
|
4
4
|
|
|
5
5
|
```js
|
|
6
6
|
import {getRPC, methods, assertRpcGenesis, TESTNET_GENESIS_HASH} from '@neuraiproject/neurai-rpc';
|
|
@@ -21,17 +21,17 @@ await rpc('sendtoaddress', [address, rpcNumber('0.12345678')]); // Local wallet
|
|
|
21
21
|
console.log(stringifyRpcJson({after_seq: 9007199254740993n}));
|
|
22
22
|
```
|
|
23
23
|
|
|
24
|
-
## DePIN RPC
|
|
24
|
+
## DePIN RPC 6
|
|
25
25
|
|
|
26
|
-
Use `@neuraiproject/neurai-depin-msg`
|
|
26
|
+
Use `@neuraiproject/neurai-depin-msg` 5.x to build and authenticate requests/replies. This transport does not sign, decrypt or authenticate `poolsig` on the application's behalf.
|
|
27
27
|
|
|
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.
|
|
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/5 fallback is provided.
|
|
29
29
|
|
|
30
30
|
Bootstrap is also request-bound:
|
|
31
31
|
|
|
32
32
|
```js
|
|
33
33
|
const response = await rpc(methods.depingetmsginfo, [{
|
|
34
|
-
protocol:
|
|
34
|
+
protocol: 6,
|
|
35
35
|
request_id: random32ByteLowercaseHex,
|
|
36
36
|
timestamp_ms: Date.now(),
|
|
37
37
|
}]);
|
|
@@ -40,7 +40,7 @@ const response = await rpc(methods.depingetmsginfo, [{
|
|
|
40
40
|
|
|
41
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.
|
|
42
42
|
|
|
43
|
-
Legacy and strict ECDSA v3 identities are supported by RPC
|
|
43
|
+
Legacy and strict ECDSA v3 identities are supported by RPC 6. PQ messaging remains outside this contract. A signature over a directory is the pool's statement, not independent proof of asset ownership.
|
|
44
44
|
|
|
45
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.
|
|
46
46
|
|
package/depin.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
/** Transport types only. Build and verify signatures with neurai-depin-msg. */
|
|
2
|
-
export const DEPIN_RPC_PROTOCOL =
|
|
2
|
+
export const DEPIN_RPC_PROTOCOL = 6 as const;
|
|
3
3
|
export const DEPIN_REMOTE_METHODS = Object.freeze([
|
|
4
4
|
'depingetmsginfo',
|
|
5
5
|
'depinpoolstats',
|
|
@@ -14,7 +14,7 @@ export const DEPIN_REMOTE_METHODS = Object.freeze([
|
|
|
14
14
|
] as const);
|
|
15
15
|
export type DepinRemoteMethod = (typeof DEPIN_REMOTE_METHODS)[number];
|
|
16
16
|
export interface DepinBootstrapRequest {
|
|
17
|
-
protocol:
|
|
17
|
+
protocol: 6;
|
|
18
18
|
request_id: string;
|
|
19
19
|
timestamp_ms: number | bigint;
|
|
20
20
|
}
|
|
@@ -40,7 +40,7 @@ export interface DepinRpcRequest extends DepinBootstrapRequest {
|
|
|
40
40
|
}
|
|
41
41
|
export type DepinRpcParams = [DepinBootstrapRequest | DepinRpcRequest] | { request: DepinBootstrapRequest | DepinRpcRequest };
|
|
42
42
|
export interface DepinRpcResponse {
|
|
43
|
-
protocol:
|
|
43
|
+
protocol: 6;
|
|
44
44
|
network: string;
|
|
45
45
|
pool_pubkey: string;
|
|
46
46
|
pool_root: string;
|
|
@@ -72,16 +72,16 @@ export function getDepinRequest(params: unknown): DepinBootstrapRequest | DepinR
|
|
|
72
72
|
typeof request !== 'object' ||
|
|
73
73
|
Array.isArray(request) ||
|
|
74
74
|
!(
|
|
75
|
-
protocol ===
|
|
75
|
+
protocol === 6 ||
|
|
76
76
|
(protocol?.isLosslessNumber === true &&
|
|
77
|
-
protocol.value === '
|
|
77
|
+
protocol.value === '6' &&
|
|
78
78
|
typeof protocol.toString === 'function' &&
|
|
79
|
-
protocol.toString() === '
|
|
79
|
+
protocol.toString() === '6')
|
|
80
80
|
)
|
|
81
81
|
) {
|
|
82
|
-
throw Object.assign(new Error('DePIN protocol
|
|
82
|
+
throw Object.assign(new Error('DePIN protocol 6 requires one request object'), {
|
|
83
83
|
code: -8,
|
|
84
|
-
data: { depin_error: 'unsupported_protocol', expected_protocol:
|
|
84
|
+
data: { depin_error: 'unsupported_protocol', expected_protocol: 6 },
|
|
85
85
|
});
|
|
86
86
|
}
|
|
87
87
|
return request;
|
|
@@ -102,15 +102,15 @@ export function createDepinNodeRouter<T extends RpcNode>(healthyNodes: () => T[]
|
|
|
102
102
|
if (!promise) {
|
|
103
103
|
discoveredAt.set(node, Date.now());
|
|
104
104
|
promise = (async () => {
|
|
105
|
-
const reply = await node.rpc('depingetmsginfo', [{ protocol:
|
|
105
|
+
const reply = await node.rpc('depingetmsginfo', [{ protocol: 6, request_id: randomId(), timestamp_ms: Date.now() }]);
|
|
106
106
|
if (
|
|
107
|
-
reply?.protocol !==
|
|
107
|
+
reply?.protocol !== 6 ||
|
|
108
108
|
typeof reply.network !== 'string' ||
|
|
109
109
|
typeof reply.pool_pubkey !== 'string' ||
|
|
110
110
|
typeof reply.pool_root !== 'string' ||
|
|
111
111
|
typeof reply.instance_id !== 'string'
|
|
112
112
|
)
|
|
113
|
-
throw new Error('Node has no RPC
|
|
113
|
+
throw new Error('Node has no RPC 6 pool identity');
|
|
114
114
|
identities.set(node, reply);
|
|
115
115
|
})().finally(() => pending.delete(node));
|
|
116
116
|
pending.set(node, promise);
|
|
@@ -137,7 +137,7 @@ export function createDepinNodeRouter<T extends RpcNode>(healthyNodes: () => T[]
|
|
|
137
137
|
if (!found)
|
|
138
138
|
throw Object.assign(new Error('DePIN service_mismatch: target pool or instance is unavailable; refresh bootstrap'), {
|
|
139
139
|
code: -32600,
|
|
140
|
-
data: { depin_error: 'service_mismatch', expected_protocol:
|
|
140
|
+
data: { depin_error: 'service_mismatch', expected_protocol: 6 },
|
|
141
141
|
});
|
|
142
142
|
return found;
|
|
143
143
|
};
|