@neuraiproject/neurai-assets 1.0.0

package/src/builders/TagAddressBuilder.js

@@ -0,0 +1,243 @@
+/**
+ * Tag Address Builder
+ * Builds transactions for tagging/untagging addresses with qualifiers
+ *
+ * Tag operations:
+ * - Assign qualifier tags to addresses (for restricted asset compliance)
+ * - Remove qualifier tags from addresses
+ * - Cost: 0.1 XNA per address (burned)
+ * - Requires qualifier's owner token (#QUALIFIER!)
+ * - Used to mark addresses as KYC'd, accredited, etc.
+ * - Owner token must be returned
+ */
+
+const BaseAssetTransactionBuilder = require('./BaseAssetTransactionBuilder');
+const { OutputFormatter, AssetNameParser } = require('../utils');
+const { AssetNotFoundError, OwnerTokenNotFoundError, InvalidAddressError } = require('../errors');
+
+class TagAddressBuilder extends BaseAssetTransactionBuilder {
+  /**
+   * Validate tag/untag parameters
+   * @param {object} params - Tag parameters
+   * @param {boolean} isUntag - True if untag operation
+   * @throws {Error} If validation fails
+   */
+  validateParams(params, isUntag = false) {
+    // Validate required parameters
+    if (!params.qualifierName) {
+      throw new Error('qualifierName is required');
+    }
+
+    if (!params.addresses || !Array.isArray(params.addresses) || params.addresses.length === 0) {
+      throw new Error('addresses is required and must be a non-empty array');
+    }
+
+    // Validate qualifier name
+    this.validateAssetName(params.qualifierName, 'QUALIFIER');
+
+    // Validate addresses
+    params.addresses.forEach((address, index) => {
+      if (!address || typeof address !== 'string') {
+        throw new InvalidAddressError(
+          `addresses[${index}] must be a non-empty string`,
+          address
+        );
+      }
+
+      // Basic address validation (starts with N or m/n depending on network)
+      const validPrefixes = this.network === 'xna' ? ['N'] : ['m', 'n'];
+      if (!validPrefixes.some(prefix => address.startsWith(prefix))) {
+        throw new InvalidAddressError(
+          `addresses[${index}] has invalid prefix for network ${this.network}`,
+          address
+        );
+      }
+    });
+
+    return true;
+  }
+
+  /**
+   * Build tag addresses transaction
+   * @param {boolean} isUntag - True for untag operation, false for tag
+   * @returns {Promise<object>} Transaction result
+   */
+  async buildTagOperation(isUntag = false) {
+    // 1. Validate parameters
+    await this.validateParams(this.params, isUntag);
+
+    const {
+      qualifierName,
+      addresses: targetAddresses,
+      assetData = ''
+    } = this.params;
+
+    // 2. Check if qualifier exists
+    const qualifierExists = await this.assetExists(qualifierName);
+    if (!qualifierExists) {
+      throw new AssetNotFoundError(
+        `Qualifier ${qualifierName} does not exist. You must create the qualifier first.`,
+        qualifierName
+      );
+    }
+
+    // 3. Get wallet addresses
+    const addresses = await this._getAddresses();
+    const changeAddress = await this.getChangeAddress();
+
+    // 4. Find qualifier's owner token (CRITICAL: must have this)
+    const ownerTokenName = AssetNameParser.getOwnerTokenName(qualifierName);
+    let ownerTokenUTXO;
+    try {
+      ownerTokenUTXO = await this.ownerTokenManager.findOwnerTokenUTXO(
+        ownerTokenName,
+        addresses
+      );
+    } catch (error) {
+      if (error instanceof OwnerTokenNotFoundError) {
+        throw new OwnerTokenNotFoundError(
+          `You must own the qualifier's owner token (${ownerTokenName}) to tag/untag addresses.`,
+          ownerTokenName
+        );
+      }
+      throw error;
+    }
+
+    // 5. Get burn information (0.1 XNA per address)
+    const addressCount = targetAddresses.length;
+    const burnInfo = isUntag
+      ? this.burnManager.getUntagAddressBurn(addressCount)
+      : this.burnManager.getTagAddressBurn(addressCount);
+
+    // 6. Estimate fee
+    const estimatedFee = await this.estimateFee(2, 3);
+
+    // 7. Calculate total XNA needed
+    const totalXNANeeded = burnInfo.amount + estimatedFee;
+
+    // 8. Select XNA UTXOs
+    const utxoSelection = await this.selectUTXOs(totalXNANeeded, null, 0);
+    const baseCurrencyUTXOs = utxoSelection.xnaUTXOs;
+    const totalXNAInput = utxoSelection.totalXNA;
+
+    // 9. Recalculate fee with actual input count
+    const actualInputCount = baseCurrencyUTXOs.length + 1; // +1 for owner token
+    const actualFee = await this.estimateFee(actualInputCount, 3);
+
+    // 10. Verify we have enough XNA
+    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);
+    }
+
+    // 11. Calculate XNA change
+    const finalTotalInput = baseCurrencyUTXOs.reduce(
+      (sum, utxo) => sum + utxo.satoshis / 100000000,
+      0
+    );
+    const xnaChange = finalTotalInput - burnInfo.amount - actualFee;
+
+    // 12. Build inputs (XNA + owner token)
+    const inputs = [];
+
+    // Add XNA inputs
+    baseCurrencyUTXOs.forEach(utxo => {
+      inputs.push({
+        txid: utxo.txid,
+        vout: utxo.outputIndex,
+        address: utxo.address,
+        satoshis: utxo.satoshis
+      });
+    });
+
+    // Add owner token input
+    inputs.push({
+      txid: ownerTokenUTXO.txid,
+      vout: ownerTokenUTXO.outputIndex,
+      address: ownerTokenUTXO.address,
+      assetName: ownerTokenUTXO.assetName,
+      satoshis: ownerTokenUTXO.satoshis
+    });
+
+    // 13. Build outputs (ORDER CRITICAL!)
+    const outputs = {};
+
+    // First: Burn output
+    outputs[burnInfo.address] = burnInfo.amount;
+
+    // Second: XNA change (if any)
+    if (xnaChange > 0.00000001) {
+      outputs[changeAddress] = parseFloat(xnaChange.toFixed(8));
+    }
+
+    // Third: Owner token return (CRITICAL - must return or lost forever!)
+    const ownerTokenReturn = this.ownerTokenManager.createOwnerTokenReturnOutput(
+      ownerTokenName,
+      changeAddress
+    );
+    Object.assign(outputs, ownerTokenReturn);
+
+    // Last: Tag/Untag operation
+    // Note: Using first address as transaction output address (protocol requirement)
+    const operationOutput = isUntag
+      ? OutputFormatter.formatUntagAddressesOutput({
+          tag_name: qualifierName,
+          addresses: targetAddresses
+        })
+      : OutputFormatter.formatTagAddressesOutput({
+          tag_name: qualifierName,
+          addresses: targetAddresses,
+          asset_data: assetData
+        });
+
+    outputs[targetAddresses[0]] = operationOutput;
+
+    // 14. Order outputs (protocol requirement)
+    const orderedOutputs = this.outputOrderer.order(outputs);
+
+    // 15. Validate owner token is returned (safety check)
+    this.ownerTokenManager.validateOwnerTokenReturn(inputs, orderedOutputs);
+
+    // 16. Create raw transaction
+    const rawTx = await this.buildRawTransaction(inputs, orderedOutputs);
+
+    // 17. Format and return result
+    const allUTXOs = [...baseCurrencyUTXOs, ownerTokenUTXO];
+
+    return this.formatResult(
+      rawTx,
+      allUTXOs,
+      inputs,
+      orderedOutputs,
+      actualFee,
+      burnInfo.amount,
+      {
+        qualifierName,
+        ownerTokenUsed: ownerTokenName,
+        targetAddresses,
+        addressCount,
+        operationType: isUntag ? 'UNTAG_ADDRESSES' : 'TAG_ADDRESSES'
+      }
+    );
+  }
+
+  /**
+   * Build tag addresses transaction
+   * @returns {Promise<object>} Transaction result
+   */
+  async build() {
+    return this.buildTagOperation(false);
+  }
+
+  /**
+   * Build untag addresses transaction
+   * @returns {Promise<object>} Transaction result
+   */
+  async buildUntag() {
+    return this.buildTagOperation(true);
+  }
+}
+
+module.exports = TagAddressBuilder;

package/src/builders/index.js

@@ -0,0 +1,38 @@
+/**
+ * Builders Module
+ * Exports all transaction builder classes
+ */
+
+// Base
+const BaseAssetTransactionBuilder = require('./BaseAssetTransactionBuilder');
+
+// Basic Builders
+const IssueRootBuilder = require('./IssueRootBuilder');
+const IssueSubBuilder = require('./IssueSubBuilder');
+const ReissueBuilder = require('./ReissueBuilder');
+
+// Advanced Builders
+const IssueUniqueBuilder = require('./IssueUniqueBuilder');
+const IssueQualifierBuilder = require('./IssueQualifierBuilder');
+const IssueRestrictedBuilder = require('./IssueRestrictedBuilder');
+const ReissueRestrictedBuilder = require('./ReissueRestrictedBuilder');
+const TagAddressBuilder = require('./TagAddressBuilder');
+const FreezeAddressBuilder = require('./FreezeAddressBuilder');
+
+module.exports = {
+  // Base
+  BaseAssetTransactionBuilder,
+
+  // Basic Builders
+  IssueRootBuilder,
+  IssueSubBuilder,
+  ReissueBuilder,
+
+  // Advanced Builders
+  IssueUniqueBuilder,
+  IssueQualifierBuilder,
+  IssueRestrictedBuilder,
+  ReissueRestrictedBuilder,
+  TagAddressBuilder,
+  FreezeAddressBuilder
+};

package/src/constants/assetTypes.js

@@ -0,0 +1,23 @@
+/**
+ * Neurai Asset Types
+ * Based on: src/assets/assettypes.h
+ */
+
+const AssetType = {
+  ROOT: 0,           // Top-level asset (Cost: 1000 XNA)
+  SUB: 1,            // Sub-asset (Cost: 200 XNA, requires PARENT!)
+  UNIQUE: 2,         // NFT/Unique asset (Cost: 10 XNA per token)
+  MSGCHANNEL: 3,     // Message channel (Cost: 200 XNA, legacy)
+  QUALIFIER: 4,      // KYC qualifier tag (Cost: 2000 XNA)
+  SUB_QUALIFIER: 5,  // Sub-qualifier (Cost: 200 XNA)
+  RESTRICTED: 6,     // Restricted/security token (Cost: 3000 XNA)
+  VOTE: 7,           // Voting asset (Reserved for future use)
+  REISSUE: 8,        // Reissuance operation (Cost: 200 XNA)
+  OWNER: 9,          // Owner token (Cost: 0 XNA, auto-generated)
+  NULL_ADD_QUALIFIER: 10,  // Qualifier assignment (Cost: 0.1 XNA)
+  DEPIN: 12          // Soulbound DePIN asset (Testnet only)
+};
+
+module.exports = {
+  AssetType
+};

package/src/constants/burnAddresses.js

@@ -0,0 +1,65 @@
+/**
+ * Burn Addresses for Asset Operations
+ * Different addresses for mainnet and testnet
+ */
+
+const MAINNET_BURN_ADDRESSES = {
+  ISSUE_ROOT: 'NbURNXXXXXXXXXXXXXXXXXXXXXXXT65Gdr',
+  ISSUE_SUB: 'NXissueSubAssetXXXXXXXXXXXXXX6B2JF',
+  ISSUE_UNIQUE: 'NXissueUniqueAssetXXXXXXXXXXUBzP4Z',
+  ISSUE_MSGCHANNEL: 'NXissueMsgChanneLAssetXXXXXXVeF2mU',
+  REISSUE: 'NXReissueAssetXXXXXXXXXXXXXXVEFAWu',
+  ISSUE_RESTRICTED: 'NXissueRestrictedXXXXXXXXXXXZaQtSE',
+  ISSUE_QUALIFIER: 'NXissueQualifierAssetXXXXXXXXWPHpDX',
+  ISSUE_SUB_QUALIFIER: 'NXissueSubQualifierAssetXXXXXYWcFp8',
+  TAG_ADDRESS: 'NXaddTagBurnXXXXXXXXXXXXXXXXUBL1a5',
+  UNTAG_ADDRESS: 'NXaddTagBurnXXXXXXXXXXXXXXXXUBL1a5'
+};
+
+const TESTNET_BURN_ADDRESSES = {
+  ISSUE_ROOT: 'mbURNXXXXXXXXXXXXXXXXXXXXXXUV9F72',
+  ISSUE_SUB: 'mXissueSubAssetXXXXXXXXXXXXXUDJP6N',
+  ISSUE_UNIQUE: 'mXissueUniqueAssetXXXXXXXXXXQV8W2V',
+  ISSUE_MSGCHANNEL: 'mXissueMsgChanneLAssetXXXXXXX9fhPh',
+  REISSUE: 'mXReissueAssetXXXXXXXXXXXXXXTZzJ3c',
+  ISSUE_RESTRICTED: 'mXissueRestrictedXXXXXXXXXXXXYHqJY',
+  ISSUE_QUALIFIER: 'mXissueQualifierAssetXXXXXXXXZhqiGs',
+  ISSUE_SUB_QUALIFIER: 'mXissueSubQualifierAssetXXXXXab7bRN',
+  TAG_ADDRESS: 'mXaddTagBurnXXXXXXXXXXXXXXXXWEKFqa',
+  UNTAG_ADDRESS: 'mXaddTagBurnXXXXXXXXXXXXXXXXWEKFqa'
+};
+
+/**
+ * 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')
+ * @returns {string} Burn address
+ */
+function getBurnAddress(operationType, network) {
+  const addresses = network === 'xna' ? MAINNET_BURN_ADDRESSES : TESTNET_BURN_ADDRESSES;
+
+  const address = addresses[operationType];
+  if (!address) {
+    throw new Error(`Unknown operation type: ${operationType} for network: ${network}`);
+  }
+
+  return address;
+}
+
+/**
+ * Check if an address is a burn address
+ * @param {string} address - Address to check
+ * @param {string} network - Network type ('xna' or 'xna-test')
+ * @returns {boolean} True if it's a burn address
+ */
+function isBurnAddress(address, network) {
+  const addresses = network === 'xna' ? MAINNET_BURN_ADDRESSES : TESTNET_BURN_ADDRESSES;
+  return Object.values(addresses).includes(address);
+}
+
+module.exports = {
+  MAINNET_BURN_ADDRESSES,
+  TESTNET_BURN_ADDRESSES,
+  getBurnAddress,
+  isBurnAddress
+};

package/src/constants/fees.js

@@ -0,0 +1,61 @@
+/**
+ * Asset Operation Costs (in XNA)
+ * These are burn amounts required for each operation
+ */
+
+const ASSET_COSTS = {
+  ISSUE_ROOT: 1000,
+  ISSUE_SUB: 200,
+  ISSUE_UNIQUE: 10,  // Per NFT
+  ISSUE_MSGCHANNEL: 200,
+  ISSUE_QUALIFIER: 2000,
+  ISSUE_SUB_QUALIFIER: 200,
+  ISSUE_RESTRICTED: 3000,
+  REISSUE: 200,
+  REISSUE_RESTRICTED: 200,
+  TAG_ADDRESS: 0.1,   // Per address
+  UNTAG_ADDRESS: 0.1, // Per address
+  FREEZE_ADDRESS: 0,  // No cost (requires owner token)
+  UNFREEZE_ADDRESS: 0, // No cost (requires owner token)
+  FREEZE_ASSET: 0,    // No cost (requires owner token)
+  UNFREEZE_ASSET: 0,  // No cost (requires owner token)
+  OWNER_TOKEN: 0      // Auto-generated, no cost
+};
+
+/**
+ * Get cost for a specific operation type
+ * @param {string} operationType - Operation type (e.g., 'ISSUE_ROOT')
+ * @returns {number} Cost in XNA
+ */
+function getAssetCost(operationType) {
+  const cost = ASSET_COSTS[operationType];
+  if (cost === undefined) {
+    throw new Error(`Unknown operation type: ${operationType}`);
+  }
+  return cost;
+}
+
+/**
+ * Calculate total cost for unique asset issuance
+ * @param {number} count - Number of unique assets to create
+ * @returns {number} Total cost in XNA
+ */
+function getUniqueAssetCost(count) {
+  return ASSET_COSTS.ISSUE_UNIQUE * count;
+}
+
+/**
+ * Calculate total cost for tagging multiple addresses
+ * @param {number} addressCount - Number of addresses to tag
+ * @returns {number} Total cost in XNA
+ */
+function getTaggingCost(addressCount) {
+  return ASSET_COSTS.TAG_ADDRESS * addressCount;
+}
+
+module.exports = {
+  ASSET_COSTS,
+  getAssetCost,
+  getUniqueAssetCost,
+  getTaggingCost
+};

package/src/constants/index.js

@@ -0,0 +1,44 @@
+/**
+ * Constants Module
+ * Exports all constant values and configurations
+ */
+
+const { AssetType } = require('./assetTypes');
+const { ASSET_COSTS, getAssetCost, getUniqueAssetCost, getTaggingCost } = require('./fees');
+const {
+  MAINNET_BURN_ADDRESSES,
+  TESTNET_BURN_ADDRESSES,
+  getBurnAddress,
+  isBurnAddress
+} = require('./burnAddresses');
+const {
+  NETWORKS,
+  ASSET_NAME_RULES,
+  ASSET_LIMITS,
+  getNetworkConfig,
+  detectNetworkFromAddress
+} = require('./networks');
+
+module.exports = {
+  // Asset Types
+  AssetType,
+
+  // Fees/Costs
+  ASSET_COSTS,
+  getAssetCost,
+  getUniqueAssetCost,
+  getTaggingCost,
+
+  // Burn Addresses
+  MAINNET_BURN_ADDRESSES,
+  TESTNET_BURN_ADDRESSES,
+  getBurnAddress,
+  isBurnAddress,
+
+  // Networks
+  NETWORKS,
+  ASSET_NAME_RULES,
+  ASSET_LIMITS,
+  getNetworkConfig,
+  detectNetworkFromAddress
+};

package/src/constants/networks.js

@@ -0,0 +1,112 @@
+/**
+ * Network Configuration for Neurai
+ */
+
+const NETWORKS = {
+  MAINNET: {
+    name: 'xna',
+    displayName: 'Neurai Mainnet',
+    addressPrefix: 'N',
+    assetNameMaxLength: 31,
+    defaultRPCPort: 8766,
+    coin: 'XNA'
+  },
+  TESTNET: {
+    name: 'xna-test',
+    displayName: 'Neurai Testnet',
+    addressPrefix: 'm',
+    assetNameMaxLength: 31,  // Same as mainnet
+    defaultRPCPort: 18766,
+    coin: 'TXNA'
+  }
+};
+
+/**
+ * Asset naming rules (same for all networks)
+ */
+const ASSET_NAME_RULES = {
+  ROOT: {
+    minLength: 3,
+    maxLength: 30,
+    pattern: /^[A-Z0-9_.]+$/,
+    cannotStartWith: ['.', 'A', 'Z'],
+    reserved: ['XNA', 'NEURAI']
+  },
+  SUB: {
+    minLength: 1,
+    maxLength: 30,
+    pattern: /^[A-Z0-9_.]+$/,
+    separator: '/',
+    maxDepth: 1  // Only one level of sub-assets
+  },
+  UNIQUE: {
+    minLength: 1,
+    maxLength: 30,
+    pattern: /^[A-Z0-9_.]+$/,
+    separator: '#'
+  },
+  QUALIFIER: {
+    minLength: 3,
+    maxLength: 30,
+    pattern: /^[A-Z0-9_]+$/,
+    prefix: '#',
+    separator: '/'
+  },
+  RESTRICTED: {
+    minLength: 3,
+    maxLength: 30,
+    pattern: /^[A-Z0-9_.]+$/,
+    prefix: '$'
+  }
+};
+
+/**
+ * Asset quantity limits
+ */
+const ASSET_LIMITS = {
+  MIN_QUANTITY: 1,
+  MAX_QUANTITY: 21000000000,  // 21 billion (same as Bitcoin's 21M with 3 extra decimals)
+  MIN_UNITS: 0,
+  MAX_UNITS: 8,
+  OWNER_TOKEN_QUANTITY: 1,    // Owner tokens are always exactly 1
+  QUALIFIER_MIN_QUANTITY: 1,
+  QUALIFIER_MAX_QUANTITY: 10  // Qualifiers are limited to 1-10 units
+};
+
+/**
+ * Get network configuration
+ * @param {string} networkName - Network name ('xna' or 'xna-test')
+ * @returns {object} Network configuration
+ */
+function getNetworkConfig(networkName) {
+  if (networkName === 'xna' || networkName === 'mainnet') {
+    return NETWORKS.MAINNET;
+  } else if (networkName === 'xna-test' || networkName === 'testnet') {
+    return NETWORKS.TESTNET;
+  } else {
+    throw new Error(`Unknown network: ${networkName}`);
+  }
+}
+
+/**
+ * Detect network from address prefix
+ * @param {string} address - Neurai address
+ * @returns {string} Network name ('xna' or 'xna-test')
+ */
+function detectNetworkFromAddress(address) {
+  if (address.startsWith('N')) {
+    return 'xna';
+  } else if (address.startsWith('m') || address.startsWith('n')) {
+    return 'xna-test';
+  } else {
+    throw new Error(`Cannot detect network from address: ${address}`);
+  }
+}
+
+module.exports = {
+  NETWORKS,
+  ASSET_NAME_RULES,
+  ASSET_LIMITS,
+  getNetworkConfig,
+  detectNetworkFromAddress
+};