Neo N3 DApp Integration Guide

This guide provides comprehensive information about integrating with Neo N3 DApps through the Neo N3 MCP Server. The server supports several popular Neo N3 DApps, allowing AI assistants to interact with these applications through a standardized interface.

Contract Availability

Not all contracts are available on both mainnet and testnet. The table below shows the availability of each contract:

NeoFS

const result = await client.callTool('neofs_create_container', {
  walletPath: '/path/to/wallet.json',
  walletPassword: 'password',
  ownerId: 'your-owner-id',
  rules: [
    { key: 'Placement', value: 'REP 3 IN X CBF 1 SELECT 1 FROM * AS X' },
    { key: 'StoragePolicy', value: 'REP 3' }
  ],
  network: 'mainnet'
});

console.log('Container created:', result);

const result = await client.callTool('neofs_get_containers', {
  ownerId: 'your-owner-id',
  network: 'mainnet'
});

console.log('Containers:', result.containers);

NeoBurger

const result = await client.callTool('neoburger_deposit', {
  walletPath: '/path/to/wallet.json',
  walletPassword: 'password',
  network: 'mainnet'
});

console.log('Deposit transaction:', result.txid);

const result = await client.callTool('neoburger_get_balance', {
  address: 'NXV7ZhHaLY2GNjp6R1AYBV9FqrVnGLfQcz',
  network: 'mainnet'
});

console.log('NeoBurger balance:', result.amount);

Flamingo

const result = await client.callTool('flamingo_stake', {
  walletPath: '/path/to/wallet.json',
  walletPassword: 'password',
  amount: '100',
  network: 'mainnet'
});

console.log('Stake transaction:', result.txid);

const result = await client.callTool('flamingo_get_staked_amount', {
  address: 'NXV7ZhHaLY2GNjp6R1AYBV9FqrVnGLfQcz',
  network: 'mainnet'
});

console.log('Staked amount:', result.amount);

Best Practices

Follow these best practices when integrating with Neo N3 DApps:

1. Check Contract Availability

   Always check if a contract is available on your target network before attempting to interact with it:

   const contracts = await client.callTool('list_famous_contracts', {
     network: 'mainnet'
   });
   
   const isAvailable = contracts.contracts.some(
     c => c.name.toLowerCase() === 'neoburger' && c.available
   );

2. Handle Rate Limits

   The service implements rate limiting to prevent abuse. Handle potential rate limit errors in your application:

   try {
     const result = await client.callTool('neoburger_deposit', {
       // parameters
     });
   } catch (error) {
     if (error.message.includes('Rate limit exceeded')) {
       // Handle rate limit error
       console.error('Rate limit exceeded. Please try again later.');
     } else {
       // Handle other errors
       console.error('Operation failed:', error.message);
     }
   }

3. Validate Inputs Client-Side

   While the service performs server-side validation, implementing client-side validation can improve user experience by catching errors earlier:

   function validateAddress(address) {
     // Neo N3 addresses are 34 characters long and start with 'N'
     return typeof address === 'string' &&
            address.length === 34 &&
            address.startsWith('N');
   }

4. Monitor Transaction Status

   After invoking a write operation, monitor the transaction status to confirm it was successfully processed on the blockchain:

   const result = await client.callTool('neoburger_deposit', {
     // parameters
   });
   
   // Get the transaction ID
   const txid = result.txid;
   
   // Monitor transaction status
   const txStatus = await client.callTool('get_transaction', {
     txid: txid,
     network: 'mainnet'
   });

5. Use Testnet First

   When developing new integrations, test on the testnet first before moving to mainnet (for contracts that are available on testnet).

Error Handling

The Neo N3 MCP Server uses specific error types to provide clear information about failures:

Example Error Handling

try {
  const result = await client.callTool('neoburger_deposit', {
    walletPath: '/path/to/wallet.json',
    walletPassword: 'password',
    network: 'mainnet'
  });
  console.log('Deposit successful:', result);
} catch (error) {
  if (error.message.includes('Contract not available')) {
    console.error('NeoBurger contract is not available on this network');
  } else if (error.message.includes('Rate limit')) {
    console.error('Rate limit exceeded. Please try again later.');
  } else if (error.message.includes('Invalid address')) {
    console.error('Invalid address format');
  } else if (error.message.includes('Failed to connect')) {
    console.error('Network connection issue. Please check your internet connection.');
  } else {
    console.error('Operation failed:', error.message);
  }
}