Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

Why Grimoire

Most onchain automation is written as ad-hoc scripts: fetch a price, build a calldata, sign and send. That works for one-offs, but it doesn't scale — there's no safety net, no audit trail, and no way to know what a script will do before it does it.

Grimoire is built around a different premise: execution should be inspectable before it's irreversible.

The Safety Model

Every Grimoire execution follows the same two-phase pipeline:

Preview → Commit

Preview runs 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 executes only if the preview was clean. If anything has changed since the preview (price drift, state changes, constraint violation), the commit is rejected before anything irreversible happens.

This means you can simulate, dry-run, and inspect a strategy as many times as you want. Nothing moves until you explicitly commit a clean preview.

Constraints Are Policy, Not Comments

In a script, a comment like // don't move more than $50k is documentation. It doesn't enforce anything.

In Grimoire, constraints are runtime checks evaluated during preview:

constraints: {
  max_single_move: 50000    // enforced — preview fails if exceeded
  max_slippage: 0.5%        // enforced — commit rejected if breached
}

If a constraint is violated, the execution stops before any onchain action is attempted. You see the failure in the receipt, not in your wallet.

Typed AI Judgment

Grimoire supports advisory decisions — AI model calls embedded in the execution pipeline with a typed schema, a timeout, and a fallback:

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

The key properties:

  • The model can only return values that match the declared schema
  • If the model times out or is unavailable, the fallback is used — execution continues
  • Every advisory call is logged in the execution ledger with inputs and outputs

This makes AI-assisted strategies auditable and safe. The model gives judgment; the spell controls what happens with it.

Auditability by Default

Every run produces a ledger entry:

Terminal
grimoire history spells/my-strategy.spell
grimoire log spells/my-strategy.spell <runId>

The log records each step — advisory calls, constraint checks, action previews, and commits. You can replay advisory decisions from a simulation run so the live cast is deterministic, using the same model outputs the simulation produced.

Portable Spell Format

Spells are venue-agnostic. The same strategy logic works across protocols:

venues: {
  lender: @aave_v3      // change to @morpho_blue and the rest stays the same
}

Switching protocols doesn't require rewriting the strategy. The adapter handles translation.

When to Use Grimoire

Grimoire is a good fit when you want:

  • Onchain automation with a safety gate before execution
  • Constraint enforcement that fails predictably before funds move
  • AI-assisted strategies with bounded, auditable model calls
  • DeFi operations across Aave, Uniswap, Morpho, Pendle, Across, Hyperliquid, or Polymarket
  • Reproducible runs where simulation and execution use the same decisions

It's less suited for: high-frequency trading that requires sub-millisecond latency, or strategies that need to bypass preview for speed.

Next Steps