@neuraiproject/neurai-assets 1.0.2 → 1.1.0

package/examples/10-depin-post-quantum.js

@@ -0,0 +1,83 @@
+/**
+ * Example: DEPIN Assets with Post-Quantum Addresses
+ *
+ * This example demonstrates how to use DEPIN assets with PQ addresses
+ * generated by neurai-key using the xna-pq / xna-pq-test networks.
+ *
+ * PQ address examples:
+ * - Mainnet: nq1...
+ * - Testnet: tnq1...
+ */
+
+const NeuraiAssets = require('@neuraiproject/neurai-assets');
+
+async function createDepinForPQAddress() {
+  const rpc = async (method, params) => {
+    console.log(`RPC Call: ${method}`, params);
+    // Replace with your actual RPC client
+  };
+
+  const assets = new NeuraiAssets(rpc, {
+    network: 'xna-pq',                          // Or 'xna-pq-test'
+    addresses: ['nq1yourpqwalletaddress...'],   // PQ addresses from neurai-key
+    changeAddress: 'nq1yourpqchangeaddress...',
+    toAddress: 'nq1recipientpqaddress...'
+  });
+
+  try {
+    const result = await assets.createDepinAsset({
+      assetName: '&DEVICE/ROUTER001',
+      quantity: 1,
+      reissuable: false
+    });
+
+    console.log('DEPIN transaction created');
+    console.log('Raw transaction:', result.rawTx);
+    console.log('Burn:', result.burnAmount, 'XNA');
+    console.log('Owner token:', result.ownerTokenName);
+  } catch (error) {
+    console.error('Error creating DEPIN asset for PQ address:', error.message);
+  }
+}
+
+async function queryDepinValidityForPQAddress() {
+  const rpc = async (method, params) => {
+    console.log(`RPC Call: ${method}`, params);
+
+    if (method === 'checkdepinvalidity') {
+      return {
+        has_asset: true,
+        amount: 1,
+        valid: 1,
+        blocked: false
+      };
+    }
+
+    if (method === 'listdepinholders') {
+      return [
+        { address: 'nq1firstholder...', amount: 1, valid: 1 },
+        { address: 'nq1secondholder...', amount: 1, valid: 0 }
+      ];
+    }
+  };
+
+  const assets = new NeuraiAssets(rpc, {
+    network: 'xna-pq',
+    addresses: ['nq1yourpqwalletaddress...'],
+    changeAddress: 'nq1yourpqchangeaddress...',
+    toAddress: 'nq1recipientpqaddress...'
+  });
+
+  try {
+    const validity = await assets.checkDepinValidity('&DEVICE/ROUTER001', 'nq1recipientpqaddress...');
+    console.log('DEPIN validity for PQ address:', validity);
+
+    const holders = await assets.listDepinHolders('&DEVICE/ROUTER001');
+    console.log('DEPIN holders:', holders);
+  } catch (error) {
+    console.error('Error querying DEPIN PQ data:', error.message);
+  }
+}
+
+createDepinForPQAddress();
+queryDepinValidityForPQAddress();

package/examples/README.md

@@ -163,6 +163,23 @@ Learn complete integration with `@neuraiproject/neurai-jswallet`.
 
 ---
 
+### 10. DEPIN with Post-Quantum Addresses
+**File:** [10-depin-post-quantum.js](10-depin-post-quantum.js)
+
+Learn how to use DEPIN assets with PQ addresses generated by `neurai-key`.
+
+- PQ mainnet network: `xna-pq`
+- PQ testnet network: `xna-pq-test`
+- PQ address formats: `nq1...` and `tnq1...`
+
+**Topics covered:**
+- Initializing `NeuraiAssets` with PQ networks
+- Creating DEPIN assets sent to PQ addresses
+- Querying DEPIN validity for PQ holders
+- Listing DEPIN holders with PQ addresses
+
+---
+
 ## Running the Examples
 
 ### Prerequisites
@@ -184,9 +201,9 @@ node 01-create-root-asset.js
 
 1. **Mock RPC**: All examples use mock RPC functions. Replace with your actual RPC client in production.
 
-2. **Network**: Examples use mainnet (`'xna'`). Change to `'xna-test'` for testnet.
+2. **Network**: Examples use mainnet (`'xna'`). Change to `'xna-test'` for testnet. PQ networks are `xna-pq` and `xna-pq-test`.
 
-3. **Addresses**: Replace placeholder addresses with your actual wallet addresses.
+3. **Addresses**: Replace placeholder addresses with your actual wallet addresses. PQ examples use `nq1...` / `tnq1...` addresses.
 
 4. **Testing**: Test on testnet first before using mainnet.
 
@@ -232,6 +249,7 @@ const txid = await wallet.broadcastTransaction(signedTx);
 | QUALIFIER | `#NAME` | 2000 XNA | `#KYC_VERIFIED` |
 | SUB_QUALIFIER | `#ROOT/#SUB` | 200 XNA | `#KYC/#LEVEL2` |
 | RESTRICTED | `$NAME` | 3000 XNA | `$SECURITY` |
+| DEPIN | `&NAME` or `&ROOT/SUB` | 10 XNA | `&DEVICE/ROUTER001` |
 | OWNER | `NAME!` | N/A | `MYTOKEN!` |
 
 ## Common Patterns

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neuraiproject/neurai-assets",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "Non-custodial Neurai asset management library for JavaScript",
   "main": "./src/index.js",
   "scripts": {
@@ -29,13 +29,16 @@
   "publishConfig": {
     "access": "public"
   },
-  "dependencies": {},
   "devDependencies": {
     "chai": "^4.3.10",
-    "mocha": "^10.2.0"
+    "mocha": "^11.7.5"
+  },
+  "overrides": {
+    "diff": "8.0.4",
+    "serialize-javascript": "7.0.5"
   },
   "peerDependencies": {
-    "@neuraiproject/neurai-rpc": "^0.4.6"
+    "@neuraiproject/neurai-rpc": "^0.4.7"
   },
   "engines": {
     "node": ">=14.0.0"

package/src/NeuraiAssets.js

@@ -25,6 +25,7 @@ const { AssetQueries } = require('./queries');
 const {
   IssueRootBuilder,
   IssueSubBuilder,
+  IssueDepinBuilder,
   IssueUniqueBuilder,
   IssueQualifierBuilder,
   IssueRestrictedBuilder,
@@ -119,6 +120,21 @@ class NeuraiAssets {
     return await builder.build();
   }
 
+  /**
+   * Create a DEPIN asset
+   * @param {object} params - DEPIN creation parameters
+   * @param {string} params.assetName - Asset name (&NAME or &NAME/SUB)
+   * @param {number} params.quantity - Total supply
+   * @param {boolean} [params.reissuable=true] - Can mint more later
+   * @param {boolean} [params.hasIpfs=false] - Has IPFS metadata
+   * @param {string} [params.ipfsHash] - IPFS hash
+   * @returns {Promise<object>} Transaction data
+   */
+  async createDepinAsset(params) {
+    const builder = new IssueDepinBuilder(this.rpc, this._buildParams(params));
+    return await builder.build();
+  }
+
   /**
    * Reissue (mint more) of a ROOT or SUB asset
    * @param {object} params - Reissue parameters
@@ -439,6 +455,25 @@ class NeuraiAssets {
     return await this.queries.cancelSnapshotRequest(assetName, blockHeight);
   }
 
+  /**
+   * List DEPIN holders with validity status
+   * @param {string} assetName - DEPIN asset name
+   * @returns {Promise<Array>} Holder entries
+   */
+  async listDepinHolders(assetName) {
+    return await this.queries.listDepinHolders(assetName);
+  }
+
+  /**
+   * Check DEPIN validity for an address
+   * @param {string} assetName - DEPIN asset name
+   * @param {string} address - Address to query
+   * @returns {Promise<object>} Validity details
+   */
+  async checkDepinValidity(assetName, address) {
+    return await this.queries.checkDepinValidity(assetName, address);
+  }
+
   /**
    * Check if asset exists
    * @param {string} assetName - Asset name
@@ -451,7 +486,7 @@ class NeuraiAssets {
   /**
    * Get asset type from name
    * @param {string} assetName - Asset name
-   * @returns {string} Asset type ('ROOT', 'SUB', 'UNIQUE', 'QUALIFIER', 'RESTRICTED', 'OWNER')
+   * @returns {string} Asset type ('ROOT', 'SUB', 'UNIQUE', 'QUALIFIER', 'RESTRICTED', 'DEPIN', 'OWNER')
    */
   getAssetType(assetName) {
     return this.queries.getAssetType(assetName);

package/src/builders/BaseAssetTransactionBuilder.js

@@ -225,6 +225,9 @@ class BaseAssetTransactionBuilder {
       case 'RESTRICTED':
         AssetNameValidator.validateRestricted(assetName);
         break;
+      case 'DEPIN':
+        AssetNameValidator.validateDepin(assetName);
+        break;
       default:
         throw new Error(`Unknown asset type: ${type}`);
     }

package/src/builders/IssueDepinBuilder.js

@@ -0,0 +1,144 @@
+/**
+ * Issue DePIN Builder
+ * Builds transactions for creating DEPIN assets.
+ *
+ * DEPIN assets:
+ * - Soulbound assets
+ * - Format: &NAME or &NAME/SUB
+ * - Cost: 10 XNA (same burn as UNIQUE assets)
+ * - Units: Always 0
+ * - Owner token is auto-created by the node
+ */
+
+const BaseAssetTransactionBuilder = require('./BaseAssetTransactionBuilder');
+const { OutputFormatter } = require('../utils');
+const { AssetExistsError } = require('../errors');
+const { IpfsValidator } = require('../validators');
+
+class IssueDepinBuilder extends BaseAssetTransactionBuilder {
+  /**
+   * Validate issue DEPIN parameters
+   * @param {object} params - Issue parameters
+   * @throws {Error} If validation fails
+   */
+  validateParams(params) {
+    if (!params.assetName) {
+      throw new Error('assetName is required');
+    }
+
+    if (params.quantity === undefined || params.quantity === null) {
+      throw new Error('quantity is required');
+    }
+
+    this.validateAssetName(params.assetName, 'DEPIN');
+    this.validateAmount(params.quantity, 0);
+
+    if (params.units !== undefined && params.units !== 0) {
+      throw new Error('DEPIN assets must use units=0');
+    }
+
+    if (params.hasIpfs && params.ipfsHash) {
+      IpfsValidator.validate(params.ipfsHash);
+    }
+
+    if (params.reissuable !== undefined && typeof params.reissuable !== 'boolean') {
+      throw new Error('reissuable must be a boolean');
+    }
+
+    return true;
+  }
+
+  /**
+   * Build DEPIN asset issuance transaction
+   * @returns {Promise<object>} Transaction result
+   */
+  async build() {
+    await this.validateParams(this.params);
+
+    const {
+      assetName,
+      quantity,
+      reissuable = true,
+      hasIpfs = false,
+      ipfsHash = ''
+    } = this.params;
+
+    const exists = await this.assetExists(assetName);
+    if (exists) {
+      throw new AssetExistsError(
+        `Asset ${assetName} already exists on the blockchain`,
+        assetName
+      );
+    }
+
+    const burnInfo = this.burnManager.getIssueDepinBurn();
+    const toAddress = await this.getToAddress();
+    const changeAddress = await this.getChangeAddress();
+
+    const estimatedFee = await this.estimateFee(1, 3);
+    const totalXNANeeded = burnInfo.amount + estimatedFee;
+
+    const utxoSelection = await this.selectUTXOs(totalXNANeeded, null, 0);
+    const baseCurrencyUTXOs = utxoSelection.xnaUTXOs;
+    const totalXNAInput = utxoSelection.totalXNA;
+
+    const actualFee = await this.estimateFee(baseCurrencyUTXOs.length, 3);
+    const totalRequired = burnInfo.amount + actualFee;
+
+    if (totalXNAInput < totalRequired) {
+      const additionalNeeded = totalRequired - totalXNAInput + 0.001;
+      const additionalSelection = await this.selectUTXOs(additionalNeeded, null, 0);
+      baseCurrencyUTXOs.push(...additionalSelection.xnaUTXOs);
+    }
+
+    const finalTotalInput = baseCurrencyUTXOs.reduce(
+      (sum, utxo) => sum + utxo.satoshis / 100000000,
+      0
+    );
+    const xnaChange = finalTotalInput - burnInfo.amount - actualFee;
+
+    const inputs = baseCurrencyUTXOs.map(utxo => ({
+      txid: utxo.txid,
+      vout: utxo.outputIndex,
+      address: utxo.address,
+      satoshis: utxo.satoshis
+    }));
+
+    const outputs = [];
+    outputs.push({ [burnInfo.address]: burnInfo.amount });
+
+    if (xnaChange > 0.00000001) {
+      outputs.push({ [changeAddress]: parseFloat(xnaChange.toFixed(8)) });
+    }
+
+    const issueOutput = OutputFormatter.formatIssueOutput({
+      asset_name: assetName,
+      asset_quantity: this.toSatoshis(quantity, 0),
+      units: 0,
+      reissuable,
+      has_ipfs: hasIpfs,
+      ipfs_hash: ipfsHash
+    });
+
+    outputs.push({ [toAddress]: issueOutput });
+
+    const orderedOutputs = this.outputOrderer.order(outputs);
+    const rawTx = await this.buildRawTransaction(inputs, orderedOutputs);
+
+    return this.formatResult(
+      rawTx,
+      baseCurrencyUTXOs,
+      inputs,
+      orderedOutputs,
+      actualFee,
+      burnInfo.amount,
+      {
+        assetName,
+        ownerTokenName: `${assetName}!`,
+        operationType: 'ISSUE_DEPIN'
+      }
+    );
+  }
+}
+
+module.exports = IssueDepinBuilder;

package/src/builders/ReissueBuilder.js

@@ -103,6 +103,7 @@ class ReissueBuilder extends BaseAssetTransactionBuilder {
     const addresses = await this._getAddresses();
     const toAddress = await this.getToAddress();
     const changeAddress = await this.getChangeAddress();
+    const isDepinAsset = AssetNameParser.isDepin(assetName);
 
     // 6. Find owner token (CRITICAL: must have this)
     const ownerTokenName = AssetNameParser.getOwnerTokenName(assetName);
@@ -201,7 +202,7 @@ class ReissueBuilder extends BaseAssetTransactionBuilder {
       asset_quantity: this.toSatoshis(quantity, units),
       reissuable: reissuable !== undefined ? reissuable : undefined,
       new_ipfs: newIpfs || undefined,
-      owner_change_address: changeAddress
+      owner_change_address: isDepinAsset ? toAddress : changeAddress
     });
 
     outputs.push({ [toAddress]: reissueOutput });

package/src/builders/index.js

@@ -9,6 +9,7 @@ const BaseAssetTransactionBuilder = require('./BaseAssetTransactionBuilder');
 // Basic Builders
 const IssueRootBuilder = require('./IssueRootBuilder');
 const IssueSubBuilder = require('./IssueSubBuilder');
+const IssueDepinBuilder = require('./IssueDepinBuilder');
 const ReissueBuilder = require('./ReissueBuilder');
 
 // Advanced Builders
@@ -26,6 +27,7 @@ module.exports = {
   // Basic Builders
   IssueRootBuilder,
   IssueSubBuilder,
+  IssueDepinBuilder,
   ReissueBuilder,
 
   // Advanced Builders

package/src/constants/burnAddresses.js

@@ -3,6 +3,21 @@
  * Different addresses for mainnet and testnet
  */
 
+const MAINNET_NETWORKS = ['xna', 'mainnet', 'xna-pq', 'mainnet-pq'];
+const TESTNET_NETWORKS = ['xna-test', 'testnet', 'regtest', 'xna-pq-test', 'testnet-pq'];
+
+function resolveNetworkFamily(network) {
+  if (MAINNET_NETWORKS.includes(network)) {
+    return 'mainnet';
+  }
+
+  if (TESTNET_NETWORKS.includes(network)) {
+    return 'testnet';
+  }
+
+  throw new Error(`Unknown network: ${network}`);
+}
+
 const MAINNET_BURN_ADDRESSES = {
   ISSUE_ROOT: 'NbURNXXXXXXXXXXXXXXXXXXXXXXXT65Gdr',
   ISSUE_SUB: 'NXissueSubAssetXXXXXXXXXXXXXX6B2JF',
@@ -32,11 +47,12 @@ const TESTNET_BURN_ADDRESSES = {
 /**
  * Get burn address for an operation and network
  * @param {string} operationType - Operation type (e.g., 'ISSUE_ROOT')
- * @param {string} network - Network type ('xna' or 'xna-test')
+ * @param {string} network - Network type ('xna', 'xna-test', 'xna-pq', or 'xna-pq-test')
  * @returns {string} Burn address
  */
 function getBurnAddress(operationType, network) {
-  const addresses = network === 'xna' ? MAINNET_BURN_ADDRESSES : TESTNET_BURN_ADDRESSES;
+  const family = resolveNetworkFamily(network);
+  const addresses = family === 'mainnet' ? MAINNET_BURN_ADDRESSES : TESTNET_BURN_ADDRESSES;
 
   const address = addresses[operationType];
   if (!address) {
@@ -49,17 +65,19 @@ function getBurnAddress(operationType, network) {
 /**
  * Check if an address is a burn address
  * @param {string} address - Address to check
- * @param {string} network - Network type ('xna' or 'xna-test')
+ * @param {string} network - Network type ('xna', 'xna-test', 'xna-pq', or 'xna-pq-test')
  * @returns {boolean} True if it's a burn address
  */
 function isBurnAddress(address, network) {
-  const addresses = network === 'xna' ? MAINNET_BURN_ADDRESSES : TESTNET_BURN_ADDRESSES;
+  const family = resolveNetworkFamily(network);
+  const addresses = family === 'mainnet' ? MAINNET_BURN_ADDRESSES : TESTNET_BURN_ADDRESSES;
   return Object.values(addresses).includes(address);
 }
 
 module.exports = {
   MAINNET_BURN_ADDRESSES,
   TESTNET_BURN_ADDRESSES,
+  resolveNetworkFamily,
   getBurnAddress,
   isBurnAddress
 };

package/src/constants/index.js

@@ -8,6 +8,7 @@ const { ASSET_COSTS, getAssetCost, getUniqueAssetCost, getTaggingCost } = requir
 const {
   MAINNET_BURN_ADDRESSES,
   TESTNET_BURN_ADDRESSES,
+  resolveNetworkFamily,
   getBurnAddress,
   isBurnAddress
 } = require('./burnAddresses');
@@ -32,6 +33,7 @@ module.exports = {
   // Burn Addresses
   MAINNET_BURN_ADDRESSES,
   TESTNET_BURN_ADDRESSES,
+  resolveNetworkFamily,
   getBurnAddress,
   isBurnAddress,
 

package/src/constants/networks.js

@@ -7,17 +7,41 @@ const NETWORKS = {
     name: 'xna',
     displayName: 'Neurai Mainnet',
     addressPrefix: 'N',
+    pqAddressPrefix: 'nq1',
     assetNameMaxLength: 32,
     defaultRPCPort: 19001,
-    coin: 'XNA'
+    coin: 'XNA',
+    baseNetwork: 'xna'
   },
   TESTNET: {
     name: 'xna-test',
     displayName: 'Neurai Testnet',
     addressPrefix: 't',
+    pqAddressPrefix: 'tnq1',
     assetNameMaxLength: 32,  // Same as mainnet
     defaultRPCPort: 19101,
-    coin: 'TXNA'
+    coin: 'TXNA',
+    baseNetwork: 'xna-test'
+  },
+  MAINNET_PQ: {
+    name: 'xna-pq',
+    displayName: 'Neurai Mainnet PQ',
+    addressPrefix: 'N',
+    pqAddressPrefix: 'nq1',
+    assetNameMaxLength: 32,
+    defaultRPCPort: 19001,
+    coin: 'XNA',
+    baseNetwork: 'xna'
+  },
+  TESTNET_PQ: {
+    name: 'xna-pq-test',
+    displayName: 'Neurai Testnet PQ',
+    addressPrefix: 't',
+    pqAddressPrefix: 'tnq1',
+    assetNameMaxLength: 32,
+    defaultRPCPort: 19101,
+    coin: 'TXNA',
+    baseNetwork: 'xna-test'
   }
 };
 
@@ -57,6 +81,13 @@ const ASSET_NAME_RULES = {
     maxLength: 30,
     pattern: /^[A-Z0-9_.]+$/,
     prefix: '$'
+  },
+  DEPIN: {
+    minLength: 3,
+    maxLength: 120,
+    pattern: /^[A-Z0-9_.]+$/,
+    prefix: '&',
+    separator: '/'
   }
 };
 
@@ -75,7 +106,7 @@ const ASSET_LIMITS = {
 
 /**
  * Get network configuration
- * @param {string} networkName - Network name ('xna' or 'xna-test')
+ * @param {string} networkName - Network name ('xna', 'xna-test', 'xna-pq', or 'xna-pq-test')
  * @returns {object} Network configuration
  */
 function getNetworkConfig(networkName) {
@@ -83,6 +114,10 @@ function getNetworkConfig(networkName) {
     return NETWORKS.MAINNET;
   } else if (networkName === 'xna-test' || networkName === 'testnet') {
     return NETWORKS.TESTNET;
+  } else if (networkName === 'xna-pq' || networkName === 'mainnet-pq') {
+    return NETWORKS.MAINNET_PQ;
+  } else if (networkName === 'xna-pq-test' || networkName === 'testnet-pq') {
+    return NETWORKS.TESTNET_PQ;
   } else {
     throw new Error(`Unknown network: ${networkName}`);
   }
@@ -91,10 +126,14 @@ function getNetworkConfig(networkName) {
 /**
  * Detect network from address prefix
  * @param {string} address - Neurai address
- * @returns {string} Network name ('xna' or 'xna-test')
+ * @returns {string} Network name ('xna', 'xna-test', 'xna-pq', or 'xna-pq-test')
  */
 function detectNetworkFromAddress(address) {
-  if (address.startsWith('N')) {
+  if (address.startsWith(NETWORKS.MAINNET_PQ.pqAddressPrefix)) {
+    return 'xna-pq';
+  } else if (address.startsWith(NETWORKS.TESTNET_PQ.pqAddressPrefix)) {
+    return 'xna-pq-test';
+  } else if (address.startsWith('N')) {
     return 'xna';
   } else if (address.startsWith('t')) {
     return 'xna-test';

package/src/index.js

@@ -9,6 +9,7 @@
  * - UNIQUE assets (NFTs)
  * - QUALIFIER assets (KYC/compliance tags)
  * - RESTRICTED assets (security tokens with compliance)
+ * - DEPIN assets (soulbound assets)
  *
  * @example
  * const NeuraiAssets = require('@neuraiproject/neurai-assets');

package/src/managers/BurnManager.js

@@ -79,6 +79,15 @@ class BurnManager {
     return this.getBurnInfo('ISSUE_UNIQUE', count);
   }
 
+  /**
+   * Get burn info for DEPIN asset issuance
+   * DEPIN assets reuse the UNIQUE burn amount/address.
+   * @returns {object} { address, amount }
+   */
+  getIssueDepinBurn() {
+    return this.getIssueUniqueBurn(1);
+  }
+
   /**
    * Get burn info for QUALIFIER asset issuance
    * @returns {object} { address, amount }

package/src/queries/AssetQueries.js

@@ -387,6 +387,53 @@ class AssetQueries {
     }
   }
 
+  /**
+   * List DEPIN holders with validity status
+   * @param {string} assetName - DEPIN asset name
+   * @returns {Promise<Array>} Array of holder objects
+   */
+  async listDepinHolders(assetName) {
+    if (!assetName) {
+      throw new Error('DEPIN asset name is required');
+    }
+
+    try {
+      const result = await this.rpc('listdepinholders', [assetName]);
+      return result || [];
+    } catch (error) {
+      if (error.message && error.message.includes('not found')) {
+        throw new AssetNotFoundError(
+          `DEPIN asset ${assetName} not found on blockchain`,
+          assetName
+        );
+      }
+      throw new Error(`Failed to list DEPIN holders: ${error.message}`);
+    }
+  }
+
+  /**
+   * Check DEPIN validity for a specific address
+   * @param {string} assetName - DEPIN asset name
+   * @param {string} address - Address to query
+   * @returns {Promise<object>} Validity information
+   */
+  async checkDepinValidity(assetName, address) {
+    if (!assetName) {
+      throw new Error('DEPIN asset name is required');
+    }
+
+    if (!address) {
+      throw new Error('Address is required');
+    }
+
+    try {
+      const result = await this.rpc('checkdepinvalidity', [assetName, address]);
+      return result || { has_asset: false };
+    } catch (error) {
+      throw new Error(`Failed to check DEPIN validity: ${error.message}`);
+    }
+  }
+
   /**
    * Get total count of assets on blockchain
    * @returns {Promise<number>} Total asset count
@@ -421,7 +468,7 @@ class AssetQueries {
   /**
    * Get asset type from name
    * @param {string} assetName - Asset name
-   * @returns {string} Asset type ('ROOT', 'SUB', 'UNIQUE', 'QUALIFIER', 'RESTRICTED', 'OWNER')
+   * @returns {string} Asset type ('ROOT', 'SUB', 'UNIQUE', 'QUALIFIER', 'RESTRICTED', 'DEPIN', 'OWNER')
    */
   getAssetType(assetName) {
     if (!assetName) {
@@ -434,6 +481,8 @@ class AssetQueries {
       return assetName.includes('/') ? 'SUB_QUALIFIER' : 'QUALIFIER';
     } else if (assetName.startsWith('$')) {
       return 'RESTRICTED';
+    } else if (assetName.startsWith('&')) {
+      return 'DEPIN';
     } else if (assetName.includes('#')) {
       return 'UNIQUE';
     } else if (assetName.includes('/')) {

package/src/utils/assetNameParser.js

@@ -15,6 +15,7 @@ class AssetNameParser {
     const isOwner = name.endsWith('!');
     const isRestricted = name.startsWith('$');
     const isQualifier = name.startsWith('#');
+    const isDepin = name.startsWith('&');
     const cleanName = isOwner ? name.slice(0, -1) : name;
 
     let type;
@@ -40,6 +41,15 @@ class AssetNameParser {
       // RESTRICTED: $NAME
       type = AssetType.RESTRICTED;
       prefix = '$';
+    } else if (isDepin) {
+      // DEPIN: &NAME or &NAME/SUB
+      type = AssetType.DEPIN;
+      prefix = '&';
+      if (cleanName.includes('/')) {
+        const parts = cleanName.split('/');
+        parent = parts[0];
+        subName = parts.slice(1).join('/');
+      }
     } else if (cleanName.includes('#')) {
       // UNIQUE: ROOT#TAG
       type = AssetType.UNIQUE;
@@ -71,6 +81,7 @@ class AssetNameParser {
         prefix,
         isOwner: true,
         isRestricted: cleanName.startsWith('$'),
+        isDepin: cleanName.startsWith('&'),
         isQualifier: false,
         fullName: name,
         baseName: cleanName
@@ -86,6 +97,7 @@ class AssetNameParser {
       prefix,
       isOwner,
       isRestricted,
+      isDepin,
       isQualifier,
       fullName: name,
       baseName: cleanName
@@ -179,7 +191,16 @@ class AssetNameParser {
    * @returns {boolean} True if sub-asset
    */
   static isSub(name) {
-    return name.includes('/') && !name.startsWith('#');
+    return name.includes('/') && !name.startsWith('#') && !name.startsWith('&');
+  }
+
+  /**
+   * Check if asset is a DEPIN asset
+   * @param {string} name - Asset name
+   * @returns {boolean} True if DEPIN
+   */
+  static isDepin(name) {
+    return name.startsWith('&');
   }
 
   /**

package/src/utils/networkDetector.js

@@ -40,13 +40,21 @@ class NetworkDetector {
   /**
    * Detect network from address
    * @param {string} address - Neurai address
-   * @returns {string} Network name ('xna' or 'xna-test')
+   * @returns {string} Network name ('xna', 'xna-test', 'xna-pq', or 'xna-pq-test')
    */
   static detectFromAddress(address) {
     if (!address || typeof address !== 'string') {
       throw new Error('Address must be a non-empty string');
     }
 
+    if (address.startsWith(NETWORKS.MAINNET_PQ.pqAddressPrefix)) {
+      return 'xna-pq';
+    }
+
+    if (address.startsWith(NETWORKS.TESTNET_PQ.pqAddressPrefix)) {
+      return 'xna-pq-test';
+    }
+
     // Mainnet addresses start with 'N'
     if (address.startsWith(NETWORKS.MAINNET.addressPrefix)) {
       return 'xna';
@@ -63,7 +71,7 @@ class NetworkDetector {
   /**
    * Detect network from multiple addresses
    * @param {string[]} addresses - Array of addresses
-   * @returns {string} Network name ('xna' or 'xna-test')
+   * @returns {string} Network name ('xna', 'xna-test', 'xna-pq', or 'xna-pq-test')
    */
   static detectFromAddresses(addresses) {
     if (!Array.isArray(addresses) || addresses.length === 0) {
@@ -87,7 +95,7 @@ class NetworkDetector {
   /**
    * Validate that addresses match expected network
    * @param {string[]} addresses - Array of addresses
-   * @param {string} expectedNetwork - Expected network ('xna' or 'xna-test')
+   * @param {string} expectedNetwork - Expected network ('xna', 'xna-test', 'xna-pq', or 'xna-pq-test')
    * @returns {boolean} True if all addresses match network
    */
   static validateAddressesNetwork(addresses, expectedNetwork) {
@@ -117,6 +125,10 @@ class NetworkDetector {
       return NETWORKS.MAINNET;
     } else if (network === 'xna-test' || network === 'testnet') {
       return NETWORKS.TESTNET;
+    } else if (network === 'xna-pq' || network === 'mainnet-pq') {
+      return NETWORKS.MAINNET_PQ;
+    } else if (network === 'xna-pq-test' || network === 'testnet-pq') {
+      return NETWORKS.TESTNET_PQ;
     } else {
       throw new Error(`Unknown network: ${network}`);
     }
@@ -128,7 +140,7 @@ class NetworkDetector {
    * @returns {boolean} True if mainnet
    */
   static isMainnet(network) {
-    return network === 'xna' || network === 'mainnet';
+    return network === 'xna' || network === 'mainnet' || network === 'xna-pq' || network === 'mainnet-pq';
   }
 
   /**
@@ -137,7 +149,11 @@ class NetworkDetector {
    * @returns {boolean} True if testnet
    */
   static isTestnet(network) {
-    return network === 'xna-test' || network === 'testnet' || network === 'regtest';
+    return network === 'xna-test' ||
+      network === 'testnet' ||
+      network === 'regtest' ||
+      network === 'xna-pq-test' ||
+      network === 'testnet-pq';
   }
 }
 

package/src/validators/assetNameValidator.js

@@ -240,6 +240,77 @@ class AssetNameValidator {
     return true;
   }
 
+  /**
+   * Validate DEPIN asset name
+   * Format: &NAME or &NAME/SUB[/...]
+   */
+  static validateDepin(name) {
+    if (!name || typeof name !== 'string') {
+      throw new InvalidAssetNameError('DEPIN asset name must be a non-empty string', name);
+    }
+
+    if (!name.startsWith(ASSET_NAME_RULES.DEPIN.prefix)) {
+      throw new InvalidAssetNameError(
+        `DEPIN asset must start with ${ASSET_NAME_RULES.DEPIN.prefix}`,
+        name
+      );
+    }
+
+    if (name.length > ASSET_NAME_RULES.DEPIN.maxLength) {
+      throw new InvalidAssetNameError(
+        `DEPIN asset name cannot exceed ${ASSET_NAME_RULES.DEPIN.maxLength} characters`,
+        name
+      );
+    }
+
+    const parts = name.split(ASSET_NAME_RULES.DEPIN.separator);
+    if (parts.length === 0) {
+      throw new InvalidAssetNameError('DEPIN asset name is invalid', name);
+    }
+
+    const rootPart = parts[0].substring(1);
+    if (rootPart.length < ASSET_NAME_RULES.DEPIN.minLength) {
+      throw new InvalidAssetNameError(
+        `DEPIN root name must be at least ${ASSET_NAME_RULES.DEPIN.minLength} characters`,
+        name
+      );
+    }
+
+    if (rootPart !== rootPart.toUpperCase()) {
+      throw new InvalidAssetNameError('DEPIN asset name must be uppercase', name);
+    }
+
+    if (!ASSET_NAME_RULES.DEPIN.pattern.test(rootPart)) {
+      throw new InvalidAssetNameError(
+        'DEPIN asset name can only contain A-Z, 0-9, underscore, and period',
+        name
+      );
+    }
+
+    const subParts = parts.slice(1);
+    subParts.forEach(part => {
+      if (part.length < ASSET_NAME_RULES.DEPIN.minLength) {
+        throw new InvalidAssetNameError(
+          `Each DEPIN sub-part must be at least ${ASSET_NAME_RULES.DEPIN.minLength} characters`,
+          name
+        );
+      }
+
+      if (part !== part.toUpperCase()) {
+        throw new InvalidAssetNameError('DEPIN asset name must be uppercase', name);
+      }
+
+      if (!ASSET_NAME_RULES.DEPIN.pattern.test(part)) {
+        throw new InvalidAssetNameError(
+          'DEPIN asset name can only contain A-Z, 0-9, underscore, and period',
+          name
+        );
+      }
+    });
+
+    return true;
+  }
+
   /**
    * Validate owner token name
    * Format: ASSETNAME!
@@ -255,9 +326,11 @@ class AssetNameValidator {
 
     const assetName = name.substring(0, name.length - 1);
 
-    // Validate the asset name part (could be ROOT or RESTRICTED)
+    // Validate the asset name part (could be ROOT, RESTRICTED, or DEPIN)
     if (assetName.startsWith('$')) {
       this.validateRestricted(assetName);
+    } else if (assetName.startsWith('&')) {
+      this.validateDepin(assetName);
     } else {
       this.validateRoot(assetName);
     }
@@ -268,7 +341,7 @@ class AssetNameValidator {
   /**
    * Auto-detect asset type and validate
    * @param {string} name - Asset name
-   * @returns {string} Asset type ('ROOT', 'SUB', 'UNIQUE', 'QUALIFIER', 'RESTRICTED', 'OWNER')
+   * @returns {string} Asset type ('ROOT', 'SUB', 'UNIQUE', 'QUALIFIER', 'RESTRICTED', 'DEPIN', 'OWNER')
    */
   static validateAndDetectType(name) {
     if (name.endsWith('!')) {
@@ -280,6 +353,9 @@ class AssetNameValidator {
     } else if (name.startsWith('$')) {
       this.validateRestricted(name);
       return 'RESTRICTED';
+    } else if (name.startsWith('&')) {
+      this.validateDepin(name);
+      return 'DEPIN';
     } else if (name.includes('#')) {
       this.validateUnique(name);
       return 'UNIQUE';

package/tests/integration/assetLifecycle.test.js

@@ -55,6 +55,18 @@ describe('Integration: Asset Lifecycle', () => {
       expect(parsed.isRestricted).to.be.true;
       expect(parsed.prefix).to.equal('$');
     });
+
+    it('should validate and parse DEPIN assets correctly', () => {
+      const assetName = '&FRANCE/PARIS';
+
+      expect(AssetNameValidator.validateDepin(assetName)).to.be.true;
+
+      const parsed = AssetNameParser.parse(assetName);
+      expect(parsed.type).to.equal(12);
+      expect(parsed.isDepin).to.be.true;
+      expect(parsed.parent).to.equal('&FRANCE');
+      expect(parsed.subName).to.equal('PARIS');
+    });
   });
 
   describe('Amount Conversion Integration', () => {
@@ -134,6 +146,7 @@ describe('Integration: Asset Lifecycle', () => {
         { name: 'MYTOKEN#NFT', expected: 'UNIQUE' },
         { name: '#KYC', expected: 'QUALIFIER' },
         { name: '$SECURITY', expected: 'RESTRICTED' },
+        { name: '&FRANCE/PARIS', expected: 'DEPIN' },
         { name: 'MYTOKEN!', expected: 'OWNER' }
       ];
 
@@ -210,6 +223,20 @@ describe('Integration: Asset Lifecycle', () => {
       expect(parsed.type).to.equal(4);
       expect(parsed.isQualifier).to.be.true;
     });
+
+    it('should handle depin workflow', () => {
+      const depinName = '&FRANCE/PARIS';
+
+      expect(AssetNameValidator.validateDepin(depinName)).to.be.true;
+      expect(AssetNameParser.isDepin(depinName)).to.be.true;
+
+      const ownerToken = AssetNameParser.getOwnerTokenName(depinName);
+      expect(ownerToken).to.equal('&FRANCE/PARIS!');
+
+      const parsed = AssetNameParser.parse(depinName);
+      expect(parsed.type).to.equal(12);
+      expect(parsed.parent).to.equal('&FRANCE');
+    });
   });
 
   describe('Error Handling Integration', () => {

package/tests/mocks/rpcMock.js

@@ -58,7 +58,9 @@ class RPCMock {
       'isaddressfrozen': false,
       'checkglobalrestriction': false,
       'getverifierstring': '',
-      'isvalidverifierstring': true
+      'isvalidverifierstring': true,
+      'listdepinholders': [],
+      'checkdepinvalidity': { has_asset: false }
     };
 
     return defaults[method] || null;

package/tests/unit/NeuraiAssets.test.js

@@ -116,6 +116,11 @@ describe('NeuraiAssets', () => {
       expect(type).to.equal('RESTRICTED');
     });
 
+    it('should detect DEPIN asset type', () => {
+      const type = assets.getAssetType('&FRANCE/PARIS');
+      expect(type).to.equal('DEPIN');
+    });
+
     it('should detect OWNER token type', () => {
       const type = assets.getAssetType('MYTOKEN!');
       expect(type).to.equal('OWNER');
@@ -165,12 +170,31 @@ describe('NeuraiAssets', () => {
       const result = await testAssets.assetExists('MYTOKEN');
       expect(result).to.exist;
     });
+
+    it('should call listDepinHolders', async () => {
+      const holders = [{ address: 't1...', amount: 1, valid: 1 }];
+      const rpcMock = createMockRPC({ 'listdepinholders': holders });
+      const testAssets = new NeuraiAssets(rpcMock);
+
+      const result = await testAssets.listDepinHolders('&FRANCE');
+      expect(result).to.deep.equal(holders);
+    });
+
+    it('should call checkDepinValidity', async () => {
+      const validity = { has_asset: true, amount: 1, valid: 1, blocked: false };
+      const rpcMock = createMockRPC({ 'checkdepinvalidity': validity });
+      const testAssets = new NeuraiAssets(rpcMock);
+
+      const result = await testAssets.checkDepinValidity('&FRANCE', 't1...');
+      expect(result).to.deep.equal(validity);
+    });
   });
 
   describe('Method Availability', () => {
     it('should have all ROOT asset methods', () => {
       expect(assets.createRootAsset).to.be.a('function');
       expect(assets.createSubAsset).to.be.a('function');
+      expect(assets.createDepinAsset).to.be.a('function');
       expect(assets.reissueAsset).to.be.a('function');
     });
 
@@ -209,6 +233,8 @@ describe('NeuraiAssets', () => {
       expect(assets.isValidVerifierString).to.be.a('function');
       expect(assets.getSnapshotRequest).to.be.a('function');
       expect(assets.cancelSnapshotRequest).to.be.a('function');
+      expect(assets.listDepinHolders).to.be.a('function');
+      expect(assets.checkDepinValidity).to.be.a('function');
       expect(assets.assetExists).to.be.a('function');
       expect(assets.getAssetType).to.be.a('function');
       expect(assets.getAssetCount).to.be.a('function');

package/tests/unit/utils/assetNameParser.test.js

@@ -58,6 +58,15 @@ describe('AssetNameParser', () => {
       expect(result.name).to.equal('$SECURITY');
     });
 
+    it('should parse DEPIN asset names', () => {
+      const result = AssetNameParser.parse('&FRANCE/PARIS');
+      expect(result.type).to.equal(AssetType.DEPIN);
+      expect(result.prefix).to.equal('&');
+      expect(result.isDepin).to.be.true;
+      expect(result.parent).to.equal('&FRANCE');
+      expect(result.subName).to.equal('PARIS');
+    });
+
     it('should parse OWNER token names', () => {
       const result = AssetNameParser.parse('MYTOKEN!');
       expect(result.type).to.equal(AssetType.OWNER);
@@ -73,6 +82,15 @@ describe('AssetNameParser', () => {
       expect(result.isRestricted).to.be.true;
       expect(result.baseName).to.equal('$SECURITY');
     });
+
+    it('should parse DEPIN OWNER token names', () => {
+      const result = AssetNameParser.parse('&FRANCE!');
+      expect(result.type).to.equal(AssetType.OWNER);
+      expect(result.isOwner).to.be.true;
+      expect(result.isDepin).to.be.true;
+      expect(result.baseType).to.equal(AssetType.DEPIN);
+      expect(result.baseName).to.equal('&FRANCE');
+    });
   });
 
   describe('getType', () => {
@@ -83,6 +101,7 @@ describe('AssetNameParser', () => {
       expect(AssetNameParser.getType('#KYC')).to.equal(AssetType.QUALIFIER);
       expect(AssetNameParser.getType('#KYC/TIER1')).to.equal(AssetType.SUB_QUALIFIER);
       expect(AssetNameParser.getType('$SECURITY')).to.equal(AssetType.RESTRICTED);
+      expect(AssetNameParser.getType('&FRANCE/PARIS')).to.equal(AssetType.DEPIN);
       expect(AssetNameParser.getType('MYTOKEN!')).to.equal(AssetType.OWNER);
     });
   });
@@ -103,6 +122,10 @@ describe('AssetNameParser', () => {
     it('should return parent for SUB_QUALIFIER', () => {
       expect(AssetNameParser.getParent('#KYC/TIER1')).to.equal('#KYC');
     });
+
+    it('should return parent for DEPIN sub-assets', () => {
+      expect(AssetNameParser.getParent('&FRANCE/PARIS')).to.equal('&FRANCE');
+    });
   });
 
   describe('isOwnerToken', () => {
@@ -121,6 +144,7 @@ describe('AssetNameParser', () => {
     it('should add ! to get owner token name', () => {
       expect(AssetNameParser.getOwnerTokenName('MYTOKEN')).to.equal('MYTOKEN!');
       expect(AssetNameParser.getOwnerTokenName('$SECURITY')).to.equal('SECURITY!');
+      expect(AssetNameParser.getOwnerTokenName('&FRANCE')).to.equal('&FRANCE!');
     });
 
     it('should return as-is if already an owner token', () => {
@@ -184,6 +208,19 @@ describe('AssetNameParser', () => {
     it('should return false for non-sub assets', () => {
       expect(AssetNameParser.isSub('MYTOKEN')).to.be.false;
       expect(AssetNameParser.isSub('#KYC/TIER1')).to.be.false;
+      expect(AssetNameParser.isSub('&FRANCE/PARIS')).to.be.false;
+    });
+  });
+
+  describe('isDepin', () => {
+    it('should identify depin assets', () => {
+      expect(AssetNameParser.isDepin('&FRANCE')).to.be.true;
+      expect(AssetNameParser.isDepin('&FRANCE/PARIS')).to.be.true;
+    });
+
+    it('should return false for non-depin assets', () => {
+      expect(AssetNameParser.isDepin('MYTOKEN')).to.be.false;
+      expect(AssetNameParser.isDepin('$SECURITY')).to.be.false;
     });
   });
 

package/tests/unit/utils/networkDetector.test.js

@@ -0,0 +1,89 @@
+/**
+ * Tests for NetworkDetector and network constants.
+ */
+
+const { expect } = require('chai');
+const NetworkDetector = require('../../../src/utils/networkDetector');
+const {
+  getNetworkConfig,
+  detectNetworkFromAddress,
+  getBurnAddress
+} = require('../../../src/constants');
+
+describe('NetworkDetector', () => {
+  describe('detectFromAddress', () => {
+    it('should detect legacy mainnet addresses', () => {
+      expect(NetworkDetector.detectFromAddress('NExampleLegacyAddress')).to.equal('xna');
+    });
+
+    it('should detect legacy testnet addresses', () => {
+      expect(NetworkDetector.detectFromAddress('tExampleLegacyAddress')).to.equal('xna-test');
+    });
+
+    it('should detect PQ mainnet addresses', () => {
+      expect(NetworkDetector.detectFromAddress('nq1examplepqaddress')).to.equal('xna-pq');
+    });
+
+    it('should detect PQ testnet addresses', () => {
+      expect(NetworkDetector.detectFromAddress('tnq1examplepqaddress')).to.equal('xna-pq-test');
+    });
+  });
+
+  describe('detectFromAddresses', () => {
+    it('should accept multiple PQ addresses from the same network', () => {
+      const result = NetworkDetector.detectFromAddresses([
+        'nq1firstpqaddress',
+        'nq1secondpqaddress'
+      ]);
+
+      expect(result).to.equal('xna-pq');
+    });
+
+    it('should reject mixed PQ networks', () => {
+      expect(() => NetworkDetector.detectFromAddresses([
+        'nq1firstpqaddress',
+        'tnq1secondpqaddress'
+      ])).to.throw('Mixed network addresses detected');
+    });
+  });
+
+  describe('validateAddressesNetwork', () => {
+    it('should validate PQ addresses against expected network', () => {
+      expect(NetworkDetector.validateAddressesNetwork(['nq1examplepqaddress'], 'xna-pq')).to.be.true;
+      expect(NetworkDetector.validateAddressesNetwork(['tnq1examplepqaddress'], 'xna-pq-test')).to.be.true;
+    });
+  });
+
+  describe('getNetworkConfig', () => {
+    it('should return PQ network config for mainnet', () => {
+      const config = getNetworkConfig('xna-pq');
+      expect(config.name).to.equal('xna-pq');
+      expect(config.pqAddressPrefix).to.equal('nq1');
+      expect(config.baseNetwork).to.equal('xna');
+    });
+
+    it('should return PQ network config for testnet', () => {
+      const config = getNetworkConfig('xna-pq-test');
+      expect(config.name).to.equal('xna-pq-test');
+      expect(config.pqAddressPrefix).to.equal('tnq1');
+      expect(config.baseNetwork).to.equal('xna-test');
+    });
+  });
+
+  describe('detectNetworkFromAddress', () => {
+    it('should detect PQ addresses through constants helper', () => {
+      expect(detectNetworkFromAddress('nq1examplepqaddress')).to.equal('xna-pq');
+      expect(detectNetworkFromAddress('tnq1examplepqaddress')).to.equal('xna-pq-test');
+    });
+  });
+
+  describe('getBurnAddress', () => {
+    it('should use mainnet burn addresses for xna-pq', () => {
+      expect(getBurnAddress('ISSUE_ROOT', 'xna-pq')).to.equal('NbURNXXXXXXXXXXXXXXXXXXXXXXXT65Gdr');
+    });
+
+    it('should use testnet burn addresses for xna-pq-test', () => {
+      expect(getBurnAddress('ISSUE_ROOT', 'xna-pq-test')).to.equal('tBURNXXXXXXXXXXXXXXXXXXXXXXXVZLroy');
+    });
+  });
+});

package/tests/unit/validators/assetNameValidator.test.js

@@ -172,10 +172,34 @@ describe('AssetNameValidator', () => {
     });
   });
 
+  describe('validateDepin', () => {
+    it('should validate correct DEPIN asset names', () => {
+      expect(AssetNameValidator.validateDepin('&FRANCE')).to.be.true;
+      expect(AssetNameValidator.validateDepin('&FRANCE/PARIS')).to.be.true;
+      expect(AssetNameValidator.validateDepin('&NODE_1')).to.be.true;
+    });
+
+    it('should reject names without & prefix', () => {
+      expect(() => AssetNameValidator.validateDepin('FRANCE'))
+        .to.throw(InvalidAssetNameError, 'must start with &');
+    });
+
+    it('should reject lowercase depin names', () => {
+      expect(() => AssetNameValidator.validateDepin('&france'))
+        .to.throw(InvalidAssetNameError, 'must be uppercase');
+    });
+
+    it('should reject depin sub-parts shorter than 3 characters', () => {
+      expect(() => AssetNameValidator.validateDepin('&FRANCE/AB'))
+        .to.throw(InvalidAssetNameError, 'Each DEPIN sub-part must be at least 3 characters');
+    });
+  });
+
   describe('validateOwnerToken', () => {
     it('should validate correct owner token names', () => {
       expect(AssetNameValidator.validateOwnerToken('MYTOKEN!')).to.be.true;
       expect(AssetNameValidator.validateOwnerToken('$SECURITY!')).to.be.true;
+      expect(AssetNameValidator.validateOwnerToken('&FRANCE!')).to.be.true;
     });
 
     it('should reject names without ! suffix', () => {
@@ -220,6 +244,11 @@ describe('AssetNameValidator', () => {
       expect(type).to.equal('RESTRICTED');
     });
 
+    it('should detect and validate DEPIN assets', () => {
+      const type = AssetNameValidator.validateAndDetectType('&FRANCE/PARIS');
+      expect(type).to.equal('DEPIN');
+    });
+
     it('should detect and validate OWNER tokens', () => {
       const type = AssetNameValidator.validateAndDetectType('MYTOKEN!');
       expect(type).to.equal('OWNER');