> Markdown twin of https://golantern.xyz/docs/deliverables/d1/ — index of every page: https://golantern.xyz/docs/llms.txt

# D1 — On-chain blacklist registry

**Statement of Work:** Deliverable 1 · **Target:** Week 1 (7–13 Sep) · **Status:** Complete and closed

A Soroban contract that replaces the hardcoded demo deny-list baked into the wallet's scanner. A list inside one wallet's bundle protects one wallet's users; a contract any wallet or dApp can read protects everyone.

## Evidence

| SOW §6.1 evidence | Where | What it shows | Status |
|---|---|---|---|
| stellar.expert testnet contract page | [`CBJWD6SA…G623F`](https://stellar.expert/explorer/testnet/contract/CBJWD6SAQ3OGLDKMQROSWVJGW6U27AESLJIURTMFPLNC4UQH5H2G623F) | The deployed contract, its WASM hash, creation time, storage entries, and a history of `report` and `set_status` calls from several accounts | Present |
| WASM hash published in the README | [README — Testnet smart contracts](https://github.com/kimerran/stellar-lantern/blob/main/README.md#testnet-smart-contracts) | `40fd37718c3fbc7f849c4d414364cdd86c01b4db9ab86be9099007ba5be23783`, identical on the published and sandbox instances and to a fresh local build | Present |
| Sample on-chain report transaction with the fee routed to the treasury | [`81fa64a6…8ed8`](https://stellar.expert/explorer/testnet/tx/81fa64a67eb583f8fb499b2d425e88754b701480f1c8aff2e3ad8a6725fb8ed8) | One transaction carrying the write, the attribution and the 1 XLM transfer reporter → treasury; the smoke script asserts the treasury delta equals the fee | Present |
| Recordings (registry end to end; captioned terminal capture) | *TODO: link* | Report → fee lands → address reads flagged → admin disputes → warning stops, on the public explorer; then the same loop from the command line | Pending link |
| Evidence decks | *TODO: link* | Proof of Deliverables (7 slides) and Technical Documentation & Demo Evidence (8 slides) | Pending link |

## What a user can do when this is done

Anyone can report a Stellar address as a scam by paying a small fee, and anyone — a wallet, a dApp, a script — can ask whether an address has been reported, by whom, why, and how many times, without owning an account, signing anything or paying. A reported address raises a warning in every wallet that reads the registry, not just the one where it was reported. An administrator can mark an entry Disputed or Revoked so a wrongful report stops raising a warning while the record of it survives.

## Traceability

| SOW clause | Change | Evidence | Status |
|---|---|---|---|
| A registry contract on Soroban with a data model for reports | [`22de070`](https://github.com/kimerran/stellar-lantern/commit/22de070) — crate scaffold, nine-field entry, storage schema, constructor | Contract page; [reference: data model](https://github.com/kimerran/stellar-lantern/blob/main/docs/blacklist-registry.md) | Evidenced |
| Fee-gated `report()` with the fee routed to a treasury in the same transaction | [`072c336`](https://github.com/kimerran/stellar-lantern/commit/072c336) | [Report tx `81fa64a6…`](https://stellar.expert/explorer/testnet/tx/81fa64a67eb583f8fb499b2d425e88754b701480f1c8aff2e3ad8a6725fb8ed8); smoke script asserts +1 XLM on the treasury | Evidenced |
| Admin status transitions (Active / Disputed / Revoked) and config management | [`76edfba`](https://github.com/kimerran/stellar-lantern/commit/76edfba) | `set_status` transactions on the contract history; sandbox tx [`ae57d189…`](https://stellar.expert/explorer/testnet/tx/ae57d1890c5ef6198e08e9723d063b1186889bef4b20286c826deb984b9130b8) | Evidenced |
| Public read API (`is_flagged`, `get`, `count`, `list`) | [`4d7b093`](https://github.com/kimerran/stellar-lantern/commit/4d7b093) | Interface tab on the contract page; unit tests with committed snapshots | Evidenced |
| Fee-free read path for per-signature screening | [`3bcfc4e`](https://github.com/kimerran/stellar-lantern/commit/3bcfc4e) — deterministic ledger key + `getLedgerEntries` | `scripts/hot-read-blacklist-registry.mjs` prints FLAGGED for the demo address with no account and no signature; the worked example in the reference is re-derived by the test suite | Evidenced |
| Continuous integration for the contract | [`619214a`](https://github.com/kimerran/stellar-lantern/commit/619214a) — fmt, clippy `-D warnings`, tests, wasm build, vendored-artifact check | [Contracts lane](https://github.com/kimerran/stellar-lantern/actions/workflows/contracts.yml) | Evidenced |
| Deployed to testnet with the evidence the SOW names | [`96c4713`](https://github.com/kimerran/stellar-lantern/commit/96c4713) — re-runnable deploy script that refuses an unverifiable hash; smoke script | Contract page; README row; report tx | Evidenced |
| Documented end to end | [`7983bd3`](https://github.com/kimerran/stellar-lantern/commit/7983bd3) — full ABI, error table, data model, events, both read paths | [`docs/blacklist-registry.md`](https://github.com/kimerran/stellar-lantern/blob/main/docs/blacklist-registry.md) | Evidenced |
| §3.9 — no secrets in the repository | Admin and treasury are local `stellar keys` identities; deploy script documents that real secrets live in environment secrets | Repository grep; CI | Evidenced |

## Scope notes

- The registry **informs a warning; it does not gate a transaction on its own**. Attribution (who reported) is stored so a consumer can weight the claim; an auto-block on one stranger's word was deliberately not built.
- Evidence is a 32-byte hash. The material itself never goes on chain.
- The wallet did not read the registry in Week 1; that wiring is Deliverable 2's Screen stage (done) and Deliverable 3's pre-sign screen.

## Implementation choices

- **Two instances of the same bytecode.** The published deployment is the one named in the README and the reference; a separate QA sandbox instance ([`CDPEFCHA…53F4N`](https://stellar.expert/explorer/testnet/contract/CDPEFCHAYIGBHZWEF4TA5VC4V6TX4DIO3KM2E25TZARQMPR2J6E53F4N)) lets a tester hold the admin key and exercise the admin paths without touching the published one. Same WASM hash on both.
- **The deploy script is the runbook.** Testnet is periodically reset; the script re-creates identities only if absent, prints every value the README needs, and aborts rather than publish a WASM hash it cannot reproduce locally.
- **Documentation coupled to code.** The reference document's worked example is parsed by the test suite and re-derived, so a half-finished re-deployment fails the tests instead of shipping a document that lies.