@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/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
- URLs for locally installed Neurai nodes.
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:19002 for mainnet (DePIN Messaging)
9
- - http://127.0.0.1:19101 for testnet (Standard RPC)
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 port 19002 and requires cryptographic signature authentication instead of username/password.
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 = await getDePinRPC({
88
- depinUrl: "http://localhost:19002",
89
- address: "NYourAddressHere",
90
- signMessage: signMessage
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 browser wallet integration, error handling, and advanced usage, see [DEPIN_EXAMPLES.md](./DEPIN_EXAMPLES.md).
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 can be any asset. Separately, the dedicated DePIN asset-management RPCs work with the newer `&ASSET` DePIN asset type, which is soulbound, documented here as enabled for mainnet and testnet, and must use `units=0`.
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
- Port 19002 uses a challenge-response authentication protocol:
110
-
111
- 1. Client requests a challenge from the server
112
- 2. Server returns a random challenge string with expiration time (60 seconds)
113
- 3. Client signs the challenge with their private key
114
- 4. Client sends RPC request with address and signature
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
- The `getDePinRPC` function handles this authentication flow automatically, including challenge caching and automatic retry on expiration.
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
- listdepinaddresses "asset_name" (count) (start)
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" ( "dummy" )
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 ["addresses",...] [include_unsafe] [query_options])
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
  ```