[Journey] Use SPEL to write LEZ programs and generate a CLI from the IDL

[vpavlin]

1. Outcome and purpose

What the user achieves:
The user has a running LEZ program written in Rust using the SPEL framework, deployed to a local sequencer, with a generated CLI client auto-derived from the program's IDL — all from a single scaffold command.

Why it matters:
SPEL removes the boilerplate of writing LEZ programs from scratch and auto-generates a type-safe CLI client from the program's IDL, enabling Rust developers to ship on-chain logic and a matching command-line interface in minutes rather than hours. It also serves as the reference path for all future LEZ program development.

Key components:

• lgs (logos-scaffold CLI): Top-level developer workflow tool. Handles project scaffolding, sequencer setup, build, deploy, and REPL in a single unified interface. Start here.
• spel (CLI): Lower-level tool invoked by lgs under the hood. Also usable standalone.
• spel-framework: Rust crate providing the #[spel_program] macro and supporting types for writing LEZ programs.
• LEZ (Logos Execution Zone): The sequencer that executes deployed programs. Cloned and built automatically by lgs setup.

---

2. Scope

Repository: https://github.com/logos-co/spel @ v0.5.0
Scaffold: https://github.com/logos-co/scaffold (logos-scaffold / lgs)

Runtime target: local

Prerequisites:

• Linux or macOS
• Rust stable toolchain (rustup installed)
• cargo install access (internet connection)
• No minimum hardware constraints beyond a standard dev machine

Note: The LEZ sequencer binary is fetched and built automatically by lgs setup — you do not need to clone or build it manually.

---

3. Happy path

# 1. Install the lgs CLI (logos-scaffold)
cargo install --git https://github.com/logos-co/scaffold.git --tag <latest> lgs

# 2. Create a new SPEL project (delegates to `spel init` under the hood)
lgs new my-program --template spel
cd my-program

# 3. Clone LEZ, build the sequencer, wallet binary, and spel CLI
#    (this takes a few minutes the first time; subsequent runs are fast)
lgs setup

# 4. Start localnet, build guest binary, generate IDL, deploy, open REPL
lgs run

At the lgs run REPL prompt you can send transactions directly:

lgs> run initialize --owner <SIGNER_ID>
lgs> run do_something --owner <SIGNER_ID> --amount 42

Or, to generate a standalone typed CLI client from the IDL:

lgs build client
# Produces a CLI binary whose subcommands mirror the program's methods.
./target/release/my-program-cli --help

---

4. Verification

Success indicator: lgs run completes the deploy step and opens the REPL prompt without errors:

[run] sequencer started (pid XXXX)
[run] deploying my_program...
[run] deployed. Program ID: <ADDR>
lgs>

Inside the REPL, help lists available commands. Alternatively, after lgs build client:

USAGE:
    my-program-cli <COMMAND>

COMMANDS:
    initialize    Initialize the program state
    do_something  Execute a state transition

---

5. Configuration

All configuration lives in scaffold.toml (generated by lgs new). No manual env vars are needed for the default local workflow.

# scaffold.toml — key fields
[lez]
pin = "cf3639d8..."   # LEZ commit used for the sequencer

[spel]
pin = "73fc462e..."   # spel version pinned by scaffold

[framework]
kind = "spel"

To use a custom sequencer endpoint (advanced):

lgs run --sequencer-url http://localhost:9000

---

6. Known issues and troubleshooting

• Symptom: lgs setup fails with linker errors
  Cause: Missing system dependencies.
  Fix: sudo apt install build-essential pkg-config libssl-dev (Ubuntu/Debian); brew install openssl pkg-config (macOS).

• Symptom: lgs run fails at the deploy step with "program not found"
  Cause: lgs build hasn't run, or the guest binary is missing.
  Fix: lgs build then retry lgs run.

• Symptom: lgs setup says sequencer binary already present but lgs run can't start it
  Cause: Stale binary from a previous LEZ pin.
  Fix: lgs setup --rebuild to force a clean rebuild.

• Symptom: Agent/AI assistant loses track of steps at the deploy stage
  Cause: The old workflow required a separately running sequencer with no clear setup path. With lgs, the sequencer is managed automatically — always use lgs run rather than manual spel deploy.

Out of scope for this journey: private/shielded transactions, multi-party programs, testnet/mainnet deployment.

---

7. Point of contact

GitHub: @vpavlin
Discord: vpavlin

---

8. Additional context

Existing docs / specs:

• https://github.com/logos-co/spel — main repo README and per-crate docs
• https://github.com/logos-co/scaffold — lgs CLI
• [doc] Use SPEL to write lez programs and generate CLI from IDL ecosystem#106 — original request that triggered this doc packet
• https://github.com/logos-blockchain/logos-execution-zone — LEZ sequencer (managed automatically by lgs setup)

Estimated time to complete: 15–20 minutes (most of which is the one-time lgs setup build step).

Version bump: Updated from v0.4.0 to v0.5.0; rewrote happy path around lgs workflow so readers don't need to source or start a sequencer manually. Previous version left readers stranded at "start the sequencer — see LEZ repo".