@neuraiproject/neurai-assets 1.0.0

package/src/validators/amountValidator.js

@@ -0,0 +1,149 @@
+/**
+ * Amount Validator
+ * Validates asset quantities and units
+ */
+
+const { ASSET_LIMITS } = require('../constants');
+const { InvalidAmountError, InvalidUnitsError } = require('../errors');
+
+class AmountValidator {
+  /**
+   * Validate asset quantity
+   * @param {number} quantity - Asset quantity
+   * @param {number} units - Decimal places (0-8)
+   */
+  static validate(quantity, units = 0) {
+    // Validate quantity is a number
+    if (typeof quantity !== 'number' || isNaN(quantity)) {
+      throw new InvalidAmountError('Quantity must be a valid number', quantity);
+    }
+
+    // Validate quantity is positive
+    if (quantity <= 0) {
+      throw new InvalidAmountError('Quantity must be greater than 0', quantity);
+    }
+
+    // Validate quantity is within limits
+    if (quantity < ASSET_LIMITS.MIN_QUANTITY) {
+      throw new InvalidAmountError(
+        `Quantity must be at least ${ASSET_LIMITS.MIN_QUANTITY}`,
+        quantity
+      );
+    }
+
+    if (quantity > ASSET_LIMITS.MAX_QUANTITY) {
+      throw new InvalidAmountError(
+        `Quantity cannot exceed ${ASSET_LIMITS.MAX_QUANTITY}`,
+        quantity
+      );
+    }
+
+    // Validate units
+    this.validateUnits(units);
+
+    // Validate quantity doesn't have more decimals than units allow
+    const decimalPlaces = this.getDecimalPlaces(quantity);
+    if (decimalPlaces > units) {
+      throw new InvalidAmountError(
+        `Quantity has ${decimalPlaces} decimal places but units is ${units}`,
+        quantity
+      );
+    }
+
+    return true;
+  }
+
+  /**
+   * Validate units (decimal places)
+   * @param {number} units - Decimal places (0-8)
+   */
+  static validateUnits(units) {
+    if (typeof units !== 'number' || isNaN(units)) {
+      throw new InvalidUnitsError('Units must be a valid number', units);
+    }
+
+    if (!Number.isInteger(units)) {
+      throw new InvalidUnitsError('Units must be an integer', units);
+    }
+
+    if (units < ASSET_LIMITS.MIN_UNITS || units > ASSET_LIMITS.MAX_UNITS) {
+      throw new InvalidUnitsError(
+        `Units must be between ${ASSET_LIMITS.MIN_UNITS} and ${ASSET_LIMITS.MAX_UNITS}`,
+        units
+      );
+    }
+
+    return true;
+  }
+
+  /**
+   * Validate qualifier quantity (1-10 only)
+   * @param {number} quantity - Qualifier quantity
+   */
+  static validateQualifierQuantity(quantity) {
+    if (typeof quantity !== 'number' || isNaN(quantity)) {
+      throw new InvalidAmountError('Qualifier quantity must be a valid number', quantity);
+    }
+
+    if (!Number.isInteger(quantity)) {
+      throw new InvalidAmountError('Qualifier quantity must be an integer', quantity);
+    }
+
+    if (quantity < ASSET_LIMITS.QUALIFIER_MIN_QUANTITY || quantity > ASSET_LIMITS.QUALIFIER_MAX_QUANTITY) {
+      throw new InvalidAmountError(
+        `Qualifier quantity must be between ${ASSET_LIMITS.QUALIFIER_MIN_QUANTITY} and ${ASSET_LIMITS.QUALIFIER_MAX_QUANTITY}`,
+        quantity
+      );
+    }
+
+    return true;
+  }
+
+  /**
+   * Validate owner token quantity (always 1)
+   * @param {number} quantity - Owner token quantity
+   */
+  static validateOwnerTokenQuantity(quantity) {
+    if (quantity !== ASSET_LIMITS.OWNER_TOKEN_QUANTITY) {
+      throw new InvalidAmountError(
+        `Owner token quantity must be exactly ${ASSET_LIMITS.OWNER_TOKEN_QUANTITY}`,
+        quantity
+      );
+    }
+
+    return true;
+  }
+
+  /**
+   * Get number of decimal places in a number
+   * @param {number} num - Number to check
+   * @returns {number} Number of decimal places
+   */
+  static getDecimalPlaces(num) {
+    const match = ('' + num).match(/(?:\.(\d+))?(?:[eE]([+-]?\d+))?$/);
+    if (!match) return 0;
+    return Math.max(
+      0,
+      (match[1] ? match[1].length : 0) - (match[2] ? +match[2] : 0)
+    );
+  }
+
+  /**
+   * Validate that sum of amounts doesn't exceed max
+   * @param {number} current - Current amount
+   * @param {number} additional - Additional amount
+   * @returns {boolean} True if sum is valid
+   */
+  static validateSum(current, additional) {
+    if (current + additional > ASSET_LIMITS.MAX_QUANTITY) {
+      throw new InvalidAmountError(
+        `Sum of current (${current}) and additional (${additional}) exceeds maximum ${ASSET_LIMITS.MAX_QUANTITY}`,
+        current + additional
+      );
+    }
+
+    return true;
+  }
+}
+
+module.exports = AmountValidator;

package/src/validators/assetNameValidator.js

@@ -0,0 +1,296 @@
+/**
+ * Asset Name Validator
+ * Validates asset names according to Neurai protocol rules
+ */
+
+const { ASSET_NAME_RULES } = require('../constants');
+const { InvalidAssetNameError } = require('../errors');
+
+class AssetNameValidator {
+  /**
+   * Validate ROOT asset name
+   * Rules: 3-30 uppercase characters, A-Z, 0-9, underscore, period
+   * Cannot start with period, A, or Z
+   * Cannot be reserved names
+   */
+  static validateRoot(name) {
+    if (!name || typeof name !== 'string') {
+      throw new InvalidAssetNameError('Asset name must be a non-empty string', name);
+    }
+
+    // Length check
+    if (name.length < ASSET_NAME_RULES.ROOT.minLength || name.length > ASSET_NAME_RULES.ROOT.maxLength) {
+      throw new InvalidAssetNameError(
+        `ROOT asset name must be ${ASSET_NAME_RULES.ROOT.minLength}-${ASSET_NAME_RULES.ROOT.maxLength} characters`,
+        name
+      );
+    }
+
+    // Uppercase check
+    if (name !== name.toUpperCase()) {
+      throw new InvalidAssetNameError('Asset name must be uppercase', name);
+    }
+
+    // Starting character check
+    if (ASSET_NAME_RULES.ROOT.cannotStartWith.some(char => name.startsWith(char))) {
+      throw new InvalidAssetNameError(
+        `Asset name cannot start with: ${ASSET_NAME_RULES.ROOT.cannotStartWith.join(', ')}`,
+        name
+      );
+    }
+
+    // Pattern check
+    if (!ASSET_NAME_RULES.ROOT.pattern.test(name)) {
+      throw new InvalidAssetNameError(
+        'Asset name can only contain A-Z, 0-9, underscore, and period',
+        name
+      );
+    }
+
+    // Reserved names check
+    if (ASSET_NAME_RULES.ROOT.reserved.includes(name)) {
+      throw new InvalidAssetNameError(`${name} is a reserved asset name`, name);
+    }
+
+    return true;
+  }
+
+  /**
+   * Validate SUB asset name
+   * Format: ROOT/SUBNAME
+   */
+  static validateSub(name) {
+    if (!name || typeof name !== 'string') {
+      throw new InvalidAssetNameError('SUB asset name must be a non-empty string', name);
+    }
+
+    const parts = name.split(ASSET_NAME_RULES.SUB.separator);
+    if (parts.length !== 2) {
+      throw new InvalidAssetNameError(
+        `SUB asset must be in ${ASSET_NAME_RULES.SUB.separator} format (ROOT/SUBNAME)`,
+        name
+      );
+    }
+
+    const [rootName, subName] = parts;
+
+    // Validate root part
+    this.validateRoot(rootName);
+
+    // Validate sub part
+    if (subName.length < ASSET_NAME_RULES.SUB.minLength || subName.length > ASSET_NAME_RULES.SUB.maxLength) {
+      throw new InvalidAssetNameError(
+        `SUB asset name must be ${ASSET_NAME_RULES.SUB.minLength}-${ASSET_NAME_RULES.SUB.maxLength} characters`,
+        name
+      );
+    }
+
+    if (subName !== subName.toUpperCase()) {
+      throw new InvalidAssetNameError('SUB asset name must be uppercase', name);
+    }
+
+    if (!ASSET_NAME_RULES.SUB.pattern.test(subName)) {
+      throw new InvalidAssetNameError(
+        'SUB asset name can only contain A-Z, 0-9, underscore, and period',
+        name
+      );
+    }
+
+    return true;
+  }
+
+  /**
+   * Validate UNIQUE asset name
+   * Format: ROOT#TAG
+   */
+  static validateUnique(name) {
+    if (!name || typeof name !== 'string') {
+      throw new InvalidAssetNameError('UNIQUE asset name must be a non-empty string', name);
+    }
+
+    const parts = name.split(ASSET_NAME_RULES.UNIQUE.separator);
+    if (parts.length !== 2) {
+      throw new InvalidAssetNameError(
+        `UNIQUE asset must be in ROOT${ASSET_NAME_RULES.UNIQUE.separator}TAG format`,
+        name
+      );
+    }
+
+    const [rootName, tag] = parts;
+
+    // Validate root part
+    this.validateRoot(rootName);
+
+    // Validate tag
+    if (tag.length < ASSET_NAME_RULES.UNIQUE.minLength || tag.length > ASSET_NAME_RULES.UNIQUE.maxLength) {
+      throw new InvalidAssetNameError(
+        `UNIQUE tag must be ${ASSET_NAME_RULES.UNIQUE.minLength}-${ASSET_NAME_RULES.UNIQUE.maxLength} characters`,
+        name
+      );
+    }
+
+    if (tag !== tag.toUpperCase()) {
+      throw new InvalidAssetNameError('UNIQUE tag must be uppercase', name);
+    }
+
+    if (!ASSET_NAME_RULES.UNIQUE.pattern.test(tag)) {
+      throw new InvalidAssetNameError(
+        'UNIQUE tag can only contain A-Z, 0-9, underscore, and period',
+        name
+      );
+    }
+
+    return true;
+  }
+
+  /**
+   * Validate QUALIFIER asset name
+   * Format: #NAME or #ROOT/SUB
+   */
+  static validateQualifier(name) {
+    if (!name || typeof name !== 'string') {
+      throw new InvalidAssetNameError('QUALIFIER asset name must be a non-empty string', name);
+    }
+
+    if (!name.startsWith(ASSET_NAME_RULES.QUALIFIER.prefix)) {
+      throw new InvalidAssetNameError(
+        `QUALIFIER asset must start with ${ASSET_NAME_RULES.QUALIFIER.prefix}`,
+        name
+      );
+    }
+
+    const withoutPrefix = name.substring(1);
+
+    if (withoutPrefix.includes(ASSET_NAME_RULES.QUALIFIER.separator)) {
+      // Sub-qualifier: #ROOT/SUB
+      const parts = withoutPrefix.split(ASSET_NAME_RULES.QUALIFIER.separator);
+      if (parts.length !== 2) {
+        throw new InvalidAssetNameError(
+          'SUB_QUALIFIER must be in #ROOT/SUB format',
+          name
+        );
+      }
+
+      // Validate each part as a qualifier name (without the #)
+      parts.forEach(part => {
+        if (part.length < ASSET_NAME_RULES.QUALIFIER.minLength || part.length > ASSET_NAME_RULES.QUALIFIER.maxLength) {
+          throw new InvalidAssetNameError(
+            `QUALIFIER name must be ${ASSET_NAME_RULES.QUALIFIER.minLength}-${ASSET_NAME_RULES.QUALIFIER.maxLength} characters`,
+            name
+          );
+        }
+
+        if (part !== part.toUpperCase()) {
+          throw new InvalidAssetNameError('QUALIFIER name must be uppercase', name);
+        }
+
+        if (!ASSET_NAME_RULES.QUALIFIER.pattern.test(part)) {
+          throw new InvalidAssetNameError(
+            'QUALIFIER name can only contain A-Z, 0-9, and underscore',
+            name
+          );
+        }
+      });
+    } else {
+      // Root qualifier: #NAME
+      if (withoutPrefix.length < ASSET_NAME_RULES.QUALIFIER.minLength ||
+          withoutPrefix.length > ASSET_NAME_RULES.QUALIFIER.maxLength) {
+        throw new InvalidAssetNameError(
+          `QUALIFIER name must be ${ASSET_NAME_RULES.QUALIFIER.minLength}-${ASSET_NAME_RULES.QUALIFIER.maxLength} characters`,
+          name
+        );
+      }
+
+      if (withoutPrefix !== withoutPrefix.toUpperCase()) {
+        throw new InvalidAssetNameError('QUALIFIER name must be uppercase', name);
+      }
+
+      if (!ASSET_NAME_RULES.QUALIFIER.pattern.test(withoutPrefix)) {
+        throw new InvalidAssetNameError(
+          'QUALIFIER name can only contain A-Z, 0-9, and underscore',
+          name
+        );
+      }
+    }
+
+    return true;
+  }
+
+  /**
+   * Validate RESTRICTED asset name
+   * Format: $NAME
+   */
+  static validateRestricted(name) {
+    if (!name || typeof name !== 'string') {
+      throw new InvalidAssetNameError('RESTRICTED asset name must be a non-empty string', name);
+    }
+
+    if (!name.startsWith(ASSET_NAME_RULES.RESTRICTED.prefix)) {
+      throw new InvalidAssetNameError(
+        `RESTRICTED asset must start with ${ASSET_NAME_RULES.RESTRICTED.prefix}`,
+        name
+      );
+    }
+
+    const withoutPrefix = name.substring(1);
+
+    // Validate the part after $ as a ROOT asset name
+    this.validateRoot(withoutPrefix);
+
+    return true;
+  }
+
+  /**
+   * Validate owner token name
+   * Format: ASSETNAME!
+   */
+  static validateOwnerToken(name) {
+    if (!name || typeof name !== 'string') {
+      throw new InvalidAssetNameError('Owner token name must be a non-empty string', name);
+    }
+
+    if (!name.endsWith('!')) {
+      throw new InvalidAssetNameError('Owner token must end with !', name);
+    }
+
+    const assetName = name.substring(0, name.length - 1);
+
+    // Validate the asset name part (could be ROOT or RESTRICTED)
+    if (assetName.startsWith('$')) {
+      this.validateRestricted(assetName);
+    } else {
+      this.validateRoot(assetName);
+    }
+
+    return true;
+  }
+
+  /**
+   * Auto-detect asset type and validate
+   * @param {string} name - Asset name
+   * @returns {string} Asset type ('ROOT', 'SUB', 'UNIQUE', 'QUALIFIER', 'RESTRICTED', 'OWNER')
+   */
+  static validateAndDetectType(name) {
+    if (name.endsWith('!')) {
+      this.validateOwnerToken(name);
+      return 'OWNER';
+    } else if (name.startsWith('#')) {
+      this.validateQualifier(name);
+      return name.includes('/') ? 'SUB_QUALIFIER' : 'QUALIFIER';
+    } else if (name.startsWith('$')) {
+      this.validateRestricted(name);
+      return 'RESTRICTED';
+    } else if (name.includes('#')) {
+      this.validateUnique(name);
+      return 'UNIQUE';
+    } else if (name.includes('/')) {
+      this.validateSub(name);
+      return 'SUB';
+    } else {
+      this.validateRoot(name);
+      return 'ROOT';
+    }
+  }
+}
+
+module.exports = AssetNameValidator;

package/src/validators/index.js

@@ -0,0 +1,16 @@
+/**
+ * Validators Module
+ * Exports all validator classes
+ */
+
+const AssetNameValidator = require('./assetNameValidator');
+const AmountValidator = require('./amountValidator');
+const VerifierValidator = require('./verifierValidator');
+const IpfsValidator = require('./ipfsValidator');
+
+module.exports = {
+  AssetNameValidator,
+  AmountValidator,
+  VerifierValidator,
+  IpfsValidator
+};

package/src/validators/ipfsValidator.js

@@ -0,0 +1,101 @@
+/**
+ * IPFS Hash Validator
+ * Validates IPFS CID formats
+ */
+
+const { InvalidIPFSHashError } = require('../errors');
+
+class IpfsValidator {
+  /**
+   * Validate IPFS hash format
+   * Accepts:
+   * - CIDv0: Qm... (46 characters, base58)
+   * - CIDv1: bafy... or bafk... (various lengths, base32)
+   * - Neurai TXID: 64 hex characters (for on-chain metadata)
+   *
+   * @param {string} hash - IPFS hash or TXID
+   * @returns {boolean} True if valid
+   */
+  static validate(hash) {
+    if (!hash || typeof hash !== 'string') {
+      throw new InvalidIPFSHashError('IPFS hash must be a non-empty string', hash);
+    }
+
+    const trimmed = hash.trim();
+
+    // Check maximum length (Neurai allows up to 40 bytes in protocol)
+    if (trimmed.length > 80) {
+      throw new InvalidIPFSHashError('IPFS hash too long (max 80 characters)', hash);
+    }
+
+    // Check if it's a valid format
+    const isCIDv0 = this.isCIDv0(trimmed);
+    const isCIDv1 = this.isCIDv1(trimmed);
+    const isTXID = this.isTXID(trimmed);
+
+    if (!isCIDv0 && !isCIDv1 && !isTXID) {
+      throw new InvalidIPFSHashError(
+        'Invalid IPFS hash format. Must be CIDv0 (Qm...), CIDv1 (bafy...), or TXID (64 hex chars)',
+        hash
+      );
+    }
+
+    return true;
+  }
+
+  /**
+   * Check if hash is CIDv0 format
+   * @param {string} hash - Hash to check
+   * @returns {boolean} True if CIDv0
+   */
+  static isCIDv0(hash) {
+    // CIDv0: Starts with "Qm", 46 characters, base58
+    if (!hash.startsWith('Qm')) return false;
+    if (hash.length !== 46) return false;
+
+    // Base58 characters: 123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz
+    const base58Pattern = /^[123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]+$/;
+    return base58Pattern.test(hash);
+  }
+
+  /**
+   * Check if hash is CIDv1 format
+   * @param {string} hash - Hash to check
+   * @returns {boolean} True if CIDv1
+   */
+  static isCIDv1(hash) {
+    // CIDv1: Starts with "bafy" or "bafk" (base32), various lengths
+    if (!hash.startsWith('bafy') && !hash.startsWith('bafk')) return false;
+
+    // Base32 characters: a-z, 2-7
+    const base32Pattern = /^[a-z2-7]+$/;
+    return base32Pattern.test(hash);
+  }
+
+  /**
+   * Check if hash is a transaction ID
+   * @param {string} hash - Hash to check
+   * @returns {boolean} True if TXID
+   */
+  static isTXID(hash) {
+    // TXID: 64 hexadecimal characters
+    if (hash.length !== 64) return false;
+
+    const hexPattern = /^[0-9a-fA-F]+$/;
+    return hexPattern.test(hash);
+  }
+
+  /**
+   * Get IPFS hash type
+   * @param {string} hash - IPFS hash
+   * @returns {string} Type ('CIDv0', 'CIDv1', 'TXID', or 'UNKNOWN')
+   */
+  static getHashType(hash) {
+    if (this.isCIDv0(hash)) return 'CIDv0';
+    if (this.isCIDv1(hash)) return 'CIDv1';
+    if (this.isTXID(hash)) return 'TXID';
+    return 'UNKNOWN';
+  }
+}
+
+module.exports = IpfsValidator;

package/src/validators/verifierValidator.js

@@ -0,0 +1,146 @@
+/**
+ * Verifier String Validator
+ * Validates verifier strings for restricted assets
+ */
+
+const { InvalidVerifierStringError } = require('../errors');
+const AssetNameValidator = require('./assetNameValidator');
+
+class VerifierValidator {
+  /**
+   * Validate verifier string syntax
+   * Verifier syntax: #TAG, !#TAG, &, |, (, )
+   * Examples:
+   *   "#KYC"
+   *   "#KYC & #ACCREDITED"
+   *   "#KYC | #INSTITUTION"
+   *   "(#KYC & #ACCREDITED) | #INSTITUTION"
+   *   "!#BANNED"
+   *
+   * @param {string} verifierString - Verifier string to validate
+   * @returns {boolean} True if valid
+   */
+  static validate(verifierString) {
+    if (!verifierString || typeof verifierString !== 'string') {
+      throw new InvalidVerifierStringError(
+        'Verifier string must be a non-empty string',
+        verifierString
+      );
+    }
+
+    // Trim whitespace
+    const trimmed = verifierString.trim();
+    if (trimmed.length === 0) {
+      throw new InvalidVerifierStringError(
+        'Verifier string cannot be empty',
+        verifierString
+      );
+    }
+
+    // Check for valid characters only
+    // Valid: #, A-Z, 0-9, _, &, |, !, (, ), space, /
+    const validPattern = /^[#A-Z0-9_&|()\s!/]+$/;
+    if (!validPattern.test(trimmed)) {
+      throw new InvalidVerifierStringError(
+        'Verifier contains invalid characters. Valid: #, A-Z, 0-9, _, &, |, !, (, ), space, /',
+        verifierString
+      );
+    }
+
+    // Extract all qualifiers (tokens starting with # or !#)
+    const qualifierMatches = trimmed.match(/!?#[A-Z0-9_/]+/g) || [];
+
+    if (qualifierMatches.length === 0) {
+      throw new InvalidVerifierStringError(
+        'Verifier must contain at least one qualifier (#TAG)',
+        verifierString
+      );
+    }
+
+    // Validate each qualifier
+    for (const match of qualifierMatches) {
+      const qualifier = match.startsWith('!') ? match.substring(1) : match;
+
+      try {
+        AssetNameValidator.validateQualifier(qualifier);
+      } catch (e) {
+        throw new InvalidVerifierStringError(
+          `Invalid qualifier in verifier: ${qualifier} - ${e.message}`,
+          verifierString
+        );
+      }
+    }
+
+    // Check balanced parentheses
+    let depth = 0;
+    for (const char of trimmed) {
+      if (char === '(') depth++;
+      if (char === ')') depth--;
+      if (depth < 0) {
+        throw new InvalidVerifierStringError(
+          'Unbalanced parentheses in verifier string',
+          verifierString
+        );
+      }
+    }
+    if (depth !== 0) {
+      throw new InvalidVerifierStringError(
+        'Unbalanced parentheses in verifier string',
+        verifierString
+      );
+    }
+
+    // Check for valid operators placement
+    // & and | must be between qualifiers, not at start/end
+    const operatorPattern = /(&|\|)/g;
+    const operators = trimmed.match(operatorPattern);
+    if (operators) {
+      // Check operators are not at start or end
+      if (trimmed.trim().match(/^(&|\|)/) || trimmed.trim().match(/(&|\|)$/)) {
+        throw new InvalidVerifierStringError(
+          'Operators & or | cannot be at start or end of verifier',
+          verifierString
+        );
+      }
+
+      // Check no consecutive operators
+      if (trimmed.match(/(&|\|)\s*(&|\|)/)) {
+        throw new InvalidVerifierStringError(
+          'Consecutive operators are not allowed',
+          verifierString
+        );
+      }
+    }
+
+    return true;
+  }
+
+  /**
+   * Extract all qualifiers from verifier string
+   * @param {string} verifierString - Verifier string
+   * @returns {string[]} Array of qualifier names (including #)
+   */
+  static extractQualifiers(verifierString) {
+    this.validate(verifierString);
+
+    const qualifierMatches = verifierString.match(/!?#[A-Z0-9_/]+/g) || [];
+
+    // Remove ! prefix and deduplicate
+    const qualifiers = [...new Set(qualifierMatches.map(q => q.replace('!', '')))];
+
+    return qualifiers;
+  }
+
+  /**
+   * Check if verifier string uses a specific qualifier
+   * @param {string} verifierString - Verifier string
+   * @param {string} qualifierName - Qualifier to check (with #)
+   * @returns {boolean} True if qualifier is used
+   */
+  static usesQualifier(verifierString, qualifierName) {
+    const qualifiers = this.extractQualifiers(verifierString);
+    return qualifiers.includes(qualifierName);
+  }
+}
+
+module.exports = VerifierValidator;