logos-co · jefdiesel · Jun 23, 2026
diff --git a/solutions/LP-0017.md b/solutions/LP-0017.md
@@ -0,0 +1,211 @@
+# Solution: LP-0017 — Whistleblower: censorship-resistant document upload + indexing
+
+**Submitted by:** jefdiesel
+
+## Summary
+
+Whistleblower is a censorship-resistant **upload → broadcast → anchor** pipeline on
+the Logos stack: a file's bytes go to **Logos Storage** (Codex) yielding a content
+CID; a JSON metadata envelope is broadcast over **Logos Delivery** (Waku) to a
+well-known permissionless topic; and a `(cid, metadata_hash)` tuple is anchored
+**on-chain** in a permissionless **LEZ** registry program — one PDA per CID — so a
+document's existence and metadata integrity are provable and **queryable by CID**.
+A permissionless, resumable **batch-anchor CLI** lets any third party gather
+broadcast CIDs and commit ≥10 in a single transaction. The pipeline is extracted
+into a reusable **`wb-index`** module with a documented API.
+
+The on-chain registry is **deployed and exercised on a real LEZ sequencer with
+`RISC0_DEV_MODE=0`**: single-CID `anchor_one` and **12- and 50-CID `anchor_batch`**
+transactions land and are read back by CID, using **real Codex CIDs and real
+canonical SHA-256 metadata hashes**.
+
+## Repository
+
+- **Repo:** https://github.com/jefdiesel/whistleblower-lp0017
+- **Demo video (narrated, `RISC0_DEV_MODE=0`):** https://github.com/jefdiesel/whistleblower-lp0017/releases/tag/v0.1.0
+- **Per-criterion status map:** [`SUBMISSION.md`](https://github.com/jefdiesel/whistleblower-lp0017/blob/main/SUBMISSION.md)
+
+## Approach
+
+**Architecture.** Four Rust crates plus a Qt/QML app and a SPEL on-chain program:
+
+- `wb-types` — dependency-light shared types: `MetadataEnvelope` (all LP-0017
+  envelope fields), the **canonical, language-agnostic `metadata_hash`**
+  (length-prefixed, domain-separated SHA-256 so the Rust core and the C++/QML app
+  agree byte-for-byte), `RegistryRecord`, `AnchorEntry`, the Delivery topic.
+- `wb-index` — the reusable module: `StorageClient`/`DeliveryClient`/`RegistryClient`
+  traits with `HttpStorage` (Codex REST) and `HttpDelivery` (Waku REST) concrete
+  impls, a `Publisher` (upload-with-retry + dedup broadcast), and a
+  `BatchAnchorRunner` (subscribe → accumulate → batch-anchor → checkpoint → resume).
+- `wb-batch-anchor` — the permissionless CLI.
+- `wb-registry-program` — the SPEL `#[lez_program]`: one PDA per CID
+  (`pda = compute_pda(program_id, SHA256("WB-CID-PDA-v1" || cid))`), storing
+  `borsh(RegistryRecord{cid, metadata_hash, anchor_timestamp})`, idempotent via
+  claim-if-default; `anchor_batch(Vec<AnchorArg>)` for ≥10 and a scalar `anchor_one`.
+- `wb-lez-registry` — the production `RegistryClient` against a live LEZ sequencer.
+
+**On-chain choice + justification (LEZ program vs zone SDK).** We chose a **LEZ
+program**. The registry is inherently *public, shared, permissionless* state — any
+third party must be able to anchor and anyone must be able to query by CID — which
+maps directly onto a public-state LEZ program with per-CID PDAs. The zone-SDK /
+direct-consensus-inscription path requires a single designated actor to perform
+inscription (decentralised sequencers aren't shipped), which would re-introduce the
+coordination/trust point the prize explicitly wants to avoid. A LEZ program keeps
+anchoring permissionless and the data model (one account per CID, queryable) clean.
+
+**Key implementation decisions / what didn't work (genuine dead-ends hit):**
+
+- **SPEL instruction wire format.** The on-chain instruction is **risc0
+  word-serde** of the generated `Instruction` enum (`Program::serialize_instruction`
+  = `risc0_zkvm::serde::to_vec`) — *not* borsh and *not* an Anchor-style
+  `SHA256("global:…")` discriminator (that exists in the IDL only, for lssa-lang
+  compatibility). An initial borsh/discriminator assumption was wrong; verified
+  against the pinned LEZ v0.1.2 + SPEL sources.
+- **The batch revert.** The first batch landed in a block but wrote nothing. Root
+  cause: nssa's `affected_public_account_ids = signer_account_ids() ++
+  message.account_ids`, and the guest receives that whole set as `pre_states`. The
+  signer-less registry IDL means a fee-payer signature **prepends an account**, so
+  `pre_states.len() == entries.len()+1` and the guest's `records.len() ==
+  entries.len()` check reverts. Fix: submit with an **empty witness** (matching the
+  SPEL-generated client for a signer-less program). After this, 12/12 and 50/50
+  persist.
+- **`Vec<struct>` instruction args.** The SPEL IDL CLI cannot encode a
+  `Vec<#[account_type] struct>` argument, so the batch is submitted by a custom
+  client (`wb-lez-registry`) that builds the same risc0 word-serde value the
+  generated client would; a scalar `anchor_one` sibling exists for the CLI path.
+- **`ring`/riscv32 (LEZ #468).** Guest cross-compile pulls `ring` via
+  `risc0-zkvm` default features; worked around by disabling them.
+
+**Why Logos.** Censorship resistance is the whole point: Storage keeps bytes
+durable without identifying the uploader; Delivery propagates the CID
+peer-to-peer with no central index; the LEZ registry is permissionless (no token
+or authority required to anchor) and trustlessly queryable. A centralised
+alternative reintroduces a host that can be subpoenaed, deplatformed, or throttled —
+exactly the failure mode whistleblowers face. Batch anchoring also **decouples
+publication from on-chain registration**, so a publisher never needs to hold tokens
+or coordinate with anyone.
+
+## Success Criteria Checklist
+
+### Functionality
+
+- [x] **Upload → CID** — `HttpStorage`/`Publisher::upload`; a **live Codex node**
+  returned real CIDs (e.g. `zDvZRwzm…`).
+- [x] **Broadcast envelope** — `HttpDelivery`/`Publisher::broadcast` to the
+  documents topic; envelope carries `cid, title, description, content_type,
+  size_bytes, timestamp, tags`. Built + unit-tested against the documented nwaku
+  REST. *Caveat:* not exercised against a **live** Waku node — no macOS-arm64
+  Delivery binary exists (issue filed); runs on Linux. The dev path is used in the
+  local demo.
+- [x] **Optional on-chain anchor action** — distinct from upload; `anchor_one`/
+  `anchor_batch` invoked any time after upload.
+- [x] **Batch anchor tool** — `BatchAnchorRunner` + CLI: subscribe→accumulate
+  `(CID, metadata_hash)`, **single batch tx**, **permissionless** (signer-less IDL,
+  empty witness), **idempotent** (re-anchoring a known CID is a no-op — verified by
+  re-running a batch).
+- [x] **On-chain registry** — LEZ program (justified above); stores
+  `(CID, metadata_hash, anchor_timestamp)`, **queryable by CID**, **≥10 per tx**
+  (12- and 50-CID batches verified on-chain).
+- [x] **Document-indexing module** — `wb-index`, self-contained, documented API,
+  no dependency on the Basecamp app.
+
+### Usability
+
+- [ ] **Basecamp GUI** — ⚠️ the complete `ui_qml` module (QML + C++ backend, Logos
+  bridge, module deps) is in source, **but not built/packaged into a loadable
+  asset**: building needs Nix + Qt6, which the build hardware (macOS) couldn't
+  provide. Honest gap.
+- [x] **Module README/SDK** — `wb-index` README + `docs/ARCHITECTURE.md` cover the
+  API and integration.
+- [x] **IDL via SPEL** — generated and committed (`whistleblower_registry-idl.json`).
+
+### Reliability
+
+- [x] **Upload retry w/ exponential backoff** — `RetryPolicy`; unit-tested
+  (succeeds-after-N and exhaustion-with-clear-error).
+- [x] **Dedup broadcast** — CID dedup; unit-tested.
+- [x] **Resumable batch** — atomic `CheckpointStore`; resume tested incl.
+  cross-process.
+
+### Performance
+
+- [x] **Single vs 50-CID cost** — measured on a Mac mini M4, `RISC0_DEV_MODE=0`:
+  **single-CID ≈ 3.0 ms**, **50-CID ≈ 48.6 ms** (= **0.97 ms/CID**, ~3× cheaper per
+  CID). *Note:* LEZ has **no "compute unit"** meter, and the registry uses **public
+  state** → **public execution** (no per-transaction STARK proof), so we report
+  executor **wall-time** rather than CU/prove-time. Details: `docs/benchmarks.md`.
+
+### Supportability
+
+- [ ] **Deployed/tested on LEZ devnet/testnet** — ⚠️ deployed to a **real local
+  standalone LEZ sequencer** (image id documented as the program address; anchors
+  with `RISC0_DEV_MODE=0`). There is **no published public LEZ sequencer endpoint**
+  to deploy to — the public testnet that exists is the L1/Bedrock node, not a LEZ
+  execution endpoint (issue filed). Honest gap vs a "public testnet" reading.
+- [~] **E2E upload→broadcast→batch-anchor tests in CI vs standalone sequencer** —
+  e2e pipeline tests exist and gate CI on the core; the **sequencer-backed** job is
+  best-effort (`continue-on-error`) because the RISC0/LEZ stack isn't reproducible
+  in stock CI. The real sequencer run is demonstrated on the build machine.
+- [x] **CI green** on default branch (fmt + build + test + clippy, Rust 1.94).
+- [x] **README** — build, deploy/program address, running the app + batch tool,
+  query-by-CID.
+- [x] **Reproducible `RISC0_DEV_MODE=0` demo** — the on-chain anchor→confirm→query
+  demo runs live with real execution; the full pipeline's Delivery beat uses the
+  dev path locally (live Waku on Linux).
+- [~] **Recorded video showing terminal output to confirm `RISC0_DEV_MODE=0`** —
+  the narrated video shows `RISC0_DEV_MODE=0` confirmed in the sequencer env + real
+  executor execution + per-tx executor times. ⚠️ It does **not** show *proof
+  generation* because the public-state registry runs as **public execution**, which
+  produces **no per-transaction STARK proof** (proofs are for private state). This
+  is a deliberate, justified design choice for a public registry, called out
+  explicitly so it isn't mistaken for dev-mode.
+
+## FURPS Self-Assessment
+
+### Functionality
+
+Upload (real Codex CID), broadcast (envelope w/ all required fields), optional
+on-chain anchor, permissionless idempotent batch anchor (≥10; 50 verified),
+public registry queryable by CID, and a reusable module. Limitation: live Waku
+broadcast and the built Basecamp GUI are not demonstrated on the build hardware
+(both upstream/environment-blocked; issues filed).
+
+### Usability
+
+CLI exposes `publish`/`run`/`anchor`/`query`/`status`. The module is one dependency
+edge (`wb_index`) with traits + ready HTTP impls. The Qt/QML app source is complete
+but not built (Nix+Qt6).
+
+### Reliability
+
+Exponential-backoff upload retry with a clear exhaustion error; CID-deduplicated
+broadcast; atomic checkpointed batch resume (cross-process tested). The on-chain
+program is idempotent (claim-if-default), so re-anchoring never fails.
+
+### Performance
+
+Single-CID ≈ 3.0 ms, 50-CID ≈ 48.6 ms (0.97 ms/CID) public execution on an M4,
+`RISC0_DEV_MODE=0`. Linear in batch size; batching ~3× cheaper per CID. No CU
+concept on LEZ; public execution has no per-tx proof.
+
+### Supportability
+
+30 passing tests (`cargo test --workspace`), CI gating job green, structured
+modules, `HANDOFF.md` + `SUBMISSION.md` + `docs/`. On-chain evidence (tx hashes,
+`seq.log`, deployed `.bin`) reproducible per `HANDOFF.md`. 6 upstream issues
+drafted in `docs/ISSUES-TO-FILE.md`.
+
+## Supporting Materials
+
+- **Narrated demo video** (`RISC0_DEV_MODE=0`, real Codex CIDs + SHA-256 hashes):
+  https://github.com/jefdiesel/whistleblower-lp0017/releases/download/v0.1.0/whistleblower-lp0017-narrated.mp4
+- **Benchmarks:** `docs/benchmarks.md`.
+- **Architecture:** `docs/ARCHITECTURE.md`. **Per-criterion map:** `SUBMISSION.md`.
+- **Upstream issues encountered:** `docs/ISSUES-TO-FILE.md` (SPEL `Vec<struct>`,
+  SPEL README drift, Storage Content-Type/base-path, no public LEZ RPC, ring/#468,
+  no macOS Waku binary).
+
+## Terms & Conditions
+
+By submitting this solution, I confirm that I have read and agree to the
+[Terms & Conditions](../TERMS.md).