Module System

Matador uses a modular architecture to keep the core interpreter lightweight while enabling unlimited extensibility. Opcodes are grouped into "Modules," which are external contracts called by the interpreter when needed.

Architecture

Module Dispatch

When the interpreter encounters an opcode:

1. It identifies the Module ID associated with that opcode (e.g., SIGNATURE_CHECK belongs to Module 1).
2. It queries the ModuleRegistry for the address of that module.
3. It invokes the module via staticcall (for view/pure checks) or delegatecall (for stateful checks).

IPermissionModule Interface

All modules must implement the IPermissionModule interface.

interface IPermissionModule {
    enum ExecutionMode { View, Mutable }

    function evaluate(
        bytes memory context,
        uint256 offset,
        address subject,
        ExecutionContext calldata exec,
        uint8 opcode,
        ExecutionMode mode
    ) external returns (uint256 newOffset, bool success);
}

Parameters

Standard Modules

Matador ships with a set of verified standard modules.

Creating a Custom Module

You can build your own module to implement domain-specific logic, such as checking a Chainlink oracle or verifying a Merkle proof.

contract OracleModule is IPermissionModule {
    using ContextReader for bytes;

    function evaluate(
        bytes memory context,
        uint256 offset,
        address,
        ExecutionContext calldata,
        uint8 opcode,
        ExecutionMode
    ) external view returns (uint256, bool) {
        if (opcode == MY_ORACLE_OPCODE) {
            // Read args from bytecode
            (uint256 minPrice, newOffset) = context.readUint256(offset);
            
            // Perform check
            uint256 price = Oracle.latestAnswer();
            return (newOffset, price >= minPrice);
        }
        revert("Unknown Opcode");
    }
}