How-to: The Keeper Execution Lifecycle

Understanding the lifecycle of a Matador-guarded transaction is critical for designing effective policies. It differs from standard execution because validation happens twice: before and after the action.

sequenceDiagram
    participant K as Keeper Bot
    participant M as Matador Interpreter
    participant P as Policy
    participant D as DeFi Protocol

    K->>M: 1. Submit Transaction
    Note right of K: exec(target, data)
    
    rect rgb(240, 240, 240)
        Note over M, P: Pre-Flight (Validation)
        M->>P: 2. Check Permissions
        P-->>M: Allow (Auth & Args OK)
    end
    
    M->>D: 3. EXECUTE CALL
    D-->>M: Success
    
    rect rgb(240, 240, 240)
        Note over M, P: Post-Flight (Verification)
        M->>P: 4. Check Invariants
        Note right of P: Balance > Min?
        P-->>M: Allow
    end
    
    M-->>K: 5. Transaction Complete

Step 1: Pre-Flight (Intent Validation)

Before any external code runs, Matador validates the intent of the transaction against the policy. This is your first line of defense.

• Authentication: Is msg.sender a recognized Keeper for this policy?
• Target Whitelisting: Is the to address allowed (e.g., Uniswap Router)?
• Selector Whitelisting: Is the function signature allowed (e.g., exactInputSingle)?
• Argument Validation: Do the call arguments meet constraints (e.g., amountIn < cap)?

Outcome: If any check fails, the transaction reverts immediately. No external state is touched.

Step 2: Execution (The Action)

If Pre-Flight passes, the Interpreter performs the actual call to the target protocol using the Smart Account's context.

• Tokens move.
• Swaps happen.
• State changes.

Step 3: Post-Flight (Outcome Verification)

After the call returns, Matador runs state-aware checks to verify the result. This captures risks that are hard to predict (like exact slippage or complex AMM math).

• Invariant Verification: Did the vault's balance increase as expected?
• Health Check: Is the collateral ratio safe?
• Oracle Sanity: Did the on-chain price deviate too much during execution?

Outcome: If a post-flight check fails, the entire transaction reverts. This atomicity guarantees that the vault never settles in an invalid state.

Next Steps

Ready to implement this? Choose a recipe:

• Recipe: Uniswap V3 Delta Rebalance
• Recipe: Aave Health Factor Guard