logos-co · Tranquil-Flow · May 20, 2026 · May 20, 2026
diff --git a/solutions/LP-0013.md b/solutions/LP-0013.md
@@ -0,0 +1,79 @@
+# Solution: LP-0013 — Token Program Improvements: Authorities
+
+**Submitted by:** Tranquil-Flow
+
+## Summary
+
+Mint authority lifecycle for the LEZ Token program — create / mint / rotate / revoke — with a proven on-chain semantic deployment under `RISC0_DEV_MODE=0`. Authority revocation is irreversible by construction: `current_authority: Option<[u8; 32]>`, where `None` is permanent. Post-revoke mint attempts and post-revoke authority restorations are both rejected on-chain at `Program error 2008: authority has been revoked`, captured live in the sequencer log.
+
+## Repository
+
+- **Repo:** <https://github.com/Tranquil-Flow/lp0013-token-suite>
+
+## Approach
+
+The implementation is split into a runtime-agnostic authority crate (`admin-authority-core`), a pure token state-transition layer (`mint-core`), an instruction-level harness (`mint-program`), an evaluator-facing SDK (`mint-sdk`), and a SPEL guest source (`spel-spike/`) that ports the same semantics into the RISC0/LEZ account adapter. The offline harness has zero LEZ runtime dependencies; the guest is exercised on a live local sequencer via the host-side driver in `spel-spike/live_lifecycle.rs`.
+
+### Key design decisions
+
+1. **Single-`None`-represents-revoked encoding.** `current_authority: Option<[u8; 32]>`; `None` means permanently revoked. We considered a two-state model (`is_revoked: bool` + `authority`) and rejected it — the redundant state opens accidental "un-revoke" paths and makes the audit story harder. `Option<T>` collapses both states into one path the type system enforces.
+2. **Offline-first proof model.** Canonical authority semantics are proven in pure Rust (`mint-core`, 7 unit tests), runtime-agnostic. The SPEL guest is a separate evidence layer demonstrating the same semantics survive translation to the RISC0/LEZ account adapter. We considered duplicating logic in the guest and rejected it — a structurally aligned port + on-chain receipts is stronger evidence than a single-runtime implementation.
+3. **Hand-written canonical IDL + real SPEL-generated alongside.** The canonical hand-written IDL is the documented superset (discriminators, declared errors, expanded `Option<T>`, nested account bodies). The real `spel generate-idl` artifact is checked in alongside as additive evidence the same instruction surface re-emerges from the real tool. We tried using only the SPEL-generated output and rejected it — the current SPEL revision emits less than the spec asks for; the canonical hand-written superset documents the full surface.
+4. **`examples/config-pda-gated` as the RFP-001 demonstration.** Derives a deterministic config-PDA authority and proves only the matching gate can mint before revocation. Exercises the canonical RFP-001 admin-authority-lib pattern offline so evaluators don't need the LEZ toolchain to validate the model.
+
+### Why the Logos stack
+
+LEZ gives us zk-proven deterministic execution: the authority guard `require_authority` is a panic inside the RISC0 guest, so the sequencer's rejection of a post-revoke mint is cryptographically backed, not just trusted. A centralized alternative (Solana / EVM) gives faster CU/gas but loses the deterministic-rejection-by-proof property — under LEZ, "authority has been revoked" is an artifact of the proof, not a trust boundary.
+
+## Success Criteria Checklist
+
+Mirrored from the LP-0013 spec.
+
+- [x] **Functionality 1 — Variable-size tokens via mint authority.** `mint-core::MintDefinition` + `mint-program::MintTo` enforce authority on every mint; `examples/variable-supply` exercises the full lifecycle.
+- [x] **Functionality 2 — Minting by authority.** `admin-authority-core::AuthorityInfo::authorize` + `mint-program::MintTo`; live on-chain proof in `docs/LEZ_PROOF_LOG.md` with five real txhashes.
+- [x] **Functionality 3 — Authority rotation and revocation.** `mint-program::SetMintAuthority` (Some → rotation, None → revocation); atomic, unit-tested + on-chain proven.
+- [x] **Functionality 4 — Two example integrations.** `examples/variable-supply` (variable supply with rotation) + `examples/fixed-supply` (revoked-authority fixed supply) + `examples/config-pda-gated` (RFP-001 reusable gate) — three examples, exceeding the spec's requirement of two.
+- [x] **Functionality 5 — Self-sufficient agnostic library (RFP-001).** `admin-authority-core` has zero deps on `nssa_core` / program runtime; `examples/config-pda-gated` shows config-PDA-derived authority gating.
+- [x] **Usability — SDK.** `mint-sdk::TokenClient` — create / mint / rotate / revoke / query.
+- [x] **Usability — SPEL IDL.** `idl/admin-authority.idl.json` (hand-written canonical superset) + `idl/admin-authority.idl.spel-generated.json` (real `spel generate-idl` output).
+- [x] **Reliability — atomicity.** `AuthoritySlot::set` returns `Err` before any write; 31 unit tests cover the failure paths; on-chain confirmed (post-revoke `set_mint_authority` rejected without state mutation).
+- [x] **Reliability — deterministic rejection.** `TokenError::AuthorityRevoked` in offline harness; on-chain proof at `Program error 2008` captured live.
+- [x] **Performance — CU costs documented.** `docs/BENCHMARKS.md` §"Compute units (CU)" — `create_mint` 8.38 ms, `mint_to` 7.58 ms, `set_mint_authority` 6.76 ms; rejected post-revoke operations 4.21–4.43 ms.
+- [x] **Supportability — README + reproducible demo + narrated video.** `README.md` covers usage; `scripts/demo.sh` is the offline reproducer; live-LEZ host driver in `spel-spike/live_lifecycle.rs`; narrated terminal demo at <https://youtu.be/3hQd2G8O-UM>.
+- [x] **Supportability — CI.** `.github/workflows/ci.yml` runs fmt + check + test + clippy + docs validator on every push.
+
+## FURPS Self-Assessment
+
+### Functionality
+
+The submission implements the full mint authority lifecycle: create mint, mint tokens to a holding, rotate authority to a new key, and revoke authority to `None`. Variable-supply tokens have an active authority that can mint; fixed-supply tokens are represented by setting `current_authority = None`. The `examples/config-pda-gated` binary demonstrates the RFP-001 reusable pattern by deriving a deterministic config-PDA authority. All four authority lifecycle states (active, rotated, revoked-cannot-mint, revoked-cannot-restore) are exercised both in offline unit tests and on a live LEZ sequencer with txhashes captured in `docs/LEZ_PROOF_LOG.md`. There is no support for SPL-compatible freeze authority or close authority — those were out of scope per the spec.
+
+### Usability
+
+`mint-sdk::TokenClient` provides an async-ready client API: `create_variable_mint`, `create_fixed_mint`, `mint_to`, `rotate_authority`, `revoke_authority`, plus `supply` / `balance` / `current_authority` queries. The offline CLI (`mint-cli`) wraps the SDK for evaluator-friendly demos via `cargo run -p mint-cli -- demo-variable` / `demo-fixed`. Three runnable examples in `examples/` are single-command (`cargo run -p variable-supply` etc.) and require no LEZ toolchain. The host-side live-LEZ driver in `spel-spike/live_lifecycle.rs` requires `lgs` + `cargo-risczero` + `spel` — its scaffold-and-deploy walkthrough is in `spel-spike/README.md`.
+
+### Reliability
+
+Failed instructions leave state unchanged: `AuthoritySlot::set` returns `Err` before any write, and `mint-program::ProgramState` clones-then-commits so a partial failure cannot corrupt the in-memory harness. On-chain confirmation: a post-revoke `set_mint_authority` was rejected by the sequencer at `Program error 2008: authority has been revoked` without state mutation (verified by re-reading the mint PDA after the rejection). 31 unit tests across `admin-authority-core`, `mint-core`, and `mint-program` cover the failure paths (zero-amount mint, supply overflow, balance overflow, post-revoke mint, post-revoke restore, rotation-by-wrong-key).
+
+### Performance
+
+Per-operation Risc0 zkVM executor time extracted from the live sequencer log: `create_mint` 8.38 ms, `mint_to` 7.58 ms, `set_mint_authority` (rotate/revoke shares one code path) 6.76 ms. Rejected post-revoke operations cost ~50% less (4.21–4.43 ms) because execution halts at the authority guard before any account writes — deterministic-rejection visible in the CU profile. Full breakdown in `docs/BENCHMARKS.md`. Bottleneck is the per-instruction Risc0 proving overhead, not the offline state-transition layer (which is sub-microsecond).
+
+### Supportability
+
+CI is green on `main` via `.github/workflows/ci.yml` (fmt + cargo check + cargo test + clippy with `-D warnings` + a docs-presence validator). 31 unit tests + 3 example tests + 1 docs validator all pass on a fresh clone. Deployment instructions for the live-LEZ semantic guest are in `spel-spike/README.md` with the exact `lgs` + `wallet` commands used to capture the proof log. Three runnable evaluator examples (`variable-supply`, `fixed-supply`, `config-pda-gated`) require only `cargo` and exercise the full SDK surface. The codebase is split into seven small crates so future maintainers can swap out individual layers (authority semantics, mint state, instruction harness, SDK) without touching the others.
+
+## Supporting Materials
+
+- **Narrated demo video:** <https://youtu.be/3hQd2G8O-UM>
+- **On-chain proof log (txhashes):** <https://github.com/Tranquil-Flow/lp0013-token-suite/blob/main/docs/LEZ_PROOF_LOG.md>
+- **CU benchmarks:** <https://github.com/Tranquil-Flow/lp0013-token-suite/blob/main/docs/BENCHMARKS.md>
+- **Spec compliance map (extended):** <https://github.com/Tranquil-Flow/lp0013-token-suite/blob/main/docs/SPEC_COMPLIANCE.md>
+- **SPEL status / architecture decisions:** <https://github.com/Tranquil-Flow/lp0013-token-suite/blob/main/docs/SPEL_STATUS.md>
+- **Canonical hand-written IDL:** <https://github.com/Tranquil-Flow/lp0013-token-suite/blob/main/idl/admin-authority.idl.json>
+- **Real `spel generate-idl` output:** <https://github.com/Tranquil-Flow/lp0013-token-suite/blob/main/idl/admin-authority.idl.spel-generated.json>
+
+## Terms & Conditions
+
+By submitting this solution, I confirm that I have read and agree to the [Terms & Conditions](../TERMS.md).