@neuraiproject/neurai-rpc 0.5.0 → 0.6.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
@@ -1,430 +1,115 @@
1
1
  # neurai-rpc
2
2
 
3
- A package that will help you do RPC calls from Node.js to your Neurai node, that is your full Neurai node.
3
+ JavaScript/TypeScript client for the Neurai JSON-RPC API.
4
4
 
5
- Endpoints for locally installed Neurai nodes.
5
+ ## Endpoints
6
6
 
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)
7
+ - Mainnet node: `http://127.0.0.1:19001`
8
+ - Testnet node: `http://127.0.0.1:19101`
9
+ - Hosted mainnet: `https://rpc-main.neurai.org/rpc`
10
+ - Hosted testnet: `https://rpc-testnet.neurai.org/rpc`
10
11
 
11
- Neurai as a service, you don't need your own node
12
+ DePIN protocol 2 uses the same authenticated HTTP JSON-RPC endpoint. The old
13
+ raw-TCP DePIN gateway and its dedicated port no longer exist.
12
14
 
13
- - https://rpc-main.neurai.org/rpc for mainnet
14
- - https://rpc-testnet.neurai.org/rpc for testnet
15
+ ## Install
15
16
 
16
- # Install
17
-
18
- ```
17
+ ```sh
19
18
  npm install @neuraiproject/neurai-rpc
20
19
  ```
21
20
 
22
- # Standard RPC Usage
23
-
24
- ## Example using ES modules
25
-
26
- This example uses Neurai as a service from https://rpc-main.neurai.org.
21
+ ## Usage
27
22
 
28
- In node.js you need to give the file the ending .mjs for modular JavaScript.
29
- Like `example.mjs`
30
-
31
- ```
23
+ ```js
32
24
  import { getRPC, methods } from "@neuraiproject/neurai-rpc";
33
25
 
34
- const username = "anonymous";
35
- const password = "anonymous";
36
- const URL = "https://rpc-main.neurai.org/rpc";
37
- const rpc = getRPC(username, password, URL);
38
-
39
- const params = [];
40
- rpc(methods.getblockcount, params).then(console.log);
26
+ const rpc = getRPC("username", "password", "http://127.0.0.1:19001");
27
+ const height = await rpc(methods.getblockcount, []);
28
+ console.log(height);
41
29
  ```
42
30
 
43
- ## Example using CommonJS
31
+ CommonJS uses `const { getRPC, methods } = require("@neuraiproject/neurai-rpc")`.
32
+ `getRPC` resolves with the JSON-RPC `result` and rejects HTTP failures and
33
+ JSON-RPC error objects, including errors returned with HTTP status 200.
44
34
 
45
- ```
35
+ ## DePIN protocol 2
46
36
 
47
- const { getRPC, methods } = require("@neuraiproject/neurai-rpc");
48
- //methods is a list of all available methods/functions/commands/procedures
37
+ Use the normal `getRPC` client for every DePIN command:
49
38
 
50
- const rpc = getRPC("UsernameSecret", "PasswordSecret", "http://localhost:19001");
39
+ ```js
40
+ const info = await rpc(methods.depingetmsginfo, []);
41
+ const stats = await rpc(methods.depinpoolstats, []);
51
42
 
52
- const promise = rpc(methods.getassetdata, ["ELVIS"]);
53
- promise.catch((e) => {
54
- console.dir(e);
55
- });
56
-
57
- promise.then((response) => {
58
- console.log(response);
59
- });
60
-
61
-
62
- ```
63
-
64
- will print out
65
-
66
- ```
67
- { name: 'ELVIS', amount: 1, units: 8, reissuable: 1, has_ipfs: 0 }
68
- ```
69
-
70
- # DePIN Messaging Usage (Node.js only)
71
-
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.
78
-
79
- ## Basic DePIN Example
80
-
81
- ```javascript
82
- import { getDePinRPC } from "@neuraiproject/neurai-rpc/depin";
83
-
84
- // Function to sign messages with your private key
85
- async function signMessage(message) {
86
- // Implement your signing logic here
87
- // Return base64-encoded signature
88
- return "signature_base64";
89
- }
90
-
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",
43
+ const sent = await rpc(methods.depinsendmsg, [
44
+ "&FRANCE/GENERAL",
104
45
  "Hello team!",
105
- "NYourAddressHere"
46
+ "NXsender...",
106
47
  ]);
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", []);
112
48
  ```
113
49
 
114
- For complete DePIN examples including error handling and advanced usage, see [DEPIN_EXAMPLES.md](./DEPIN_EXAMPLES.md).
115
-
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.
117
-
118
- ## DePIN Authentication
119
-
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
131
- 5. Server verifies the signature against the address
50
+ Authenticated reads and administrative purges use signed, single-use
51
+ challenges. A wallet-backed flow uses these commands in order:
132
52
 
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.
53
+ 1. `depinsignrequest(address, token, type)`
54
+ 2. `depinchallenge(token, address, timestamp, signature, type)`
55
+ 3. `depindecrypt(address, encrypted)` to recover the challenge
56
+ 4. `depinsignchallenge(address, token, challenge, type)`
57
+ 5. `depinreceivemsg`, `depinlistsections`, or `depinclearmsg`
58
+ 6. Verify `poolsig`, then decrypt the encrypted response
141
59
 
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.
60
+ See [DEPIN_EXAMPLES.md](./DEPIN_EXAMPLES.md) for call sequences and
61
+ [DEPIN_IMPLEMENTATION_GUIDE_EN.md](./DEPIN_IMPLEMENTATION_GUIDE_EN.md) for the
62
+ protocol details.
146
63
 
147
- ## Node compatibility
64
+ ### Method changes
148
65
 
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.
66
+ Added:
153
67
 
154
- ## Example list all generated addresses in a Wallet (Raven core)
68
+ - `depinchallenge`
69
+ - `depinsignrequest` (wallet helper)
70
+ - `depinsignchallenge` (wallet helper)
71
+ - `depindecrypt` (wallet helper)
72
+ - `getibdstatus` (header synchronization diagnostics)
155
73
 
156
- Use method `listreceivedbyaddress` to receive a list of all generated addresses.
157
- Write the result to a .json file
74
+ Changed:
158
75
 
159
- ```
160
- const { getRPC, methods } = require("@neuraiproject/neurai-rpc");
161
- //methods is a list of all available methods/functions/commands/procedures
162
-
163
- const method = methods.listreceivedbyaddress;
164
- const minConfirmations = 1;
165
- const includeEmpty = true;
76
+ - `depinsendmsg(token, message, fromaddress)` is local; host/port parameters
77
+ were removed.
78
+ - `depinreceivemsg` now requires a receive challenge and signature.
79
+ - `depinclearmsg` now requires an admin challenge and signature.
80
+ - Address mode in `depinlistsections` now requires scope, challenge, and
81
+ signature.
82
+ - `depinsubmitmsg` accepts only an encrypted envelope object.
83
+ - `depingetmsg(token, fromaddress?)` is local-wallet only.
166
84
 
167
- const params = [minConfirmations, includeEmpty];
85
+ Removed:
168
86
 
169
- const rpc = getRPC("UsernameSecret", "PasswordSecret", "http://localhost:19001");
87
+ - `depingetpoolcontent`
88
+ - `@neuraiproject/neurai-rpc/depin` and `getDePinRPC`, which implemented the
89
+ retired TCP transport
170
90
 
171
- const promise = rpc(method, params);
172
- promise.catch((e) => {
173
- console.dir(e);
174
- });
91
+ ## Compatibility
175
92
 
176
- promise.then((response) => {
177
- const addresses = [];
178
- response.map(function (obj) {
179
- addresses.push(obj.address);
180
- });
181
- writeToFile(addresses);
182
- console.log("DONE, check out addresses.json");
183
- });
93
+ - DePIN protocol 2 methods require Neurai node 2.0.0 or later.
94
+ - `getibdstatus` requires a node from August 2026 or later.
95
+ - `createrawtransaction` with `refinputs` requires a node from April 2026 or
96
+ later.
97
+ - `dumpextkeypq` and `exportxpqpub` require PQ wallet support.
98
+ - Wallet-only commands are unavailable when the wallet is disabled.
184
99
 
185
- function writeToFile(list){
186
- const json = JSON.stringify(list, null, 4);
187
- require("fs").writeFileSync("./addresses.json", json);
100
+ ## Method catalog
188
101
 
189
- }
102
+ `methods` exposes the supported command names with TypeScript declarations:
190
103
 
104
+ ```js
105
+ await rpc(methods.getibdstatus, []);
106
+ await rpc(methods.checkdepinvalidity, ["&FRANCE", "NXaddress..."]);
191
107
  ```
192
108
 
193
- # Methods / commands / Procedure calls
194
-
195
- Here is a list of all method/commands [All methods](neurai_methods.md)
196
-
197
- In your local Neurai wallet, you can go to
109
+ Generated command documentation is in
110
+ [neurai_methods.md](./neurai_methods.md).
198
111
 
199
- help > debug window > console
112
+ ## Links
200
113
 
201
- type `help`
202
- ..and you get a list of all available commands
203
-
204
- ```
205
- == Addressindex ==
206
- getaddressbalance
207
- getaddressdeltas
208
- getaddressmempool
209
- getaddresstxids
210
- getaddressutxos
211
-
212
- == Assets ==
213
- getassetdata "asset_name"
214
- getcacheinfo
215
- getsnapshot "asset_name" block_height
216
- issue "asset_name" qty "( to_address )" "( change_address )" ( units ) ( reissuable ) ( has_ipfs ) "( ipfs_hash )"
217
- issueunique "root_name" [asset_tags] ( [ipfs_hashes] ) "( to_address )" "( change_address )"
218
- listaddressesbyasset "asset_name" (onlytotal) (count) (start)
219
- listassetbalancesbyaddress "address" (onlytotal) (count) (start)
220
- listassets "( asset )" ( verbose ) ( count ) ( start )
221
- listmyassets "( asset )" ( verbose ) ( count ) ( start ) (confs)
222
- purgesnapshot "asset_name" block_height
223
- reissue "asset_name" qty "to_address" "change_address" ( reissuable ) ( new_units) "( new_ipfs )"
224
- transfer "asset_name" qty "to_address" "message" expire_time "change_address" "asset_change_address"
225
- transferfromaddress "asset_name" "from_address" qty "to_address" "message" expire_time "xna_change_address" "asset_change_address"
226
- transferfromaddresses "asset_name" ["from_addresses"] qty "to_address" "message" expire_time "xna_change_address" "asset_change_address"
227
-
228
- == Blockchain ==
229
- clearmempool
230
- decodeblock "blockhex"
231
- getbestblockhash
232
- getblock "blockhash" ( verbosity )
233
- getblockchaininfo
234
- getblockcount
235
-
236
- getblockhash height
237
- getblockhashes timestamp
238
- getblockheader "hash" ( verbose )
239
- getchaintips
240
- getchaintxstats ( nblocks blockhash )
241
- getdifficulty
242
- getmempoolancestors txid (verbose)
243
- getmempooldescendants txid (verbose)
244
- getmempoolentry txid
245
- getmempoolinfo
246
- getpubkey "address"
247
- getrawmempool ( verbose )
248
- getspentinfo
249
- gettxout "txid" n ( include_mempool )
250
- gettxoutproof ["txid",...] ( blockhash )
251
- gettxoutsetinfo
252
- preciousblock "blockhash"
253
- pruneblockchain
254
- savemempool
255
- verifychain ( checklevel nblocks )
256
- verifytxoutproof "proof"
257
-
258
- == Control ==
259
- getinfo
260
- getmemoryinfo ("mode")
261
- getrpcinfo
262
- help ( "command" )
263
- stop
264
- uptime
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
-
288
- == Generating ==
289
- generate nblocks ( maxtries )
290
- generatetoaddress nblocks address (maxtries)
291
- getgenerate
292
- setgenerate generate ( genproclimit )
293
-
294
- == Messages ==
295
- clearmessages
296
- sendmessage "channel_name" "ipfs_hash" (expire_time)
297
- subscribetochannel
298
- unsubscribefromchannel
299
- viewallmessagechannels
300
- viewallmessages
301
-
302
- == Mining ==
303
- getblocktemplate ( TemplateRequest )
304
- getkawpowhash "header_hash" "mix_hash" nonce, height, "target"
305
- getmininginfo
306
- getnetworkhashps ( nblocks height )
307
- pprpcsb "header_hash" "mix_hash" "nonce"
308
- prioritisetransaction <txid> <dummy value> <fee delta>
309
- submitblock "hexdata" ( "dummy" )
310
-
311
- == Network ==
312
- addnode "node" "add|remove|onetry"
313
- clearbanned
314
- disconnectnode "[address]" [nodeid]
315
- getaddednodeinfo ( "node" )
316
- getconnectioncount
317
- getnettotals
318
- getnetworkinfo
319
- getpeerinfo
320
- listbanned
321
- ping
322
- setban "subnet" "add|remove" (bantime) (absolute)
323
- setnetworkactive true|false
324
-
325
- == Rawtransactions ==
326
- combinerawtransaction ["hexstring",...]
327
- createrawtransaction [{"txid":"id","vout":n},...] {"address":(amount or object),"data":"hex",...}
328
- decoderawtransaction "hexstring"
329
- decodescript "hexstring"
330
- fundrawtransaction "hexstring" ( options )
331
- getrawtransaction "txid" ( verbose )
332
- sendrawtransaction "hexstring" ( allowhighfees )
333
- signrawtransaction "hexstring" ( [{"txid":"id","vout":n,"scriptPubKey":"hex","redeemScript":"hex"},...] ["privatekey1",...] sighashtype )
334
- testmempoolaccept ["rawtxs"] ( allowhighfees )
335
-
336
- == Restricted assets ==
337
- addtagtoaddress tag_name to_address (change_address) (asset_data)
338
- checkaddressrestriction address restricted_name
339
- checkaddresstag address tag_name
340
- checkglobalrestriction restricted_name
341
- freezeaddress asset_name address (change_address) (asset_data)
342
- freezerestrictedasset asset_name (change_address) (asset_data)
343
- getverifierstring restricted_name
344
- issuequalifierasset "asset_name" qty "( to_address )" "( change_address )" ( has_ipfs ) "( ipfs_hash )"
345
- issuerestrictedasset "asset_name" qty "verifier" "to_address" "( change_address )" (units) ( reissuable ) ( has_ipfs ) "( ipfs_hash )"
346
- isvalidverifierstring verifier_string
347
- listaddressesfortag tag_name
348
- listaddressrestrictions address
349
- listglobalrestrictions
350
- listtagsforaddress address
351
- reissuerestrictedasset "asset_name" qty to_address ( change_verifier ) ( "new_verifier" ) "( change_address )" ( new_units ) ( reissuable ) "( new_ipfs )"
352
- removetagfromaddress tag_name to_address (change_address) (asset_data)
353
- transferqualifier "qualifier_name" qty "to_address" ("change_address") ("message") (expire_time)
354
- unfreezeaddress asset_name address (change_address) (asset_data)
355
- unfreezerestrictedasset asset_name (change_address) (asset_data)
356
-
357
- == Restricted ==
358
- viewmyrestrictedaddresses
359
- viewmytaggedaddresses
360
-
361
- == Rewards ==
362
- cancelsnapshotrequest "asset_name" block_height
363
- distributereward "asset_name" snapshot_height "distribution_asset_name" gross_distribution_amount ( "exception_addresses" ) ("change_address") ("dry_run")
364
- getdistributestatus "asset_name" snapshot_height "distribution_asset_name" gross_distribution_amount ( "exception_addresses" )
365
- getsnapshotrequest "asset_name" block_height
366
- listsnapshotrequests ["asset_name" [block_height]]
367
- requestsnapshot "asset_name" block_height
368
-
369
- == Util ==
370
- createmultisig nrequired ["key",...]
371
- estimatefee nblocks
372
- estimatesmartfee conf_target ("estimate_mode")
373
- signmessagewithprivkey "privkey" "message"
374
- validateaddress "address"
375
- verifymessage "address" "signature" "message"
376
-
377
- == Wallet ==
378
- abandontransaction "txid"
379
- abortrescan
380
- addmultisigaddress nrequired ["key",...] ( "account" )
381
- addwitnessaddress "address"
382
- backupwallet "destination"
383
- bumpfee has been deprecated on the XNA Wallet.
384
- dumpextkeypq
385
- dumpprivkey "address"
386
- dumpwallet "filename"
387
- encryptwallet "passphrase"
388
- exportxpqpub count ( chain offset )
389
- getaccount "address"
390
- getaccountaddress "account"
391
- getaddressesbyaccount "account"
392
- getbalance ( "account" minconf include_watchonly )
393
- getmasterkeyinfo
394
- getmywords ( "account" )
395
- getnewaddress ( "account" )
396
- getrawchangeaddress
397
- getreceivedbyaccount "account" ( minconf )
398
- getreceivedbyaddress "address" ( minconf )
399
- gettransaction "txid" ( include_watchonly )
400
- getunconfirmedbalance
401
- getwalletinfo
402
- importaddress "address" ( "label" rescan p2sh )
403
- importmulti "requests" ( "options" )
404
- importprivkey "privkey" ( "label" ) ( rescan )
405
- importprunedfunds
406
- importpubkey "pubkey" ( "label" rescan )
407
- importwallet "filename"
408
- keypoolrefill ( newsize )
409
- listaccounts ( minconf include_watchonly)
410
- listaddressgroupings
411
- listlockunspent
412
- listpqaddresses
413
- listreceivedbyaccount ( minconf include_empty include_watchonly)
414
- listreceivedbyaddress ( minconf include_empty include_watchonly)
415
- listsinceblock ( "blockhash" target_confirmations include_watchonly include_removed )
416
- listtransactions ( "account" count skip include_watchonly)
417
- listunspent ( minconf maxconf ["addresses",...] [include_unsafe] [query_options])
418
- listwallets
419
- lockunspent unlock ([{"txid":"txid","vout":n},...])
420
- move "fromaccount" "toaccount" amount ( minconf "comment" )
421
- removeprunedfunds "txid"
422
- rescanblockchain ("start_height") ("stop_height")
423
- sendfrom "fromaccount" "toaddress" amount ( minconf "comment" "comment_to" )
424
- sendfromaddress "from_address" "to_address" amount ( "comment" "comment_to" subtractfeefromamount replaceable conf_target "estimate_mode")
425
- sendmany "fromaccount" {"address":amount,...} ( minconf "comment" ["address",...] replaceable conf_target "estimate_mode")
426
- sendtoaddress "address" amount ( "comment" "comment_to" subtractfeefromamount replaceable conf_target "estimate_mode")
427
- setaccount "address" "account"
428
- settxfee amount
429
- signmessage "address" "message"
430
- ```
114
+ - [GitHub repository](https://github.com/neuraiproject/neurai-rpc)
115
+ - [NPM package](https://www.npmjs.com/package/@neuraiproject/neurai-rpc)