@lit-protocol/fss-tool-erc20-send

A Lit AI Agent tool for sending ERC20 tokens. This package serves as both an example implementation and a production-ready tool for token transfers.

Features

• ERC20 token transfers across multiple networks
• Configurable policy-based transfer limits
• Token and recipient allowlist support
• Automatic gas estimation and optimization
• Multi-chain support with network presets
• Detailed transaction logging
• Error handling with descriptive messages

Installation

pnpm add @lit-protocol/fss-tool-erc20-send

Supported Networks

Out of the box, the tool supports:

• Base Sepolia (testnet)
• Base Mainnet
• Ethereum Mainnet
• Ethereum Goerli (testnet)
• Polygon
• Optimism

Custom networks can be added through configuration.

Usage

Basic Token Transfer

import { LitAgent } from '@lit-protocol/fss';

const agent = new LitAgent(authKey, openAiKey);
await agent.init();

// Execute token transfer
const result = await agent.executeTool(
  'ipfs://Qm...', // ERC20 Send tool CID
  {
    tokenIn: '0x...', // Token contract address
    recipientAddress: '0x...', // Recipient wallet address
    amountIn: '1.0', // Amount in token decimals
    rpcUrl: 'https://base-sepolia-rpc.publicnode.com',
    chainId: 84532 // Base Sepolia
  }
);

console.log('Transfer hash:', result.response.transferHash);

Advanced Usage

With Gas Price Configuration

const result = await agent.executeTool(
  'ipfs://Qm...',
  {
    ...params,
    gasConfig: {
      maxFeePerGas: '50000000000', // 50 gwei
      maxPriorityFeePerGas: '1500000000' // 1.5 gwei
    }
  }
);

With Custom RPC Configuration

const result = await agent.executeTool(
  'ipfs://Qm...',
  {
    ...params,
    rpcConfig: {
      timeout: 30000, // 30 seconds
      retries: 3
    }
  }
);

Policy Configuration

The tool supports flexible policy configuration to ensure secure token transfers:

const policy = {
  type: 'SendERC20',
  version: '1.0.0',
  // Maximum amount per transfer in token base units (e.g., wei)
  maxAmount: '1000000000000000000', // 1 token
  // List of allowed token contract addresses
  allowedTokens: [
    '0x4070c8325e278ca1056e602e08d16d2D5cd79b27', // DevERC20
    '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'  // USDC
  ],
  // List of allowed recipient addresses
  allowedRecipients: [
    '0x600DC16993EA1AbdA674A20d432F93041cDa2ef4',
    '0x...'
  ],
  // Optional network restrictions
  allowedNetworks: [
    84532, // Base Sepolia
    8453   // Base Mainnet
  ]
};

// Apply policy through agent
const result = await agent.executeTool(
  'ipfs://Qm...',
  params,
  {
    policyCallback: async () => ({
      usePolicy: true,
      policyValues: policy
    })
  }
);

Error Handling

The tool provides detailed error messages for common scenarios:

try {
  const result = await agent.executeTool('ipfs://Qm...', params);
} catch (error) {
  if (error.code === 'INSUFFICIENT_BALANCE') {
    console.error('Token balance too low:', error.message);
  } else if (error.code === 'POLICY_VIOLATION') {
    console.error('Transfer violates policy:', error.message);
  } else if (error.code === 'GAS_ESTIMATION_FAILED') {
    console.error('Gas estimation failed:', error.message);
  } else {
    console.error('Unexpected error:', error);
  }
}

Tool Implementation Details

The tool is implemented as a Lit Action that follows this execution flow:

1. Parameter validation and normalization
2. Policy constraint verification
3. Token contract interaction setup
4. Balance and allowance checks
5. Gas estimation and optimization
6. Transaction construction and signing
7. Broadcasting and confirmation

Required Parameters

| Parameter | Type | Description | | ------------------ | -------- | ------------------------------------ | | tokenIn | string | ERC20 token contract address | | recipientAddress | string | Recipient wallet address | | amountIn | string | Amount to transfer in token decimals | | rpcUrl | string | RPC endpoint for the target chain | | chainId | number | Target chain ID |

Optional Parameters

| Parameter | Type | Description | | --------------------- | --------- | -------------------------------------------- | | gasConfig | object | Custom gas price settings | | rpcConfig | object | RPC client configuration | | waitForConfirmation | boolean | Whether to wait for transaction confirmation |

Development

Building

# Build the package
pnpm build

# Run tests
pnpm test

# Generate documentation
pnpm docs

Testing

The package includes comprehensive tests:

# Run all tests
pnpm test

# Run specific test suite
pnpm test:unit
pnpm test:integration

# Run with coverage
pnpm test:coverage

Contributing

Please see our Contributing Guide for details on how to contribute to this package.

License

MIT