Grimoire
Run Grimoire simulate and dry-run cast against a local Anvil fork with pinned blocks and persisted state before touching mainnet.
Overview
Grimoire is an agent skill most often used in Ship (also Build integrations) that documents Anvil fork setup and Grimoire simulate/dry-run commands for safe EVM spell testing.
Install
npx skills add https://github.com/franalgaba/grimoire --skill grimoireWhat is this skill?
- Foundry install via foundryup with anvil and cast version checks
- Forked Anvil node recipes with optional pinned block and state.json persistence
- Grimoire simulate and cast --dry-run wired to localhost:8545 and chain-id alignment
- Explicit scope: Anvil is EVM-only; Hyperliquid uses separate venue meta commands
- Preflight and sanity check section for reproducible local previews
- Documents EVM-only Anvil scope with explicit Hyperliquid offchain exception
- Optional persisted state path .grimoire/anvil/state.json with --state-interval 60
Adoption & trust: 1k installs on skills.sh; 5 GitHub stars; 1/3 security scanners passed (skills.sh audits).
What problem does it solve?
You have a Grimoire spell but lack a reproducible local fork workflow to preview transactions before broadcasting.
Who is it for?
Indie builders validating Grimoire spells on forked mainnet state with Foundry before production sends.
Skip if: Pure offchain venue testing on Hyperliquid via Anvil, or teams that only need mainnet casts without local fork discipline.
When should I use this skill?
Running Grimoire preview or dry-run workflows against local forked EVM state with Foundry Anvil.
What do I get? / Deliverables
You run simulate and dry-run cast against a local Anvil RPC with aligned chain ID and optional pinned state, then promote to live cast only after checks pass.
- Running local Anvil fork matched to spell chain ID
- Successful simulate or dry-run cast transcript against localhost RPC
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Canonical shelf is Ship/testing because the cheat sheet centers on forked EVM preview and dry-run validation, even though spell authoring starts in Build. Testing matches Anvil fork setup, Grimoire simulate/cast dry-run, and preflight sanity checks rather than production monitoring.
Where it fits
Wire FORK_RPC_URL and CHAIN_ID in spell docs before first simulate against a fresh Anvil fork.
Run cast --dry-run with --key-env PRIVATE_KEY on localhost:8545 to validate wallet wiring without broadcasting.
Restart Anvil from saved .grimoire/anvil/state.json to reproduce a failed spell at a pinned block.
How it compares
Local fork testing runbook for Grimoire plus Anvil, not a hosted testnet SaaS or a generic Hardhat tutorial unrelated to spells.
Common Questions / FAQ
Who is grimoire for?
Developers using Grimoire on EVM chains who want Foundry Anvil forks for preview-only simulate and dry-run workflows.
When should I use grimoire?
In Ship testing before mainnet cast; in Build integrations when wiring RPC and chain-id for a new spell; in Operate iterate when reproducing a fork at a pinned block after an incident.
Is grimoire safe to install?
The skill describes PRIVATE_KEY env usage for dry-run wiring—never commit keys; review Security Audits on this page and use throwaway fork wallets.
Workflow Chain
Then invoke: grimoire uniswap
SKILL.md
READMESKILL.md - Grimoire
# Anvil Cheat Sheet (Grimoire) Use this when running Grimoire preview/dry-run workflows against local forked state. Scope: - Anvil is EVM-only. - Do not use Anvil workflows for offchain venues (for example `hyperliquid`). - For Hyperliquid checks, use venue commands such as `grimoire venue hyperliquid meta --format json`. ## 0) Install Foundry (Anvil + Cast) ```bash curl -L https://foundry.paradigm.xyz | bash && foundryup anvil --version cast --version ``` If your shell does not find the commands immediately, start a new shell session. ## 1) Start a Forked Anvil Node Baseline: ```bash anvil \ --fork-url "$FORK_RPC_URL" \ --chain-id "$CHAIN_ID" \ --host 127.0.0.1 \ --port 8545 ``` Reproducible (pinned block + persisted state): ```bash anvil \ --fork-url "$FORK_RPC_URL" \ --chain-id "$CHAIN_ID" \ --fork-block-number "$FORK_BLOCK" \ --state .grimoire/anvil/state.json \ --state-interval 60 \ --host 127.0.0.1 \ --port 8545 ``` Notes: - `--fork-url` is the same as `--rpc-url` in Anvil. - Keep Grimoire `--chain` equal to Anvil `--chain-id`. ## 2) Run Grimoire Against Anvil Preview only: ```bash <grimoire-cmd> simulate <spell-path> \ --chain "$CHAIN_ID" \ --rpc-url "http://127.0.0.1:8545" ``` Dry-run with wallet path (preview-only, wallet wiring included): ```bash <grimoire-cmd> cast <spell-path> \ --dry-run \ --chain "$CHAIN_ID" \ --rpc-url "http://127.0.0.1:8545" \ --key-env PRIVATE_KEY ``` ## 3) Preflight and Sanity Checks Check that Grimoire is using the endpoint you expect: ```bash <grimoire-cmd> venue doctor \ --adapter uniswap \ --chain "$CHAIN_ID" \ --rpc-url "http://127.0.0.1:8545" \ --json ``` Quick RPC checks: ```bash cast chain-id --rpc-url http://127.0.0.1:8545 cast block-number --rpc-url http://127.0.0.1:8545 ``` ## 4) High-Value Anvil Flags - `--fork-block-number <n>`: pin fork for repeatability. - `--state <path>`: load and dump state automatically. - `--dump-state <path>` / `--load-state <path>`: explicit state lifecycle. - `--auto-impersonate`: enables impersonation workflows. - `--compute-units-per-second <n>`: tune upstream provider throughput. - `--retries <n>`: retry transient upstream errors. - `--no-rate-limit`: disable local provider rate limiting. - `--fork-header "Key: Value"`: pass authenticated headers to upstream RPC. ## 5) Useful RPC Controls During Debugging ```bash cast rpc evm_increaseTime 3600 --rpc-url http://127.0.0.1:8545 cast rpc evm_mine --rpc-url http://127.0.0.1:8545 SNAP=$(cast rpc evm_snapshot --rpc-url http://127.0.0.1:8545) cast rpc evm_revert "$SNAP" --rpc-url http://127.0.0.1:8545 cast rpc anvil_impersonateAccount 0x... --rpc-url http://127.0.0.1:8545 cast rpc anvil_stopImpersonatingAccount 0x... --rpc-url http://127.0.0.1:8545 ``` ## 6) Common Failure Patterns - Chain mismatch: - align Anvil `--chain-id` and Grimoire `--chain`. - Wrong RPC endpoint used: - pass `--rpc-url` explicitly and verify `rpcUrl` in `venue doctor --json`. - Upstream fork instability: - set `--fork-block-number`, raise `--retries`, tune `--compute-units-per-second`. # Authoring Workflow (Agent Procedure) Use this procedure whenever creating or editing `.spell` files. ## 1. Load Context 1. Read `references/syntax-capabilities.md`. 2. Identify the target spell path and trigger intent (`manual`, `hourly`, etc.). 3. Identify whether the spell has value-moving actions. 4. If using EVM custom RPC/fork or signing transactions, run Foundry Cast quickchecks from `references/cast-cheatsheet.md`. 5. For offchain venues (for example `hyperliquid`), skip Cast/Anvil checks and validate via venue API commands. ## 2. Author With Minimal Safe Skeleton Start from: ```spell spell Hello { params: { amount: 42 } on manual: { doubled = params.amount * 2 emit hello(amount=params.amount, doubled=doubled) } } ``` Then incrementally add venues/actions/guards/advisory blocks. **Decision guide — query functions vs advisory:** - Need