diff --git a/solutions/LP-0013.md b/solutions/LP-0013.md new file mode 100644 index 0000000..1b7bcda --- /dev/null +++ b/solutions/LP-0013.md @@ -0,0 +1,172 @@ +# Solution: LP-0013 — Token program improvements: authorities + +**Submitted by:** Tranquil-Flow + +## Summary + +This submission implements a mint-authority lifecycle for LEZ tokens: variable-supply minting by an authority, atomic authority rotation, permanent revocation to `None` for fixed-supply tokens, deterministic post-revocation rejection, SDK/CLI support, examples, and IDL artifacts. + +The corrected LEZ guest is deployed and exercised on the public LEZ testnet (`https://testnet.lez.logos.co/`, real consensus, `RISC0_DEV_MODE=0`). The load-bearing 2026-06-04 lifecycle proves the reviewer-critical fix: two mints to the same holding account both confirm and accumulate (`60 + 40 = 100`), then a post-revocation mint to that already-existing holding is rejected by the authority guard rather than by an account-initialization side effect. + +## Repository + +Public repository: + +```text +https://github.com/Tranquil-Flow/lp0013-token-suite +``` + +**License:** MIT OR Apache-2.0 + +## Approach + +The implementation splits the token-authority surface into reusable library and LEZ-facing layers: + +1. `mint-core` and `admin-authority-core` define mint state, authority state, deterministic errors, and offline contract tests. +2. `mint-program` implements the corrected four-instruction LEZ guest surface: `create_mint`, `create_holding`, `mint_to`, and `set_mint_authority`. +3. `mint-sdk`, `mint-cli`, and `onchain-program/examples` provide SDK/client flows for Logos-module interactions and live LEZ lifecycle execution. +4. `idl/` contains SPEL-generated IDL artifacts for the deployed four-instruction surface; the hand-written IDL is retained only as a caveated design reference. +5. `examples/` includes fixed-supply, variable-supply, and config-PDA-gated integrations. +6. `scripts/demo-localnet.sh`, `scripts/preflight-localnet-e2e.sh`, `scripts/demo-testnet-live.sh`, and `scripts/ci-verify-testnet.sh` provide reproducible localnet and public-testnet verification paths. + +## Public-testnet evidence + +Network: `https://testnet.lez.logos.co/` + +ProgramId / ImageID: + +```text +32335764e583cd45684e0100ca63a3564a02274daa6ea6a5f758fad671b0a9ce +``` + +Explorer-form base58 ProgramId: + +```text +4NxnuVrQBiwq2dCwZ3g3EnaD8JXGgBwEf6CR2a8L9JXF +``` + +Canonical lifecycle: + +| Step | Transaction hash | Verdict | +|---|---|---| +| deploy_program | `5b39deec38e49bb1bedf1956e5d7429ec20e3c009f0ccfe7a4fc449685cb4ce0` | `Some(ProgramDeployment)` | +| create_mint | `7d1dcb04b5f339b33f04a120b7334cf9802720d4a917e600becd62476e44da74` | `Some(Public)` | +| create_holding | `520d080b833c7e4038a1aa214bba43a3fc97328e8f379a093b74ca3e32be5893` | `Some(Public)` | +| mint_to(60) | `8c865d0184f55ce5a881e24c8c125cd3729c5f90a4b83d0484c8d1610f743f61` | `Some(Public)` | +| mint_to(40) | `c63168b7f615221ab2425b2ba003d32183f4df2e482eb4203e4e216675993d21` | `Some(Public)` | +| set_mint_authority(None) | `8c4b08b5c750c57d0dbb4e9f43c32b7c0f2627ce5508da85408e3aaf01f5a331` | `Some(Public)` | +| mint_to(post-revoke) | `6e92e605e932756332c9721a4e4754f155780069490b256fe67b35f374a972d1` | not included (`Transaction is None`) | + +Final state read from chain: + +- mint PDA `HtCYkKN5K3dUVnPhJ4tCNpvDrnEcLZKgh8i4PkUjigfu`: `authority=None`, `supply=100`, `decimals=6` +- holding PDA `4yswbZaRR1HQt4a5HS4uN7nLvAwL1txHTMSXKo1WZH2S`: `balance=100` +- signer / authority: `B6Sa77taeQgQ3FXHP88wjs15sJw3EyfcRjnSAZKnYchb` + +Read-only re-verification: + +```bash +bash scripts/demo-testnet-live.sh verify +``` + +Full requirements matrix: `docs/LP0013_REQUIREMENTS_MATRIX.md` in the implementation repository. + +If `wallet` is unavailable, build it from the LEZ `v0.1.2` tag as described in the implementation repository docs (`docs/LEZ_PROOF_LOG.md` and `onchain-program/README.md`). + +## What was fixed after the previous review + +The rejected build used `#[account(init, pda)]` on the recipient holding account inside `mint_to`. That meant: + +1. a second mint to the same holding failed because `init` rejected the already-claimed account; and +2. the post-revocation mint was rejected before the authority guard ran, so it did not prove revoked-authority enforcement. + +The corrected guest splits holding creation from minting: + +- `create_holding(#[account(init, pda)] holding, #[account(signer)] payer)` claims the holding once. +- `mint_to(#[account(mut, pda)] mint, #[account(mut, pda)] recipient_holding, #[account(signer)] authority, amount)` mutates an existing holding and performs `require_authority` before any state change. + +The public-testnet lifecycle above demonstrates this distinction on chain: both mints land into the same holding, then the post-revocation mint targets the same existing holding and is rejected by the authority guard. + +## Success Criteria Checklist + +### Functionality + +- [x] Variable-size tokens through minting authority. +- [x] Mint authority set at token initialization. +- [x] Minting by the authority, with repeated mints to the same holding account (`60 + 40 = 100`) verified on the public testnet. +- [x] Authority rotation and permanent revocation to `None`. +- [x] Fixed-supply behavior after revocation: post-revocation mint is rejected and supply remains `100`. +- [x] Deterministic revoked-authority rejection through the authority guard, not an account-init side effect. + +### Usability + +- [x] SDK/module support through `mint-sdk`, `mint-cli`, and `onchain-program/examples`. +- [x] At least two example integrations: fixed-supply, variable-supply, and config-PDA-gated examples are included. +- [x] SPEL-generated IDL artifacts are included under `idl/`. +- [x] README and spec-compliance docs explain build, localnet, and public-testnet verification commands. + +### Reliability + +- [x] Contract tests cover repeated minting to the same holding and post-revocation guard rejection. +- [x] Offline workspace tests and validator self-tests run in CI. +- [x] Public-testnet evidence can be re-queried read-only without private keys or faucet access. +- [x] Standalone local-sequencer e2e is included in CI config via hosted preflight plus manual self-hosted prepared-run job, and a real `RISC0_DEV_MODE=0` prepared-host run passed on 2026-06-09. + +### Performance + +- [x] CU methodology and platform limitation are documented in `docs/BENCHMARKS.md`. +- [x] The public testnet does not expose per-transaction CU, so the repository avoids inventing chain-native CU numbers and labels local sequencer/executor measurements honestly. + +### Supportability + +- [x] Deployable guest source lives in the repository under `onchain-program/`. +- [x] Public-testnet ProgramId/ImageID and tx hashes are documented. +- [x] `scripts/demo-localnet.sh` supports standalone local-sequencer reproduction under `RISC0_DEV_MODE=0`. +- [x] `.github/workflows/ci.yml` includes `local-sequencer-e2e-preflight` and manual `local-sequencer-e2e`. +- [x] `scripts/demo-testnet-live.sh verify` and `scripts/ci-verify-testnet.sh` support public-testnet re-verification. +- [x] Fresh narrated demo video recorded and linked: https://youtu.be/rUgsCCPiQfo + +## Local verification commands + +```bash +cargo fmt --all -- --check +cargo check --workspace +cargo test --workspace +cargo clippy --workspace --all-targets -- -D warnings +python3 scripts/validate-submission-docs.py +python3 -m pytest tests/test_validate_submission_docs.py -q +``` + +## Video status + +Fresh narrated demo video: https://youtu.be/rUgsCCPiQfo. This recording is the final video evidence for the corrected public-testnet lifecycle. + +## Honesty note + +The 2026-06-03 public-testnet run (`ProgramId 4153e159…`, `ImageID 59e15341…`) is superseded historical evidence only. It used the pre-fix single-`init` holding pattern; the load-bearing fix evidence is the 2026-06-04 corrected run documented above. + +## FURPS Self-Assessment + +### Functionality + +The implementation delivers the requested token mint-authority lifecycle and the reviewer-critical fix. Holding creation is separated from minting, repeated mints accumulate on chain, and revocation is enforced by the authority guard. + +### Usability + +Evaluators can run library tests, inspect the SPEL-generated IDL, try the examples, run localnet verification, and re-query public-testnet evidence from a clean clone. The final narrated video is recorded and linked above. + +### Reliability + +The codebase contains deterministic contract tests for variable supply, authority rotation/revocation, repeated minting, and invalid authority paths. The public-testnet verifier checks both transaction inclusion and final mint PDA state; the local-sequencer path is also represented in CI and backed by a prepared-host run. + +### Performance + +The submission documents the current LEZ CU visibility limitation clearly. It uses available executor/local sequencer evidence without pretending the public testnet exposes per-transaction CU telemetry. + +### Supportability + +The repository is public, dual-licensed MIT/Apache-2.0, documented, CI-backed, and includes scripts for prerequisite checks, localnet verification, and public-testnet evidence verification. The canonical proof artifacts identify the 2026-06-04 corrected public-testnet lifecycle and 2026-06-09 standalone local-sequencer prepared-host run as final evidence. + +## Terms & Conditions + +By submitting this solution, I confirm that I have read and agree to the [Terms & Conditions](../TERMS.md), and that the implementation is original work published under MIT OR Apache-2.0 licensing.