@neuraiproject/neurai-rpc 0.5.1 → 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/dist/index.cjs CHANGED
@@ -722,35 +722,36 @@ var methods = {
722
722
  > curl --user myusername --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "decodescript", "params": ["hexstring"] }' -H 'content-type: text/plain;' http://127.0.0.1:19001/
723
723
  **/
724
724
  decodescript: "decodescript",
725
- /** depinclearmsg ( "all" | hours ) ( "scope" )
725
+ /** depinchallenge "token" "address" timestamp "signature" ( "type" )
726
726
 
727
- Remove messages from DePIN messaging pool
727
+ Issues a single-use challenge for authenticated DePIN RPCs. The request must be signed over:
728
+ "DEPIN-REQ|<type>|<token>|<address>|<timestamp>", where timestamp is Unix time in milliseconds and type is "receive" (default) or "admin".
728
729
 
729
- Arguments:
730
- 1. mode (string or numeric, optional) Cleanup mode:
731
- - omitted: Remove only expired messages (default)
732
- - "all": Remove ALL messages from pool
733
- - <hours>: Remove messages older than specified hours (numeric)
734
- 2. scope (string, optional) Section token. When given, only messages of that
735
- section's subtree are removed; parents and siblings are untouched.
736
- Omitted or "" keeps the historical pool-wide behavior.
730
+ The encrypted result contains challenge, expires_in and type. Decrypt it with depindecrypt, then sign the challenge with depinsignchallenge or signmessage.
731
+
732
+ Examples:
733
+ > neurai-cli depinchallenge "&TOKEN/SECTION" "NXholder..." 1730000000000 "<signature>"
734
+ **/
735
+ depinchallenge: "depinchallenge",
736
+ /** depinclearmsg "scope" "address" "challenge" "signature" ( "all" | hours )
737
+
738
+ Removes messages from a DePIN pool. This owner-level operation requires an admin challenge issued for the exact scope. Use an empty scope for the pool root. Omit mode to remove expired messages, use "all" to remove every message in scope, or pass an age in hours.
737
739
 
738
740
  Result:
739
741
  {
740
- "removed": n, (numeric) Number of messages removed
741
- "remaining": n (numeric) Number of messages remaining
742
+ "removed": n,
743
+ "remaining": n
742
744
  }
743
-
744
- Examples:
745
- > neurai-cli depinclearmsg
746
- > neurai-cli depinclearmsg "all"
747
- > neurai-cli depinclearmsg 7
748
- > neurai-cli depinclearmsg "all" "&TOKEN/GENERAL"
749
- > curl --user myusername --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "depinclearmsg", "params": [] }' -H 'content-type: text/plain;' http://127.0.0.1:19001/
750
- > curl --user myusername --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "depinclearmsg", "params": ["all"] }' -H 'content-type: text/plain;' http://127.0.0.1:19001/
751
- > curl --user myusername --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "depinclearmsg", "params": [7] }' -H 'content-type: text/plain;' http://127.0.0.1:19001/
752
745
  **/
753
746
  depinclearmsg: "depinclearmsg",
747
+ /** depindecrypt "address" "encrypted"
748
+
749
+ Decrypts an encrypted DePIN reply with a wallet key. Verify the reply's poolsig before using this method; depindecrypt does not verify it.
750
+
751
+ Result:
752
+ The decrypted JSON value, or a string when the plaintext is not JSON.
753
+ **/
754
+ depindecrypt: "depindecrypt",
754
755
  /** depingetancestorrecipients "token" ( max_results ) ( "stop_at" )
755
756
 
756
757
  List the active holders of a DEPIN branch: the deduplicated union of the
@@ -809,155 +810,19 @@ var methods = {
809
810
  > curl --user myusername --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "depingetancestorrecipients", "params": ["&TEST/APPLE/GOLDEN", 50, "&TEST/APPLE"] }' -H 'content-type: text/plain;' http://127.0.0.1:19001/
810
811
  **/
811
812
  depingetancestorrecipients: "depingetancestorrecipients",
812
- /** depingetmsg "token" ("ip[:port]"|"fromaddress") ("fromaddress")
813
-
814
- Retrieve and decrypt DePIN messages for your addresses
815
-
816
- Arguments:
817
- 1. "token" (string, required) Token name
818
- 2. "ip[:port]" OR "fromaddress" (string, optional)
819
- - IP address with optional port (e.g., "192.168.1.31" or "192.168.1.31:19002")
820
- - OR Neurai address for local query with specific address
821
- - Omit for local query with all addresses
822
- 3. "fromaddress" (string, optional) Specific address to decrypt with (only if arg 2 is an IP)
813
+ /** depingetmsg "token" ( "fromaddress" )
823
814
 
824
- Result:
825
- [
826
- {
827
- "recipient": "address", (string) Recipient address (your address)
828
- "sender": "address", (string) Sender address
829
- "message": "text", (string) Decrypted message
830
- "timestamp": n, (numeric) Unix timestamp
831
- "date": "YYYY-MM-DD HH:MM:SS", (string) Formatted date
832
- "expires": "YYYY-MM-DD HH:MM:SS" (string) Expiration date
833
- },
834
- ...
835
- ]
836
-
837
- Examples:
838
- > neurai-cli depingetmsg "MYTOKEN"
839
- > neurai-cli depingetmsg "MYTOKEN" "NXyouraddress..."
840
- > neurai-cli depingetmsg "MYTOKEN" "192.168.1.78"
841
- > neurai-cli depingetmsg "MYTOKEN" "192.168.1.78:19002" "NXyouraddress..."
842
- > curl --user myusername --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "depingetmsg", "params": ["MYTOKEN"] }' -H 'content-type: text/plain;' http://127.0.0.1:19001/
815
+ Uses the local node wallet to decrypt messages from the local DePIN pool. The optional address must belong to the wallet and hold the requested token or a related branch token.
843
816
  **/
844
817
  depingetmsg: "depingetmsg",
845
818
  /** depingetmsginfo
846
819
 
847
- Returns information about the DePIN messaging system
848
-
849
- Result:
850
- {
851
- "enabled": true|false, (boolean) Whether DePIN messaging is enabled
852
- "token": "name", (string) Active token name
853
- "port": n, (numeric) Listening port
854
- "cipher": "name", (string) Encryption cipher used by the pool
855
- "maxrecipients": n, (numeric) Maximum recipients per message
856
- "maxmessagesize": n, (numeric) Maximum message size in bytes
857
- "messageexpiryhours": n, (numeric) Message expiry time in hours
858
- "maxpoolsizemb": n, (numeric) Maximum pool size in MB
859
- "messages": n, (numeric) Number of messages in mempool
860
- "memoryusage": n, (numeric) Memory usage in bytes
861
- "memoryusagemb": n, (numeric) Memory usage in MB
862
- "oldestmessage": "time", (string) Timestamp of oldest message
863
- "newestmessage": "time" (string) Timestamp of newest message
864
- }
865
-
866
- Examples:
867
- > neurai-cli depingetmsginfo
868
- > curl --user myusername --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "depingetmsginfo", "params": [] }' -H 'content-type: text/plain;' http://127.0.0.1:19001/
820
+ Returns DePIN protocol and pool configuration. Protocol 2 publishes depinpoolpkey in this response; clients should pin it on first use. Responses are signed with the pool key.
869
821
  **/
870
822
  depingetmsginfo: "depingetmsginfo",
871
- /** depingetpoolcontent ( verbose sender_address recipient_address start_time end_time limit offset )
872
-
873
- Inspect the contents of the DePIN message pool.
874
-
875
- Arguments:
876
- 1. verbose (boolean, "all", or "raw", optional, default=false) Show detailed message structure. Use "all" for all messages, "raw" to show encrypted hex data
877
- 2. sender_address (string, optional) Filter by sender address
878
- 3. recipient_address (string, optional) Filter by recipient address
879
- 4. start_time (numeric, optional) Filter messages after timestamp
880
- 5. end_time (numeric, optional) Filter messages before timestamp
881
- 6. limit (numeric, optional, default=100) Maximum messages to return
882
- 7. offset (numeric, optional, default=0) Skip first N messages
883
-
884
- Result (verbose=false):
885
- [
886
- {
887
- "hash": "hex",
888
- "sender": "address",
889
- "message_type": "private|group",
890
- "timestamp": n,
891
- "date": "YYYY-MM-DD HH:MM:SS",
892
- "expires": "YYYY-MM-DD HH:MM:SS",
893
- "recipients": n,
894
- "size": n
895
- },
896
- ...
897
- ]
898
-
899
- Result (verbose=true):
900
- [
901
- {
902
- "hash": "hex",
903
- "sender": "address",
904
- "message_type": "private|group",
905
- "timestamp": n,
906
- "date": "YYYY-MM-DD HH:MM:SS",
907
- "expires": "YYYY-MM-DD HH:MM:SS",
908
- "recipients": [
909
- {
910
- "address": "address",
911
- "encrypted_size": n
912
- },
913
- ...
914
- ],
915
- "signature_size": n,
916
- "total_encrypted_size": n,
917
- "total_size": n
918
- },
919
- ...
920
- ]
823
+ /** depinlistsections ( "address" "scope" "challenge" "signature" )
921
824
 
922
- Examples:
923
- > neurai-cli depingetpoolcontent
924
- > neurai-cli depingetpoolcontent true
925
- > neurai-cli depingetpoolcontent all
926
- > neurai-cli depingetpoolcontent raw
927
- > neurai-cli depingetpoolcontent false "NXXaddress..."
928
- > curl --user myusername --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "depingetpoolcontent", "params": [true] }' -H 'content-type: text/plain;' http://127.0.0.1:19001/
929
- **/
930
- depingetpoolcontent: "depingetpoolcontent",
931
- /** depinlistsections ( "address" )
932
-
933
- List the sections (sub-assets) of the pool's active token, for UI tabs.
934
- The list is served from a per-tip snapshot; section names are public on
935
- chain, so no address is needed to see them. Message counters, however,
936
- are only exposed for sections the given address has access to -- counts
937
- of an unreadable section would leak metadata. For the same reason the
938
- address mode is only served over node RPC: the DePIN port is
939
- unauthenticated and answers the bare form (names only) there.
940
-
941
- Arguments:
942
- 1. "address" (string, optional) Report this address's access per section
943
-
944
- Result:
945
- [
946
- {
947
- "name": "&TOKEN/GENERAL", (string) Full section token
948
- "label": "GENERAL", (string) Name relative to the pool root ("" = root)
949
- "depth": n, (numeric) Levels below the pool root (0 = root)
950
- "access": true|false, (boolean, only with address) Active inherited access
951
- "messages": n (numeric, only with address and access) Messages in
952
- this section's subtree
953
- },
954
- ...
955
- ]
956
-
957
- Examples:
958
- > neurai-cli depinlistsections
959
- > neurai-cli depinlistsections "NXyouraddress..."
960
- > curl --user myusername --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "depinlistsections", "params": [] }' -H 'content-type: text/plain;' http://127.0.0.1:19001/
825
+ With no arguments, lists public section names. Address mode requires all four arguments, authenticates with a receive challenge for scope, limits results to that subtree, and returns encrypted personal access and message counters.
961
826
  **/
962
827
  depinlistsections: "depinlistsections",
963
828
  /** depinmcpstatus
@@ -990,23 +855,14 @@ var methods = {
990
855
  depinmcpstatus: "depinmcpstatus",
991
856
  /** depinpoolpkey
992
857
 
993
- Returns the public key of the DePIN pool address from the internal wallet.
994
- This command only works if the wallet is loaded and unlocked at node startup.
995
-
996
- Derived path:
997
- Mainnet: m/44'/0'/200'/0/0
998
- Testnet: m/44'/0'/200'/1/0
858
+ Wallet-only operator helper that derives the dedicated DePIN pool public key from the loaded service wallet.
999
859
 
1000
860
  Result:
1001
861
  {
1002
- "pubkey": "hex", (string) Public key in hex format
1003
- "address": "address", (string) Corresponding Neurai address
1004
- "path": "derivation_path" (string) BIP44 derivation path used
862
+ "pubkey": "hex",
863
+ "address": "address",
864
+ "path": "derivation_path"
1005
865
  }
1006
-
1007
- Examples:
1008
- > neurai-cli depinpoolpkey
1009
- > curl --user myusername --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "depinpoolpkey", "params": [] }' -H 'content-type: text/plain;' http://127.0.0.1:19001/
1010
866
  **/
1011
867
  depinpoolpkey: "depinpoolpkey",
1012
868
  /** depinpoolstats
@@ -1039,109 +895,42 @@ var methods = {
1039
895
  > curl --user myusername --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "depinpoolstats", "params": [] }' -H 'content-type: text/plain;' http://127.0.0.1:19001/
1040
896
  **/
1041
897
  depinpoolstats: "depinpoolstats",
1042
- /** depinreceivemsg "token" "address" (timestamp) ("after_hash") (limit)
1043
-
1044
- Retrieve DePIN messages from the pool with optional pagination
1045
-
1046
- This endpoint returns the messages. If the server has a DePIN pool key
1047
- and the requester's address has a revealed public key, the response will be
1048
- fully encrypted using the privacy layer.
1049
-
1050
- Arguments:
1051
- 1. "token" (string, required) Token name
1052
- 2. "address" (string, required) Neurai address (used as access selector and encryption target)
1053
- 3. timestamp (numeric, optional) Unix time. Return only messages with timestamp >= (timestamp-1 if timestamp>0)
1054
- 4. "after_hash" (string, optional) Hash of last received message for pagination. Empty "" starts from beginning
1055
- 5. limit (numeric, optional) Maximum messages to return. 0 or omitted = no limit (return all)
1056
-
1057
- Result (without pagination - backward compatible):
1058
- [
1059
- {
1060
- "hash": "...", (string) Message hash
1061
- "token": "...", (string) Token
1062
- "sender": "...", (string) Sender address
1063
- "timestamp": n, (numeric) Unix timestamp
1064
- "message_type": "private|group", (string) Message type (private=1-to-1, group=broadcast)
1065
- "encrypted_payload_hex": "...", (string) Encrypted payload (hex)
1066
- "signature_hex": "..." (string) Message signature (hex)
1067
- },
1068
- ...
1069
- ]
1070
-
1071
- Result (with pagination - when limit > 0):
1072
- {
1073
- "messages": [...], (array) Array of message objects (same structure as above)
1074
- "has_more": true|false (boolean) Whether more messages are available
1075
- }
1076
-
1077
- Note: Both message types are filtered by recipientKeys membership; the sender always sees their own messages.
898
+ /** depinreceivemsg "token" "address" "challenge" "signature" ( timestamp "after_hash" limit )
1078
899
 
1079
- Result (privacy layer active):
1080
- {
1081
- "encrypted": "hex_blob" (string) Full JSON response encrypted with ECIES
1082
- }
1083
-
1084
- Examples:
1085
- > neurai-cli depinreceivemsg "TOKEN" "NeuraiAddress"
1086
- > neurai-cli depinreceivemsg "TOKEN" "NeuraiAddress" 1730000000
1087
- > neurai-cli depinreceivemsg "TOKEN" "NeuraiAddress" 0 "" 5
1088
- > neurai-cli depinreceivemsg "TOKEN" "NeuraiAddress" 0 "abc123..." 5
1089
- > curl --user myusername --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "depinreceivemsg", "params": ["TOKEN", "NeuraiAddress", 0, "", 5] }' -H 'content-type: text/plain;' http://127.0.0.1:19001/
900
+ Returns messages accessible to an address, encrypted for its revealed public key and signed by the pool key. Requires a receive challenge. Pagination uses timestamp, after_hash and limit. The decrypted reply includes next_challenge for subsequent calls.
1090
901
  **/
1091
902
  depinreceivemsg: "depinreceivemsg",
1092
- /** depinsendmsg "token" "ip[:port]" "message" "fromaddress" (port)
903
+ /** depinsendmsg "token" "message" "fromaddress"
1093
904
 
1094
- Send an encrypted message through a remote DePIN gateway (challenge/response)
905
+ Uses the local node wallet to sign and encrypt a message for eligible recipients, then adds it to the local DePIN pool. Remote host and port parameters were removed in protocol 2.
906
+ **/
907
+ depinsendmsg: "depinsendmsg",
908
+ /** depinsignchallenge "address" "token" "challenge" ( "type" )
1095
909
 
1096
- Arguments:
1097
- 1. "token" (string, required) Token name
1098
- 2. "ip[:port]" (string, required) Target node address (optional :port to contact remote gateway)
1099
- 3. "message" (string, required) Message to send (max 1KB)
1100
- 4. "fromaddress" (string, required) Wallet address used for signing/encryption
1101
- 5. port (numeric, optional) Destination message port (defaults to 19002). Only used when specified after fromaddress
910
+ Wallet helper that signs "DEPIN-GET|<token>|<address>|<challenge>" for receive access or "DEPIN-CLEAR|..." for admin access.
1102
911
 
1103
912
  Result:
1104
913
  {
1105
- "result": "success", (string) Status
1106
- "hash": "hash", (string) Message hash
1107
- "recipients": n, (numeric) Number of recipients
1108
- "timestamp": n (numeric) Message timestamp
914
+ "signature": "base64",
915
+ "preimage": "text"
1109
916
  }
1110
-
1111
- Examples:
1112
- > neurai-cli depinsendmsg "MYTOKEN" "192.168.1.100" "Hello team!" "NXsender..."
1113
- > neurai-cli depinsendmsg "MYTOKEN" "192.168.1.100:19005" "Hello team!" "NXsender..." 19005
1114
- > curl --user myusername --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "depinsendmsg", "params": ["MYTOKEN", "192.168.1.100", "Hello team!", "NXsender..."] }' -H 'content-type: text/plain;' http://127.0.0.1:19001/
1115
917
  **/
1116
- depinsendmsg: "depinsendmsg",
1117
- /** depinsubmitmsg "hexmessage"|{"sender":"...","encrypted":"..."}
918
+ depinsignchallenge: "depinsignchallenge",
919
+ /** depinsignrequest "address" "token" ( "type" )
1118
920
 
1119
- Submit a pre-encrypted and signed DePIN message to the pool
1120
-
1121
- This is the secure protocol where the client prepares the complete message
1122
- (encryption + signature) and the server only validates and stores it.
1123
-
1124
- This command also supports an optional privacy layer where the entire message
1125
- is wrapped in a second layer of encryption for the server's pool key.
1126
-
1127
- Arguments:
1128
- 1. "hexmessage" (string) Hex-encoded serialized CDepinMessage
1129
- OR
1130
- { (json object) Wrapped encrypted message
1131
- "sender": "...", (string, required) Sender address
1132
- "encrypted": "..." (string, required) Hex-encoded ECIES wrapper
1133
- }
921
+ Wallet helper that signs a depinchallenge request over the current Unix time in milliseconds.
1134
922
 
1135
923
  Result:
1136
924
  {
1137
- "result": "success", (string) Status
1138
- "hash": "hash", (string) Message hash
1139
- "timestamp": n (numeric) Unix timestamp
925
+ "timestamp": n,
926
+ "signature": "base64",
927
+ "preimage": "DEPIN-REQ|..."
1140
928
  }
929
+ **/
930
+ depinsignrequest: "depinsignrequest",
931
+ /** depinsubmitmsg {"sender":"...","encrypted":"..."}
1141
932
 
1142
- Examples:
1143
- > neurai-cli depinsubmitmsg "0a3f2e..."
1144
- > curl --user myusername --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "depinsubmitmsg", "params": [{"sender":"NX...","encrypted":"..."}] }' -H 'content-type: text/plain;' http://127.0.0.1:19001/
933
+ Submits a client-prepared, signed DePIN message wrapped in an ECIES envelope for the pool key published by depingetmsginfo. Bare serialized hex is no longer accepted.
1145
934
  **/
1146
935
  depinsubmitmsg: "depinsubmitmsg",
1147
936
  /** disconnectnode "[address]" [nodeid]
@@ -2243,6 +2032,27 @@ var methods = {
2243
2032
  > curl --user myusername --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "getgenerate", "params": [] }' -H 'content-type: text/plain;' http://127.0.0.1:19001/
2244
2033
  **/
2245
2034
  getgenerate: "getgenerate",
2035
+ /** getibdstatus
2036
+
2037
+ Returns header synchronization timing collected since process start.
2038
+
2039
+ Result:
2040
+ {
2041
+ "blocks": n,
2042
+ "headers": n,
2043
+ "header_batches": n,
2044
+ "headers_in_batches": n,
2045
+ "unsolicited_header_responses": n,
2046
+ "average_request_to_response_us": n,
2047
+ "average_validation_us": n,
2048
+ "peers": [...]
2049
+ }
2050
+
2051
+ Examples:
2052
+ > neurai-cli getibdstatus
2053
+ > curl --user myusername --data-binary '{"jsonrpc":"2.0","id":1,"method":"getibdstatus","params":[]}' -H 'content-type: application/json' http://127.0.0.1:19001/
2054
+ **/
2055
+ getibdstatus: "getibdstatus",
2246
2056
  /** getinfo
2247
2057
 
2248
2058
  DEPRECATED. Returns an object containing various state info.
package/dist/index.d.cts CHANGED
@@ -21,17 +21,20 @@ interface IMethods {
21
21
  decodeblock: string;
22
22
  decoderawtransaction: string;
23
23
  decodescript: string;
24
+ depinchallenge: string;
24
25
  depinclearmsg: string;
26
+ depindecrypt: string;
25
27
  depingetancestorrecipients: string;
26
28
  depingetmsg: string;
27
29
  depingetmsginfo: string;
28
- depingetpoolcontent: string;
29
30
  depinlistsections: string;
30
31
  depinmcpstatus: string;
31
32
  depinpoolpkey: string;
32
33
  depinpoolstats: string;
33
34
  depinreceivemsg: string;
34
35
  depinsendmsg: string;
36
+ depinsignchallenge: string;
37
+ depinsignrequest: string;
35
38
  depinsubmitmsg: string;
36
39
  disconnectnode: string;
37
40
  distributereward: string;
@@ -74,6 +77,7 @@ interface IMethods {
74
77
  getdifficulty: string;
75
78
  getdistributestatus: string;
76
79
  getgenerate: string;
80
+ getibdstatus: string;
77
81
  getinfo: string;
78
82
  getkawpowhash: string;
79
83
  getmasterkeyinfo: string;
package/dist/index.d.ts CHANGED
@@ -21,17 +21,20 @@ interface IMethods {
21
21
  decodeblock: string;
22
22
  decoderawtransaction: string;
23
23
  decodescript: string;
24
+ depinchallenge: string;
24
25
  depinclearmsg: string;
26
+ depindecrypt: string;
25
27
  depingetancestorrecipients: string;
26
28
  depingetmsg: string;
27
29
  depingetmsginfo: string;
28
- depingetpoolcontent: string;
29
30
  depinlistsections: string;
30
31
  depinmcpstatus: string;
31
32
  depinpoolpkey: string;
32
33
  depinpoolstats: string;
33
34
  depinreceivemsg: string;
34
35
  depinsendmsg: string;
36
+ depinsignchallenge: string;
37
+ depinsignrequest: string;
35
38
  depinsubmitmsg: string;
36
39
  disconnectnode: string;
37
40
  distributereward: string;
@@ -74,6 +77,7 @@ interface IMethods {
74
77
  getdifficulty: string;
75
78
  getdistributestatus: string;
76
79
  getgenerate: string;
80
+ getibdstatus: string;
77
81
  getinfo: string;
78
82
  getkawpowhash: string;
79
83
  getmasterkeyinfo: string;