@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/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,30 +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
- });
92
-
93
- // Send a DePIN message
94
- const result = await depinRPC("depinsendmsg", ["SEND", "ipfs_hash", 3600]);
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 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).
99
115
 
100
- ## DePIN Authentication
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
- Port 19002 uses a challenge-response authentication protocol:
118
+ ## DePIN Authentication
103
119
 
104
- 1. Client requests a challenge from the server
105
- 2. Server returns a random challenge string with expiration time (60 seconds)
106
- 3. Client signs the challenge with their private key
107
- 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
108
131
  5. Server verifies the signature against the address
109
132
 
110
- 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.
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" ( "dummy" )
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 ["addresses",...] [include_unsafe] [query_options])
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
  ```