Skip to content

x402agent/SolanaOS / skills/qedgen

qedgen

Flagged

Formally verify programs by writing Lean 4 proofs. Trigger this skill whenever the user wants to formally verify code, generate Lean 4 proofs, prove properties about algorithms or smart contracts, verify invariants, convert program logic into formal specifications, or anything involving Lean 4 and formal verification. Also trigger when the user mentions "qedgen", "lean proof", "formal proof", "verify my code", "prove correctness", "formal verification", or wants mathematical guarantees about their implementation.

FileKindSize
Cargo.lockmanifest38.2 KB
Cargo.tomlmanifest347 B
LICENSEother1.0 KB
README.mdmarkdown4.1 KB
SKILL.mdskill md21.0 KB
claude.mdmarkdown9.7 KB
crates/qedgen/Cargo.tomlmanifest544 B
crates/qedgen/src/api.rsscript38.9 KB
crates/qedgen/src/asm2lean.rsscript26.2 KB
crates/qedgen/src/consolidate.rsscript6.2 KB
crates/qedgen/src/main.rsscript4.7 KB
crates/qedgen/src/project.rsscript3.0 KB
crates/qedgen/src/spec.rsscript19.4 KB
crates/qedgen/src/validate.rsscript5.6 KB
crates/qedgen/templates/Main.leanother154 B
crates/qedgen/templates/PROMPT_TEMPLATE.mdmarkdown3.2 KB
crates/qedgen/templates/README.lean.mdmarkdown1.6 KB
crates/qedgen/templates/lakefile.leanother292 B
crates/qedgen/templates/lean-toolchainother25 B
docs/CNAMEother10 B
docs/index.htmlother11.6 KB
docs/llms-full.txtmarkdown8.7 KB
docs/llms.txtmarkdown2.1 KB
docs/logo-dark.svgother648 B
docs/logo-light.svgother648 B
docs/qgn_demo.htmlother69.3 KB
docs/style.cssother8.1 KB
examples/rust/escrow/Anchor.tomlconfig353 B
examples/rust/escrow/Cargo.lockmanifest72.8 KB
examples/rust/escrow/Cargo.tomlmanifest215 B
examples/rust/escrow/migrations/deploy.tsscript428 B
examples/rust/escrow/package.jsonmanifest528 B
examples/rust/escrow/programs/escrow/Cargo.tomlmanifest376 B
examples/rust/escrow/programs/escrow/Xargo.tomlconfig62 B
examples/rust/escrow/programs/escrow/src/lib.rsscript6.7 KB
examples/rust/escrow/tests/escrow.tsscript8.6 KB
examples/rust/escrow/tsconfig.jsonconfig205 B
examples/rust/percolator/Cargo.lockmanifest8.5 KB
examples/rust/percolator/Cargo.tomlmanifest639 B
examples/rust/percolator/LICENSEother11.1 KB
examples/rust/percolator/README.mdmarkdown4.9 KB
examples/rust/percolator/examples/offsets.rsscript1.3 KB
examples/rust/percolator/scripts/audit-proof-strength.mdmarkdown6.4 KB
examples/rust/percolator/scripts/proof-strength-audit-results.mdmarkdown89.2 KB
examples/rust/percolator/scripts/run_kani_full_audit.shexecutablescript1.2 KB
examples/rust/percolator/spec.mdmarkdown108.4 KB
examples/rust/percolator/src/i128.rsscript20.4 KB
examples/rust/percolator/src/percolator.rsscript139.3 KB
examples/rust/percolator/src/wide_math.rsscript59.8 KB
examples/rust/percolator/tests/amm_tests.rsscript7.4 KB
examples/rust/percolator/tests/common/mod.rsscript4.7 KB
examples/rust/percolator/tests/fuzzing.proptest-regressionsother4.7 KB
examples/rust/percolator/tests/fuzzing.rsscript43.1 KB
examples/rust/percolator/tests/proofs_arithmetic.rsscript17.1 KB
examples/rust/percolator/tests/proofs_audit.rsscript35.0 KB
examples/rust/percolator/tests/proofs_instructions.rsscript64.8 KB
examples/rust/percolator/tests/proofs_invariants.rsscript21.0 KB
examples/rust/percolator/tests/proofs_lazy_ak.rsscript22.4 KB
examples/rust/percolator/tests/proofs_liveness.rsscript17.1 KB
examples/rust/percolator/tests/proofs_safety.rsscript104.2 KB
examples/rust/percolator/tests/proofs_v1131.rsscript25.4 KB
examples/rust/percolator/tests/unit_tests.rsscript93.8 KB
examples/sbpf/counter/src/counter.sother22.9 KB
examples/sbpf/slippage/src/asm-slippage/asm-slippage.sother698 B
examples/sbpf/transfer/src/transfer.sother2.4 KB
examples/sbpf/tree/src/tree.sother61.1 KB
install.shexecutablescript5.5 KB
lean_solana/QEDGen.leanother165 B
lean_solana/QEDGen/Solana.leanother165 B
lean_solana/QEDGen/Solana/Account.leanother4.0 KB
lean_solana/QEDGen/Solana/Authority.leanother285 B
lean_solana/QEDGen/Solana/Cpi.leanother9.0 KB
lean_solana/QEDGen/Solana/SBPF.leanother130 B
lean_solana/QEDGen/Solana/SBPF/Execute.leanother12.2 KB
lean_solana/QEDGen/Solana/SBPF/ISA.leanother5.1 KB
lean_solana/QEDGen/Solana/SBPF/Memory.leanother6.1 KB
lean_solana/QEDGen/Solana/SBPF/Tactic.leanother2.3 KB
lean_solana/QEDGen/Solana/State.leanother1.9 KB
lean_solana/QEDGen/Solana/Valid.leanother2.0 KB
lean_solana/README.mdmarkdown2.5 KB
lean_solana/lake-manifest.jsonconfig119 B
lean_solana/lakefile.leanother112 B
lean_solana/lean-toolchainother25 B
lean_solana/test_lemmas.leanother2.3 KB
package.jsonmanifest762 B
tools/qedgenexecutablescript357 B
# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Overview

QEDGen is a Claude Code skill for formally verifying Solana programs using Lean 4 proofs. Claude (the local LLM) drives proof writing directly — reading code, writing Lean models/theorems/proofs, and iterating on `lake build` errors. Leanstral (Mistral's theorem prover) is called only for hard sub-goals via `fill-sorry`.

**Core workflow**: Claude reads source → writes SPEC.md → writes Lean 4 proofs → `lake build` → iterates → calls `qedgen fill-sorry` for hard sub-goals

## Build and Development Commands

### Build the CLI

```bash
# Build qedgen binary (outputs to ./bin/qedgen)
cargo build --release

# Build just the Lean support library
cd lean_solana
lake build
```

### Run Tests

```bash
# Rust unit tests
cargo test

# Test Lean support library axioms
cd lean_solana
lake env lean test_lemmas.lean

# Build the example escrow verification
cd examples/rust/escrow/formal_verification
lake build                # Verify all proofs compile
```

### QEDGen Commands

```bash
# Set up global validation workspace (first time: 15-45 min for Mathlib)
qedgen setup

# Generate proofs from a prompt file (used by Claude internally)
qedgen generate \
  --prompt-file /tmp/proof/prompt.txt \
  --output-dir /tmp/proof \
  --passes 3 \
  --temperature 0.3 \
  --validate

# Fill sorry markers in a Lean file (Claude calls this for hard sub-goals)
qedgen fill-sorry \
  --file formal_verification/Proofs/Hard.lean \
  --passes 3 \
  --validate

# Generate a draft SPEC.md from an Anchor IDL
qedgen spec --idl target/idl/program.json --output-dir ./formal_verification

# Consolidate multiple proof projects into single project
qedgen consolidate \
  --input-dir /tmp/proofs \
  --output-dir formal_verification

# Transpile sBPF assembly to Lean 4 program module
qedgen asm2lean \
  --input examples/sbpf/transfer/src/transfer.s \
  --output formal_verification/TransferProg.lean \
  --namespace TransferProg
```

## Architecture

### Crate Structure

**`crates/qedgen/`** - Single crate: CLI and Mistral API client
- `main.rs` - CLI entry points (generate, fill-sorry, spec, consolidate, asm2lean, setup)
- `api.rs` - Mistral API client, pass@N sampling, sorry-filling, retry logic
- `asm2lean.rs` - sBPF assembly → Lean 4 transpiler (parses `.s`, emits program module)
- `validate.rs` - Lake build validation in persistent workspace
- `project.rs` - Lean project scaffolding generation
- `consolidate.rs` - Merges multiple proof projects
- `spec.rs` - SPEC.md generation from Anchor IDL

**`lean_solana/`** - Standalone Lean 4 library: Solana axioms (QEDGen.Solana)
- `QEDGen/Solana/Account.lean` - Account structure
- `QEDGen/Solana/Authority.lean` - Authorization predicates
- `QEDGen/Solana/Cpi.lean` - Generic CPI envelope (invoke_signed model)
- `QEDGen/Solana/State.lean` - Lifecycle and state machines
- `QEDGen/Solana/Valid.lean` - Numeric bounds and validity predicates

### Key Design Decisions

**Why Claude-driven (not pipeline-driven)?**
- Claude reads code context and writes proofs directly — no lossy analyzer step
- Proof patterns generalize across programs without per-property prompt templates
- Claude iterates on `lake build` errors naturally
- Scales to large programs without combinatorial prompt explosion

**Why Leanstral model only for sorry-filling?**
- Full module generation requires too much context (import ordering, namespace management)
- Focused sorry-filling gives Leanstral maximum signal with minimal noise
- Claude handles the modeling/structuring; Leanstral handles hard tactic proofs

**Why pass@N sampling?**
- The Leanstral model is non-deterministic; multiple attempts increase success rate
- Validation selects compilable proof over heuristics (sorry count)

**Why persistent validation workspace?**
- Lake's first Mathlib build takes 15-45 minutes
- Reusing `.lake/packages/` avoids repeated Mathlib compilation
- Location: platform cache dir or `QEDGEN_VALIDATION_WORKSPACE`

**Why axioms instead of proving SPL Token?**
- Verification scope: program logic only (see VERIFICATION_SCOPE.md)
- Trust boundary: SPL Token, Solana runtime, CPI mechanics
- Pragmatic: keeps proofs tractable and completion time reasonable

## Verification Scope

**What we verify:**
- Authorization (signer checks, constraints)
- Conservation (token totals preserved)
- State machines (lifecycle, one-shot safety)
- Arithmetic safety (overflow/underflow)
- CPI correctness (program, accounts, discriminator match intent)

**What we trust (axioms):**
- SPL Token implementation
- Solana runtime (PDA derivation, account ownership)
- CPI mechanics
- Anchor framework

See `examples/rust/escrow/formal_verification/VERIFICATION_SCOPE.md` for details.

## Common Development Tasks

### Adding New Axioms

When a proof pattern is reusable across programs:

1. Add to the appropriate module in `lean_solana/QEDGen/Solana/`
2. Document the trust assumption with a comment
3. Export in `QEDGen.lean`
4. Update SKILL.md support library API section
5. Test: `cd lean_solana && lake build`

### Debugging Failed Proofs

If `lake build` fails:
1. Read the error output directly
2. Common issues:
   - `split_ifs` fails → use `unfold` before `split_ifs`
   - `omega could not prove` → unfold named predicates in BOTH hypothesis and goal: `unfold pred at h ⊢`
   - `no goals to be solved` → remove redundant tactic (e.g., `· contradiction` after auto-closed branch)
   - `unexpected token 'open'` → use `«open»` quoting for Lean keywords
   - Namespace collision → check `open` statements
   - `simp` timeout on sBPF proofs → see **sBPF simp performance** section below
3. Fix the proof and re-run `lake build`

### sBPF Proof Workflow

For sBPF assembly programs, use `qedgen asm2lean` to generate the program module instead of hand-transcribing:

```bash
qedgen asm2lean --input src/program.s --output formal_verification/Prog.lean
```

Then write proofs in a separate file that imports the generated module:

```lean
import QEDGen.Solana.SBPF
import Prog
open Prog

theorem my_property ... :=
    (execute prog (initState inputAddr mem) FUEL).exitCode = some CODE := by
  sbpf_steps
```

The `sbpf_steps` tactic automates sBPF execution unrolling via `simp`. It requires `@[simp]` on `prog`.

### sBPF simp Performance (Critical)

The `sbpf_steps` tactic is extremely sensitive to how constants are typed and named. Violations cause exponential blowup (seconds → hours).

**Rule 1: Offset constants MUST be `Int`, not `Nat`.**
`effectiveAddr` takes `(off : Int)`. With `Nat` offsets, Lean inserts a `Nat → Int` coercion that `simp` cannot efficiently process.
```lean
-- BAD: causes simp timeout
abbrev MY_OFFSET : Nat := 80

-- GOOD: matches effectiveAddr signature directly
abbrev MY_OFFSET : Int := 80
```

**Rule 2: Named constants in `prog` MUST match hypothesis names.**
`simp` uses syntactic matching. If `prog` has a raw numeric but the hypothesis uses a named constant, `simp` must unfold the constant at every subterm at every step.
```lean
-- BAD: prog has 80, hypothesis has MY_OFFSET — simp must unfold at each step
@[simp] def prog := #[ .ldx .dword .r2 .r1 80, ... ]
theorem t ... (h : readU64 mem (effectiveAddr inputAddr MY_OFFSET) = v) ...

-- GOOD: both use MY_OFFSET — syntactic match, instant
@[simp] def prog := #[ .ldx .dword .r2 .r1 MY_OFFSET, ... ]
theorem t ... (h : readU64 mem (effectiveAddr inputAddr MY_OFFSET) = v) ...
```

**Rule 3: `@[simp]` on `prog` is required.** The tactic needs to evaluate `prog[n]?` at each step.

The `qedgen asm2lean` command handles Rules 1-3 automatically: it emits `Int`-typed offsets, `Nat`-typed non-offsets, named constants in the `prog` array, and `@[simp]` on `prog`.

## Environment Variables

- `MISTRAL_API_KEY` - Required for `fill-sorry` and `generate` commands
- `QEDGEN_VALIDATION_WORKSPACE` - Override validation workspace path (default: platform cache dir)

## Common Lean Proof Patterns

### Tactic Sequencing
```lean
-- BAD: simp eliminates if-structure
simp [transition] at h
split_ifs at h  -- ERROR

-- GOOD: unfold preserves structure
unfold transition at h
split_ifs at h with h_eq
```

### Conservation Proofs
```lean
-- CRITICAL: unfold named predicate in BOTH hypothesis and goal
unfold conservation at h_inv ⊢
omega
```

### CPI Correctness (pure rfl)
```lean
-- Build a generic CpiInstruction (models invoke_signed)
def build_cpi (ctx : Context) : CpiInstruction :=
  { programId := TOKEN_PROGRAM_ID
  , accounts := [⟨ctx.src, false, true⟩, ⟨ctx.dst, false, true⟩, ⟨ctx.auth, true, false⟩]
  , data := [DISC_TRANSFER] }

theorem cpi_correct (ctx : Context) :
    let cpi := build_cpi ctx
    targetsProgram cpi TOKEN_PROGRAM_ID ∧
    accountAt cpi 0 ctx.src false true ∧
    accountAt cpi 1 ctx.dst false true ∧
    accountAt cpi 2 ctx.auth true false ∧
    hasDiscriminator cpi [DISC_TRANSFER] := by
  unfold build_cpi targetsProgram accountAt hasDiscriminator
  exact ⟨rfl, rfl, rfl, rfl, rfl⟩
```

## Output Artifacts

After `qedgen generate`:
```
/tmp/proof/
├── Best.lean              # Selected best completion
├── metadata.json          # Rankings, timings, tokens
├── prompt.txt             # Prompt sent to Leanstral model
├── attempts/
│   ├── completion_0.lean
│   ├── completion_0_raw.txt
│   └── ...
└── validation/
    └── completion_0.log   # Lake build log
```

## Notes

- First Lean build is expensive (15-45 min for Mathlib). Run `qedgen setup` first.
- If `lake build` fails with "could not resolve 'HEAD' to a commit", remove `.lake/packages/mathlib` and run `lake update`.
- Binary is built to `./bin/qedgen`, not `target/release/qedgen`.
- The SKILL.md file defines the full proof-writing workflow that Claude follows.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall