@neuraiproject/neurai-assets 1.0.0

package/examples/06-create-restricted-asset.js

@@ -0,0 +1,223 @@
+/**
+ * Example: Create RESTRICTED Assets (Security Tokens)
+ *
+ * This example demonstrates how to create RESTRICTED assets.
+ * RESTRICTED assets are security tokens with built-in compliance controls.
+ *
+ * Format: $NAME (e.g., $SECURITY, $STOCK)
+ *
+ * Features:
+ * - Only addresses meeting verifier requirements can receive/hold
+ * - Can freeze individual addresses or entire asset
+ * - Uses QUALIFIER tags for compliance (e.g., #KYC_VERIFIED)
+ *
+ * Cost: 3000 XNA (most expensive asset type)
+ */
+
+const NeuraiAssets = require('@neuraiproject/neurai-assets');
+
+async function createRestrictedAsset() {
+  // Mock RPC function (replace with your actual RPC client)
+  const rpc = async (method, params) => {
+    console.log(`RPC Call: ${method}`, params);
+    // Your RPC implementation here
+  };
+
+  // Initialize NeuraiAssets
+  const assets = new NeuraiAssets(rpc, {
+    network: 'xna',
+    addresses: ['NYourAddress1...'],
+    changeAddress: 'NChangeAddress...',
+    toAddress: 'NReceivingAddress...'
+  });
+
+  try {
+    // Step 1: Ensure qualifiers exist
+    console.log('=== Step 1: Verify Qualifiers Exist ===\n');
+
+    // You need to create qualifiers first (see example 05)
+    const requiredQualifiers = ['#KYC_VERIFIED', '#ACCREDITED'];
+
+    for (const qualifier of requiredQualifiers) {
+      const exists = await assets.assetExists(qualifier);
+      if (!exists) {
+        console.warn(`⚠ Qualifier ${qualifier} does not exist. Create it first!`);
+        // You would need to create it using createQualifier()
+      } else {
+        console.log(`✓ Qualifier ${qualifier} exists`);
+      }
+    }
+
+    // Step 2: Create the RESTRICTED asset with verifier string
+    console.log('\n=== Step 2: Create RESTRICTED Asset ===\n');
+
+    const result = await assets.createRestrictedAsset({
+      assetName: '$SECURITY',                              // Must start with $
+      quantity: 1000000,                                   // Total supply
+      units: 2,                                            // Decimals (0-8)
+      verifierString: '#KYC_VERIFIED & #ACCREDITED',      // Boolean logic
+      reissuable: true,                                    // Allow reissuance
+      hasIpfs: true,
+      ipfsHash: 'QmSecurityTokenMetadata...'
+    });
+
+    console.log('RESTRICTED Asset created successfully!');
+    console.log('Asset Name:', '$SECURITY');
+    console.log('Owner Token:', '$SECURITY!');
+    console.log('Verifier String:', result.metadata.verifierString);
+    console.log('Required Qualifiers:', result.metadata.requiredQualifiers);
+    console.log('Burn:', result.burn, 'XNA');
+
+    console.log('\n=== Verifier String Explained ===');
+    console.log('Verifier: #KYC_VERIFIED & #ACCREDITED');
+    console.log('Meaning: Address must have BOTH tags to receive this asset');
+    console.log('- #KYC_VERIFIED (required)');
+    console.log('- #ACCREDITED (required)');
+
+    console.log('\nNext steps:');
+    console.log('1. Tag addresses with required qualifiers');
+    console.log('2. Only tagged addresses can receive $SECURITY');
+    console.log('3. Use owner token ($SECURITY!) to manage the asset');
+
+  } catch (error) {
+    console.error('Error creating RESTRICTED asset:', error.message);
+
+    if (error.name === 'InvalidVerifierStringError') {
+      console.error('Invalid verifier string syntax');
+    }
+  }
+}
+
+// Example: Create RESTRICTED asset with complex verifier logic
+async function createRestrictedWithComplexVerifier() {
+  const rpc = async (method, params) => {
+    console.log(`RPC Call: ${method}`, params);
+  };
+
+  const assets = new NeuraiAssets(rpc, {
+    network: 'xna',
+    addresses: ['NYourAddress1...'],
+    changeAddress: 'NChangeAddress...',
+    toAddress: 'NReceivingAddress...'
+  });
+
+  try {
+    // Create RESTRICTED asset with OR logic
+    const result = await assets.createRestrictedAsset({
+      assetName: '$FLEXIBLE_TOKEN',
+      quantity: 500000,
+      units: 0,
+      // Complex verifier: (KYC AND Accredited) OR Institutional
+      verifierString: '(#KYC_VERIFIED & #ACCREDITED) | #INSTITUTIONAL',
+      reissuable: true,
+      hasIpfs: false,
+      ipfsHash: ''
+    });
+
+    console.log('RESTRICTED Asset with complex verifier created!');
+    console.log('Asset:', '$FLEXIBLE_TOKEN');
+    console.log('Verifier:', result.metadata.verifierString);
+
+    console.log('\n=== Verifier Logic ===');
+    console.log('Option 1: Address has #KYC_VERIFIED AND #ACCREDITED');
+    console.log('Option 2: Address has #INSTITUTIONAL');
+    console.log('Result: Address can receive if either option is true');
+
+  } catch (error) {
+    console.error('Error:', error.message);
+  }
+}
+
+// Example: Validate verifier string before creating asset
+async function validateVerifierString() {
+  const rpc = async (method, params) => {
+    console.log(`RPC Call: ${method}`, params);
+  };
+
+  const assets = new NeuraiAssets(rpc, {
+    network: 'xna',
+    addresses: ['NYourAddress1...'],
+    changeAddress: 'NChangeAddress...',
+    toAddress: 'NReceivingAddress...'
+  });
+
+  try {
+    // Test different verifier strings
+    const verifiers = [
+      '#KYC_VERIFIED',                                    // Simple
+      '#KYC_VERIFIED & #ACCREDITED',                      // AND
+      '#KYC_VERIFIED | #INSTITUTIONAL',                   // OR
+      '(#KYC_VERIFIED & #ACCREDITED) | #INSTITUTIONAL',  // Complex
+      '#KYC & (#ACCREDITED | #INSTITUTIONAL)',            // Nested
+      'INVALID STRING',                                   // Invalid
+    ];
+
+    console.log('=== Verifier String Validation ===\n');
+
+    for (const verifier of verifiers) {
+      const isValid = await assets.isValidVerifierString(verifier);
+      console.log(`${isValid ? '✓' : '✗'} "${verifier}"`);
+    }
+
+  } catch (error) {
+    console.error('Error:', error.message);
+  }
+}
+
+// Example: Check if address can receive restricted asset
+async function checkAddressCompliance() {
+  const rpc = async (method, params) => {
+    console.log(`RPC Call: ${method}`, params);
+  };
+
+  const assets = new NeuraiAssets(rpc, {
+    network: 'xna',
+    addresses: ['NYourAddress1...'],
+    changeAddress: 'NChangeAddress...',
+    toAddress: 'NReceivingAddress...'
+  });
+
+  try {
+    const testAddress = 'NTestAddress...';
+    const restrictedAsset = '$SECURITY';
+
+    console.log('=== Compliance Check ===\n');
+    console.log(`Address: ${testAddress}`);
+    console.log(`Asset: ${restrictedAsset}`);
+
+    // Check if address meets verifier requirements
+    const canReceive = await assets.checkAddressRestriction(
+      testAddress,
+      restrictedAsset
+    );
+
+    console.log(`\nCan receive asset: ${canReceive ? 'YES ✓' : 'NO ✗'}`);
+
+    if (!canReceive) {
+      // Check what tags the address has
+      const tags = await assets.listTagsForAddress(testAddress);
+      console.log('\nCurrent tags:', tags.length > 0 ? tags : 'None');
+
+      // Get verifier requirements
+      const verifier = await assets.getVerifierString(restrictedAsset);
+      console.log('Required verifier:', verifier);
+      console.log('\nThe address needs to be tagged with required qualifiers');
+    }
+
+  } catch (error) {
+    console.error('Error:', error.message);
+  }
+}
+
+// Run the examples
+console.log('=== Example 1: Create Simple RESTRICTED Asset ===\n');
+createRestrictedAsset();
+
+console.log('\n\n=== Example 2: Create with Complex Verifier ===\n');
+createRestrictedWithComplexVerifier();
+
+console.log('\n\n=== Example 3: Validate Verifier Strings ===\n');
+validateVerifierString();
+
+console.log('\n\n=== Example 4: Check Address Compliance ===\n');
+checkAddressCompliance();

package/examples/07-freeze-and-unfreeze.js

@@ -0,0 +1,292 @@
+/**
+ * Example: Freeze and Unfreeze Operations
+ *
+ * This example demonstrates how to freeze/unfreeze addresses and assets.
+ * Freezing is only available for RESTRICTED assets.
+ *
+ * Requirements:
+ * - Must own the restricted asset's owner token ($ASSET!)
+ *
+ * Operations:
+ * - Freeze specific addresses (prevent trading)
+ * - Unfreeze specific addresses (allow trading again)
+ * - Global freeze (freeze entire asset)
+ * - Global unfreeze (unfreeze entire asset)
+ *
+ * Cost: No burn (only network fee)
+ */
+
+const NeuraiAssets = require('@neuraiproject/neurai-assets');
+
+async function freezeAddresses() {
+  // Mock RPC function (replace with your actual RPC client)
+  const rpc = async (method, params) => {
+    console.log(`RPC Call: ${method}`, params);
+    // Your RPC implementation here
+  };
+
+  // Initialize NeuraiAssets
+  const assets = new NeuraiAssets(rpc, {
+    network: 'xna',
+    addresses: ['NYourAddress1...'],
+    changeAddress: 'NChangeAddress...',
+    toAddress: 'NReceivingAddress...'
+  });
+
+  try {
+    const restrictedAsset = '$SECURITY';
+    const ownerToken = `${restrictedAsset}!`;
+
+    // Step 1: Verify you own the owner token
+    console.log('=== Step 1: Verify Owner Token ===\n');
+
+    const myAssets = await assets.listMyAssets(ownerToken);
+    if (!myAssets[ownerToken]) {
+      throw new Error(`You must own ${ownerToken} to freeze/unfreeze`);
+    }
+
+    console.log(`✓ Owner token found: ${ownerToken}`);
+
+    // Step 2: Freeze specific addresses
+    console.log('\n=== Step 2: Freeze Addresses ===\n');
+
+    const addressesToFreeze = [
+      'NAddressToFreeze1...',
+      'NAddressToFreeze2...',
+      'NAddressToFreeze3...'
+    ];
+
+    const freezeResult = await assets.freezeAddresses({
+      assetName: restrictedAsset,
+      addresses: addressesToFreeze
+    });
+
+    console.log('Addresses frozen successfully!');
+    console.log('Asset:', freezeResult.metadata.assetName);
+    console.log('Addresses frozen:', freezeResult.metadata.addressCount);
+    console.log('Fee:', freezeResult.fee, 'XNA');
+    console.log('Burn:', freezeResult.burn, 'XNA (no burn for freeze operations)');
+
+    console.log('\nFrozen addresses:');
+    freezeResult.metadata.targetAddresses.forEach((addr, i) => {
+      console.log(`${i + 1}. ${addr}`);
+    });
+
+    console.log('\nEffect: These addresses can NO LONGER:');
+    console.log('- Send the restricted asset');
+    console.log('- Receive the restricted asset');
+    console.log('- Trade the restricted asset');
+
+    // Step 3: Check if address is frozen
+    console.log('\n=== Step 3: Verify Freeze Status ===\n');
+
+    for (const address of addressesToFreeze) {
+      const isFrozen = await assets.isAddressFrozen(address, restrictedAsset);
+      console.log(`${address}: ${isFrozen ? 'FROZEN ❄️' : 'ACTIVE ✓'}`);
+    }
+
+  } catch (error) {
+    console.error('Error freezing addresses:', error.message);
+
+    if (error.name === 'OwnerTokenNotFoundError') {
+      console.error('You need the owner token to freeze addresses');
+    }
+  }
+}
+
+// Example: Unfreeze addresses
+async function unfreezeAddresses() {
+  const rpc = async (method, params) => {
+    console.log(`RPC Call: ${method}`, params);
+  };
+
+  const assets = new NeuraiAssets(rpc, {
+    network: 'xna',
+    addresses: ['NYourAddress1...'],
+    changeAddress: 'NChangeAddress...',
+    toAddress: 'NReceivingAddress...'
+  });
+
+  try {
+    const restrictedAsset = '$SECURITY';
+    const addressesToUnfreeze = [
+      'NAddressToUnfreeze1...',
+      'NAddressToUnfreeze2...'
+    ];
+
+    console.log('=== Unfreezing Addresses ===\n');
+
+    const result = await assets.unfreezeAddresses({
+      assetName: restrictedAsset,
+      addresses: addressesToUnfreeze
+    });
+
+    console.log('Addresses unfrozen successfully!');
+    console.log('Addresses unfrozen:', result.metadata.addressCount);
+    console.log('Fee:', result.fee, 'XNA');
+
+    console.log('\nThese addresses can now:');
+    console.log('- Send the restricted asset');
+    console.log('- Receive the restricted asset');
+    console.log('- Trade the restricted asset');
+    console.log('(if they still meet verifier requirements)');
+
+  } catch (error) {
+    console.error('Error unfreezing addresses:', error.message);
+  }
+}
+
+// Example: Global freeze (freeze entire asset)
+async function freezeAssetGlobally() {
+  const rpc = async (method, params) => {
+    console.log(`RPC Call: ${method}`, params);
+  };
+
+  const assets = new NeuraiAssets(rpc, {
+    network: 'xna',
+    addresses: ['NYourAddress1...'],
+    changeAddress: 'NChangeAddress...',
+    toAddress: 'NReceivingAddress...'
+  });
+
+  try {
+    const restrictedAsset = '$SECURITY';
+
+    console.log('=== Global Asset Freeze ===\n');
+    console.log('⚠️  WARNING: This will freeze the ENTIRE asset!');
+    console.log('ALL addresses will be unable to trade this asset.\n');
+
+    const result = await assets.freezeAssetGlobally({
+      assetName: restrictedAsset
+    });
+
+    console.log('Asset frozen globally!');
+    console.log('Asset:', result.metadata.assetName);
+    console.log('Operation:', result.metadata.operationType);
+    console.log('Fee:', result.fee, 'XNA');
+
+    console.log('\nEffect:');
+    console.log('- ALL addresses are frozen for this asset');
+    console.log('- Nobody can send/receive/trade');
+    console.log('- Use for emergency situations or regulatory compliance');
+
+    // Verify global freeze status
+    const isGloballyFrozen = await assets.checkGlobalRestriction(restrictedAsset);
+    console.log(`\nGlobal freeze status: ${isGloballyFrozen ? 'FROZEN ❄️' : 'ACTIVE ✓'}`);
+
+  } catch (error) {
+    console.error('Error freezing asset globally:', error.message);
+  }
+}
+
+// Example: Global unfreeze (unfreeze entire asset)
+async function unfreezeAssetGlobally() {
+  const rpc = async (method, params) => {
+    console.log(`RPC Call: ${method}`, params);
+  };
+
+  const assets = new NeuraiAssets(rpc, {
+    network: 'xna',
+    addresses: ['NYourAddress1...'],
+    changeAddress: 'NChangeAddress...',
+    toAddress: 'NReceivingAddress...'
+  });
+
+  try {
+    const restrictedAsset = '$SECURITY';
+
+    console.log('=== Global Asset Unfreeze ===\n');
+
+    const result = await assets.unfreezeAssetGlobally({
+      assetName: restrictedAsset
+    });
+
+    console.log('Asset unfrozen globally!');
+    console.log('Asset:', result.metadata.assetName);
+    console.log('Fee:', result.fee, 'XNA');
+
+    console.log('\nEffect:');
+    console.log('- Global freeze lifted');
+    console.log('- Trading resumes for all addresses');
+    console.log('- Individual freezes (if any) remain in effect');
+    console.log('- Verifier requirements still apply');
+
+  } catch (error) {
+    console.error('Error unfreezing asset globally:', error.message);
+  }
+}
+
+// Example: Complete freeze workflow
+async function completeWorkflow() {
+  const rpc = async (method, params) => {
+    console.log(`RPC Call: ${method}`, params);
+  };
+
+  const assets = new NeuraiAssets(rpc, {
+    network: 'xna',
+    addresses: ['NYourAddress1...'],
+    changeAddress: 'NChangeAddress...',
+    toAddress: 'NReceivingAddress...'
+  });
+
+  try {
+    const restrictedAsset = '$SECURITY';
+    const suspiciousAddress = 'NSuspiciousAddress...';
+
+    console.log('=== Complete Freeze/Unfreeze Workflow ===\n');
+
+    // Scenario: Detect suspicious activity
+    console.log('Scenario: Suspicious activity detected on address');
+    console.log(`Address: ${suspiciousAddress}\n`);
+
+    // Step 1: Freeze the suspicious address
+    console.log('Step 1: Freeze suspicious address');
+    await assets.freezeAddresses({
+      assetName: restrictedAsset,
+      addresses: [suspiciousAddress]
+    });
+    console.log('✓ Address frozen\n');
+
+    // Step 2: Verify freeze status
+    console.log('Step 2: Verify freeze status');
+    const isFrozen = await assets.isAddressFrozen(suspiciousAddress, restrictedAsset);
+    console.log(`Status: ${isFrozen ? 'FROZEN ❄️' : 'ACTIVE ✓'}\n`);
+
+    // Step 3: Investigate...
+    console.log('Step 3: Investigation period...\n');
+
+    // Step 4: If cleared, unfreeze
+    console.log('Step 4: Investigation complete - address cleared');
+    await assets.unfreezeAddresses({
+      assetName: restrictedAsset,
+      addresses: [suspiciousAddress]
+    });
+    console.log('✓ Address unfrozen\n');
+
+    // Step 5: Verify unfreeze
+    console.log('Step 5: Verify final status');
+    const isFrozenAfter = await assets.isAddressFrozen(suspiciousAddress, restrictedAsset);
+    console.log(`Status: ${isFrozenAfter ? 'FROZEN ❄️' : 'ACTIVE ✓'}\n`);
+
+    console.log('Workflow completed successfully!');
+
+  } catch (error) {
+    console.error('Error in workflow:', error.message);
+  }
+}
+
+// Run the examples
+console.log('=== Example 1: Freeze Specific Addresses ===\n');
+freezeAddresses();
+
+console.log('\n\n=== Example 2: Unfreeze Addresses ===\n');
+unfreezeAddresses();
+
+console.log('\n\n=== Example 3: Global Freeze ===\n');
+freezeAssetGlobally();
+
+console.log('\n\n=== Example 4: Global Unfreeze ===\n');
+unfreezeAssetGlobally();
+
+console.log('\n\n=== Example 5: Complete Workflow ===\n');
+completeWorkflow();