Running Spells

How to take a spell from validation through simulation to live onchain execution.

The Execution Pipeline

Every spell goes through the same safety pipeline:

validate → simulate → cast --dry-run → cast

Each step adds more confidence before you commit real value.

Validate

Terminal

grimoire validate spells/my-strategy.spell

Checks that the spell compiles, types are correct, and structural rules pass. No chain connection needed.

Simulate (Preview)

Terminal

grimoire simulate spells/my-strategy.spell \
  --chain 1 \
  --rpc-url YOUR_RPC_URL

Runs the full spell logic against live protocol data. The runtime plans all actions, evaluates constraints, and produces a receipt — but nothing is submitted onchain.

The receipt shows:

Planned actions and their parameters
Constraint evaluation results
Expected value movements
Status: ready or rejected

Dry-Run Cast

Terminal

grimoire cast spells/my-strategy.spell \
  --dry-run \
  --key-env PRIVATE_KEY \
  --rpc-url YOUR_RPC_URL

This runs the full pipeline including wallet signing, but does not submit the transaction. Use this to verify everything works end-to-end before going live.

Live Cast

Terminal

grimoire cast spells/my-strategy.spell \
  --key-env PRIVATE_KEY \
  --rpc-url YOUR_RPC_URL

Without --dry-run, this runs preview and then commits — submitting transactions onchain.

Wallet Setup

Grimoire manages wallets through its own keystore.

Generate a new wallet:

Terminal

grimoire wallet generate

Import an existing key:

Terminal

grimoire wallet import --key-env PRIVATE_KEY

Check address and balance:

Terminal

grimoire wallet address
grimoire wallet balance --chain 1 --rpc-url YOUR_RPC_URL

Wrap/unwrap ETH:

Terminal

grimoire wallet wrap --amount 0.1 --chain 1 --rpc-url YOUR_RPC_URL
grimoire wallet unwrap --amount 0.1 --chain 1 --rpc-url YOUR_RPC_URL

Simulation on a Fork

For thorough testing, you can simulate against a local Anvil fork:

Terminal

# Start Anvil fork
anvil --fork-url YOUR_RPC_URL --fork-block-number 12345678
 
# Run against the fork
grimoire simulate spells/my-strategy.spell \
  --chain 1 \
  --rpc-url http://127.0.0.1:8545

Reviewing Results

After any run:

Terminal

# List all runs
grimoire history
 
# Show detailed event ledger for the last run
grimoire log --last
 
# Show a specific run
grimoire log --run-id <id>

Parameter Overrides

Override default spell parameters at runtime:

Terminal

grimoire simulate spells/my-strategy.spell \
  --chain 1 \
  --params '{"amount": 5000}'

Cross-Chain Execution

For spells that span multiple chains:

Terminal

grimoire cast spells/bridge-and-swap.spell \
  --key-env PRIVATE_KEY \
  --rpc-url YOUR_RPC_URL \
  --destination-chain 8453 \
  --destination-spell spells/swap-on-base.spell