Replace Sample ABI with Any Contract

This guide shows you how to swap out the Uniswap V3 Factory ABI bundled with the sample Sim IDX app and replace it with the ABI of any contract you would like to index. As an example, we’ll use the USDC contract, but you can follow the same process for any contract. The sample app is what gets created by default when you run sim init without any additional templates. The workflow mirrors the process you will follow in a real project: locate the ABI, register it with the CLI, extend your listener, and validate the new triggers against historical data.

​

1. Remove the Uniswap V3 Factory ABI from the project

Inside the sample repository you will find a file at abis/UniswapV3Factory.json. Because you are replacing this ABI entirely, delete the file (or move it out of abis/). Leaving it in place would cause the CLI to generate bindings for both Factory and USDC, which is not what you want for this walkthrough.

rm abis/UniswapV3Factory.json
# Regenerate bindings
sim abi codegen

Running sim abi codegen removes the now-missing Factory bindings from listeners/lib/sim-idx-generated/.

​

2. Locate the ABI for your target contract

Start by obtaining the ABI for the contract you want to observe. The most common approach is to open the contract page on a blockchain explorer such as Etherscan, Basescan or Polygonscan and click the Contract tab. From there select Contract ABI and copy the full JSON blob to your clipboard.

For the purposes of this guide we’ll trigger on the Ethereum USDC contract.

​

3. Add the new ABI JSON file

Create a fresh file under abis/ and paste the JSON you copied earlier. The filename should match the contract you are tracking, e.g. abis/USDC.json.

touch abis/USDC.json
# then paste the JSON using your editor or:
cat > abis/USDC.json  # Ctrl-D to save

You can just as easily create the file through your editor’s GUI. Both approaches work the same.

​

4. Generate Solidity bindings with sim abi add

Run the command below in the root of your project to register the ABI and generate strongly-typed Solidity bindings. The CLI parses the JSON, creates the corresponding structs, abstract contracts and helper functions, and writes them into listeners/lib/sim-idx-generated/.

sim abi add abis/USDC.json

After the command completes you will see the updated files in listeners/lib/sim-idx-generated/. The generated Solidity bindings expose multiple abstract contracts that fire whenever a specific USDC function is called or event is emitted onchain. You will extend one of these contracts in the next step.

​

5. Update the listener contract to inherit the new functionality

Open listeners/src/Main.sol and update the Listener contract so that it inherits from the abstract contracts generated for your ABI. For example, to react to the Transfer event of USDC the inheritance line might look like this:

contract Listener is USDC$OnTransferEvent {
    event USDCTransfer(
        uint64  chainId,
        address from,
        address to,
        uint256 value
    );

    function onTransferEvent(
        EventContext memory /* ctx */,
        USDC$TransferEventParams memory inputs
    ) external override {
        emit USDCTransfer(
            uint64(block.chainid),
            inputs.from,
            inputs.to,
            inputs.value
        );
    }
}

Add or modify event definitions to capture the onchain data you want persisted and implement each handler function required by the abstract contract. The Sim IDX framework will create the associated database tables automatically on deployment.

​

6. Register triggers for the new contract

In the Triggers contract within the same Main.sol file, replace the existing addTrigger call so that it points to the USDC contract address on Ethereum and references the helper selector exposed by the listener:

addTrigger(
    chainContract(Chains.Ethereum, 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48),
    listener.triggerOnTransferEvent()
);

Want to listen on multiple networks (e.g. Base)? Simply add additional addTrigger calls with the appropriate chain name from the Chains enum (for example, Chains.Base) and contract address. You can find the list of supported chains at sim.dune.com/chains.

​

7. Evaluate the listener against historical blocks

Before deploying, replay historical chain data to confirm that the new triggers activate and that the listener emits the expected events. sim listeners evaluate compiles your listener, fetches onchain transactions for the specified block range and prints a structured summary of events and errors.

sim listeners evaluate \
  --chain-id 1 \
  --start-block <BLOCK_NUMBER> \
  --listeners=Listener
  # --end-block   <BLOCK_NUMBER>   # optional, evaluates a single block if omitted

Replace the placeholders with blocks that are known to interact with USDC. You can usually find them on the same explorer page where you copied the ABI. If the summary shows your custom events in events and errors is empty, the evaluation succeeded.

​

8. Rebuild and update the API endpoint

Next, rebuild the project so that Drizzle schemas are regenerated from the new events:

sim build

sim build places the generated Drizzle schema for your listener under apis/src/db/schema/Listener.ts. The existing apis/src/index.ts still imports poolCreated (an event from the previous Uniswap V3 ABI included in the sample) which no longer exists.

Update apis/src/index.ts so that it queries the new usdcTransfer table generated from your USDCTransfer event:

import { eq } from "drizzle-orm";
import { usdcTransfer } from "./db/schema/Listener"; // adjust path if needed
import { types, db, App } from "@duneanalytics/sim-idx";

const app = App.create();
app.get("/*", async (c) => {
  try {
    const result = await db.client(c).select().from(usdcTransfer).limit(10);

    return Response.json({
      result,
    });
  } catch (e) {
    console.error("Database operation failed:", e);
    return Response.json({ error: (e as Error).message }, { status: 500 });
  }
});

export default app;

After saving, run sim build once again to verify the API is building correctly with the new Drizzle schema.

​

Next steps

With your listener, tests, and API all pointing at USDC data, you’re ready to deploy your updated app to Sim’s managed infrastructure.