Skip to content

x402agent/SolanaOS / skills/solana-formal-verification

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
.gitignoreother753 B
.npmignoreother352 B
Cargo.lockmanifest46.3 KB
Cargo.tomlmanifest307 B
LICENSEother1.0 KB
README.mdmarkdown3.7 KB
SKILL.mdskill md10.8 KB
bin/leanstralexecutablescript6.2 MB
claude.mdmarkdown6.8 KB
crates/qedgen/Cargo.tomlmanifest544 B
crates/qedgen/lean_support/QEDGen.leanother166 B
crates/qedgen/lean_support/QEDGen/Solana.leanother166 B
crates/qedgen/lean_support/QEDGen/Solana/Account.leanother4.0 KB
crates/qedgen/lean_support/QEDGen/Solana/Authority.leanother285 B
crates/qedgen/lean_support/QEDGen/Solana/Cpi.leanother3.3 KB
crates/qedgen/lean_support/QEDGen/Solana/State.leanother1.9 KB
crates/qedgen/lean_support/QEDGen/Solana/Token.leanother1.4 KB
crates/qedgen/lean_support/QEDGen/Solana/Valid.leanother2.0 KB
crates/qedgen/lean_support/README.mdmarkdown2.8 KB
crates/qedgen/lean_support/lake-manifest.jsonconfig119 B
crates/qedgen/lean_support/lakefile.leanother112 B
crates/qedgen/lean_support/lean-toolchainother25 B
crates/qedgen/lean_support/test_lemmas.leanother1.2 KB
crates/qedgen/src/api.rsscript32.3 KB
crates/qedgen/src/consolidate.rsscript6.9 KB
crates/qedgen/src/main.rsscript4.1 KB
crates/qedgen/src/project.rsscript3.1 KB
crates/qedgen/src/spec.rsscript19.3 KB
crates/qedgen/src/validate.rsscript5.6 KB
crates/qedgen/templates/.gitignoreother29 B
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.leanother293 B
crates/qedgen/templates/lean-toolchainother25 B
docs/CNAMEother10 B
docs/index.htmlother10.9 KB
docs/llms-full.txtmarkdown8.7 KB
docs/llms.txtmarkdown2.1 KB
docs/logo-dark.svgother648 B
docs/logo-light.svgother648 B
docs/style.cssother7.6 KB
example/escrow/.gitignoreother67 B
example/escrow/.prettierignoreother61 B
example/escrow/Anchor.tomlconfig353 B
example/escrow/Cargo.lockmanifest72.8 KB
example/escrow/Cargo.tomlmanifest215 B
example/escrow/migrations/deploy.tsscript428 B
example/escrow/package.jsonmanifest528 B
example/escrow/programs/escrow/Cargo.tomlmanifest376 B
example/escrow/programs/escrow/Xargo.tomlconfig62 B
example/escrow/programs/escrow/src/lib.rsscript6.7 KB
example/escrow/tests/escrow.tsscript8.6 KB
example/escrow/tsconfig.jsonconfig205 B
example/percolator/.cargo/config.tomlconfig33 B
example/percolator/.gitignoreother320 B
example/percolator/Cargo.lockmanifest8.5 KB
example/percolator/Cargo.tomlmanifest639 B
example/percolator/LICENSEother11.1 KB
example/percolator/README.mdmarkdown4.9 KB
example/percolator/examples/offsets.rsscript1.3 KB
example/percolator/scripts/audit-proof-strength.mdmarkdown6.4 KB
example/percolator/scripts/proof-strength-audit-results.mdmarkdown89.2 KB
example/percolator/scripts/run_kani_full_audit.shexecutablescript1.2 KB
example/percolator/spec.mdmarkdown108.4 KB
example/percolator/src/i128.rsscript20.4 KB
example/percolator/src/percolator.rsscript139.2 KB
example/percolator/src/wide_math.rsscript59.8 KB
example/percolator/tests/amm_tests.rsscript7.4 KB
example/percolator/tests/common/mod.rsscript4.7 KB
example/percolator/tests/fuzzing.proptest-regressionsother4.7 KB
example/percolator/tests/fuzzing.rsscript43.1 KB
example/percolator/tests/proofs_arithmetic.rsscript17.1 KB
example/percolator/tests/proofs_audit.rsscript35.0 KB
example/percolator/tests/proofs_instructions.rsscript64.8 KB
example/percolator/tests/proofs_invariants.rsscript21.0 KB
example/percolator/tests/proofs_lazy_ak.rsscript22.4 KB
example/percolator/tests/proofs_liveness.rsscript17.1 KB
example/percolator/tests/proofs_safety.rsscript104.2 KB
example/percolator/tests/proofs_v1131.rsscript25.4 KB
example/percolator/tests/unit_tests.rsscript93.8 KB
install.shexecutablescript4.9 KB
package.jsonmanifest1.1 KB
# 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 crates/qedgen/lean_support
lake build
```

### Run Tests

```bash
# Rust unit tests
cargo test

# Test Lean support library axioms
cd crates/qedgen/lean_support
lake env lean test_lemmas.lean

# Build the example escrow verification
cd example/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
```

## Architecture

### Crate Structure

**`crates/qedgen/`** - Single crate: CLI and Mistral API client
- `main.rs` - CLI entry points (generate, fill-sorry, spec, consolidate, setup)
- `api.rs` - Mistral API client, pass@N sampling, sorry-filling, retry logic
- `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

**`crates/qedgen/lean_support/`** - Canonical Lean axioms for Solana
- `QEDGen/Solana/Account.lean` - Account structure
- `QEDGen/Solana/Token.lean` - Token operations and conservation axioms
- `QEDGen/Solana/Authority.lean` - Authorization predicates
- `QEDGen/Solana/State.lean` - Lifecycle and state machines

### 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 (parameters match intent)

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

See `example/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 `crates/qedgen/lean_support/QEDGen/Solana/Token.lean` (or other module)
2. Document the trust assumption with a comment
3. Export in `QEDGen.lean`
4. Update SKILL.md support library API section
5. Test: `cd crates/qedgen/lean_support && 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
3. Fix the proof and re-run `lake build`

## 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
theorem cpi_correct (ctx : Context) :
    let cpi := build_cpi ctx
    cpi.program = TOKEN_PROGRAM_ID ∧ cpi.amount = ctx.amount := by
  unfold build_cpi
  exact ⟨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: 323kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 323kUpdated 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: 323kUpdated Claude CodeCodexVerifiedInstall