@neuraiproject/neurai-assets 1.0.0

package/tests/README.md

@@ -0,0 +1,126 @@
+# Tests para @neuraiproject/neurai-assets
+
+Esta carpeta contiene la suite completa de tests para la librería de gestión de activos de Neurai.
+
+## Estructura de Tests
+
+```
+tests/
+├── mocks/              # Mocks para RPC y dependencias
+│   └── rpcMock.js     # Mock del RPC de Neurai
+├── unit/              # Tests unitarios
+│   ├── validators/    # Tests para validadores
+│   ├── utils/         # Tests para utilidades
+│   └── NeuraiAssets.test.js  # Tests de la clase principal
+└── integration/       # Tests de integración
+    └── assetLifecycle.test.js  # Tests del ciclo de vida completo
+```
+
+## Ejecutar Tests
+
+### Todos los tests
+```bash
+npm test
+```
+
+### Solo tests unitarios
+```bash
+npm run test:unit
+```
+
+### Solo tests de integración
+```bash
+npm run test:integration
+```
+
+### Tests en modo watch (re-ejecuta al guardar cambios)
+```bash
+npm run test:watch
+```
+
+## Cobertura de Tests
+
+### Validators (Validadores)
+- **assetNameValidator.test.js**: Valida nombres de activos ROOT, SUB, UNIQUE, QUALIFIER, RESTRICTED y OWNER
+- **amountValidator.test.js**: Valida cantidades, unidades y rangos de activos
+
+### Utils (Utilidades)
+- **assetNameParser.test.js**: Prueba el parsing y detección de tipos de activos
+- **amountConverter.test.js**: Prueba conversiones entre cantidades y satoshis
+
+### Clase Principal
+- **NeuraiAssets.test.js**: Prueba la clase principal y sus métodos
+
+### Integración
+- **assetLifecycle.test.js**: Prueba workflows completos de creación y gestión de activos
+
+## Tests Actuales
+
+Total: **124 tests pasando**
+
+### Desglose por módulo:
+- AmountConverter: 24 tests
+- AssetNameParser: 29 tests
+- AmountValidator: 21 tests
+- AssetNameValidator: 33 tests
+- NeuraiAssets: 10 tests
+- Integration Tests: 7 tests
+
+## Mocks Disponibles
+
+### RPCMock
+Mock flexible del RPC de Neurai que permite:
+- Configurar respuestas personalizadas para métodos específicos
+- Rastrear llamadas realizadas
+- Simular errores y casos edge
+
+```javascript
+const { createMockRPC, createMockUTXO, createMockAssetData } = require('./mocks/rpcMock');
+
+// Crear mock con respuestas personalizadas
+const mockRPC = createMockRPC({
+  'getassetdata': { name: 'MYTOKEN', amount: 1000000 }
+});
+
+// Usar en tests
+const assets = new NeuraiAssets(mockRPC);
+```
+
+## Agregar Nuevos Tests
+
+Para agregar nuevos tests:
+
+1. **Tests unitarios**: Coloca el archivo en `tests/unit/[modulo]/`
+2. **Tests de integración**: Coloca el archivo en `tests/integration/`
+3. **Nombra el archivo**: `*.test.js` para que Mocha lo detecte automáticamente
+4. **Usa la estructura estándar**:
+
+```javascript
+const { expect } = require('chai');
+
+describe('NombreDelModulo', () => {
+  describe('nombreDelMetodo', () => {
+    it('debería hacer algo específico', () => {
+      // Arrange
+      const input = 'valor';
+
+      // Act
+      const result = someFunction(input);
+
+      // Assert
+      expect(result).to.equal('esperado');
+    });
+  });
+});
+```
+
+## Frameworks Utilizados
+
+- **Mocha**: Framework de testing
+- **Chai**: Librería de assertions (expect)
+
+## Notas
+
+- Los tests no requieren conexión a un nodo Neurai real
+- Todos los tests usan mocks para simular llamadas RPC
+- Los tests verifican tanto casos exitosos como errores esperados

package/tests/integration/assetLifecycle.test.js

@@ -0,0 +1,244 @@
+/**
+ * Integration Tests - Asset Lifecycle
+ * Tests the complete workflow of asset operations
+ */
+
+const { expect } = require('chai');
+const NeuraiAssets = require('../../src/NeuraiAssets');
+const AssetNameValidator = require('../../src/validators/assetNameValidator');
+const AssetNameParser = require('../../src/utils/assetNameParser');
+const AmountConverter = require('../../src/utils/amountConverter');
+const { createMockRPC, createMockUTXO, createMockAssetData } = require('../mocks/rpcMock');
+
+describe('Integration: Asset Lifecycle', () => {
+  describe('Validator and Parser Integration', () => {
+    it('should validate and parse ROOT assets correctly', () => {
+      const assetName = 'MYTOKEN';
+
+      expect(AssetNameValidator.validateRoot(assetName)).to.be.true;
+
+      const parsed = AssetNameParser.parse(assetName);
+      expect(parsed.type).to.equal(0);
+      expect(parsed.name).to.equal(assetName);
+      expect(parsed.isOwner).to.be.false;
+    });
+
+    it('should validate and parse UNIQUE assets correctly', () => {
+      const assetName = 'MYTOKEN#NFT1';
+
+      expect(AssetNameValidator.validateUnique(assetName)).to.be.true;
+
+      const parsed = AssetNameParser.parse(assetName);
+      expect(parsed.type).to.equal(2);
+      expect(parsed.parent).to.equal('MYTOKEN');
+      expect(parsed.tag).to.equal('NFT1');
+    });
+
+    it('should validate and parse QUALIFIER assets correctly', () => {
+      const assetName = '#KYC_VERIFIED';
+
+      expect(AssetNameValidator.validateQualifier(assetName)).to.be.true;
+
+      const parsed = AssetNameParser.parse(assetName);
+      expect(parsed.type).to.equal(4);
+      expect(parsed.isQualifier).to.be.true;
+      expect(parsed.prefix).to.equal('#');
+    });
+
+    it('should validate and parse RESTRICTED assets correctly', () => {
+      const assetName = '$SECURITY_TOKEN';
+
+      expect(AssetNameValidator.validateRestricted(assetName)).to.be.true;
+
+      const parsed = AssetNameParser.parse(assetName);
+      expect(parsed.type).to.equal(6);
+      expect(parsed.isRestricted).to.be.true;
+      expect(parsed.prefix).to.equal('$');
+    });
+  });
+
+  describe('Amount Conversion Integration', () => {
+    it('should convert amounts correctly for different units', () => {
+      const testCases = [
+        { amount: 100, units: 0, expected: 100 },
+        { amount: 1.5, units: 1, expected: 15 },
+        { amount: 1.5, units: 2, expected: 150 },
+        { amount: 1.00000001, units: 8, expected: 100000001 }
+      ];
+
+      testCases.forEach(({ amount, units, expected }) => {
+        const satoshis = AmountConverter.toSatoshis(amount, units);
+        expect(satoshis).to.equal(expected);
+
+        const back = AmountConverter.fromSatoshis(satoshis, units);
+        expect(back).to.equal(amount);
+      });
+    });
+
+    it('should format and parse amounts correctly', () => {
+      const amount = 1.5;
+      const units = 2;
+
+      const formatted = AmountConverter.format(amount, units);
+      expect(formatted).to.equal('1.50');
+
+      const parsed = AmountConverter.parse(formatted);
+      expect(parsed).to.equal(amount);
+    });
+  });
+
+  describe('NeuraiAssets Integration', () => {
+    let assets;
+    let mockRPC;
+
+    beforeEach(() => {
+      mockRPC = createMockRPC({
+        'listunspent': [
+          createMockUTXO('N123...', 100),
+          createMockUTXO('N123...', 50, 'MYTOKEN')
+        ],
+        'getassetdata': createMockAssetData('MYTOKEN', {
+          amount: 1000000,
+          units: 2,
+          reissuable: true
+        })
+      });
+
+      assets = new NeuraiAssets(mockRPC, {
+        network: 'xna',
+        addresses: ['N123...'],
+        changeAddress: 'N123...',
+        toAddress: 'N456...'
+      });
+    });
+
+    it('should validate asset name before operations', async () => {
+      expect(() => assets.getAssetType('invalid-name'))
+        .to.not.throw();
+
+      const type = assets.getAssetType('MYTOKEN');
+      expect(type).to.equal('ROOT');
+    });
+
+    it('should query asset data successfully', async () => {
+      const data = await assets.getAssetData('MYTOKEN');
+      expect(data.name).to.equal('MYTOKEN');
+      expect(data.amount).to.equal(1000000);
+      expect(data.units).to.equal(2);
+    });
+
+    it('should detect different asset types', () => {
+      const testCases = [
+        { name: 'MYTOKEN', expected: 'ROOT' },
+        { name: 'MYTOKEN/SUB', expected: 'SUB' },
+        { name: 'MYTOKEN#NFT', expected: 'UNIQUE' },
+        { name: '#KYC', expected: 'QUALIFIER' },
+        { name: '$SECURITY', expected: 'RESTRICTED' },
+        { name: 'MYTOKEN!', expected: 'OWNER' }
+      ];
+
+      testCases.forEach(({ name, expected }) => {
+        const type = assets.getAssetType(name);
+        expect(type).to.equal(expected);
+      });
+    });
+  });
+
+  describe('Complex Workflows', () => {
+    it('should handle owner token derivation', () => {
+      const assetName = 'MYTOKEN';
+      const ownerToken = AssetNameParser.getOwnerTokenName(assetName);
+
+      expect(ownerToken).to.equal('MYTOKEN!');
+      expect(AssetNameParser.isOwnerToken(ownerToken)).to.be.true;
+
+      const baseAsset = AssetNameParser.getBaseAssetName(ownerToken);
+      expect(baseAsset).to.equal(assetName);
+    });
+
+    it('should handle sub-asset creation workflow', () => {
+      const rootName = 'MYTOKEN';
+      const subName = 'ALPHA';
+
+      expect(AssetNameValidator.validateRoot(rootName)).to.be.true;
+
+      const fullSubName = AssetNameParser.buildSubName(rootName, subName);
+      expect(fullSubName).to.equal('MYTOKEN/ALPHA');
+
+      expect(AssetNameValidator.validateSub(fullSubName)).to.be.true;
+
+      const parsed = AssetNameParser.parse(fullSubName);
+      expect(parsed.parent).to.equal(rootName);
+      expect(parsed.subName).to.equal(subName);
+    });
+
+    it('should handle unique asset creation workflow', () => {
+      const rootName = 'MYTOKEN';
+      const tag = 'NFT001';
+
+      expect(AssetNameValidator.validateRoot(rootName)).to.be.true;
+
+      const uniqueName = AssetNameParser.buildUniqueName(rootName, tag);
+      expect(uniqueName).to.equal('MYTOKEN#NFT001');
+
+      expect(AssetNameValidator.validateUnique(uniqueName)).to.be.true;
+
+      const parsed = AssetNameParser.parse(uniqueName);
+      expect(parsed.parent).to.equal(rootName);
+      expect(parsed.tag).to.equal(tag);
+      expect(parsed.type).to.equal(2);
+    });
+
+    it('should handle restricted asset workflow', () => {
+      const assetName = '$SECURITY';
+
+      expect(AssetNameValidator.validateRestricted(assetName)).to.be.true;
+      expect(AssetNameParser.isRestricted(assetName)).to.be.true;
+
+      const parsed = AssetNameParser.parse(assetName);
+      expect(parsed.type).to.equal(6);
+      expect(parsed.prefix).to.equal('$');
+    });
+
+    it('should handle qualifier workflow', () => {
+      const qualifierName = '#KYC_VERIFIED';
+
+      expect(AssetNameValidator.validateQualifier(qualifierName)).to.be.true;
+      expect(AssetNameParser.isQualifier(qualifierName)).to.be.true;
+
+      const parsed = AssetNameParser.parse(qualifierName);
+      expect(parsed.type).to.equal(4);
+      expect(parsed.isQualifier).to.be.true;
+    });
+  });
+
+  describe('Error Handling Integration', () => {
+    it('should propagate validation errors correctly', () => {
+      expect(() => AssetNameValidator.validateRoot('ab'))
+        .to.throw();
+
+      expect(() => AssetNameValidator.validateSub('INVALID'))
+        .to.throw();
+
+      expect(() => AssetNameValidator.validateUnique('INVALID'))
+        .to.throw();
+
+      expect(() => AssetNameValidator.validateQualifier('INVALID'))
+        .to.throw();
+
+      expect(() => AssetNameValidator.validateRestricted('INVALID'))
+        .to.throw();
+    });
+
+    it('should handle amount conversion errors', () => {
+      expect(() => AmountConverter.toSatoshis('invalid', 0))
+        .to.throw();
+
+      expect(() => AmountConverter.toSatoshis(100, -1))
+        .to.throw();
+
+      expect(() => AmountConverter.fromSatoshis('invalid', 0))
+        .to.throw();
+    });
+  });
+});

package/tests/mocks/rpcMock.js

@@ -0,0 +1,156 @@
+/**
+ * Mock RPC Function for Testing
+ * Simulates Neurai RPC calls without requiring a live node
+ */
+
+class RPCMock {
+  constructor() {
+    this.mockResponses = new Map();
+    this.callHistory = [];
+  }
+
+  /**
+   * Set mock response for a specific RPC method
+   * @param {string} method - RPC method name
+   * @param {*} response - Response to return
+   */
+  setMockResponse(method, response) {
+    this.mockResponses.set(method, response);
+  }
+
+  /**
+   * Mock RPC function
+   * @param {string} method - RPC method name
+   * @param {Array} params - RPC parameters
+   * @returns {Promise<*>} Mock response
+   */
+  async call(method, ...params) {
+    this.callHistory.push({ method, params });
+
+    if (this.mockResponses.has(method)) {
+      const response = this.mockResponses.get(method);
+
+      // If response is a function, call it with params
+      if (typeof response === 'function') {
+        return response(...params);
+      }
+
+      return response;
+    }
+
+    // Default responses for common methods
+    return this.getDefaultResponse(method, params);
+  }
+
+  /**
+   * Get default response for common RPC methods
+   */
+  getDefaultResponse(method, params) {
+    const defaults = {
+      'listunspent': [],
+      'getassetdata': { name: params[0], amount: 1000000 },
+      'listassets': [],
+      'listmyassets': {},
+      'listaddressesbyasset': [],
+      'listassetbalancesbyaddress': [],
+      'checkaddresstag': false,
+      'checkaddressrestriction': true,
+      'isaddressfrozen': false,
+      'checkglobalrestriction': false,
+      'getverifierstring': '',
+      'isvalidverifierstring': true
+    };
+
+    return defaults[method] || null;
+  }
+
+  /**
+   * Clear call history
+   */
+  clearHistory() {
+    this.callHistory = [];
+  }
+
+  /**
+   * Get number of times a method was called
+   */
+  getCallCount(method) {
+    return this.callHistory.filter(call => call.method === method).length;
+  }
+
+  /**
+   * Get last call for a method
+   */
+  getLastCall(method) {
+    const calls = this.callHistory.filter(call => call.method === method);
+    return calls[calls.length - 1];
+  }
+
+  /**
+   * Reset all mocks
+   */
+  reset() {
+    this.mockResponses.clear();
+    this.callHistory = [];
+  }
+}
+
+/**
+ * Create a simple mock RPC function
+ */
+function createMockRPC(responses = {}) {
+  const mock = new RPCMock();
+
+  Object.entries(responses).forEach(([method, response]) => {
+    mock.setMockResponse(method, response);
+  });
+
+  return mock.call.bind(mock);
+}
+
+/**
+ * Create mock UTXO data
+ */
+function createMockUTXO(address, amount = 100, assetName = null) {
+  const utxo = {
+    txid: '0000000000000000000000000000000000000000000000000000000000000001',
+    vout: 0,
+    address: address,
+    scriptPubKey: '76a914...',
+    amount: assetName ? undefined : amount,
+    confirmations: 10,
+    spendable: true,
+    solvable: true,
+    safe: true
+  };
+
+  if (assetName) {
+    utxo.assetName = assetName;
+    utxo.assetAmount = amount;
+  }
+
+  return utxo;
+}
+
+/**
+ * Create mock asset data
+ */
+function createMockAssetData(assetName, options = {}) {
+  return {
+    name: assetName,
+    amount: options.amount || 1000000,
+    units: options.units || 0,
+    reissuable: options.reissuable !== undefined ? options.reissuable : true,
+    has_ipfs: options.hasIpfs || false,
+    ipfs_hash: options.ipfsHash || '',
+    block_height: 1000,
+    blockhash: '0000000000000000000000000000000000000000000000000000000000000001'
+  };
+}
+
+module.exports = {
+  RPCMock,
+  createMockRPC,
+  createMockUTXO,
+  createMockAssetData
+};