@neuraiproject/neurai-assets 1.0.0

package/src/builders/BaseAssetTransactionBuilder.js

@@ -0,0 +1,303 @@
+/**
+ * Base Asset Transaction Builder
+ * Abstract base class for all transaction builders
+ *
+ * Provides common functionality:
+ * - UTXO selection
+ * - Fee estimation
+ * - Output ordering
+ * - Raw transaction creation
+ * - Validation
+ *
+ * Subclasses must implement:
+ * - validateParams(params)
+ * - build()
+ */
+
+const { BurnManager, OwnerTokenManager, UTXOSelector, OutputOrderer } = require('../managers');
+const { AssetNameValidator, AmountValidator } = require('../validators');
+
+class BaseAssetTransactionBuilder {
+  /**
+   * @param {Function} rpc - RPC function
+   * @param {string} network - Network type ('xna' or 'xna-test')
+   * @param {string[]|Function} addresses - Wallet addresses or function that returns addresses
+   * @param {object} params - Transaction parameters
+   */
+  constructor(rpc, network, addresses, params) {
+    if (!rpc || typeof rpc !== 'function') {
+      throw new Error('RPC function is required');
+    }
+
+    if (!network) {
+      throw new Error('Network is required');
+    }
+
+    // Addresses can be an array or a function that returns addresses
+    if (typeof addresses === 'function') {
+      this.getAddresses = addresses;
+    } else if (Array.isArray(addresses)) {
+      this.getAddresses = () => addresses;
+    } else {
+      throw new Error('Addresses must be an array or a function');
+    }
+
+    this.rpc = rpc;
+    this.network = network;
+    this.params = params || {};
+
+    // Initialize managers
+    this.burnManager = new BurnManager(network);
+    this.ownerTokenManager = new OwnerTokenManager(rpc);
+    this.utxoSelector = new UTXOSelector(rpc);
+    this.outputOrderer = new OutputOrderer();
+  }
+
+  /**
+   * Get wallet addresses
+   * @returns {string[]} Array of addresses
+   */
+  async _getAddresses() {
+    const addresses = await this.getAddresses();
+    if (!Array.isArray(addresses) || addresses.length === 0) {
+      throw new Error('No addresses available');
+    }
+    return addresses;
+  }
+
+  /**
+   * Validate transaction parameters
+   * Must be implemented by subclasses
+   * @param {object} params - Parameters to validate
+   * @throws {Error} If validation fails
+   */
+  validateParams(params) {
+    throw new Error('validateParams must be implemented by subclass');
+  }
+
+  /**
+   * Build the transaction
+   * Must be implemented by subclasses
+   * @returns {Promise<object>} Transaction result
+   */
+  async build() {
+    throw new Error('build must be implemented by subclass');
+  }
+
+  /**
+   * Estimate transaction fee
+   * @param {number} inputCount - Number of inputs
+   * @param {number} outputCount - Number of outputs
+   * @returns {Promise<number>} Estimated fee in XNA
+   */
+  async estimateFee(inputCount, outputCount) {
+    const feeRate = await this.utxoSelector.getFeeRate();
+    return this.utxoSelector.estimateFee(inputCount, outputCount, feeRate);
+  }
+
+  /**
+   * Select UTXOs for transaction
+   * @param {number} xnaAmount - Required XNA amount (for fees + burn)
+   * @param {string|null} assetName - Asset name if needed
+   * @param {number} assetAmount - Asset amount if needed
+   * @returns {Promise<object>} Selected UTXOs
+   */
+  async selectUTXOs(xnaAmount, assetName = null, assetAmount = 0) {
+    const addresses = await this._getAddresses();
+    return this.utxoSelector.selectMixedUTXOs(
+      addresses,
+      xnaAmount,
+      assetName,
+      assetAmount
+    );
+  }
+
+  /**
+   * Build raw transaction using RPC
+   * @param {Array} inputs - Transaction inputs
+   * @param {object} outputs - Transaction outputs (must be ordered)
+   * @returns {Promise<string>} Raw transaction hex
+   */
+  async buildRawTransaction(inputs, outputs) {
+    try {
+      // Format inputs for createrawtransaction
+      const formattedInputs = inputs.map(input => ({
+        txid: input.txid,
+        vout: input.vout !== undefined ? input.vout : input.outputIndex
+      }));
+
+      // Call createrawtransaction
+      const rawTx = await this.rpc('createrawtransaction', [
+        formattedInputs,
+        outputs
+      ]);
+
+      return rawTx;
+    } catch (error) {
+      throw new Error(`Failed to create raw transaction: ${error.message}`);
+    }
+  }
+
+  /**
+   * Calculate change amount
+   * @param {number} totalInput - Total input amount
+   * @param {number} totalOutput - Total output amount (including fee)
+   * @returns {number} Change amount
+   */
+  calculateChange(totalInput, totalOutput) {
+    const change = totalInput - totalOutput;
+    if (change < 0) {
+      throw new Error('Insufficient funds: inputs < outputs');
+    }
+    return change;
+  }
+
+  /**
+   * Get change address
+   * Uses first address from wallet by default
+   * Can be overridden by params.changeAddress
+   * @returns {Promise<string>} Change address
+   */
+  async getChangeAddress() {
+    if (this.params.changeAddress) {
+      return this.params.changeAddress;
+    }
+
+    const addresses = await this._getAddresses();
+    return addresses[0];
+  }
+
+  /**
+   * Get recipient address
+   * Uses first address from wallet if not specified
+   * @returns {Promise<string>} Recipient address
+   */
+  async getToAddress() {
+    if (this.params.toAddress) {
+      return this.params.toAddress;
+    }
+
+    const addresses = await this._getAddresses();
+    return addresses[0];
+  }
+
+  /**
+   * Common validation for asset name
+   * @param {string} assetName - Asset name to validate
+   * @param {string} type - Expected type ('ROOT', 'SUB', etc.)
+   */
+  validateAssetName(assetName, type) {
+    if (!assetName) {
+      throw new Error('Asset name is required');
+    }
+
+    switch (type) {
+      case 'ROOT':
+        AssetNameValidator.validateRoot(assetName);
+        break;
+      case 'SUB':
+        AssetNameValidator.validateSub(assetName);
+        break;
+      case 'UNIQUE':
+        AssetNameValidator.validateUnique(assetName);
+        break;
+      case 'QUALIFIER':
+        AssetNameValidator.validateQualifier(assetName);
+        break;
+      case 'RESTRICTED':
+        AssetNameValidator.validateRestricted(assetName);
+        break;
+      default:
+        throw new Error(`Unknown asset type: ${type}`);
+    }
+  }
+
+  /**
+   * Common validation for amount and units
+   * @param {number} quantity - Quantity to validate
+   * @param {number} units - Units (decimal places)
+   */
+  validateAmount(quantity, units) {
+    AmountValidator.validate(quantity, units);
+  }
+
+  /**
+   * Convert amount to satoshis
+   * @param {number} amount - Amount in asset units
+   * @param {number} units - Decimal places
+   * @returns {number} Amount in satoshis
+   */
+  toSatoshis(amount, units) {
+    return Math.round(amount * Math.pow(10, units));
+  }
+
+  /**
+   * Convert satoshis to amount
+   * @param {number} satoshis - Amount in satoshis
+   * @param {number} units - Decimal places
+   * @returns {number} Amount in asset units
+   */
+  fromSatoshis(satoshis, units) {
+    return satoshis / Math.pow(10, units);
+  }
+
+  /**
+   * Format transaction result
+   * @param {string} rawTx - Raw transaction hex
+   * @param {Array} utxos - UTXOs used
+   * @param {Array} inputs - Transaction inputs
+   * @param {object} outputs - Transaction outputs
+   * @param {number} fee - Transaction fee
+   * @param {number} burnAmount - Burn amount
+   * @param {object} extra - Extra information
+   * @returns {object} Formatted result
+   */
+  formatResult(rawTx, utxos, inputs, outputs, fee, burnAmount, extra = {}) {
+    return {
+      rawTx,
+      utxos,
+      inputs,
+      outputs,
+      fee,
+      burnAmount,
+      ...extra
+    };
+  }
+
+  /**
+   * Check if asset exists (to prevent creating duplicates)
+   * @param {string} assetName - Asset name to check
+   * @returns {Promise<boolean>} True if exists
+   */
+  async assetExists(assetName) {
+    try {
+      const assetData = await this.rpc('getassetdata', [assetName]);
+      return assetData !== null && assetData !== undefined;
+    } catch (error) {
+      // If asset doesn't exist, RPC will throw error
+      if (error.message && error.message.includes('not found')) {
+        return false;
+      }
+      // Re-throw other errors
+      throw error;
+    }
+  }
+
+  /**
+   * Get asset data from blockchain
+   * @param {string} assetName - Asset name
+   * @returns {Promise<object|null>} Asset data or null if not found
+   */
+  async getAssetData(assetName) {
+    try {
+      return await this.rpc('getassetdata', [assetName]);
+    } catch (error) {
+      if (error.message && error.message.includes('not found')) {
+        return null;
+      }
+      throw error;
+    }
+  }
+}
+
+module.exports = BaseAssetTransactionBuilder;

package/src/builders/FreezeAddressBuilder.js

@@ -0,0 +1,271 @@
+/**
+ * Freeze Address Builder
+ * Builds transactions for freezing/unfreezing addresses and assets
+ *
+ * Freeze operations (restricted assets only):
+ * - Freeze specific addresses (prevent trading)
+ * - Unfreeze specific addresses (allow trading again)
+ * - Global asset freeze (freeze entire asset)
+ * - Global asset unfreeze (unfreeze entire asset)
+ * - Cost: No burn (but requires fee)
+ * - Requires restricted asset's owner token ($ASSET!)
+ * - Owner token must be returned
+ */
+
+const BaseAssetTransactionBuilder = require('./BaseAssetTransactionBuilder');
+const { OutputFormatter, AssetNameParser } = require('../utils');
+const { AssetNotFoundError, OwnerTokenNotFoundError, InvalidAddressError } = require('../errors');
+
+class FreezeAddressBuilder extends BaseAssetTransactionBuilder {
+  /**
+   * Validate freeze/unfreeze parameters
+   * @param {object} params - Freeze parameters
+   * @param {string} operationType - Operation type
+   * @throws {Error} If validation fails
+   */
+  validateParams(params, operationType) {
+    // Validate required parameters
+    if (!params.assetName) {
+      throw new Error('assetName is required');
+    }
+
+    // Validate asset name is restricted
+    this.validateAssetName(params.assetName, 'RESTRICTED');
+
+    // For address-specific operations, validate addresses
+    if (operationType === 'FREEZE_ADDRESSES' || operationType === 'UNFREEZE_ADDRESSES') {
+      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 each address
+      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
+        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 freeze operation transaction
+   * @param {string} operationType - Operation type
+   * @returns {Promise<object>} Transaction result
+   */
+  async buildFreezeOperation(operationType) {
+    // 1. Validate parameters
+    await this.validateParams(this.params, operationType);
+
+    const { assetName } = this.params;
+
+    // 2. Check if asset exists and is restricted
+    const assetData = await this.getAssetData(assetName);
+    if (!assetData) {
+      throw new AssetNotFoundError(
+        `Asset ${assetName} does not exist on the blockchain`,
+        assetName
+      );
+    }
+
+    // 3. Get wallet addresses
+    const addresses = await this._getAddresses();
+    const changeAddress = await this.getChangeAddress();
+
+    // 4. Find owner token (CRITICAL: must have this)
+    const ownerTokenName = AssetNameParser.getOwnerTokenName(assetName);
+    let ownerTokenUTXO;
+    try {
+      ownerTokenUTXO = await this.ownerTokenManager.findOwnerTokenUTXO(
+        ownerTokenName,
+        addresses
+      );
+    } catch (error) {
+      if (error instanceof OwnerTokenNotFoundError) {
+        throw new OwnerTokenNotFoundError(
+          `You must own the restricted asset's owner token (${ownerTokenName}) to freeze/unfreeze addresses or the asset.`,
+          ownerTokenName
+        );
+      }
+      throw error;
+    }
+
+    // 5. No burn for freeze operations (only fee)
+    const burnAmount = 0;
+
+    // 6. Estimate fee
+    const estimatedFee = await this.estimateFee(2, 3);
+
+    // 7. Select XNA UTXOs (only for fee, no burn)
+    const utxoSelection = await this.selectUTXOs(estimatedFee, null, 0);
+    const baseCurrencyUTXOs = utxoSelection.xnaUTXOs;
+    const totalXNAInput = utxoSelection.totalXNA;
+
+    // 8. Recalculate fee with actual input count
+    const actualInputCount = baseCurrencyUTXOs.length + 1; // +1 for owner token
+    const actualFee = await this.estimateFee(actualInputCount, 3);
+
+    // 9. Verify we have enough XNA for fee
+    if (totalXNAInput < actualFee) {
+      const additionalNeeded = actualFee - totalXNAInput + 0.001;
+      const additionalSelection = await this.selectUTXOs(additionalNeeded, null, 0);
+      baseCurrencyUTXOs.push(...additionalSelection.xnaUTXOs);
+    }
+
+    // 10. Calculate XNA change
+    const finalTotalInput = baseCurrencyUTXOs.reduce(
+      (sum, utxo) => sum + utxo.satoshis / 100000000,
+      0
+    );
+    const xnaChange = finalTotalInput - actualFee;
+
+    // 11. 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
+    });
+
+    // 12. Build outputs (ORDER CRITICAL!)
+    const outputs = {};
+
+    // First: XNA change (if any)
+    if (xnaChange > 0.00000001) {
+      outputs[changeAddress] = parseFloat(xnaChange.toFixed(8));
+    }
+
+    // Second: Owner token return (CRITICAL - must return or lost forever!)
+    const ownerTokenReturn = this.ownerTokenManager.createOwnerTokenReturnOutput(
+      ownerTokenName,
+      changeAddress
+    );
+    Object.assign(outputs, ownerTokenReturn);
+
+    // Last: Freeze/Unfreeze operation
+    let operationOutput;
+    let targetAddresses = [];
+
+    switch (operationType) {
+      case 'FREEZE_ADDRESSES':
+        targetAddresses = this.params.addresses;
+        operationOutput = OutputFormatter.formatFreezeAddressesOutput({
+          asset_name: assetName,
+          addresses: targetAddresses
+        });
+        outputs[targetAddresses[0]] = operationOutput;
+        break;
+
+      case 'UNFREEZE_ADDRESSES':
+        targetAddresses = this.params.addresses;
+        operationOutput = OutputFormatter.formatUnfreezeAddressesOutput({
+          asset_name: assetName,
+          addresses: targetAddresses
+        });
+        outputs[targetAddresses[0]] = operationOutput;
+        break;
+
+      case 'FREEZE_ASSET':
+        operationOutput = OutputFormatter.formatFreezeAssetOutput(assetName);
+        outputs[changeAddress] = operationOutput;
+        break;
+
+      case 'UNFREEZE_ASSET':
+        operationOutput = OutputFormatter.formatUnfreezeAssetOutput(assetName);
+        outputs[changeAddress] = operationOutput;
+        break;
+
+      default:
+        throw new Error(`Unknown freeze operation type: ${operationType}`);
+    }
+
+    // 13. Order outputs (protocol requirement)
+    const orderedOutputs = this.outputOrderer.order(outputs);
+
+    // 14. Validate owner token is returned (safety check)
+    this.ownerTokenManager.validateOwnerTokenReturn(inputs, orderedOutputs);
+
+    // 15. Create raw transaction
+    const rawTx = await this.buildRawTransaction(inputs, orderedOutputs);
+
+    // 16. Format and return result
+    const allUTXOs = [...baseCurrencyUTXOs, ownerTokenUTXO];
+
+    return this.formatResult(
+      rawTx,
+      allUTXOs,
+      inputs,
+      orderedOutputs,
+      actualFee,
+      burnAmount,
+      {
+        assetName,
+        ownerTokenUsed: ownerTokenName,
+        targetAddresses: targetAddresses.length > 0 ? targetAddresses : null,
+        addressCount: targetAddresses.length,
+        operationType
+      }
+    );
+  }
+
+  /**
+   * Build freeze addresses transaction
+   * @returns {Promise<object>} Transaction result
+   */
+  async build() {
+    return this.buildFreezeOperation('FREEZE_ADDRESSES');
+  }
+
+  /**
+   * Build unfreeze addresses transaction
+   * @returns {Promise<object>} Transaction result
+   */
+  async buildUnfreeze() {
+    return this.buildFreezeOperation('UNFREEZE_ADDRESSES');
+  }
+
+  /**
+   * Build global freeze asset transaction
+   * @returns {Promise<object>} Transaction result
+   */
+  async buildGlobalFreeze() {
+    return this.buildFreezeOperation('FREEZE_ASSET');
+  }
+
+  /**
+   * Build global unfreeze asset transaction
+   * @returns {Promise<object>} Transaction result
+   */
+  async buildGlobalUnfreeze() {
+    return this.buildFreezeOperation('UNFREEZE_ASSET');
+  }
+}
+
+module.exports = FreezeAddressBuilder;