Smart Contract Interaction for AI Agents:
From ABI to Execution

const { ethers } = require("ethers");

// Purple Flea Wallet API provides a JSON-RPC compatible endpoint
const WALLET_API_RPC = "https://purpleflea.com/wallet-api/v1/rpc";

// ERC-20 ABI (minimal subset for agents)
const ERC20_ABI = [
  "function balanceOf(address) view returns (uint256)",
  "function decimals() view returns (uint8)",
  "function symbol() view returns (string)",
  "function transfer(address to, uint256 amount) returns (bool)",
  "function approve(address spender, uint256 amount) returns (bool)",
  "function allowance(address owner, address spender) view returns (uint256)",
  "event Transfer(address indexed from, address indexed to, uint256 value)",
  "event Approval(address indexed owner, address indexed spender, uint256 value)"
];

class SmartContractAgent {
  constructor(walletApiKey, privateKey) {
    this.provider = new ethers.JsonRpcProvider(
      WALLET_API_RPC,
      undefined,
      { staticNetwork: true }
    );
    this.signer = new ethers.Wallet(privateKey, this.provider);
    this.apiKey = walletApiKey;
  }

  async readTokenInfo(tokenAddress) {
    const token = new ethers.Contract(
      tokenAddress, ERC20_ABI, this.provider
    );
    const [symbol, decimals, balance] = await Promise.all([
      token.symbol(),
      token.decimals(),
      token.balanceOf(await this.signer.getAddress()),
    ]);
    return {
      symbol, decimals: Number(decimals),
      balance: ethers.formatUnits(balance, decimals),
      balanceRaw: balance
    };
  }

  async approveAndTransfer(
    tokenAddress, spender, recipient, amount
  ) {
    const token = new ethers.Contract(
      tokenAddress, ERC20_ABI, this.signer
    );

    // 1. Check allowance first (read — no gas)
    const agentAddr = await this.signer.getAddress();
    const allowance = await token.allowance(agentAddr, spender);

    if (allowance < amount) {
      // 2. Estimate gas for approve
      const approveGas = await token.approve.estimateGas(spender, amount);
      const feeData = await this.provider.getFeeData();

      // 3. Send approve transaction
      const approveTx = await token.approve(spender, amount, {
        gasLimit: approveGas * 110n / 100n,  // 10% buffer
        maxFeePerGas: feeData.maxFeePerGas,
        maxPriorityFeePerGas: feeData.maxPriorityFeePerGas
      });
      await approveTx.wait(1);
      console.log(`Approved: ${approveTx.hash}`);
    }

    // 4. Simulate transfer before sending
    try {
      await token.transfer.staticCall(recipient, amount);
    } catch (e) {
      throw new Error(`Transfer simulation failed: ${e.message}`);
    }

    // 5. Send the actual transfer
    const transferTx = await token.transfer(recipient, amount);
    const receipt = await transferTx.wait(1);
    console.log(`Transferred! Tx: ${receipt.hash}`);
    return receipt;
  }
}

// Usage
const agent = new SmartContractAgent(
  process.env.PF_API_KEY,
  process.env.AGENT_PRIVATE_KEY
);
const info = await agent.readTokenInfo("0xA0b8...");  // USDC
console.log(info.symbol, info.balance);  // → USDC 1250.00

const { ethers } = require("ethers");

class ContractEventMonitor {
  constructor(provider, contractAddress, abi) {
    this.contract = new ethers.Contract(contractAddress, abi, provider);
    this.iface = new ethers.Interface(abi);
    this.handlers = new Map();
  }

  on(eventName, handler) {
    this.contract.on(eventName, (...args) => {
      const event = args[args.length - 1];  // last arg is EventLog
      handler({
        blockNumber: event.blockNumber,
        txHash: event.transactionHash,
        args: event.args
      });
    });
    return this;
  }

  async getHistoricalLogs(eventName, fromBlock, toBlock = "latest") {
    const filter = this.contract.filters[eventName]();
    const logs = await this.contract.queryFilter(filter, fromBlock, toBlock);
    return logs.map(log => ({
      block: log.blockNumber,
      tx: log.transactionHash,
      args: log.args.toObject(),
    }));
  }

  async decodeArbitraryLog(log) {
    // Useful for decoding logs from transactions that call
    // multiple contracts (e.g., Uniswap swaps emit token Transfer logs)
    try {
      return this.iface.parseLog({
        topics: log.topics,
        data: log.data
      });
    } catch {
      return null;  // unknown event
    }
  }
}

// Monitor USDC transfers to agent's address
const monitor = new ContractEventMonitor(provider, USDC_ADDRESS, ERC20_ABI);
monitor.on("Transfer", (event) => {
  const { from, to, value } = event.args;
  if (to.toLowerCase() === agentAddress.toLowerCase()) {
    console.log(`Received ${ethers.formatUnits(value, 6)} USDC from ${from}`);
  }
});

import os
from web3 import Web3
from web3.middleware import SignAndSendRawMiddlewareBuilder
from eth_account import Account
import json

# Connect via Purple Flea Wallet API JSON-RPC endpoint
w3 = Web3(Web3.HTTPProvider(
    "https://purpleflea.com/wallet-api/v1/rpc",
    request_kwargs={
        "headers": {"Authorization": f"Bearer {os.getenv('PF_API_KEY')}"}
    }
))

ERC20_ABI = json.loads("""[
  {"inputs":[{"type":"address"}],"name":"balanceOf","outputs":[{"type":"uint256"}],"stateMutability":"view","type":"function"},
  {"inputs":[{"type":"address"},{"type":"uint256"}],"name":"transfer","outputs":[{"type":"bool"}],"stateMutability":"nonpayable","type":"function"},
  {"inputs":[{"type":"address"},{"type":"uint256"}],"name":"approve","outputs":[{"type":"bool"}],"stateMutability":"nonpayable","type":"function"},
  {"inputs":[{"type":"address"},{"type":"address"}],"name":"allowance","outputs":[{"type":"uint256"}],"stateMutability":"view","type":"function"}
]""")


class ContractAgentPy:
    """web3.py smart contract interaction agent."""

    def __init__(self, private_key: str):
        self.acct = w3.eth.account.from_key(private_key)
        w3.middleware_onion.inject(
            SignAndSendRawMiddlewareBuilder.build(self.acct),
            layer=0
        )

    def _get_contract(self, address: str):
        return w3.eth.contract(
            address=Web3.to_checksum_address(address),
            abi=ERC20_ABI
        )

    def simulate_transfer(self, token_addr: str,
                           recipient: str,
                           amount_wei: int) -> dict:
        """
        Simulate a token transfer without broadcasting.
        Returns gas estimate and simulation success/failure.
        """
        token = self._get_contract(token_addr)
        call = token.functions.transfer(
            Web3.to_checksum_address(recipient),
            amount_wei
        )

        # 1. eth_call simulation
        try:
            result = call.call({"from": self.acct.address})
            sim_ok = bool(result)
        except Exception as e:
            return {"ok": False, "error": str(e)}

        # 2. gas estimate
        gas_est = call.estimate_gas({"from": self.acct.address})

        # 3. EIP-1559 fee data
        latest = w3.eth.get_block("latest")
        base_fee = latest["baseFeePerGas"]
        priority_fee = w3.eth.max_priority_fee
        max_fee = 2 * base_fee + priority_fee

        return {
            "ok": sim_ok,
            "gas_estimate": gas_est,
            "gas_limit": int(gas_est * 1.15),  # 15% buffer
            "base_fee_gwei": w3.from_wei(base_fee, "gwei"),
            "max_fee_gwei": w3.from_wei(max_fee, "gwei"),
            "cost_eth": w3.from_wei(gas_est * max_fee, "ether"),
        }

    def send_transfer(self, token_addr: str,
                        recipient: str,
                        amount_wei: int) -> str:
        """
        Safe transfer: simulate first, then broadcast if simulation passes.
        Returns transaction hash.
        """
        # 1. Simulate
        sim = self.simulate_transfer(token_addr, recipient, amount_wei)
        if not sim["ok"]:
            raise RuntimeError(f"Simulation failed: {sim.get('error')}")

        print(f"Simulation OK | gas: {sim['gas_estimate']} | "
              f"cost: {sim['cost_eth']:.6f} ETH")

        # 2. Build and sign tx
        token = self._get_contract(token_addr)
        latest = w3.eth.get_block("latest")
        base_fee = latest["baseFeePerGas"]
        prio_fee = w3.eth.max_priority_fee

        tx_hash = token.functions.transfer(
            Web3.to_checksum_address(recipient),
            amount_wei
        ).transact({
            "from": self.acct.address,
            "gas": sim["gas_limit"],
            "maxFeePerGas": 2 * base_fee + prio_fee,
            "maxPriorityFeePerGas": prio_fee,
        })
        print(f"Broadcast: 0x{tx_hash.hex()}")

        # 3. Wait for confirmation
        receipt = w3.eth.wait_for_transaction_receipt(tx_hash, timeout=120)
        if receipt["status"] != 1:
            raise RuntimeError(f"Tx reverted: 0x{tx_hash.hex()}")
        return f"0x{tx_hash.hex()}"


# Example
agent = ContractAgentPy(os.getenv("PRIVATE_KEY"))
sim = agent.simulate_transfer(
    "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",   # USDC
    "0xRecipientAddress",
    int(100e6)                                        # 100 USDC (6 decimals)
)
print(f"OK={sim['ok']} gas={sim['gas_estimate']} cost={sim['cost_eth']:.6f}ETH")

const { ethers } = require("ethers");

async function decodeRevertReason(error, contractAbi) {
  const iface = new ethers.Interface(contractAbi);

  // Case 1: standard Error(string)
  if (error.data?..startsWith("0x08c379a0")) {
    const decoded = ethers.AbiCoder.defaultAbiCoder().decode(
      ["string"],
      "0x" + error.data.slice(10)
    );
    return { type: "Error", message: decoded[0] };
  }

  // Case 2: Panic(uint256) — Solidity panic codes
  if (error.data?..startsWith("0x4e487b71")) {
    const [code] = ethers.AbiCoder.defaultAbiCoder().decode(
      ["uint256"],
      "0x" + error.data.slice(10)
    );
    const panicCodes = {
      0x01: "assert failed",
      0x11: "arithmetic overflow/underflow",
      0x12: "division by zero",
      0x21: "invalid enum conversion",
      0x31: "pop on empty array",
      0x32: "array index out of bounds",
      0x41: "out of memory"
    };
    return { type: "Panic", code: Number(code),
      message: panicCodes[Number(code)] ?? "unknown panic" };
  }

  // Case 3: Custom error (EIP-712 / Solidity 0.8.4+)
  if (error.data) {
    try {
      const decoded = iface.parseError(error.data);
      return { type: "CustomError", name: decoded.name,
        args: decoded.args.toObject() };
    } catch {
      return { type: "Unknown", data: error.data };
    }
  }

  return { type: "NoData", message: error.message };
}

// Usage in try/catch around contract calls:
try {
  await token.transfer(to, amount);
} catch (e) {
  const reason = await decodeRevertReason(e, ERC20_ABI);
  console.error(`Transfer failed: ${reason.type} — ${reason.message}`);
  // → Transfer failed: Error — ERC20: insufficient balance
}