@neuraiproject/neurai-assets 1.0.0

package/src/builders/IssueQualifierBuilder.js

@@ -0,0 +1,251 @@
+/**
+ * Issue Qualifier Builder
+ * Builds transactions for creating QUALIFIER assets
+ *
+ * QUALIFIER assets:
+ * - KYC/compliance tags (e.g., #KYC_VERIFIED, #ACCREDITED)
+ * - Format: #NAME or #ROOT/SUB
+ * - Cost: 2000 XNA (root) or 200 XNA (sub-qualifier)
+ * - Quantity: 1-10 units only
+ * - Units: Always 0 (non-divisible)
+ * - Used to tag addresses for restricted asset compliance
+ * - Creates owner token (#QUALIFIER!)
+ */
+
+const BaseAssetTransactionBuilder = require('./BaseAssetTransactionBuilder');
+const { OutputFormatter, AssetNameParser } = require('../utils');
+const { AssetExistsError, ParentAssetNotFoundError, OwnerTokenNotFoundError } = require('../errors');
+const { IpfsValidator, AmountValidator } = require('../validators');
+
+class IssueQualifierBuilder extends BaseAssetTransactionBuilder {
+  /**
+   * Validate issue QUALIFIER parameters
+   * @param {object} params - Issue parameters
+   * @throws {Error} If validation fails
+   */
+  validateParams(params) {
+    // Validate required parameters
+    if (!params.assetName) {
+      throw new Error('assetName is required');
+    }
+
+    if (params.quantity === undefined || params.quantity === null) {
+      throw new Error('quantity is required');
+    }
+
+    // Validate asset name (QUALIFIER format: #NAME)
+    this.validateAssetName(params.assetName, 'QUALIFIER');
+
+    // Validate quantity (1-10 only for qualifiers)
+    AmountValidator.validateQualifierQuantity(params.quantity);
+
+    // Validate IPFS hash if provided
+    if (params.hasIpfs && params.ipfsHash) {
+      IpfsValidator.validate(params.ipfsHash);
+    }
+
+    return true;
+  }
+
+  /**
+   * Determine if this is a sub-qualifier
+   * @param {string} assetName - Qualifier name
+   * @returns {boolean} True if sub-qualifier
+   */
+  isSubQualifier(assetName) {
+    return assetName.includes('/');
+  }
+
+  /**
+   * Build QUALIFIER asset issuance transaction
+   * @returns {Promise<object>} Transaction result
+   */
+  async build() {
+    // 1. Validate parameters
+    await this.validateParams(this.params);
+
+    const {
+      assetName,
+      quantity,
+      hasIpfs = false,
+      ipfsHash = ''
+    } = this.params;
+
+    // 2. Determine if root or sub-qualifier
+    const isSub = this.isSubQualifier(assetName);
+    const parsed = AssetNameParser.parse(assetName);
+
+    // 3. If sub-qualifier, check parent exists and get owner token
+    let ownerTokenUTXO = null;
+    let ownerTokenName = null;
+    const addresses = await this._getAddresses();
+
+    if (isSub) {
+      const parentQualifierName = parsed.parent;
+
+      // Check parent qualifier exists
+      const parentExists = await this.assetExists(parentQualifierName);
+      if (!parentExists) {
+        throw new ParentAssetNotFoundError(
+          `Parent qualifier ${parentQualifierName} does not exist. You must create the parent qualifier first.`,
+          parentQualifierName
+        );
+      }
+
+      // Find parent's owner token
+      ownerTokenName = AssetNameParser.getOwnerTokenName(parentQualifierName);
+      try {
+        ownerTokenUTXO = await this.ownerTokenManager.findOwnerTokenUTXO(
+          ownerTokenName,
+          addresses
+        );
+      } catch (error) {
+        if (error instanceof OwnerTokenNotFoundError) {
+          throw new OwnerTokenNotFoundError(
+            `You must own the parent qualifier's owner token (${ownerTokenName}) to create a sub-qualifier.`,
+            ownerTokenName
+          );
+        }
+        throw error;
+      }
+    }
+
+    // 4. Check if qualifier already exists
+    const exists = await this.assetExists(assetName);
+    if (exists) {
+      throw new AssetExistsError(
+        `Qualifier ${assetName} already exists on the blockchain`,
+        assetName
+      );
+    }
+
+    // 5. Get burn information (2000 XNA for root, 200 XNA for sub)
+    const burnInfo = isSub
+      ? this.burnManager.getIssueSubQualifierBurn()
+      : this.burnManager.getIssueQualifierBurn();
+
+    // 6. Get addresses
+    const toAddress = await this.getToAddress();
+    const changeAddress = await this.getChangeAddress();
+
+    // 7. Estimate fee
+    const outputCount = isSub ? 4 : 3; // Sub has owner token return
+    const estimatedFee = await this.estimateFee(2, outputCount);
+
+    // 8. Calculate total XNA needed
+    const totalXNANeeded = burnInfo.amount + estimatedFee;
+
+    // 9. Select XNA UTXOs
+    const utxoSelection = await this.selectUTXOs(totalXNANeeded, null, 0);
+    const baseCurrencyUTXOs = utxoSelection.xnaUTXOs;
+    const totalXNAInput = utxoSelection.totalXNA;
+
+    // 10. Recalculate fee with actual input count
+    const actualInputCount = baseCurrencyUTXOs.length + (ownerTokenUTXO ? 1 : 0);
+    const actualFee = await this.estimateFee(actualInputCount, outputCount);
+
+    // 11. 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);
+    }
+
+    // 12. Calculate XNA change
+    const finalTotalInput = baseCurrencyUTXOs.reduce(
+      (sum, utxo) => sum + utxo.satoshis / 100000000,
+      0
+    );
+    const xnaChange = finalTotalInput - burnInfo.amount - actualFee;
+
+    // 13. Build inputs
+    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 if sub-qualifier
+    if (ownerTokenUTXO) {
+      inputs.push({
+        txid: ownerTokenUTXO.txid,
+        vout: ownerTokenUTXO.outputIndex,
+        address: ownerTokenUTXO.address,
+        assetName: ownerTokenUTXO.assetName,
+        satoshis: ownerTokenUTXO.satoshis
+      });
+    }
+
+    // 14. 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 (if sub-qualifier)
+    if (ownerTokenUTXO && ownerTokenName) {
+      const ownerTokenReturn = this.ownerTokenManager.createOwnerTokenReturnOutput(
+        ownerTokenName,
+        changeAddress
+      );
+      Object.assign(outputs, ownerTokenReturn);
+    }
+
+    // Last: Issue qualifier operation
+    const issueQualifierOutput = OutputFormatter.formatIssueQualifierOutput({
+      asset_name: assetName,
+      asset_quantity: quantity,
+      has_ipfs: hasIpfs,
+      ipfs_hash: ipfsHash
+    });
+
+    outputs[toAddress] = issueQualifierOutput;
+
+    // 15. Order outputs (protocol requirement)
+    const orderedOutputs = this.outputOrderer.order(outputs);
+
+    // 16. Validate owner token is returned if sub-qualifier
+    if (ownerTokenUTXO) {
+      this.ownerTokenManager.validateOwnerTokenReturn(inputs, orderedOutputs);
+    }
+
+    // 17. Create raw transaction
+    const rawTx = await this.buildRawTransaction(inputs, orderedOutputs);
+
+    // 18. Format and return result
+    const allUTXOs = ownerTokenUTXO
+      ? [...baseCurrencyUTXOs, ownerTokenUTXO]
+      : baseCurrencyUTXOs;
+
+    return this.formatResult(
+      rawTx,
+      allUTXOs,
+      inputs,
+      orderedOutputs,
+      actualFee,
+      burnInfo.amount,
+      {
+        assetName,
+        qualifierType: isSub ? 'SUB_QUALIFIER' : 'QUALIFIER',
+        parentQualifier: isSub ? parsed.parent : null,
+        ownerTokenName: assetName + '!',
+        parentOwnerTokenUsed: ownerTokenName,
+        operationType: isSub ? 'ISSUE_SUB_QUALIFIER' : 'ISSUE_QUALIFIER'
+      }
+    );
+  }
+}
+
+module.exports = IssueQualifierBuilder;

package/src/builders/IssueRestrictedBuilder.js

@@ -0,0 +1,187 @@
+/**
+ * Issue Restricted Builder
+ * Builds transactions for creating RESTRICTED assets (security tokens)
+ *
+ * RESTRICTED assets:
+ * - Security tokens with KYC/compliance controls
+ * - Format: $NAME (e.g., $SECURITY, $STOCK)
+ * - Cost: 3000 XNA (burned)
+ * - Requires verifier string (boolean logic with qualifiers)
+ * - Only addresses meeting verifier requirements can receive/hold
+ * - Can freeze individual addresses or entire asset
+ * - Creates owner token ($ASSET!)
+ */
+
+const BaseAssetTransactionBuilder = require('./BaseAssetTransactionBuilder');
+const { OutputFormatter } = require('../utils');
+const { AssetExistsError } = require('../errors');
+const { IpfsValidator, VerifierValidator } = require('../validators');
+
+class IssueRestrictedBuilder extends BaseAssetTransactionBuilder {
+  /**
+   * Validate issue RESTRICTED parameters
+   * @param {object} params - Issue parameters
+   * @throws {Error} If validation fails
+   */
+  validateParams(params) {
+    // Validate required parameters
+    if (!params.assetName) {
+      throw new Error('assetName is required');
+    }
+
+    if (params.quantity === undefined || params.quantity === null) {
+      throw new Error('quantity is required');
+    }
+
+    if (!params.verifierString) {
+      throw new Error('verifierString is required for restricted assets');
+    }
+
+    // Validate asset name (RESTRICTED format: $NAME)
+    this.validateAssetName(params.assetName, 'RESTRICTED');
+
+    // Validate quantity and units
+    const units = params.units !== undefined ? params.units : 0;
+    this.validateAmount(params.quantity, units);
+
+    // Validate verifier string (critical for compliance)
+    VerifierValidator.validate(params.verifierString);
+
+    // Validate IPFS hash if provided
+    if (params.hasIpfs && params.ipfsHash) {
+      IpfsValidator.validate(params.ipfsHash);
+    }
+
+    // Validate reissuable is boolean if provided
+    if (params.reissuable !== undefined && typeof params.reissuable !== 'boolean') {
+      throw new Error('reissuable must be a boolean');
+    }
+
+    return true;
+  }
+
+  /**
+   * Build RESTRICTED asset issuance transaction
+   * @returns {Promise<object>} Transaction result
+   */
+  async build() {
+    // 1. Validate parameters
+    await this.validateParams(this.params);
+
+    const {
+      assetName,
+      quantity,
+      units = 0,
+      verifierString,
+      reissuable = true,
+      hasIpfs = false,
+      ipfsHash = ''
+    } = this.params;
+
+    // 2. Check if asset already exists
+    const exists = await this.assetExists(assetName);
+    if (exists) {
+      throw new AssetExistsError(
+        `Asset ${assetName} already exists on the blockchain`,
+        assetName
+      );
+    }
+
+    // 3. Extract qualifiers from verifier string for info
+    const requiredQualifiers = VerifierValidator.extractQualifiers(verifierString);
+
+    // 4. Get burn information (3000 XNA for restricted assets)
+    const burnInfo = this.burnManager.getIssueRestrictedBurn();
+
+    // 5. Get addresses
+    const addresses = await this._getAddresses();
+    const toAddress = await this.getToAddress();
+    const changeAddress = await this.getChangeAddress();
+
+    // 6. Estimate fee
+    const estimatedFee = await this.estimateFee(1, 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 actualFee = await this.estimateFee(baseCurrencyUTXOs.length, 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
+    const inputs = baseCurrencyUTXOs.map(utxo => ({
+      txid: utxo.txid,
+      vout: utxo.outputIndex,
+      address: utxo.address,
+      satoshis: utxo.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));
+    }
+
+    // Last: Issue restricted operation
+    const issueRestrictedOutput = OutputFormatter.formatIssueRestrictedOutput({
+      asset_name: assetName,
+      asset_quantity: this.toSatoshis(quantity, units),
+      verifier_string: verifierString,
+      units: units,
+      reissuable: reissuable,
+      has_ipfs: hasIpfs,
+      ipfs_hash: ipfsHash
+    });
+
+    outputs[toAddress] = issueRestrictedOutput;
+
+    // 14. Order outputs (protocol requirement)
+    const orderedOutputs = this.outputOrderer.order(outputs);
+
+    // 15. Create raw transaction
+    const rawTx = await this.buildRawTransaction(inputs, orderedOutputs);
+
+    // 16. Format and return result
+    return this.formatResult(
+      rawTx,
+      baseCurrencyUTXOs,
+      inputs,
+      orderedOutputs,
+      actualFee,
+      burnInfo.amount,
+      {
+        assetName,
+        ownerTokenName: assetName + '!',
+        verifierString,
+        requiredQualifiers,
+        operationType: 'ISSUE_RESTRICTED'
+      }
+    );
+  }
+}
+
+module.exports = IssueRestrictedBuilder;

package/src/builders/IssueRootBuilder.js

@@ -0,0 +1,173 @@
+/**
+ * Issue Root Builder
+ * Builds transactions for creating ROOT assets
+ *
+ * ROOT assets:
+ * - Top-level assets (3-30 uppercase characters)
+ * - Cost: 1000 XNA (burned)
+ * - Automatically creates owner token (ASSET!)
+ * - Can be reissuable or non-reissuable
+ * - Optional IPFS metadata
+ */
+
+const BaseAssetTransactionBuilder = require('./BaseAssetTransactionBuilder');
+const { OutputFormatter } = require('../utils');
+const { AssetExistsError, InvalidIPFSHashError } = require('../errors');
+const { IpfsValidator } = require('../validators');
+
+class IssueRootBuilder extends BaseAssetTransactionBuilder {
+  /**
+   * Validate issue ROOT parameters
+   * @param {object} params - Issue parameters
+   * @throws {Error} If validation fails
+   */
+  validateParams(params) {
+    // Validate required parameters
+    if (!params.assetName) {
+      throw new Error('assetName is required');
+    }
+
+    if (params.quantity === undefined || params.quantity === null) {
+      throw new Error('quantity is required');
+    }
+
+    // Validate asset name (ROOT format)
+    this.validateAssetName(params.assetName, 'ROOT');
+
+    // Validate quantity and units
+    const units = params.units !== undefined ? params.units : 0;
+    this.validateAmount(params.quantity, units);
+
+    // Validate IPFS hash if provided
+    if (params.hasIpfs && params.ipfsHash) {
+      IpfsValidator.validate(params.ipfsHash);
+    }
+
+    // Validate reissuable is boolean if provided
+    if (params.reissuable !== undefined && typeof params.reissuable !== 'boolean') {
+      throw new Error('reissuable must be a boolean');
+    }
+
+    return true;
+  }
+
+  /**
+   * Build ROOT asset issuance transaction
+   * @returns {Promise<object>} Transaction result
+   */
+  async build() {
+    // 1. Validate parameters
+    await this.validateParams(this.params);
+
+    const {
+      assetName,
+      quantity,
+      units = 0,
+      reissuable = true,
+      hasIpfs = false,
+      ipfsHash = ''
+    } = this.params;
+
+    // 2. Check if asset already exists
+    const exists = await this.assetExists(assetName);
+    if (exists) {
+      throw new AssetExistsError(
+        `Asset ${assetName} already exists on the blockchain`,
+        assetName
+      );
+    }
+
+    // 3. Get burn information
+    const burnInfo = this.burnManager.getIssueRootBurn();
+
+    // 4. Get addresses
+    const addresses = await this._getAddresses();
+    const toAddress = await this.getToAddress();
+    const changeAddress = await this.getChangeAddress();
+
+    // 5. Estimate fee (rough estimate for initial UTXO selection)
+    const estimatedFee = await this.estimateFee(1, 3);
+
+    // 6. Calculate total XNA needed
+    const totalXNANeeded = burnInfo.amount + estimatedFee;
+
+    // 7. Select UTXOs
+    const utxoSelection = await this.selectUTXOs(totalXNANeeded, null, 0);
+    const baseCurrencyUTXOs = utxoSelection.xnaUTXOs;
+    const totalXNAInput = utxoSelection.totalXNA;
+
+    // 8. Recalculate fee with actual input count
+    const actualFee = await this.estimateFee(baseCurrencyUTXOs.length, 3);
+
+    // 9. Verify we still have enough after fee recalculation
+    const totalRequired = burnInfo.amount + actualFee;
+    if (totalXNAInput < totalRequired) {
+      // Need to select more UTXOs
+      const additionalNeeded = totalRequired - totalXNAInput + 0.001; // Add small buffer
+      const additionalSelection = await this.selectUTXOs(additionalNeeded, null, 0);
+      baseCurrencyUTXOs.push(...additionalSelection.xnaUTXOs);
+    }
+
+    // 10. Calculate final totals
+    const finalTotalInput = baseCurrencyUTXOs.reduce(
+      (sum, utxo) => sum + utxo.satoshis / 100000000,
+      0
+    );
+    const xnaChange = finalTotalInput - burnInfo.amount - actualFee;
+
+    // 11. Build inputs
+    const inputs = baseCurrencyUTXOs.map(utxo => ({
+      txid: utxo.txid,
+      vout: utxo.outputIndex,
+      address: utxo.address,
+      satoshis: utxo.satoshis
+    }));
+
+    // 12. Build outputs (ORDER MATTERS!)
+    const outputs = {};
+
+    // First: Burn output
+    outputs[burnInfo.address] = burnInfo.amount;
+
+    // Second: XNA change (if any)
+    if (xnaChange > 0.00000001) {
+      // Only add change if meaningful amount
+      outputs[changeAddress] = parseFloat(xnaChange.toFixed(8));
+    }
+
+    // Last: Issue operation
+    const issueOutput = OutputFormatter.formatIssueOutput({
+      asset_name: assetName,
+      asset_quantity: this.toSatoshis(quantity, units),
+      units: units,
+      reissuable: reissuable,
+      has_ipfs: hasIpfs,
+      ipfs_hash: ipfsHash
+    });
+
+    outputs[toAddress] = issueOutput;
+
+    // 13. Order outputs (critical for protocol)
+    const orderedOutputs = this.outputOrderer.order(outputs);
+
+    // 14. Create raw transaction
+    const rawTx = await this.buildRawTransaction(inputs, orderedOutputs);
+
+    // 15. Format and return result
+    return this.formatResult(
+      rawTx,
+      baseCurrencyUTXOs,
+      inputs,
+      orderedOutputs,
+      actualFee,
+      burnInfo.amount,
+      {
+        assetName,
+        ownerTokenName: assetName + '!',
+        operationType: 'ISSUE_ROOT'
+      }
+    );
+  }
+}
+
+module.exports = IssueRootBuilder;