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

Writing Your First Spell

Create a simple spell from scratch, compile it, and run it.

Goal

Write a spell that takes a parameter, uses it in logic, and emits an event. This introduces the basic spell structure without touching any protocols.

1. Create the Spell File

Create a file called spells/hello-grimoire.spell:

spell HelloGrimoire {
  version: "0.1.0"
  description: "My first Grimoire spell"

  params: {
    amount: 42
  }

  on manual: {
    emit("hello", { value: params.amount })
  }
}

This spell:

  • Declares a parameter amount with a default value of 42
  • Triggers manually (not on a schedule)
  • Emits an event with the parameter value

2. Compile

Terminal
grimoire compile spells/hello-grimoire.spell --pretty

This shows the compiled intermediate representation (IR). If there are syntax errors, the compiler will tell you exactly what to fix.

3. Validate

Terminal
grimoire validate spells/hello-grimoire.spell

Validation goes beyond compilation — it checks structural rules, type consistency, and constraint validity.

4. Simulate

Terminal
grimoire simulate spells/hello-grimoire.spell --chain 1

Simulation runs the full preview. Since this spell has no onchain actions, it will complete without needing wallet credentials.

5. Override Parameters

You can override default parameter values at runtime:

Terminal
grimoire simulate spells/hello-grimoire.spell \
  --chain 1 \
  --params '{"amount": 100}'

6. Inspect the Run

Terminal
grimoire history
grimoire log --last

The history shows your run, and the log shows every event that occurred — including the hello event with your parameter value.

Next Steps