Contract Interfaces

This reference documents the core interfaces, data structures, and errors used by the on-chain components of Matador.

IPermissionInterpreter

The IPermissionInterpreter is the heart of the system. It executes the compiled bytecode to validate transactions.

contracts/src/interfaces/IPermissionInterpreter.sol

interface IPermissionInterpreter {
    function enforce(
        bytes memory context,
        address subject,
        ExecutionContext calldata exec
    ) external;

    function enforceView(
        bytes memory context,
        address subject,
        ExecutionContext calldata exec
    ) external view;
}

ExecutionContext

The ExecutionContext struct contains all runtime metadata available to the interpreter during a policy check.

Property	Type	Description
`caller`	`address`	The address initiating the execution (usually the entry point or msg.sender).
`target`	`address`	The destination contract address.
`value`	`uint256`	The native value (Wei) sent with the call.
`data`	`bytes`	The transaction calldata.
`gasLimit`	`uint256`	The gas limit for the execution.
`gasPrice`	`uint256`	The gas price (or max fee per gas) of the transaction.
`nonce`	`uint256`	The nonce of the smart account.
`blobBaseFee`	`uint256`	The base fee for blob gas (EIP-4844).
`blobGasPrice`	`uint256`	The blob gas price.

Methods

`enforce`

Executes the permission policy in a mutable context. This is required for policies that update state, such as RATE_LIMIT_CHECK or OPERATION_COUNT_CHECK.

Reverts: If any condition in the policy fails.
Gas: Costs vary based on the policy complexity and state access.

`enforceView`

Executes the permission policy in a read-only context. Useful for off-chain simulations or validateUserOp where storage modification is restricted.

Stateful Opcodes

Calling enforceView with a policy that contains state-modifying opcodes (like RATE_LIMIT_CHECK) will revert.

IModuleRegistry

The registry maps 1-byte module IDs to their deployed contract addresses.

contracts/src/interfaces/IModuleRegistry.sol

interface IModuleRegistry {
    function getModule(uint8 moduleId) external view returns (address module);
}

Errors

Matador uses custom errors for gas efficiency and clarity.

Permission Errors

Errors thrown when a specific policy condition fails.

Error	Parameters	Description
`UnknownOpcode`	`uint8 opcode`	The bytecode contained an undefined opcode.
`InvalidCondition`	-	A logical condition (AND/OR) was malformed.
`RateLimitExceeded`	`count, limit, reset`	A rate limit has been breached.
`BalanceCheckFailed`	`token, account, req, act`	Token or native balance requirements were not met.
`CallerCheckFailed`	`required, actual`	The caller is not allowed.
`PermissionExpired`	`expiry, current`	The policy includes an expiry timestamp that has passed.

System Errors

Errors related to the interpreter's internal execution or account management.

Error	Parameters	Description
`Unauthorized`	-	Caller is not authorized to grant/revoke permissions.
`StackOverflow`	-	Policy complexity exceeded the interpreter's stack limit (1024).
`StackUnderflow`	-	An opcode attempted to pop from an empty stack.
`PermissionNotFound`	`bytes32 id`	The requested permission ID does not exist on the account.

Contract Interfaces

On this page