ABI Integration

Matador's type system is extensible through standard Ethereum ABI (Application Binary Interface) files. Importing an ABI allows the compiler to validate function calls, decoding paths, and parameter types at compile time.

Importing ABIs

Use the import keyword to load a JSON ABI file and assign it an alias. This alias becomes a namespace for accessing the contract's functions and events.

import "abis/UniswapRouter.json" as Uniswap;
import "abis/ERC20.json" as Token;

Path Resolution

The compiler supports flexible path resolution strategies to suit different project structures.

// Policy is in /policies/swap.matador
// ABI is in /policies/abis/Router.json
import "./abis/Router.json" as Router;

import "/usr/local/project/abis/Router.json" as Router;

// Run compiler from project root
import "src/abis/Router.json" as Router;

Capabilities

Importing an ABI unlocks three powerful capabilities in your policies.

// Checks if the transaction is a call to 'transfer'
// AND if the recipient matches the parameter
if (context.selector == Token.transfer) {
  return Token.transfer.to == parameters.allowedRecipient;
}

import "abis/ERC721.json" as NFT;

permission BalanceGate -> 1.0.0 {
  parameters: {
    collection: NFT
  }

  let minBalance = 10;

  fn main() -> bool {
    let ownerBalance = parameters.collection.balanceOf(context.account);
    return ownerBalance > minBalance;
  }

  pub fn balanceOf(account: address) -> uint256 {
    return parameters.collection.balanceOf(account);
  }
}

parameters: {
    // 'router' must be an address that adheres to the Uniswap ABI
    router: Uniswap
}

Static ABI Field Access

Matador supports reading fixed-width fields from ABI calldata when the field can be resolved to one 32-byte ABI word and the source code is visibly guarded by the same function selector.

For example, given a function exactInputSingle that takes a ExactInputSingleParams struct:

struct ExactInputSingleParams {
    address tokenIn;
    address tokenOut;
    uint24 fee;
    address recipient;
    uint256 deadline;
    uint256 amountIn;
    uint256 amountOutMinimum;
    uint160 sqrtPriceLimitX96;
}

You can write a policy that enforces rules on specific fields of that struct:

fn main() -> bool {
    if (context.target != parameters.router) {
        return false;
    }

    if (context.selector == Uniswap.exactInputSingle) {
        // Enforce the recipient is the approved wallet
        if (Uniswap.exactInputSingle.params.recipient != parameters.recipient) {
            return false;
        }

        // Enforce the quoted minimum output amount is at least the policy floor
        return Uniswap.exactInputSingle.params.amountOutMinimum >= parameters.minOut;
    }

    return false;
}

Multi-output view functions are supported when you select one named fixed-word output. The compiler uses the ABI to jump directly to the selected return word instead of decoding the whole tuple.

import "abis/AavePool.json" as AavePool;

permission AaveHealthGate -> 1.0.0 {
    parameters: {
        authorizer: address,
        pool: AavePool,
        account: address,
        minHealthFactor: uint256
    }

    pub fn authorize() -> bool {
        return authorizedBy(parameters.authorizer);
    }

    fn main() -> bool {
        let healthFactor = parameters.pool.getUserAccountData(parameters.account).healthFactor;
        return healthFactor >= parameters.minHealthFactor;
    }
}

Best Practices

1. Strip Unused Artifacts: Use "human-readable" ABIs or minimal JSON files containing only the functions you need. Full Foundry/Hardhat artifacts are supported but can be large.
2. Version Control: Commit your ABIs to git alongside your policies to ensure reproducible builds.
3. Use Aliases: Pick short, descriptive aliases (e.g., Aave instead of AavePoolV3Helper) to keep your policy logic readable.