@neuraiproject/neurai-assets 1.0.0

package/src/managers/OutputOrderer.js

@@ -0,0 +1,289 @@
+/**
+ * Output Orderer
+ * Orders transaction outputs according to Neurai protocol requirements
+ *
+ * CRITICAL: Output ordering is mandatory for asset transactions
+ *
+ * Correct order:
+ * 1. All XNA outputs (burn addresses + change) FIRST
+ * 2. Owner token change outputs SECOND
+ * 3. Asset operations (issue, reissue, transfer, etc.) LAST
+ *
+ * Incorrect ordering will cause transaction rejection by the network.
+ */
+
+const { AssetNameParser } = require('../utils');
+
+class OutputOrderer {
+  /**
+   * Order outputs according to protocol requirements
+   * @param {object} outputs - Unordered outputs object
+   * @returns {object} Ordered outputs object
+   */
+  order(outputs) {
+    if (!outputs || typeof outputs !== 'object') {
+      throw new Error('Outputs must be an object');
+    }
+
+    // Categorize outputs
+    const xnaOutputs = [];       // XNA amounts (burn + change)
+    const ownerOutputs = [];     // Owner token transfers
+    const assetOutputs = [];     // Asset operations and transfers
+
+    for (const [address, value] of Object.entries(outputs)) {
+      if (typeof value === 'number') {
+        // XNA output (numeric value)
+        xnaOutputs.push({ address, value, order: 1 });
+      } else if (typeof value === 'object') {
+        // Complex output (transfer or operation)
+        if (value.transfer) {
+          // Check if it's an owner token transfer
+          if (this.isOwnerTokenTransfer(value.transfer)) {
+            ownerOutputs.push({ address, value, order: 2 });
+          } else {
+            // Regular asset transfer
+            assetOutputs.push({ address, value, order: 3 });
+          }
+        } else {
+          // Asset operation (issue, reissue, etc.)
+          assetOutputs.push({ address, value, order: 3 });
+        }
+      }
+    }
+
+    // Build ordered output object
+    const orderedOutputs = {};
+
+    // 1. Add XNA outputs first
+    xnaOutputs.forEach(({ address, value }) => {
+      orderedOutputs[address] = value;
+    });
+
+    // 2. Add owner token outputs second
+    ownerOutputs.forEach(({ address, value }) => {
+      orderedOutputs[address] = value;
+    });
+
+    // 3. Add asset operations/transfers last
+    assetOutputs.forEach(({ address, value }) => {
+      orderedOutputs[address] = value;
+    });
+
+    return orderedOutputs;
+  }
+
+  /**
+   * Check if a transfer output contains an owner token
+   * @param {object} transfer - Transfer object
+   * @returns {boolean} True if contains owner token
+   */
+  isOwnerTokenTransfer(transfer) {
+    if (!transfer || typeof transfer !== 'object') {
+      return false;
+    }
+
+    // Check if any asset name in transfer ends with '!'
+    return Object.keys(transfer).some(assetName => {
+      return AssetNameParser.isOwnerToken(assetName);
+    });
+  }
+
+  /**
+   * Validate output ordering
+   * Ensures outputs are in correct order
+   *
+   * @param {object} outputs - Outputs to validate
+   * @returns {boolean} True if valid
+   * @throws {Error} If ordering is invalid
+   */
+  validateOrdering(outputs) {
+    const entries = Object.entries(outputs);
+    let currentCategory = 0; // 0 = not started, 1 = XNA, 2 = owner, 3 = assets
+
+    for (const [address, value] of entries) {
+      let category;
+
+      if (typeof value === 'number') {
+        category = 1; // XNA
+      } else if (value.transfer && this.isOwnerTokenTransfer(value.transfer)) {
+        category = 2; // Owner token
+      } else {
+        category = 3; // Asset operation/transfer
+      }
+
+      // Check if we're going backwards in category order
+      if (category < currentCategory) {
+        throw new Error(
+          'Invalid output ordering. Outputs must be ordered as: ' +
+          '1) XNA outputs, 2) Owner token outputs, 3) Asset operations'
+        );
+      }
+
+      currentCategory = category;
+    }
+
+    return true;
+  }
+
+  /**
+   * Get output category for debugging
+   * @param {*} value - Output value
+   * @returns {string} Category name
+   */
+  getOutputCategory(value) {
+    if (typeof value === 'number') {
+      return 'XNA';
+    } else if (value.transfer && this.isOwnerTokenTransfer(value.transfer)) {
+      return 'OWNER_TOKEN';
+    } else if (value.transfer) {
+      return 'ASSET_TRANSFER';
+    } else if (value.issue) {
+      return 'ISSUE';
+    } else if (value.issue_unique) {
+      return 'ISSUE_UNIQUE';
+    } else if (value.issue_restricted) {
+      return 'ISSUE_RESTRICTED';
+    } else if (value.issue_qualifier) {
+      return 'ISSUE_QUALIFIER';
+    } else if (value.reissue) {
+      return 'REISSUE';
+    } else if (value.reissue_restricted) {
+      return 'REISSUE_RESTRICTED';
+    } else if (value.tag_addresses) {
+      return 'TAG_ADDRESSES';
+    } else if (value.untag_addresses) {
+      return 'UNTAG_ADDRESSES';
+    } else if (value.freeze_addresses) {
+      return 'FREEZE_ADDRESSES';
+    } else if (value.unfreeze_addresses) {
+      return 'UNFREEZE_ADDRESSES';
+    } else if (value.freeze_asset) {
+      return 'FREEZE_ASSET';
+    } else if (value.unfreeze_asset) {
+      return 'UNFREEZE_ASSET';
+    } else {
+      return 'UNKNOWN';
+    }
+  }
+
+  /**
+   * Debug output ordering
+   * Returns detailed information about output categories
+   *
+   * @param {object} outputs - Outputs to analyze
+   * @returns {Array} Array of { address, category, order }
+   */
+  debugOrdering(outputs) {
+    const debug = [];
+
+    for (const [address, value] of Object.entries(outputs)) {
+      const category = this.getOutputCategory(value);
+      let order;
+
+      if (typeof value === 'number') {
+        order = 1;
+      } else if (value.transfer && this.isOwnerTokenTransfer(value.transfer)) {
+        order = 2;
+      } else {
+        order = 3;
+      }
+
+      debug.push({
+        address,
+        category,
+        order,
+        value
+      });
+    }
+
+    return debug;
+  }
+
+  /**
+   * Merge multiple output objects with proper ordering
+   * Useful when building outputs from multiple sources
+   *
+   * @param {...object} outputObjects - Multiple output objects to merge
+   * @returns {object} Merged and ordered outputs
+   */
+  merge(...outputObjects) {
+    const merged = {};
+
+    // Merge all objects
+    for (const outputs of outputObjects) {
+      if (outputs && typeof outputs === 'object') {
+        Object.assign(merged, outputs);
+      }
+    }
+
+    // Order the merged result
+    return this.order(merged);
+  }
+
+  /**
+   * Add XNA output (convenience method)
+   * @param {object} outputs - Existing outputs
+   * @param {string} address - Address
+   * @param {number} amount - XNA amount
+   * @returns {object} Updated outputs (not ordered yet)
+   */
+  addXNAOutput(outputs, address, amount) {
+    return {
+      ...outputs,
+      [address]: amount
+    };
+  }
+
+  /**
+   * Add owner token output (convenience method)
+   * @param {object} outputs - Existing outputs
+   * @param {string} address - Address
+   * @param {string} ownerTokenName - Owner token name
+   * @returns {object} Updated outputs (not ordered yet)
+   */
+  addOwnerTokenOutput(outputs, address, ownerTokenName) {
+    return {
+      ...outputs,
+      [address]: {
+        transfer: {
+          [ownerTokenName]: 1.0
+        }
+      }
+    };
+  }
+
+  /**
+   * Add asset transfer output (convenience method)
+   * @param {object} outputs - Existing outputs
+   * @param {string} address - Address
+   * @param {string} assetName - Asset name
+   * @param {number} amount - Amount
+   * @returns {object} Updated outputs (not ordered yet)
+   */
+  addAssetTransferOutput(outputs, address, assetName, amount) {
+    return {
+      ...outputs,
+      [address]: {
+        transfer: {
+          [assetName]: amount
+        }
+      }
+    };
+  }
+
+  /**
+   * Add asset operation output (convenience method)
+   * @param {object} outputs - Existing outputs
+   * @param {string} address - Address
+   * @param {object} operation - Operation object (issue, reissue, etc.)
+   * @returns {object} Updated outputs (not ordered yet)
+   */
+  addOperationOutput(outputs, address, operation) {
+    return {
+      ...outputs,
+      [address]: operation
+    };
+  }
+}
+
+module.exports = OutputOrderer;

package/src/managers/OwnerTokenManager.js

@@ -0,0 +1,265 @@
+/**
+ * Owner Token Manager
+ * CRITICAL: Manages owner token UTXOs and ensures they are properly returned
+ *
+ * Owner tokens (ASSET!) are required for:
+ * - Reissuing assets
+ * - Creating sub-assets
+ * - Managing restricted assets (freeze/unfreeze)
+ *
+ * WARNING: If an owner token is not included in transaction outputs,
+ * it will be PERMANENTLY LOST and the asset can never be reissued or managed.
+ */
+
+const { AssetNameParser } = require('../utils');
+const {
+  OwnerTokenNotFoundError,
+  OwnerTokenNotReturnedError,
+  AssetError
+} = require('../errors');
+
+class OwnerTokenManager {
+  /**
+   * @param {Function} rpc - RPC function to call Neurai node
+   */
+  constructor(rpc) {
+    if (!rpc || typeof rpc !== 'function') {
+      throw new Error('RPC function is required');
+    }
+    this.rpc = rpc;
+  }
+
+  /**
+   * Find owner token UTXO in wallet addresses
+   * @param {string} ownerTokenName - Owner token name (e.g., 'MYTOKEN!')
+   * @param {string[]} addresses - Array of wallet addresses
+   * @returns {Promise<object>} Owner token UTXO
+   * @throws {OwnerTokenNotFoundError} If owner token not found
+   */
+  async findOwnerTokenUTXO(ownerTokenName, addresses) {
+    if (!ownerTokenName || !ownerTokenName.endsWith('!')) {
+      throw new Error('Owner token name must end with !');
+    }
+
+    if (!Array.isArray(addresses) || addresses.length === 0) {
+      throw new Error('Addresses array is required');
+    }
+
+    try {
+      // Query UTXOs for the owner token
+      const utxos = await this.rpc('getaddressutxos', [{ addresses }]);
+
+      // Filter for the specific owner token
+      const ownerTokenUTXOs = utxos.filter(utxo => utxo.assetName === ownerTokenName);
+
+      if (ownerTokenUTXOs.length === 0) {
+        throw new OwnerTokenNotFoundError(
+          `Owner token ${ownerTokenName} not found in wallet addresses. ` +
+          `You must own the owner token to perform this operation.`,
+          ownerTokenName
+        );
+      }
+
+      // Owner tokens should be indivisible (only 1 UTXO typically)
+      // But if split, return the first one found
+      return ownerTokenUTXOs[0];
+    } catch (error) {
+      if (error instanceof OwnerTokenNotFoundError) {
+        throw error;
+      }
+
+      throw new AssetError(
+        `Failed to find owner token ${ownerTokenName}: ${error.message}`
+      );
+    }
+  }
+
+  /**
+   * Find owner token UTXO by base asset name
+   * @param {string} assetName - Base asset name (without !)
+   * @param {string[]} addresses - Array of wallet addresses
+   * @returns {Promise<object>} Owner token UTXO
+   */
+  async findOwnerTokenByAssetName(assetName, addresses) {
+    const ownerTokenName = AssetNameParser.getOwnerTokenName(assetName);
+    return this.findOwnerTokenUTXO(ownerTokenName, addresses);
+  }
+
+  /**
+   * Create owner token return output
+   * Owner tokens must always be returned to an address or they're lost forever
+   *
+   * @param {string} ownerTokenName - Owner token name (e.g., 'MYTOKEN!')
+   * @param {string} returnAddress - Address to return owner token to
+   * @returns {object} Output object for owner token transfer
+   */
+  createOwnerTokenReturnOutput(ownerTokenName, returnAddress) {
+    if (!ownerTokenName || !ownerTokenName.endsWith('!')) {
+      throw new Error('Owner token name must end with !');
+    }
+
+    if (!returnAddress) {
+      throw new Error('Return address is required');
+    }
+
+    // Owner tokens are always exactly 1.0
+    return {
+      [returnAddress]: {
+        transfer: {
+          [ownerTokenName]: 1.0
+        }
+      }
+    };
+  }
+
+  /**
+   * Validate that owner token inputs are properly returned in outputs
+   * CRITICAL: This prevents permanent loss of owner tokens
+   *
+   * @param {Array} inputs - Transaction inputs
+   * @param {object} outputs - Transaction outputs
+   * @returns {boolean} True if valid
+   * @throws {OwnerTokenNotReturnedError} If owner token not returned
+   */
+  validateOwnerTokenReturn(inputs, outputs) {
+    // Find all owner token inputs
+    const ownerTokenInputs = inputs.filter(input => {
+      return input.assetName && input.assetName.endsWith('!');
+    });
+
+    // If no owner tokens in inputs, validation passes
+    if (ownerTokenInputs.length === 0) {
+      return true;
+    }
+
+    // Check each owner token is in outputs
+    for (const ownerInput of ownerTokenInputs) {
+      const ownerTokenName = ownerInput.assetName;
+      let foundInOutputs = false;
+
+      // Check all outputs for owner token
+      for (const [address, output] of Object.entries(outputs)) {
+        // Check if output has transfer field
+        if (output && typeof output === 'object' && output.transfer) {
+          // Check if owner token is in the transfer
+          if (output.transfer[ownerTokenName]) {
+            foundInOutputs = true;
+            break;
+          }
+        }
+      }
+
+      if (!foundInOutputs) {
+        throw new OwnerTokenNotReturnedError(
+          `CRITICAL: Owner token ${ownerTokenName} is not returned in outputs! ` +
+          `This will result in PERMANENT LOSS of the owner token and you will ` +
+          `never be able to reissue or manage this asset again. ` +
+          `The owner token MUST be included in the transaction outputs.`,
+          ownerTokenName
+        );
+      }
+    }
+
+    return true;
+  }
+
+  /**
+   * Check if wallet owns an owner token
+   * @param {string} ownerTokenName - Owner token name (e.g., 'MYTOKEN!')
+   * @param {string[]} addresses - Array of wallet addresses
+   * @returns {Promise<boolean>} True if wallet owns the owner token
+   */
+  async hasOwnerToken(ownerTokenName, addresses) {
+    try {
+      await this.findOwnerTokenUTXO(ownerTokenName, addresses);
+      return true;
+    } catch (error) {
+      if (error instanceof OwnerTokenNotFoundError) {
+        return false;
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Get all owner tokens in wallet
+   * @param {string[]} addresses - Array of wallet addresses
+   * @returns {Promise<Array>} Array of owner token UTXOs
+   */
+  async getAllOwnerTokens(addresses) {
+    if (!Array.isArray(addresses) || addresses.length === 0) {
+      throw new Error('Addresses array is required');
+    }
+
+    try {
+      const utxos = await this.rpc('getaddressutxos', [{ addresses }]);
+
+      // Filter for owner tokens (asset names ending with !)
+      const ownerTokenUTXOs = utxos.filter(utxo => {
+        return utxo.assetName && utxo.assetName.endsWith('!');
+      });
+
+      return ownerTokenUTXOs;
+    } catch (error) {
+      throw new AssetError(
+        `Failed to get owner tokens: ${error.message}`
+      );
+    }
+  }
+
+  /**
+   * Verify owner token quantity is correct (always 1)
+   * @param {object} ownerTokenUTXO - Owner token UTXO
+   * @returns {boolean} True if valid
+   * @throws {Error} If quantity is not 1
+   */
+  validateOwnerTokenQuantity(ownerTokenUTXO) {
+    // Owner tokens should always have satoshis = 100000000 (1.0 with 8 decimals)
+    const expectedSatoshis = 100000000;
+
+    if (ownerTokenUTXO.satoshis !== expectedSatoshis) {
+      throw new Error(
+        `Invalid owner token quantity. Expected ${expectedSatoshis} satoshis, ` +
+        `got ${ownerTokenUTXO.satoshis}. Owner tokens must always be exactly 1.0`
+      );
+    }
+
+    return true;
+  }
+
+  /**
+   * Add owner token input and output to transaction
+   * Convenience method that handles both finding and returning owner token
+   *
+   * @param {string} assetName - Base asset name (without !)
+   * @param {string[]} addresses - Wallet addresses
+   * @param {string} returnAddress - Address to return owner token to
+   * @returns {Promise<object>} { input, output }
+   */
+  async prepareOwnerTokenForTransaction(assetName, addresses, returnAddress) {
+    // Find owner token UTXO
+    const ownerTokenUTXO = await this.findOwnerTokenByAssetName(assetName, addresses);
+
+    // Validate quantity
+    this.validateOwnerTokenQuantity(ownerTokenUTXO);
+
+    // Create input
+    const input = {
+      txid: ownerTokenUTXO.txid,
+      vout: ownerTokenUTXO.outputIndex,
+      address: ownerTokenUTXO.address,
+      assetName: ownerTokenUTXO.assetName,
+      satoshis: ownerTokenUTXO.satoshis
+    };
+
+    // Create output
+    const output = this.createOwnerTokenReturnOutput(
+      ownerTokenUTXO.assetName,
+      returnAddress
+    );
+
+    return { input, output, utxo: ownerTokenUTXO };
+  }
+}
+
+module.exports = OwnerTokenManager;