@neuraiproject/neurai-rpc 0.4.6 → 0.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +103 -20
- package/DEPIN_EXAMPLES.md +148 -220
- package/DEPIN_IMPLEMENTATION_GUIDE_EN.md +278 -80
- package/README.md +106 -40
- 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 +5241 -4892
- package/dist/{types.d.ts → index.d.cts} +12 -63
- package/dist/index.d.ts +200 -0
- package/dist/index.mjs +5214 -4884
- package/docs.json +140 -132
- package/docs.ts +544 -43
- package/index.ts +13 -9
- package/neurai_methods.md +504 -43
- 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,30 +88,68 @@ async function signMessage(message) {
|
|
|
84
88
|
return "signature_base64";
|
|
85
89
|
}
|
|
86
90
|
|
|
87
|
-
const depinRPC =
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
91
|
+
const depinRPC = getDePinRPC(
|
|
92
|
+
{ host: "127.0.0.1", port: 19002 },
|
|
93
|
+
{
|
|
94
|
+
token: "&FRANCE",
|
|
95
|
+
address: "NYourAddressHere",
|
|
96
|
+
signMessage: signMessage,
|
|
97
|
+
}
|
|
98
|
+
);
|
|
99
|
+
|
|
100
|
+
// Send a DePIN message (challenge/signature handled automatically)
|
|
101
|
+
const result = await depinRPC("depinsendmsg", [
|
|
102
|
+
"&FRANCE",
|
|
103
|
+
"192.168.1.100:19002",
|
|
104
|
+
"Hello team!",
|
|
105
|
+
"NYourAddressHere"
|
|
106
|
+
]);
|
|
95
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", []);
|
|
96
112
|
```
|
|
97
113
|
|
|
98
|
-
For complete DePIN examples including
|
|
114
|
+
For complete DePIN examples including error handling and advanced usage, see [DEPIN_EXAMPLES.md](./DEPIN_EXAMPLES.md).
|
|
99
115
|
|
|
100
|
-
|
|
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.
|
|
101
117
|
|
|
102
|
-
|
|
118
|
+
## DePIN Authentication
|
|
103
119
|
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
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
|
|
108
131
|
5. Server verifies the signature against the address
|
|
109
132
|
|
|
110
|
-
|
|
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.
|
|
111
153
|
|
|
112
154
|
## Example list all generated addresses in a Wallet (Raven core)
|
|
113
155
|
|
|
@@ -169,16 +211,16 @@ getaddressutxos
|
|
|
169
211
|
|
|
170
212
|
== Assets ==
|
|
171
213
|
getassetdata "asset_name"
|
|
172
|
-
getcacheinfo
|
|
214
|
+
getcacheinfo
|
|
173
215
|
getsnapshot "asset_name" block_height
|
|
174
216
|
issue "asset_name" qty "( to_address )" "( change_address )" ( units ) ( reissuable ) ( has_ipfs ) "( ipfs_hash )"
|
|
175
217
|
issueunique "root_name" [asset_tags] ( [ipfs_hashes] ) "( to_address )" "( change_address )"
|
|
176
218
|
listaddressesbyasset "asset_name" (onlytotal) (count) (start)
|
|
177
219
|
listassetbalancesbyaddress "address" (onlytotal) (count) (start)
|
|
178
220
|
listassets "( asset )" ( verbose ) ( count ) ( start )
|
|
179
|
-
listmyassets "( asset )" ( verbose ) ( count ) ( start ) (confs)
|
|
221
|
+
listmyassets "( asset )" ( verbose ) ( count ) ( start ) (confs)
|
|
180
222
|
purgesnapshot "asset_name" block_height
|
|
181
|
-
reissue "asset_name" qty "to_address" "change_address" ( reissuable ) ( new_units) "( new_ipfs )"
|
|
223
|
+
reissue "asset_name" qty "to_address" "change_address" ( reissuable ) ( new_units) "( new_ipfs )"
|
|
182
224
|
transfer "asset_name" qty "to_address" "message" expire_time "change_address" "asset_change_address"
|
|
183
225
|
transferfromaddress "asset_name" "from_address" qty "to_address" "message" expire_time "xna_change_address" "asset_change_address"
|
|
184
226
|
transferfromaddresses "asset_name" ["from_addresses"] qty "to_address" "message" expire_time "xna_change_address" "asset_change_address"
|
|
@@ -187,7 +229,7 @@ transferfromaddresses "asset_name" ["from_addresses"] qty "to_address" "message"
|
|
|
187
229
|
clearmempool
|
|
188
230
|
decodeblock "blockhex"
|
|
189
231
|
getbestblockhash
|
|
190
|
-
getblock "blockhash" ( verbosity )
|
|
232
|
+
getblock "blockhash" ( verbosity )
|
|
191
233
|
getblockchaininfo
|
|
192
234
|
getblockcount
|
|
193
235
|
|
|
@@ -201,6 +243,7 @@ getmempoolancestors txid (verbose)
|
|
|
201
243
|
getmempooldescendants txid (verbose)
|
|
202
244
|
getmempoolentry txid
|
|
203
245
|
getmempoolinfo
|
|
246
|
+
getpubkey "address"
|
|
204
247
|
getrawmempool ( verbose )
|
|
205
248
|
getspentinfo
|
|
206
249
|
gettxout "txid" n ( include_mempool )
|
|
@@ -220,6 +263,28 @@ help ( "command" )
|
|
|
220
263
|
stop
|
|
221
264
|
uptime
|
|
222
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
|
+
|
|
223
288
|
== Generating ==
|
|
224
289
|
generate nblocks ( maxtries )
|
|
225
290
|
generatetoaddress nblocks address (maxtries)
|
|
@@ -227,12 +292,12 @@ getgenerate
|
|
|
227
292
|
setgenerate generate ( genproclimit )
|
|
228
293
|
|
|
229
294
|
== Messages ==
|
|
230
|
-
clearmessages
|
|
295
|
+
clearmessages
|
|
231
296
|
sendmessage "channel_name" "ipfs_hash" (expire_time)
|
|
232
|
-
subscribetochannel
|
|
233
|
-
unsubscribefromchannel
|
|
234
|
-
viewallmessagechannels
|
|
235
|
-
viewallmessages
|
|
297
|
+
subscribetochannel
|
|
298
|
+
unsubscribefromchannel
|
|
299
|
+
viewallmessagechannels
|
|
300
|
+
viewallmessages
|
|
236
301
|
|
|
237
302
|
== Mining ==
|
|
238
303
|
getblocktemplate ( TemplateRequest )
|
|
@@ -241,7 +306,7 @@ getmininginfo
|
|
|
241
306
|
getnetworkhashps ( nblocks height )
|
|
242
307
|
pprpcsb "header_hash" "mix_hash" "nonce"
|
|
243
308
|
prioritisetransaction <txid> <dummy value> <fee delta>
|
|
244
|
-
submitblock "hexdata"
|
|
309
|
+
submitblock "hexdata" ( "dummy" )
|
|
245
310
|
|
|
246
311
|
== Network ==
|
|
247
312
|
addnode "node" "add|remove|onetry"
|
|
@@ -252,7 +317,6 @@ getconnectioncount
|
|
|
252
317
|
getnettotals
|
|
253
318
|
getnetworkinfo
|
|
254
319
|
getpeerinfo
|
|
255
|
-
getpubkey "address"
|
|
256
320
|
listbanned
|
|
257
321
|
ping
|
|
258
322
|
setban "subnet" "add|remove" (bantime) (absolute)
|
|
@@ -286,13 +350,13 @@ listglobalrestrictions
|
|
|
286
350
|
listtagsforaddress address
|
|
287
351
|
reissuerestrictedasset "asset_name" qty to_address ( change_verifier ) ( "new_verifier" ) "( change_address )" ( new_units ) ( reissuable ) "( new_ipfs )"
|
|
288
352
|
removetagfromaddress tag_name to_address (change_address) (asset_data)
|
|
289
|
-
transferqualifier "qualifier_name" qty "to_address" ("change_address") ("message") (expire_time)
|
|
353
|
+
transferqualifier "qualifier_name" qty "to_address" ("change_address") ("message") (expire_time)
|
|
290
354
|
unfreezeaddress asset_name address (change_address) (asset_data)
|
|
291
355
|
unfreezerestrictedasset asset_name (change_address) (asset_data)
|
|
292
356
|
|
|
293
357
|
== Restricted ==
|
|
294
|
-
viewmyrestrictedaddresses
|
|
295
|
-
viewmytaggedaddresses
|
|
358
|
+
viewmyrestrictedaddresses
|
|
359
|
+
viewmytaggedaddresses
|
|
296
360
|
|
|
297
361
|
== Rewards ==
|
|
298
362
|
cancelsnapshotrequest "asset_name" block_height
|
|
@@ -317,9 +381,11 @@ addmultisigaddress nrequired ["key",...] ( "account" )
|
|
|
317
381
|
addwitnessaddress "address"
|
|
318
382
|
backupwallet "destination"
|
|
319
383
|
bumpfee has been deprecated on the XNA Wallet.
|
|
384
|
+
dumpextkeypq
|
|
320
385
|
dumpprivkey "address"
|
|
321
386
|
dumpwallet "filename"
|
|
322
387
|
encryptwallet "passphrase"
|
|
388
|
+
exportxpqpub count ( chain offset )
|
|
323
389
|
getaccount "address"
|
|
324
390
|
getaccountaddress "account"
|
|
325
391
|
getaddressesbyaccount "account"
|
|
@@ -343,11 +409,12 @@ keypoolrefill ( newsize )
|
|
|
343
409
|
listaccounts ( minconf include_watchonly)
|
|
344
410
|
listaddressgroupings
|
|
345
411
|
listlockunspent
|
|
412
|
+
listpqaddresses
|
|
346
413
|
listreceivedbyaccount ( minconf include_empty include_watchonly)
|
|
347
414
|
listreceivedbyaddress ( minconf include_empty include_watchonly)
|
|
348
415
|
listsinceblock ( "blockhash" target_confirmations include_watchonly include_removed )
|
|
349
416
|
listtransactions ( "account" count skip include_watchonly)
|
|
350
|
-
listunspent ( minconf maxconf
|
|
417
|
+
listunspent ( minconf maxconf ["addresses",...] [include_unsafe] [query_options])
|
|
351
418
|
listwallets
|
|
352
419
|
lockunspent unlock ([{"txid":"txid","vout":n},...])
|
|
353
420
|
move "fromaccount" "toaccount" amount ( minconf "comment" )
|
|
@@ -360,5 +427,4 @@ sendtoaddress "address" amount ( "comment" "comment_to" subtractfeefromamount re
|
|
|
360
427
|
setaccount "address" "account"
|
|
361
428
|
settxfee amount
|
|
362
429
|
signmessage "address" "message"
|
|
363
|
-
|
|
364
430
|
```
|