@neuraiproject/neurai-assets 1.0.0

package/src/errors/AssetErrors.js

@@ -0,0 +1,135 @@
+/**
+ * Asset-Specific Error Classes
+ * Errors related to asset operations
+ */
+
+class AssetError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'AssetError';
+    this.code = 'ASSET_ERROR';
+  }
+}
+
+class AssetExistsError extends AssetError {
+  constructor(message, assetName) {
+    super(message);
+    this.name = 'AssetExistsError';
+    this.code = 'ASSET_EXISTS';
+    this.assetName = assetName;
+  }
+}
+
+class AssetNotFoundError extends AssetError {
+  constructor(message, assetName) {
+    super(message);
+    this.name = 'AssetNotFoundError';
+    this.code = 'ASSET_NOT_FOUND';
+    this.assetName = assetName;
+  }
+}
+
+class OwnerTokenNotFoundError extends AssetError {
+  constructor(message, ownerTokenName) {
+    super(message);
+    this.name = 'OwnerTokenNotFoundError';
+    this.code = 'OWNER_TOKEN_NOT_FOUND';
+    this.ownerTokenName = ownerTokenName;
+    this.severity = 'HIGH';
+  }
+}
+
+class OwnerTokenNotReturnedError extends AssetError {
+  constructor(message, ownerTokenName) {
+    super(message);
+    this.name = 'OwnerTokenNotReturnedError';
+    this.code = 'OWNER_TOKEN_NOT_RETURNED';
+    this.ownerTokenName = ownerTokenName;
+    this.severity = 'CRITICAL';  // This results in permanent loss
+  }
+}
+
+class AssetNotReissuableError extends AssetError {
+  constructor(message, assetName) {
+    super(message);
+    this.name = 'AssetNotReissuableError';
+    this.code = 'ASSET_NOT_REISSUABLE';
+    this.assetName = assetName;
+  }
+}
+
+class InsufficientBurnAmountError extends AssetError {
+  constructor(message, required, provided) {
+    super(message);
+    this.name = 'InsufficientBurnAmountError';
+    this.code = 'INSUFFICIENT_BURN_AMOUNT';
+    this.required = required;
+    this.provided = provided;
+  }
+}
+
+class InvalidBurnAddressError extends AssetError {
+  constructor(message, expectedAddress, providedAddress) {
+    super(message);
+    this.name = 'InvalidBurnAddressError';
+    this.code = 'INVALID_BURN_ADDRESS';
+    this.expectedAddress = expectedAddress;
+    this.providedAddress = providedAddress;
+  }
+}
+
+class MaxSupplyExceededError extends AssetError {
+  constructor(message, assetName, currentSupply, additionalAmount, maxSupply) {
+    super(message);
+    this.name = 'MaxSupplyExceededError';
+    this.code = 'MAX_SUPPLY_EXCEEDED';
+    this.assetName = assetName;
+    this.currentSupply = currentSupply;
+    this.additionalAmount = additionalAmount;
+    this.maxSupply = maxSupply;
+  }
+}
+
+class RestrictedAssetViolationError extends AssetError {
+  constructor(message, assetName, address, reason) {
+    super(message);
+    this.name = 'RestrictedAssetViolationError';
+    this.code = 'RESTRICTED_ASSET_VIOLATION';
+    this.assetName = assetName;
+    this.address = address;
+    this.reason = reason;
+  }
+}
+
+class QualifierNotFoundError extends AssetError {
+  constructor(message, qualifierName) {
+    super(message);
+    this.name = 'QualifierNotFoundError';
+    this.code = 'QUALIFIER_NOT_FOUND';
+    this.qualifierName = qualifierName;
+  }
+}
+
+class ParentAssetNotFoundError extends AssetError {
+  constructor(message, parentAssetName) {
+    super(message);
+    this.name = 'ParentAssetNotFoundError';
+    this.code = 'PARENT_ASSET_NOT_FOUND';
+    this.parentAssetName = parentAssetName;
+  }
+}
+
+module.exports = {
+  AssetError,
+  AssetExistsError,
+  AssetNotFoundError,
+  OwnerTokenNotFoundError,
+  OwnerTokenNotReturnedError,
+  AssetNotReissuableError,
+  InsufficientBurnAmountError,
+  InvalidBurnAddressError,
+  MaxSupplyExceededError,
+  RestrictedAssetViolationError,
+  QualifierNotFoundError,
+  ParentAssetNotFoundError
+};

package/src/errors/ValidationErrors.js

@@ -0,0 +1,87 @@
+/**
+ * Validation Error Classes
+ * Errors thrown during parameter validation
+ */
+
+class ValidationError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'ValidationError';
+    this.code = 'VALIDATION_ERROR';
+  }
+}
+
+class InvalidAssetNameError extends ValidationError {
+  constructor(message, assetName) {
+    super(message);
+    this.name = 'InvalidAssetNameError';
+    this.code = 'INVALID_ASSET_NAME';
+    this.assetName = assetName;
+  }
+}
+
+class InvalidAmountError extends ValidationError {
+  constructor(message, amount) {
+    super(message);
+    this.name = 'InvalidAmountError';
+    this.code = 'INVALID_AMOUNT';
+    this.amount = amount;
+  }
+}
+
+class InvalidUnitsError extends ValidationError {
+  constructor(message, units) {
+    super(message);
+    this.name = 'InvalidUnitsError';
+    this.code = 'INVALID_UNITS';
+    this.units = units;
+  }
+}
+
+class InvalidVerifierStringError extends ValidationError {
+  constructor(message, verifier) {
+    super(message);
+    this.name = 'InvalidVerifierStringError';
+    this.code = 'INVALID_VERIFIER_STRING';
+    this.verifier = verifier;
+  }
+}
+
+class InvalidIPFSHashError extends ValidationError {
+  constructor(message, hash) {
+    super(message);
+    this.name = 'InvalidIPFSHashError';
+    this.code = 'INVALID_IPFS_HASH';
+    this.ipfsHash = hash;
+  }
+}
+
+class InvalidAddressError extends ValidationError {
+  constructor(message, address) {
+    super(message);
+    this.name = 'InvalidAddressError';
+    this.code = 'INVALID_ADDRESS';
+    this.address = address;
+  }
+}
+
+class InsufficientFundsError extends ValidationError {
+  constructor(message, required, available) {
+    super(message);
+    this.name = 'InsufficientFundsError';
+    this.code = 'INSUFFICIENT_FUNDS';
+    this.required = required;
+    this.available = available;
+  }
+}
+
+module.exports = {
+  ValidationError,
+  InvalidAssetNameError,
+  InvalidAmountError,
+  InvalidUnitsError,
+  InvalidVerifierStringError,
+  InvalidIPFSHashError,
+  InvalidAddressError,
+  InsufficientFundsError
+};

package/src/errors/index.js

@@ -0,0 +1,56 @@
+/**
+ * Errors Module
+ * Exports all error classes
+ */
+
+const {
+  ValidationError,
+  InvalidAssetNameError,
+  InvalidAmountError,
+  InvalidUnitsError,
+  InvalidVerifierStringError,
+  InvalidIPFSHashError,
+  InvalidAddressError,
+  InsufficientFundsError
+} = require('./ValidationErrors');
+
+const {
+  AssetError,
+  AssetExistsError,
+  AssetNotFoundError,
+  OwnerTokenNotFoundError,
+  OwnerTokenNotReturnedError,
+  AssetNotReissuableError,
+  InsufficientBurnAmountError,
+  InvalidBurnAddressError,
+  MaxSupplyExceededError,
+  RestrictedAssetViolationError,
+  QualifierNotFoundError,
+  ParentAssetNotFoundError
+} = require('./AssetErrors');
+
+module.exports = {
+  // Validation Errors
+  ValidationError,
+  InvalidAssetNameError,
+  InvalidAmountError,
+  InvalidUnitsError,
+  InvalidVerifierStringError,
+  InvalidIPFSHashError,
+  InvalidAddressError,
+  InsufficientFundsError,
+
+  // Asset Errors
+  AssetError,
+  AssetExistsError,
+  AssetNotFoundError,
+  OwnerTokenNotFoundError,
+  OwnerTokenNotReturnedError,
+  AssetNotReissuableError,
+  InsufficientBurnAmountError,
+  InvalidBurnAddressError,
+  MaxSupplyExceededError,
+  RestrictedAssetViolationError,
+  QualifierNotFoundError,
+  ParentAssetNotFoundError
+};

package/src/index.js

@@ -0,0 +1,68 @@
+/**
+ * @neuraiproject/neurai-assets
+ * Non-custodial Neurai asset management library
+ *
+ * Comprehensive asset management library for Neurai blockchain
+ * Supports creation, reissuance, transfers, and queries for all asset types:
+ * - ROOT assets (standard tokens)
+ * - SUB assets (sub-tokens)
+ * - UNIQUE assets (NFTs)
+ * - QUALIFIER assets (KYC/compliance tags)
+ * - RESTRICTED assets (security tokens with compliance)
+ *
+ * @example
+ * const NeuraiAssets = require('@neuraiproject/neurai-assets');
+ *
+ * // Initialize with RPC function
+ * const assets = new NeuraiAssets(rpc, {
+ *   network: 'xna',
+ *   addresses: walletAddresses,
+ *   changeAddress: myChangeAddress,
+ *   toAddress: myReceivingAddress
+ * });
+ *
+ * // Create a ROOT asset
+ * const result = await assets.createRootAsset({
+ *   assetName: 'MYTOKEN',
+ *   quantity: 1000000,
+ *   units: 2,
+ *   reissuable: true
+ * });
+ *
+ * // Sign and broadcast
+ * const signedTx = await wallet.signTransaction(result.rawTx);
+ * const txid = await wallet.broadcastTransaction(signedTx);
+ */
+
+// Main API class
+const NeuraiAssets = require('./NeuraiAssets');
+
+// Builders
+const builders = require('./builders');
+
+// Queries
+const { AssetQueries } = require('./queries');
+
+// Constants
+const constants = require('./constants');
+
+// Errors
+const errors = require('./errors');
+
+// Validators
+const validators = require('./validators');
+
+// Utils
+const utils = require('./utils');
+
+// Export main class as default
+module.exports = NeuraiAssets;
+
+// Export everything as named exports
+module.exports.NeuraiAssets = NeuraiAssets;
+module.exports.AssetQueries = AssetQueries;
+module.exports.builders = builders;
+module.exports.constants = constants;
+module.exports.errors = errors;
+module.exports.validators = validators;
+module.exports.utils = utils;

package/src/managers/BurnManager.js

@@ -0,0 +1,222 @@
+/**
+ * Burn Manager
+ * Manages burn addresses and amounts for asset operations
+ *
+ * Each asset operation requires burning XNA to specific addresses.
+ * This manager ensures correct burn addresses and amounts are used
+ * based on network (mainnet/testnet) and operation type.
+ */
+
+const { getBurnAddress, getAssetCost } = require('../constants');
+const { InsufficientBurnAmountError, InvalidBurnAddressError } = require('../errors');
+
+class BurnManager {
+  /**
+   * @param {string} network - Network type ('xna' or 'xna-test')
+   */
+  constructor(network) {
+    if (!network) {
+      throw new Error('Network is required');
+    }
+    this.network = network;
+  }
+
+  /**
+   * Get burn address for an operation
+   * @param {string} operationType - Operation type (e.g., 'ISSUE_ROOT')
+   * @returns {string} Burn address for the network
+   */
+  getBurnAddress(operationType) {
+    return getBurnAddress(operationType, this.network);
+  }
+
+  /**
+   * Get burn amount for an operation
+   * @param {string} operationType - Operation type (e.g., 'ISSUE_ROOT')
+   * @param {number} multiplier - Multiplier for operations like UNIQUE (default: 1)
+   * @returns {number} Burn amount in XNA
+   */
+  getBurnAmount(operationType, multiplier = 1) {
+    const baseCost = getAssetCost(operationType);
+    return baseCost * multiplier;
+  }
+
+  /**
+   * Get burn info (address + amount) for an operation
+   * @param {string} operationType - Operation type
+   * @param {number} multiplier - Multiplier (default: 1)
+   * @returns {object} { address, amount }
+   */
+  getBurnInfo(operationType, multiplier = 1) {
+    return {
+      address: this.getBurnAddress(operationType),
+      amount: this.getBurnAmount(operationType, multiplier)
+    };
+  }
+
+  /**
+   * Get burn info for ROOT asset issuance
+   * @returns {object} { address, amount }
+   */
+  getIssueRootBurn() {
+    return this.getBurnInfo('ISSUE_ROOT');
+  }
+
+  /**
+   * Get burn info for SUB asset issuance
+   * @returns {object} { address, amount }
+   */
+  getIssueSubBurn() {
+    return this.getBurnInfo('ISSUE_SUB');
+  }
+
+  /**
+   * Get burn info for UNIQUE asset issuance
+   * @param {number} count - Number of unique assets to create
+   * @returns {object} { address, amount }
+   */
+  getIssueUniqueBurn(count) {
+    return this.getBurnInfo('ISSUE_UNIQUE', count);
+  }
+
+  /**
+   * Get burn info for QUALIFIER asset issuance
+   * @returns {object} { address, amount }
+   */
+  getIssueQualifierBurn() {
+    return this.getBurnInfo('ISSUE_QUALIFIER');
+  }
+
+  /**
+   * Get burn info for SUB_QUALIFIER asset issuance
+   * @returns {object} { address, amount }
+   */
+  getIssueSubQualifierBurn() {
+    return this.getBurnInfo('ISSUE_SUB_QUALIFIER');
+  }
+
+  /**
+   * Get burn info for RESTRICTED asset issuance
+   * @returns {object} { address, amount }
+   */
+  getIssueRestrictedBurn() {
+    return this.getBurnInfo('ISSUE_RESTRICTED');
+  }
+
+  /**
+   * Get burn info for REISSUE operation
+   * @returns {object} { address, amount }
+   */
+  getReissueBurn() {
+    return this.getBurnInfo('REISSUE');
+  }
+
+  /**
+   * Get burn info for TAG_ADDRESS operation
+   * @param {number} addressCount - Number of addresses to tag
+   * @returns {object} { address, amount }
+   */
+  getTagAddressBurn(addressCount) {
+    return this.getBurnInfo('TAG_ADDRESS', addressCount);
+  }
+
+  /**
+   * Get burn info for UNTAG_ADDRESS operation
+   * @param {number} addressCount - Number of addresses to untag
+   * @returns {object} { address, amount }
+   */
+  getUntagAddressBurn(addressCount) {
+    return this.getBurnInfo('UNTAG_ADDRESS', addressCount);
+  }
+
+  /**
+   * Validate that burn output is correct
+   * @param {object} outputs - Transaction outputs
+   * @param {string} operationType - Expected operation type
+   * @param {number} multiplier - Expected multiplier (default: 1)
+   * @returns {boolean} True if valid
+   * @throws {Error} If burn is invalid
+   */
+  validateBurnOutput(outputs, operationType, multiplier = 1) {
+    const expectedBurn = this.getBurnInfo(operationType, multiplier);
+
+    // Check if burn address exists in outputs
+    const burnAmount = outputs[expectedBurn.address];
+    if (burnAmount === undefined) {
+      throw new InvalidBurnAddressError(
+        `Expected burn to ${expectedBurn.address} not found in outputs`,
+        expectedBurn.address,
+        null
+      );
+    }
+
+    // Check if burn amount is correct
+    if (burnAmount !== expectedBurn.amount) {
+      throw new InsufficientBurnAmountError(
+        `Incorrect burn amount. Expected ${expectedBurn.amount} XNA, got ${burnAmount} XNA`,
+        expectedBurn.amount,
+        burnAmount
+      );
+    }
+
+    return true;
+  }
+
+  /**
+   * Check if an address is a burn address for this network
+   * @param {string} address - Address to check
+   * @returns {boolean} True if it's a burn address
+   */
+  isBurnAddress(address) {
+    const burnTypes = [
+      'ISSUE_ROOT',
+      'ISSUE_SUB',
+      'ISSUE_UNIQUE',
+      'ISSUE_MSGCHANNEL',
+      'REISSUE',
+      'ISSUE_RESTRICTED',
+      'ISSUE_QUALIFIER',
+      'ISSUE_SUB_QUALIFIER',
+      'TAG_ADDRESS',
+      'UNTAG_ADDRESS'
+    ];
+
+    for (const type of burnTypes) {
+      if (this.getBurnAddress(type) === address) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  /**
+   * Get operation type from burn address
+   * @param {string} address - Burn address
+   * @returns {string|null} Operation type or null if not a burn address
+   */
+  getOperationTypeFromBurnAddress(address) {
+    const burnTypes = [
+      'ISSUE_ROOT',
+      'ISSUE_SUB',
+      'ISSUE_UNIQUE',
+      'ISSUE_MSGCHANNEL',
+      'REISSUE',
+      'ISSUE_RESTRICTED',
+      'ISSUE_QUALIFIER',
+      'ISSUE_SUB_QUALIFIER',
+      'TAG_ADDRESS',
+      'UNTAG_ADDRESS'
+    ];
+
+    for (const type of burnTypes) {
+      if (this.getBurnAddress(type) === address) {
+        return type;
+      }
+    }
+
+    return null;
+  }
+}
+
+module.exports = BurnManager;