@neuraiproject/neurai-rpc 0.4.6 → 0.4.7

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 CHANGED
@@ -8,15 +8,14 @@ and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.ht
8
8
  ## [0.4.6] - 2025-12-10
9
9
 
10
10
  ### Fixed
11
- - **IMPORTANT**: Removed an incorrect restriction that required DePIN assets to start with `&`.
12
- - The Neurai DePIN system can operate with **any asset** on the blockchain.
13
- - Documentation updated in `docs.json`, `docs.ts`, `DEPIN_IMPLEMENTATION_GUIDE.md`, and `neurai_methods.md`.
14
- - Examples that showed tokens requiring the `&` prefix were corrected.
15
- - Affected commands: `checkdepinvalidity`, `listdepinholders`, `freezedepin`, `unfreezedepin`, `selfrevokedepin`.
11
+ - Clarified the DePIN documentation to distinguish between:
12
+ - the messaging token configured in `depintoken`, which can be any asset
13
+ - the dedicated DePIN asset type used by asset-management RPCs, which uses the `&` prefix in current core
14
+ - Corrected examples for the dedicated DePIN asset-management RPCs.
16
15
 
17
16
  ### Changed
18
- - Updated owner token example from `&ASSET!` to `ASSET!` in the documentation.
19
- - Updated the technical implementation guide (`DEPIN_IMPLEMENTATION_GUIDE.md`) to reflect that any asset can be used.
17
+ - Documented the dedicated DePIN asset behavior for package consumers as enabled on mainnet and testnet, with `units=0` on issue/reissue.
18
+ - Added missing RPC documentation for `listdepinaddresses` and `listpqaddresses`.
20
19
 
21
20
  ## [0.4.5] - 2025-12-09
22
21
 
@@ -78,28 +77,31 @@ See repository commits for the full history of changes.
78
77
 
79
78
  ### From 0.4.5 to 0.4.6
80
79
 
81
- **IMPORTANT**: If you were validating that DePIN tokens start with `&` in your code:
80
+ **IMPORTANT**: Distinguish between DePIN messaging tokens and dedicated DePIN assets:
82
81
 
83
- ❌ **Incorrect (old code):**
82
+ ❌ **Incorrect (treating them as the same thing):**
84
83
  ```javascript
85
- if (!token.startsWith('&')) {
86
- throw new Error('Token must start with &');
87
- }
84
+ const token = 'FRANCE';
85
+ await rpc('checkdepinvalidity', [token, address]);
88
86
  ```
89
87
 
90
88
  ✅ **Correct (0.4.6+):**
91
89
  ```javascript
92
- // DePIN tokens can be any asset on the blockchain
93
- // Do not validate by prefix; use checkdepinvalidity instead
94
- const validity = await rpc('checkdepinvalidity', [token, address]);
90
+ const messagingToken = 'FRANCE';
91
+ const depinAsset = '&FRANCE';
92
+
93
+ // Messaging token for depinmsg can be any asset.
94
+ // Dedicated DePIN asset-management commands use the &-prefixed DePIN asset type.
95
+ const validity = await rpc('checkdepinvalidity', [depinAsset, address]);
95
96
  if (!validity.has_asset || validity.valid === 0) {
96
- throw new Error('Invalid DePIN token for this address');
97
+ throw new Error('Invalid DePIN asset for this address');
97
98
  }
98
99
  ```
99
100
 
100
101
  **Updated examples:**
101
- - `&FRANCE` → may be `FRANCE`, `&FRANCE`, or any other asset
102
- - Owner token: `&ASSET!` → `ASSET!` (no mandatory prefix)
102
+ - Messaging token: `FRANCE` can still be any asset
103
+ - Dedicated DePIN asset: `&FRANCE`
104
+ - Owner token for a dedicated DePIN asset: `&FRANCE!`
103
105
 
104
106
  ### Node configuration
105
107
 
@@ -108,14 +110,15 @@ Ensure the following in `neurai.conf`:
108
110
  ```ini
109
111
  # DePIN Messaging
110
112
  depinmsg=1
111
- depintoken=YOUR_TOKEN_HERE # Any valid asset
113
+ depintoken=YOUR_TOKEN_HERE # Messaging token, can be any valid asset
112
114
  depinport=19002
113
115
  depinmaxmessagesize=1024
114
116
  depinmessageexpiry=168
115
117
  depinmaxpoolsize=100
116
118
 
117
- # Asset Index (required for listdepinholders)
119
+ # Asset indexes (required for listdepinholders/listdepinaddresses)
118
120
  assetindex=1
121
+ pubkeyindex=1
119
122
  ```
120
123
 
121
124
  ---
@@ -21,11 +21,10 @@ The DePIN system uses two distinct ports for different operations:
21
21
 
22
22
  ### 1.2 DePIN Asset Types
23
23
 
24
- DePIN assets are special tokens that:
25
- - **Can be any asset on the Neurai blockchain** (no specific prefix required)
26
- - Are **soulbound** (non-transferable except by the owner)
27
- - Can be frozen/revoked by the owner or self-revoked by the holder
28
- - Require the owner token `ASSET!` for administration operations
24
+ There are two related but different concepts in the current DePIN stack:
25
+
26
+ - **DePIN messaging token:** the asset configured in `depintoken` for gateway messaging. This can be any asset.
27
+ - **Dedicated DePIN asset type:** a newer asset class used by the asset-management RPCs (`checkdepinvalidity`, `listdepinholders`, `freezedepin`, `unfreezedepin`, `selfrevokedepin`). These assets use the `&` prefix, are soulbound, are documented here as enabled for mainnet and testnet, require the owner token `&ASSET!`, and must be issued and reissued with `units=0`.
29
28
 
30
29
  ---
31
30
 
@@ -49,7 +48,7 @@ checkdepinvalidity(asset_name: string, address: string): Promise<{
49
48
  **Example:**
50
49
  ```javascript
51
50
  const rpc = getRPC('http://127.0.0.1:8766', 'username', 'password');
52
- const result = await rpc('checkdepinvalidity', ['FRANCE', 'NXabcd...']);
51
+ const result = await rpc('checkdepinvalidity', ['&FRANCE', 'NXabcd...']);
53
52
  // Returns: { has_asset: true, amount: 1, valid: 1, blocked: false }
54
53
  ```
55
54
 
@@ -72,7 +71,7 @@ listdepinholders(asset_name: string): Promise<Array<{
72
71
 
73
72
  **Example:**
74
73
  ```javascript
75
- const holders = await rpc('listdepinholders', ['FRANCE']);
74
+ const holders = await rpc('listdepinholders', ['&FRANCE']);
76
75
  // Returns: [
77
76
  // { address: 'NXabc...', amount: 1, valid: 1 },
78
77
  // { address: 'NXdef...', amount: 1, valid: 0 }
@@ -84,6 +83,32 @@ const holders = await rpc('listdepinholders', ['FRANCE']);
84
83
 
85
84
  ---
86
85
 
86
+ #### **listdepinaddresses**
87
+ Lists addresses that own an asset and have already revealed a public key on-chain.
88
+ This is useful when discovering recipients for DePIN messaging.
89
+
90
+ **Signature:**
91
+ ```typescript
92
+ listdepinaddresses(asset_name: string, count?: number, start?: number): Promise<Array<{
93
+ address: string;
94
+ pubkey: string;
95
+ }>>
96
+ ```
97
+
98
+ **Example:**
99
+ ```javascript
100
+ const recipients = await rpc('listdepinaddresses', ['&FRANCE']);
101
+ // Returns: [
102
+ // { address: 'NXabc...', pubkey: '02ab...' },
103
+ // { address: 'NXdef...', pubkey: '03cd...' }
104
+ // ]
105
+ ```
106
+
107
+ **Port:** 8766
108
+ **Requires:** `-assetindex` and `-pubkeyindex` enabled on the node
109
+
110
+ ---
111
+
87
112
  #### **freezedepin**
88
113
  Freezes a DePIN asset for a specific address (owner only).
89
114
 
@@ -98,12 +123,12 @@ freezedepin(
98
123
 
99
124
  **Example:**
100
125
  ```javascript
101
- const txid = await rpc('freezedepin', ['FRANCE', 'NXmalicious...']);
126
+ const txid = await rpc('freezedepin', ['&FRANCE', 'NXmalicious...']);
102
127
  // Returns: "a1b2c3d4e5f6..." (transaction ID)
103
128
  ```
104
129
 
105
130
  **Port:** 8766
106
- **Requires:** Owner token `FRANCE!` in the wallet
131
+ **Requires:** Owner token `&FRANCE!` in the wallet
107
132
 
108
133
  ---
109
134
 
@@ -134,7 +159,7 @@ selfrevokedepin(asset_name: string): Promise<string> // txid
134
159
 
135
160
  **Example:**
136
161
  ```javascript
137
- const txid = await rpc('selfrevokedepin', ['FRANCE']);
162
+ const txid = await rpc('selfrevokedepin', ['&FRANCE']);
138
163
  ```
139
164
 
140
165
  **Port:** 8766
@@ -729,7 +754,7 @@ async function verifyTokenOwnership(address: string, token: string) {
729
754
  }
730
755
  ```
731
756
 
732
- **Note:** The token can be any asset on the Neurai blockchain; no special prefix is required.
757
+ **Note:** For DePIN messaging, the token can be any asset. For the dedicated DePIN asset-management RPCs, use the `&ASSET` asset type.
733
758
 
734
759
  ### 5.2 Key Management
735
760
 
@@ -786,8 +811,12 @@ depinmaxmessagesize=1024
786
811
  depinmessageexpiry=168 # 7 days in hours
787
812
  depinmaxpoolsize=100 # MB
788
813
 
789
- # Asset Index (required for listdepinholders)
814
+ # Asset indexes (required for DePIN holder and pubkey discovery)
790
815
  assetindex=1
816
+ pubkeyindex=1
817
+
818
+ # Dedicated DePIN assets are issued separately via the standard asset RPCs
819
+ # Example on testnet: issue "&FRANCE" 1 "to_address" "change_address" 0 true
791
820
 
792
821
  # MCP/AI Worker (optional)
793
822
  depinmcp=1
@@ -838,7 +867,7 @@ async function testMessaging() {
838
867
  });
839
868
 
840
869
  // Verify token
841
- const validity = await client.checkValidity('FRANCE', 'NXyouraddr...');
870
+ const validity = await client.checkValidity('&FRANCE', 'NXyouraddr...');
842
871
  console.log('Token validity:', validity);
843
872
 
844
873
  // Send message
package/README.md CHANGED
@@ -91,12 +91,19 @@ const depinRPC = await getDePinRPC({
91
91
  });
92
92
 
93
93
  // Send a DePIN message
94
- const result = await depinRPC("depinsendmsg", ["SEND", "ipfs_hash", 3600]);
94
+ const result = await depinRPC("depinsendmsg", [
95
+ "FRANCE",
96
+ "192.168.1.100:19002",
97
+ "Hello team!",
98
+ "NYourAddressHere"
99
+ ]);
95
100
  console.log(result);
96
101
  ```
97
102
 
98
103
  For complete DePIN examples including browser wallet integration, error handling, and advanced usage, see [DEPIN_EXAMPLES.md](./DEPIN_EXAMPLES.md).
99
104
 
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`.
106
+
100
107
  ## DePIN Authentication
101
108
 
102
109
  Port 19002 uses a challenge-response authentication protocol:
@@ -173,15 +180,21 @@ getcacheinfo
173
180
  getsnapshot "asset_name" block_height
174
181
  issue "asset_name" qty "( to_address )" "( change_address )" ( units ) ( reissuable ) ( has_ipfs ) "( ipfs_hash )"
175
182
  issueunique "root_name" [asset_tags] ( [ipfs_hashes] ) "( to_address )" "( change_address )"
183
+ checkdepinvalidity "asset_name" "address"
184
+ freezedepin "asset_name" "address" ("change_address")
176
185
  listaddressesbyasset "asset_name" (onlytotal) (count) (start)
177
186
  listassetbalancesbyaddress "address" (onlytotal) (count) (start)
178
187
  listassets "( asset )" ( verbose ) ( count ) ( start )
188
+ listdepinaddresses "asset_name" (count) (start)
189
+ listdepinholders "asset_name"
179
190
  listmyassets "( asset )" ( verbose ) ( count ) ( start ) (confs)
180
191
  purgesnapshot "asset_name" block_height
181
192
  reissue "asset_name" qty "to_address" "change_address" ( reissuable ) ( new_units) "( new_ipfs )"
193
+ selfrevokedepin "asset_name"
182
194
  transfer "asset_name" qty "to_address" "message" expire_time "change_address" "asset_change_address"
183
195
  transferfromaddress "asset_name" "from_address" qty "to_address" "message" expire_time "xna_change_address" "asset_change_address"
184
196
  transferfromaddresses "asset_name" ["from_addresses"] qty "to_address" "message" expire_time "xna_change_address" "asset_change_address"
197
+ unfreezedepin "asset_name" "address" ("change_address")
185
198
 
186
199
  == Blockchain ==
187
200
  clearmempool
@@ -343,6 +356,7 @@ keypoolrefill ( newsize )
343
356
  listaccounts ( minconf include_watchonly)
344
357
  listaddressgroupings
345
358
  listlockunspent
359
+ listpqaddresses
346
360
  listreceivedbyaccount ( minconf include_empty include_watchonly)
347
361
  listreceivedbyaddress ( minconf include_empty include_watchonly)
348
362
  listsinceblock ( "blockhash" target_confirmations include_watchonly include_removed )
package/dist/index.cjs CHANGED
@@ -173,10 +173,10 @@ Examples:
173
173
  **/ checkaddresstag: 'checkaddresstag',
174
174
  /** checkdepinvalidity "asset_name" "address"
175
175
 
176
- Check if a DEPIN asset is valid/active for a specific address
176
+ Check if a dedicated DePIN asset is valid/active for a specific address. Dedicated DePIN assets currently use the '&' prefix.
177
177
 
178
178
  Arguments:
179
- 1. "asset_name" (string, required) The DEPIN asset name
179
+ 1. "asset_name" (string, required) The DePIN asset name
180
180
  2. "address" (string, required) The address to check
181
181
 
182
182
  Result:
@@ -1042,14 +1042,14 @@ Examples:
1042
1042
  **/ freezeaddress: 'freezeaddress',
1043
1043
  /** freezedepin "asset_name" "address" ("change_address")
1044
1044
 
1045
- Freeze a DEPIN asset for a specific address (owner only)
1045
+ Freeze a dedicated DePIN asset for a specific address (owner only)
1046
1046
 
1047
1047
  The address will still hold the asset but it will be marked as invalid
1048
1048
 
1049
- Requires the owner token (ASSET!) in the wallet
1049
+ Requires the owner token for the DePIN asset (for example, '&FRANCE!' for '&FRANCE') in the wallet
1050
1050
 
1051
1051
  Arguments:
1052
- 1. "asset_name" (string, required) The DEPIN asset name
1052
+ 1. "asset_name" (string, required) The DePIN asset name
1053
1053
  2. "address" (string, required) The address to freeze
1054
1054
  3. "change_address" (string, optional) The change address for the owner token
1055
1055
 
@@ -2862,6 +2862,7 @@ Asset name must not conflict with any existing asset.
2862
2862
  Unit as the number of decimals precision for the asset (0 for whole units ("1"), 8 for max precision ("1.00000000")
2863
2863
  Reissuable is true/false for whether additional units can be issued by the original issuer.
2864
2864
  If issuing a unique asset these values are required (and will be defaulted to): qty=1, units=0, reissuable=false.
2865
+ Dedicated DePIN assets (name starts with '&') are documented here as enabled for mainnet and testnet, with qty > 0 and units=0.
2865
2866
 
2866
2867
  Arguments:
2867
2868
  1. "asset_name" (string, required) a unique name
@@ -3158,20 +3159,43 @@ Examples:
3158
3159
  > neurai-cli listbanned
3159
3160
  > curl --user myusername --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "listbanned", "params": [] }' -H 'content-type: text/plain;' http://127.0.0.1:8766/
3160
3161
  **/ listbanned: 'listbanned',
3162
+ /** listdepinaddresses "asset_name" (count) (start)
3163
+
3164
+ Returns a list of addresses that own the given asset and have a revealed public key on-chain.
3165
+ Useful for DePIN messaging recipient discovery. Requires -assetindex and -pubkeyindex.
3166
+
3167
+ Arguments:
3168
+ 1. "asset_name" (string, required) name of asset
3169
+ 2. "count" (integer, optional, default=50000, MAX=50000) truncates results to include only the first _count_ addresses found
3170
+ 3. "start" (integer, optional, default=0) results skip over the first _start_ addresses found (if negative it skips back from the end)
3171
+
3172
+ Result:
3173
+ [
3174
+ {
3175
+ "address": "address", (string) The address
3176
+ "pubkey": "pubkey_hex" (string) The revealed public key in hex
3177
+ },
3178
+ ...
3179
+ ]
3180
+
3181
+ Examples:
3182
+ > neurai-cli listdepinaddresses "&FRANCE"
3183
+ > curl --user myusername --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "listdepinaddresses", "params": ["&FRANCE"] }' -H 'content-type: text/plain;' http://127.0.0.1:8766/
3184
+ **/ listdepinaddresses: 'listdepinaddresses',
3161
3185
  /** listdepinholders "asset_name"
3162
3186
 
3163
- Returns all addresses holding a DEPIN asset with validity status
3187
+ Returns all addresses holding a dedicated DePIN asset with validity status
3164
3188
 
3165
- DEPIN assets are soulbound (non-transferable except by owner) and can be frozen/revoked
3189
+ Dedicated DePIN assets are soulbound and can be frozen/revoked. They currently use the '&' prefix.
3166
3190
 
3167
3191
  Arguments:
3168
- 1. "asset_name" (string, required) The DEPIN asset name
3192
+ 1. "asset_name" (string, required) The DePIN asset name
3169
3193
 
3170
3194
  Result:
3171
3195
  [
3172
3196
  {
3173
3197
  "address": "address", (string) The address
3174
- "amount": n, (numeric) The amount (always 1 for DEPIN)
3198
+ "amount": n, (numeric) The amount held
3175
3199
  "valid": 1|0 (numeric) 1 = active/valid, 0 = blocked/revoked
3176
3200
  },
3177
3201
  ...
@@ -3266,6 +3290,20 @@ Examples:
3266
3290
  > neurai-cli listmyassets "ASSET*" true 10 20
3267
3291
  > neurai-cli listmyassets "ASSET*" true 10 20 1
3268
3292
  **/ listmyassets: 'listmyassets',
3293
+ /** listpqaddresses
3294
+
3295
+ Returns post-quantum (ML-DSA-44) Bech32m addresses in the wallet.
3296
+
3297
+ Result:
3298
+ [
3299
+ "nq1...", (string) A post-quantum wallet address
3300
+ ...
3301
+ ]
3302
+
3303
+ Examples:
3304
+ > neurai-cli listpqaddresses
3305
+ > curl --user myusername --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "listpqaddresses", "params": [] }' -H 'content-type: text/plain;' http://127.0.0.1:8766/
3306
+ **/ listpqaddresses: 'listpqaddresses',
3269
3307
  /** listreceivedbyaccount ( minconf include_empty include_watchonly)
3270
3308
 
3271
3309
  DEPRECATED. List balances by account.
@@ -3699,6 +3737,7 @@ Examples:
3699
3737
  Reissues a quantity of an asset to an owned address if you own the Owner Token
3700
3738
  Can change the reissuable flag during reissuance
3701
3739
  Can change the ipfs hash during reissuance
3740
+ For dedicated DePIN assets (name starts with '&'), qty must stay positive and units must remain 0.
3702
3741
  Arguments:
3703
3742
  1. "asset_name" (string, required) name of asset that is being reissued
3704
3743
  2. "qty" (numeric, required) number of assets to reissue
@@ -3818,14 +3857,14 @@ Examples:
3818
3857
  **/ savemempool: 'savemempool',
3819
3858
  /** selfrevokedepin "asset_name"
3820
3859
 
3821
- Self-revoke a DEPIN asset held in this wallet
3860
+ Self-revoke a dedicated DePIN asset held in this wallet
3822
3861
 
3823
3862
  The asset will be marked as invalid but will remain in the address
3824
3863
 
3825
3864
  This action can only be undone by the asset owner
3826
3865
 
3827
3866
  Arguments:
3828
- 1. "asset_name" (string, required) The DEPIN asset name
3867
+ 1. "asset_name" (string, required) The DePIN asset name
3829
3868
 
3830
3869
  Result:
3831
3870
  "txid" (string) The transaction id
@@ -4361,14 +4400,14 @@ Examples:
4361
4400
  **/ unfreezeaddress: 'unfreezeaddress',
4362
4401
  /** unfreezedepin "asset_name" "address" ("change_address")
4363
4402
 
4364
- Unfreeze a DEPIN asset for a specific address (owner only)
4403
+ Unfreeze a dedicated DePIN asset for a specific address (owner only)
4365
4404
 
4366
4405
  The asset will be marked as valid again
4367
4406
 
4368
- Requires the owner token (ASSET!) in the wallet
4407
+ Requires the owner token for the DePIN asset (for example, '&FRANCE!' for '&FRANCE') in the wallet
4369
4408
 
4370
4409
  Arguments:
4371
- 1. "asset_name" (string, required) The DEPIN asset name
4410
+ 1. "asset_name" (string, required) The DePIN asset name
4372
4411
  2. "address" (string, required) The address to unfreeze
4373
4412
  3. "change_address" (string, optional) The change address for the owner token
4374
4413