@neuraiproject/neurai-rpc 0.4.7 → 0.5.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +83 -0
- package/DEPIN_EXAMPLES.md +148 -220
- package/DEPIN_IMPLEMENTATION_GUIDE_EN.md +239 -70
- package/README.md +98 -46
- package/depin.ts +465 -214
- package/dist/depin.cjs +305 -0
- package/dist/depin.d.cts +96 -0
- package/dist/depin.d.ts +96 -0
- package/dist/depin.mjs +280 -0
- package/dist/index.cjs +5251 -4941
- package/dist/{types.d.ts → index.d.cts} +10 -63
- package/dist/index.d.ts +200 -0
- package/dist/index.mjs +5224 -4933
- package/docs.json +187 -181
- package/docs.ts +686 -238
- package/index.ts +13 -9
- package/neurai_methods.md +656 -238
- package/package.json +39 -11
- package/createDocs.mjs +0 -61
- package/dist/index.cjs.map +0 -1
- package/dist/index.mjs.map +0 -1
- package/dist/types.d.ts.map +0 -1
- package/test-depin.ts +0 -187
- package/test.js +0 -56
- package/tsconfig.json +0 -26
package/README.md
CHANGED
|
@@ -2,12 +2,11 @@
|
|
|
2
2
|
|
|
3
3
|
A package that will help you do RPC calls from Node.js to your Neurai node, that is your full Neurai node.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
Endpoints for locally installed Neurai nodes.
|
|
6
6
|
|
|
7
|
-
- http://127.0.0.1:19001 for mainnet (Standard RPC)
|
|
8
|
-
- http://127.0.0.1:
|
|
9
|
-
-
|
|
10
|
-
- http://127.0.0.1:19102 for testnet (DePIN Messaging)
|
|
7
|
+
- http://127.0.0.1:19001 for mainnet (Standard RPC, HTTP)
|
|
8
|
+
- http://127.0.0.1:19101 for testnet (Standard RPC, HTTP)
|
|
9
|
+
- TCP 127.0.0.1:19002 — DePIN Messaging gateway (raw TCP, not HTTP; default of `-depinmsgport` on every network)
|
|
11
10
|
|
|
12
11
|
Neurai as a service, you don't need your own node
|
|
13
12
|
|
|
@@ -68,14 +67,19 @@ will print out
|
|
|
68
67
|
{ name: 'ELVIS', amount: 1, units: 8, reissuable: 1, has_ipfs: 0 }
|
|
69
68
|
```
|
|
70
69
|
|
|
71
|
-
# DePIN Messaging Usage
|
|
70
|
+
# DePIN Messaging Usage (Node.js only)
|
|
72
71
|
|
|
73
|
-
DePIN (Decentralized Physical Infrastructure Network) messaging uses
|
|
72
|
+
DePIN (Decentralized Physical Infrastructure Network) messaging uses a raw TCP
|
|
73
|
+
line protocol on port 19002 — not HTTP — and authenticates with cryptographic
|
|
74
|
+
signatures instead of username/password. Because browsers cannot open raw TCP
|
|
75
|
+
connections, the DePIN client only works in Node.js and lives in its own
|
|
76
|
+
package entry: `@neuraiproject/neurai-rpc/depin`. To use DePIN from a browser
|
|
77
|
+
you need an external HTTP/WebSocket proxy in front of the gateway.
|
|
74
78
|
|
|
75
79
|
## Basic DePIN Example
|
|
76
80
|
|
|
77
81
|
```javascript
|
|
78
|
-
import { getDePinRPC } from "@neuraiproject/neurai-rpc";
|
|
82
|
+
import { getDePinRPC } from "@neuraiproject/neurai-rpc/depin";
|
|
79
83
|
|
|
80
84
|
// Function to sign messages with your private key
|
|
81
85
|
async function signMessage(message) {
|
|
@@ -84,37 +88,68 @@ async function signMessage(message) {
|
|
|
84
88
|
return "signature_base64";
|
|
85
89
|
}
|
|
86
90
|
|
|
87
|
-
const depinRPC =
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
91
|
+
const depinRPC = getDePinRPC(
|
|
92
|
+
{ host: "127.0.0.1", port: 19002 },
|
|
93
|
+
{
|
|
94
|
+
token: "&FRANCE",
|
|
95
|
+
address: "NYourAddressHere",
|
|
96
|
+
signMessage: signMessage,
|
|
97
|
+
}
|
|
98
|
+
);
|
|
92
99
|
|
|
93
|
-
// Send a DePIN message
|
|
100
|
+
// Send a DePIN message (challenge/signature handled automatically)
|
|
94
101
|
const result = await depinRPC("depinsendmsg", [
|
|
95
|
-
"FRANCE",
|
|
102
|
+
"&FRANCE",
|
|
96
103
|
"192.168.1.100:19002",
|
|
97
104
|
"Hello team!",
|
|
98
105
|
"NYourAddressHere"
|
|
99
106
|
]);
|
|
100
107
|
console.log(result);
|
|
108
|
+
|
|
109
|
+
// Unauthenticated queries need no auth options at all:
|
|
110
|
+
const publicRPC = getDePinRPC({ host: "127.0.0.1", port: 19002 });
|
|
111
|
+
const info = await publicRPC("depingetmsginfo", []);
|
|
101
112
|
```
|
|
102
113
|
|
|
103
|
-
For complete DePIN examples including
|
|
114
|
+
For complete DePIN examples including error handling and advanced usage, see [DEPIN_EXAMPLES.md](./DEPIN_EXAMPLES.md).
|
|
104
115
|
|
|
105
|
-
The messaging token configured for a DePIN gateway
|
|
116
|
+
The messaging token configured for a DePIN gateway (`-depinmsgtoken`) must be a dedicated `&ASSET` DePIN asset (e.g. `&FRANCE`). DePIN assets are soulbound, must use `units=0`, and are currently enabled on testnet and regtest only in the node; the same `&` type is what the DePIN asset-management RPCs operate on.
|
|
106
117
|
|
|
107
118
|
## DePIN Authentication
|
|
108
119
|
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
120
|
+
The gateway uses a challenge-response authentication protocol over the TCP
|
|
121
|
+
line protocol:
|
|
122
|
+
|
|
123
|
+
1. Client sends `AUTH|token|address|MODE` (MODE is `SEND`, `RECEIVE` or `ADMIN`)
|
|
124
|
+
2. Server returns `CHALLENGE|<challenge>|<timeout>` (challenge expires, typically 60 seconds)
|
|
125
|
+
3. Client signs the mode-specific message with the address key:
|
|
126
|
+
- `DEPIN-SEND|token|address|challenge` for `depinsendmsg`
|
|
127
|
+
- `DEPIN-GET|token|address|challenge` for RECEIVE challenges
|
|
128
|
+
- `DEPIN-CLEAR|token|address|challenge` for `depinclearmsg` (ADMIN, owner only)
|
|
129
|
+
4. Client sends the JSON-RPC request with the challenge and signature placed
|
|
130
|
+
where the gateway expects them for that method
|
|
115
131
|
5. Server verifies the signature against the address
|
|
116
132
|
|
|
117
|
-
|
|
133
|
+
`getDePinRPC` handles all of this automatically — per-method challenge type,
|
|
134
|
+
signature format and parameter placement, requesting a fresh challenge for
|
|
135
|
+
every authenticated call (challenges are single-use: the node consumes the
|
|
136
|
+
nonce when validating it) and retrying once on challenge expiration. Methods
|
|
137
|
+
that the gateway serves
|
|
138
|
+
without authentication (`depinreceivemsg`, `depinsubmitmsg`, `depingetmsginfo`,
|
|
139
|
+
`depingetpoolcontent`, `depinpoolstats`, `depinmcpstatus`, `depinlistsections`,
|
|
140
|
+
`depinpoolpkey`) are sent with their params untouched.
|
|
141
|
+
|
|
142
|
+
Note: `depingetmsg` over the gateway is currently blocked by a node-side bug
|
|
143
|
+
(the gateway reads `fromaddress` from the wrong parameter position for this
|
|
144
|
+
method); the client rejects it with a clear error. Use `depinreceivemsg`, or
|
|
145
|
+
call `depingetmsg` through the standard RPC port.
|
|
146
|
+
|
|
147
|
+
## Node compatibility
|
|
148
|
+
|
|
149
|
+
- `createrawtransaction` with `refinputs` (NIP-014, v3 transactions) requires a node from April 2026 or later.
|
|
150
|
+
- `depingetancestorrecipients`, `depinlistsections`, sub-DePIN sections and `depinreceivemsg` pagination (`after_hash`, `limit`) require a node from July 2026 or later.
|
|
151
|
+
- `dumpextkeypq` and `exportxpqpub` (post-quantum wallet, ML-DSA-44) require a node built with PQ wallet support (July 2026 or later).
|
|
152
|
+
- `depinsendmsg` and `depingetmsg` only exist on nodes built with the DePIN gateway enabled.
|
|
118
153
|
|
|
119
154
|
## Example list all generated addresses in a Wallet (Raven core)
|
|
120
155
|
|
|
@@ -176,31 +211,25 @@ getaddressutxos
|
|
|
176
211
|
|
|
177
212
|
== Assets ==
|
|
178
213
|
getassetdata "asset_name"
|
|
179
|
-
getcacheinfo
|
|
214
|
+
getcacheinfo
|
|
180
215
|
getsnapshot "asset_name" block_height
|
|
181
216
|
issue "asset_name" qty "( to_address )" "( change_address )" ( units ) ( reissuable ) ( has_ipfs ) "( ipfs_hash )"
|
|
182
217
|
issueunique "root_name" [asset_tags] ( [ipfs_hashes] ) "( to_address )" "( change_address )"
|
|
183
|
-
checkdepinvalidity "asset_name" "address"
|
|
184
|
-
freezedepin "asset_name" "address" ("change_address")
|
|
185
218
|
listaddressesbyasset "asset_name" (onlytotal) (count) (start)
|
|
186
219
|
listassetbalancesbyaddress "address" (onlytotal) (count) (start)
|
|
187
220
|
listassets "( asset )" ( verbose ) ( count ) ( start )
|
|
188
|
-
|
|
189
|
-
listdepinholders "asset_name"
|
|
190
|
-
listmyassets "( asset )" ( verbose ) ( count ) ( start ) (confs)
|
|
221
|
+
listmyassets "( asset )" ( verbose ) ( count ) ( start ) (confs)
|
|
191
222
|
purgesnapshot "asset_name" block_height
|
|
192
|
-
reissue "asset_name" qty "to_address" "change_address" ( reissuable ) ( new_units) "( new_ipfs )"
|
|
193
|
-
selfrevokedepin "asset_name"
|
|
223
|
+
reissue "asset_name" qty "to_address" "change_address" ( reissuable ) ( new_units) "( new_ipfs )"
|
|
194
224
|
transfer "asset_name" qty "to_address" "message" expire_time "change_address" "asset_change_address"
|
|
195
225
|
transferfromaddress "asset_name" "from_address" qty "to_address" "message" expire_time "xna_change_address" "asset_change_address"
|
|
196
226
|
transferfromaddresses "asset_name" ["from_addresses"] qty "to_address" "message" expire_time "xna_change_address" "asset_change_address"
|
|
197
|
-
unfreezedepin "asset_name" "address" ("change_address")
|
|
198
227
|
|
|
199
228
|
== Blockchain ==
|
|
200
229
|
clearmempool
|
|
201
230
|
decodeblock "blockhex"
|
|
202
231
|
getbestblockhash
|
|
203
|
-
getblock "blockhash" ( verbosity )
|
|
232
|
+
getblock "blockhash" ( verbosity )
|
|
204
233
|
getblockchaininfo
|
|
205
234
|
getblockcount
|
|
206
235
|
|
|
@@ -214,6 +243,7 @@ getmempoolancestors txid (verbose)
|
|
|
214
243
|
getmempooldescendants txid (verbose)
|
|
215
244
|
getmempoolentry txid
|
|
216
245
|
getmempoolinfo
|
|
246
|
+
getpubkey "address"
|
|
217
247
|
getrawmempool ( verbose )
|
|
218
248
|
getspentinfo
|
|
219
249
|
gettxout "txid" n ( include_mempool )
|
|
@@ -233,6 +263,28 @@ help ( "command" )
|
|
|
233
263
|
stop
|
|
234
264
|
uptime
|
|
235
265
|
|
|
266
|
+
== Depin asset ==
|
|
267
|
+
checkdepinvalidity "asset_name" "address"
|
|
268
|
+
freezedepin "asset_name" "address" ("change_address")
|
|
269
|
+
listdepinholders "asset_name"
|
|
270
|
+
selfrevokedepin "asset_name"
|
|
271
|
+
unfreezedepin "asset_name" "address" ("change_address")
|
|
272
|
+
|
|
273
|
+
== Depin messaging ==
|
|
274
|
+
depinclearmsg ( "all" | hours ) ( "scope" )
|
|
275
|
+
depingetancestorrecipients "token" ( max_results ) ( "stop_at" )
|
|
276
|
+
depingetmsg "token" ("ip[:port]"|"fromaddress") ("fromaddress")
|
|
277
|
+
depingetmsginfo
|
|
278
|
+
depingetpoolcontent ( verbose sender_address recipient_address start_time end_time limit offset )
|
|
279
|
+
depinlistsections ( "address" )
|
|
280
|
+
depinmcpstatus
|
|
281
|
+
depinpoolpkey
|
|
282
|
+
depinpoolstats
|
|
283
|
+
depinreceivemsg "token" "address" (timestamp) ("after_hash") (limit)
|
|
284
|
+
depinsendmsg "token" "ip[:port]" "message" "fromaddress" (port)
|
|
285
|
+
depinsubmitmsg "hexmessage"|{"sender":"...","encrypted":"..."}
|
|
286
|
+
listdepinaddresses "asset_name" (count) (start)
|
|
287
|
+
|
|
236
288
|
== Generating ==
|
|
237
289
|
generate nblocks ( maxtries )
|
|
238
290
|
generatetoaddress nblocks address (maxtries)
|
|
@@ -240,12 +292,12 @@ getgenerate
|
|
|
240
292
|
setgenerate generate ( genproclimit )
|
|
241
293
|
|
|
242
294
|
== Messages ==
|
|
243
|
-
clearmessages
|
|
295
|
+
clearmessages
|
|
244
296
|
sendmessage "channel_name" "ipfs_hash" (expire_time)
|
|
245
|
-
subscribetochannel
|
|
246
|
-
unsubscribefromchannel
|
|
247
|
-
viewallmessagechannels
|
|
248
|
-
viewallmessages
|
|
297
|
+
subscribetochannel
|
|
298
|
+
unsubscribefromchannel
|
|
299
|
+
viewallmessagechannels
|
|
300
|
+
viewallmessages
|
|
249
301
|
|
|
250
302
|
== Mining ==
|
|
251
303
|
getblocktemplate ( TemplateRequest )
|
|
@@ -254,7 +306,7 @@ getmininginfo
|
|
|
254
306
|
getnetworkhashps ( nblocks height )
|
|
255
307
|
pprpcsb "header_hash" "mix_hash" "nonce"
|
|
256
308
|
prioritisetransaction <txid> <dummy value> <fee delta>
|
|
257
|
-
submitblock "hexdata"
|
|
309
|
+
submitblock "hexdata" ( "dummy" )
|
|
258
310
|
|
|
259
311
|
== Network ==
|
|
260
312
|
addnode "node" "add|remove|onetry"
|
|
@@ -265,7 +317,6 @@ getconnectioncount
|
|
|
265
317
|
getnettotals
|
|
266
318
|
getnetworkinfo
|
|
267
319
|
getpeerinfo
|
|
268
|
-
getpubkey "address"
|
|
269
320
|
listbanned
|
|
270
321
|
ping
|
|
271
322
|
setban "subnet" "add|remove" (bantime) (absolute)
|
|
@@ -299,13 +350,13 @@ listglobalrestrictions
|
|
|
299
350
|
listtagsforaddress address
|
|
300
351
|
reissuerestrictedasset "asset_name" qty to_address ( change_verifier ) ( "new_verifier" ) "( change_address )" ( new_units ) ( reissuable ) "( new_ipfs )"
|
|
301
352
|
removetagfromaddress tag_name to_address (change_address) (asset_data)
|
|
302
|
-
transferqualifier "qualifier_name" qty "to_address" ("change_address") ("message") (expire_time)
|
|
353
|
+
transferqualifier "qualifier_name" qty "to_address" ("change_address") ("message") (expire_time)
|
|
303
354
|
unfreezeaddress asset_name address (change_address) (asset_data)
|
|
304
355
|
unfreezerestrictedasset asset_name (change_address) (asset_data)
|
|
305
356
|
|
|
306
357
|
== Restricted ==
|
|
307
|
-
viewmyrestrictedaddresses
|
|
308
|
-
viewmytaggedaddresses
|
|
358
|
+
viewmyrestrictedaddresses
|
|
359
|
+
viewmytaggedaddresses
|
|
309
360
|
|
|
310
361
|
== Rewards ==
|
|
311
362
|
cancelsnapshotrequest "asset_name" block_height
|
|
@@ -330,9 +381,11 @@ addmultisigaddress nrequired ["key",...] ( "account" )
|
|
|
330
381
|
addwitnessaddress "address"
|
|
331
382
|
backupwallet "destination"
|
|
332
383
|
bumpfee has been deprecated on the XNA Wallet.
|
|
384
|
+
dumpextkeypq
|
|
333
385
|
dumpprivkey "address"
|
|
334
386
|
dumpwallet "filename"
|
|
335
387
|
encryptwallet "passphrase"
|
|
388
|
+
exportxpqpub count ( chain offset )
|
|
336
389
|
getaccount "address"
|
|
337
390
|
getaccountaddress "account"
|
|
338
391
|
getaddressesbyaccount "account"
|
|
@@ -361,7 +414,7 @@ listreceivedbyaccount ( minconf include_empty include_watchonly)
|
|
|
361
414
|
listreceivedbyaddress ( minconf include_empty include_watchonly)
|
|
362
415
|
listsinceblock ( "blockhash" target_confirmations include_watchonly include_removed )
|
|
363
416
|
listtransactions ( "account" count skip include_watchonly)
|
|
364
|
-
listunspent ( minconf maxconf
|
|
417
|
+
listunspent ( minconf maxconf ["addresses",...] [include_unsafe] [query_options])
|
|
365
418
|
listwallets
|
|
366
419
|
lockunspent unlock ([{"txid":"txid","vout":n},...])
|
|
367
420
|
move "fromaccount" "toaccount" amount ( minconf "comment" )
|
|
@@ -374,5 +427,4 @@ sendtoaddress "address" amount ( "comment" "comment_to" subtractfeefromamount re
|
|
|
374
427
|
setaccount "address" "account"
|
|
375
428
|
settxfee amount
|
|
376
429
|
signmessage "address" "message"
|
|
377
|
-
|
|
378
430
|
```
|