Core Concepts

The key ideas behind Grimoire. Understanding these will help you work with both the CLI and the Platform.

Spells

A spell is a strategy written in Grimoire's .spell format. It describes what you want to do — which assets, which protocols, under what conditions — in a readable, structured way.

spell SwapExample {
  venues: {
    uniswap: @uniswap_v3
  }

  params: {
    amount: 1000
  }

  on manual: {
    uniswap.swap(USDC, ETH, params.amount)
  }
}

A spell is not code that runs directly. It compiles into an intermediate representation (IR) that the runtime can evaluate safely.

Preview and Commit

Every spell execution follows a two-phase safety model:

Preview

The runtime executes the full spell logic — evaluating conditions, planning actions, checking constraints — without moving any funds. The result is a receipt that describes exactly what would happen.

Commit

If the preview receipt is ready, commit executes the planned actions onchain. If anything has changed since the preview (price drift, state changes), commit can reject the execution.

This separation means:

• You always see the plan before it runs
• Constraints are checked before irreversible actions
• You can simulate and dry-run as many times as needed

validate → simulate (preview) → cast --dry-run (preview + sign) → cast (preview + commit)

Venues and Adapters

A venue is a protocol that Grimoire can interact with — Aave, Uniswap, Morpho Blue, and others.

Each venue has an adapter that translates spell actions into protocol-specific calls. This means your spell logic stays the same even if you switch between venues.

venues: {
  lender: @aave_v3      // swap this to @morpho_blue and the spell still works
}

Currently supported venues:

Constraints

Constraints are runtime policy — not comments or suggestions. They are checked during preview and can reject execution before anything irreversible happens.

Examples:

• max_slippage: 0.5% — reject if slippage exceeds threshold
• max_single_move: 50000 — cap the size of any single action
• approval_required_above: 100000 — require explicit approval for large moves

Advisory Decisions

Some strategies need judgment calls — "Is now a good time to rebalance?" or "Which pool has better yield?"

Grimoire handles this with advisory decisions: typed prompts sent to an AI model during execution. The key difference from a free-form AI call is that advisories have:

• A schema for the expected output
• A fallback value if the model is unavailable
• A timeout to prevent hanging
• Full audit trail in the execution ledger

decision = advise risk: "Should we rebalance given current gas costs?" {
  output: { type: boolean }
  timeout: 10
  fallback: false
}

This keeps AI assistance explicit, bounded, and replayable.