ABI Plugin

The ABI plugin provides a dynamic way to interact with any Ethereum-compatible smart contract by generating actions from the contract’s Application Binary Interface (ABI). This plugin automatically creates callable actions for both read and write functions defined in the ABI.

Installation

Install the required packages:
- npm
- pnpm
- yarn
Terminal window
npm i @iqai/plugin-abi
Terminal window
pnpm add @iqai/plugin-abi
Terminal window
yarn add @iqai/plugin-abi
Create a .env file with required configuration:
```
WALLET_PRIVATE_KEY=your-wallet-private-key
```

Basic Setup

Here’s how to set up an agent with the ABI plugin:

import { AgentBuilder, ModelProviderName } from "@iqai/agent";
import { createAbiPlugin } from "@iqai/plugin-abi";
import YourABI from "yourABI";
import { fraxtal } from "viem/chains";

async function main() {
  // Initialize ABI plugin
  const abiPlugin = await createAbiPlugin({
    abi: YourABI,
    contractName: "name-of-contract",
    contractAddress: "address-of-contract",
    description: "description-of-contract",
    privateKey: process.env.WALLET_PRIVATE_KEY,
    chain: fraxtal, // Optional, defaults to Fraxtal chain
  });

  // Create agent with plugin
  const agent = new AgentBuilder()
    .withModelProvider(
      ModelProviderName.OPENAI,
      process.env.OPENAI_API_KEY
    )
    .withPlugin(abiPlugin)
    .build();

  await agent.start();
}

main().catch(console.error);

How It Works

The ABI plugin works by:

Analyzing the provided contract ABI
Extracting function definitions (both read and write)
Generating corresponding actions for each function
Automatically handling parameter parsing and response formatting

Available Operations

The plugin dynamically creates actions based on the ABI functions provided. Each function in the ABI is transformed into an action with the naming pattern CONTRACT_NAME_FUNCTION_NAME.

Example ERC20 Actions

When using the plugin with an ERC20 contract, the following actions would be automatically created:

Action Name	Description	Function Type
`ERC20_BALANCE_OF`	Check token balance	Read function
`ERC20_TRANSFER`	Transfer tokens	Write function
`ERC20_APPROVE`	Approve token spending	Write function
`ERC20_TRANSFER_FROM`	Transfer tokens from another address	Write function
`ERC20_ALLOWANCE`	Check spending allowance	Read function
`ERC20_TOTAL_SUPPLY`	Get total token supply	Read function

Usage Examples

Here’s how to interact with your ABI-enabled agent:

Querying Token Balance

Query:

What's the balance of 0x1234...5678?

The agent will parse this query, identify the address, and call the appropriate contract function (balanceOf).

Response:

✅ Successfully called balanceOf

Result: "1000000000000000000"

Transferring Tokens

Query:

Transfer 10 tokens to 0x1234...5678

The agent will parse this query, extract the amount and recipient address, and execute the transfer function.

Response:

✅ Successfully executed transfer

Transaction hash: 0x123abc...

You can view this transaction on the blockchain explorer.

Configuration Options

The ABI plugin accepts these configuration parameters:

interface AbiPluginOptions {
  abi: any[];                           // Smart contract ABI
  contractName: string;                 // Name for the contract (used in action names)
  contractAddress: `0x${string}`;       // Contract address
  description: string;                  // Description for the plugin
  privateKey: string;                   // Private key for transactions
  chain?: Chain;                        // Optional: blockchain network (defaults to Fraxtal)
}

Error Handling

The plugin handles various error scenarios:

Invalid function arguments

❌ Error parsing arguments: Expected number, got string

Transaction execution failures

❌ Error with transfer: execution reverted: ERC20: transfer amount exceeds balance

Network connection issues

❌ Error with balanceOf: network connection failed

Best Practices

Store private keys securely: Never hardcode private keys in your application code. Always use environment variables.
Use proper error handling: Implement try/catch blocks around plugin initialization and usage.
Test with testnets first: Before using the plugin with mainnet contracts, test thoroughly on testnet networks.
Validate ABIs: Ensure that the ABI you provide is valid and complete.
Handle gas efficiently: For write functions, be aware of gas costs and implement proper error handling for insufficient gas scenarios.

Common Issues and Troubleshooting

Invalid ABI Format: Ensure your ABI is correctly formatted JSON
Contract Address Format: The contract address must be a valid Ethereum address starting with “0x”
Function Not Found: Verify that the function you’re trying to call exists in the ABI
Transaction Failures: Check for sufficient balance and proper permissions