docs: present CipherBid engineering and verified mainnet evidence

AGENTS.md

@@ -21,5 +21,5 @@ Features target `development`; promotion is `development -> staging -> main` thr
 ## Required gates
 
 - Web: format check, lint, strict TypeScript, unit/integration tests, Playwright, production build.
-- Cairo: `scarb fmt --check`, `scarb build`, `snforge test` in WSL `Ubuntu-24.04`.
+- Cairo: `scarb fmt --check`, `scarb build`, `snforge test` in WSL `Ubuntu`.
 - Security: dependency, secret, static analysis, value-conservation invariants, independent contract review.

context/stack.md

@@ -7,6 +7,6 @@
 - Cairo, Scarb 2.20.1, Starknet Foundry 0.63.0
 - OpenZeppelin Contracts for Cairo 3.0.0
 - Vitest, Testing Library, Playwright
-- GitHub Actions and Vercel
+- GitHub Actions and GitHub Pages (static Next.js export)
 
 The original starter pin (Next.js 16.0.8 / React 19.2.1) was rejected after a fresh production audit identified known RSC and later Next.js advisories. Pin dependencies and commit lockfiles. Re-verify STRK20 package, wallet, pool, and provider compatibility before every deployment.

docs/engineering.md

@@ -0,0 +1,61 @@
+# CipherBid engineering notes
+
+CipherBid implements a one-unit Vickrey auction for ERC-721 assets. Cairo contracts own custody and accounting; the browser reads public state and requests wallet actions. The implemented payment asset is STRK, with a maximum of 32 bidders per auction.
+
+## Funding without exposing the bid
+
+A commitment hides a value but does not prove that its author can pay. Escrowing the exact bid funds it, but the token transfer from STRK20 into the helper contract is a public boundary.
+
+CipherBid accepts the same public cap from every bidder. In the recorded mainnet auction, both participants locked `4 STRK`, then revealed `2 STRK` and `4 STRK`. The bid amount was concealed until reveal without pretending the helper's collateral balance was encrypted. This trades capital efficiency for a simple, enforceable funding rule.
+
+The [`privacy_invoke` entrypoint](../contracts/src/lib.cairo) accepts only the configured pool. It validates the operation, deadline, bidder bound and uniqueness, then requires the observed STRK balance to equal the previous accounted balance plus the cap before recording ingress. Claims likewise reject balance drift. Unexpected direct token transfers can therefore stop these paths rather than being silently treated as auction collateral.
+
+## Auction state and atomic delivery
+
+Creation transfers the NFT into contract custody. During bidding, the contract records commitments and claim handles, not bid amounts. Reveal checks the commitment and recipient during the configured reveal window. After that window, settlement scans the bounded bid set.
+
+The highest revealed bid wins if it meets the reserve. The clearing price is the greater of the reserve and second-highest revealed bid; an equal highest bid does not replace an earlier accepted winner. If no bid meets the reserve, settlement returns the NFT to the seller.
+
+Settlement writes the outcome, transfers the NFT and checks the resulting owner in one Starknet transaction. A failed transfer or owner assertion reverts the transaction. This is the precise meaning of atomic delivery, not a guarantee of service availability or audited security.
+
+The [lifecycle specification](evidence/task-2-3-lifecycle-specification.md) records the phase and deadline rules. The [Cairo implementation](../contracts/src/lib.cairo) is authoritative; the [TypeScript settlement model](../web/src/features/auction/auctionLifecycle.ts) supports client reasoning and tests.
+
+## Claims and conservation
+
+Each accepted bidder funds the full cap. A losing bidder can recover that cap; a winner can recover the cap minus the clearing price. The seller's entitlement is the clearing price. The contract binds claims to their handles, checks the claim secret and prevents repeated consumption. Seller proceeds additionally require authorization of the exact open note by the auction's seller.
+
+Payments return through STRK20 open-note claims. Open-note edges and their amounts are not secret. The economic result also depends on the live pool fee, which the UI reads rather than assuming a fixed rate.
+
+The [mainnet lifecycle](evidence/mainnet/auction-lifecycle.md) records all three completed claims and zero final actual/accounted house balances. The seller deliberately completed a `2 STRK` claim while the pool charged `6 STRK`; this demonstrated the lifecycle but was economically unfavorable. The historical amount is not a promise about future fees.
+
+## Credentials and wallet authority
+
+The [bid commitment](../contracts/src/commitment.cairo) binds chain ID, auction-house address, auction ID, amount, nonce, claim handle and NFT recipient under a domain tag. Recovery credentials also identify the network, deployment, auction and role so that importing a file does not authorize a different auction.
+
+The wallet keeps signing keys, viewing keys, private notes and proof witnesses. It owns note discovery, proving, signing and submission. The app holds its active bid/claim credentials in browser memory, encrypts a user-downloaded recovery bundle and verifies that it can be imported before submission. It does not put plaintext credentials in browser storage, URLs, logs or a backend. See [recovery bundle validation](../web/src/features/credentials/recoveryBundle.ts).
+
+That division limits custody exposure but does not remove frontend risk. A compromised page can substitute an action descriptor before the wallet prompt. Users still need to verify the target and value shown by their wallet; strong recovery passwords and possession of the encrypted file also matter.
+
+## Public reads and confirmation
+
+The [auction reader](../web/src/features/auction/auctionReader.ts) checks the deployed class hash, configured pool, token and bidder bound. It then reads auction configuration, state, bids and NFT ownership, rejecting a custody mismatch instead of rendering an assumed result.
+
+The [receipt verifier](../web/src/features/transactions/receiptVerifier.ts) requires successful accepted execution, the expected AuctionHouse event, a pool event where required, and a matching state readback. A timeout is an unconfirmed result, not proof that the transaction failed. The recorded creation flow recovered its public event and NFT custody after a lost RPC response rather than replaying the write.
+
+Published receipt links are scoped to the known mainnet auction. Current state still comes from RPC. Neither fixture tests nor a static screenshot substitute for the [transaction ledger](evidence/mainnet/transactions.md).
+
+## Deployment and verification
+
+Next.js exports the public frontend to GitHub Pages under `/cipherbid`. The deployment workflow publishes only public network configuration. There is no application server or database; the browser talks to public RPC and a supported wallet. The repository name and live URL remain stable because the sprint registry and demo video already reference them.
+
+The web gates cover formatting, lint, strict types, unit/integration tests, Chromium journeys, a normal production build and the static Pages build. Cairo gates cover formatting, compilation and contract tests. The [security invariants](evidence/task-2-4-security-invariants.md) describe the intended negative cases; [local development](local-development.md) lists commands.
+
+The [current dependency advisory caveat](local-development.md#dependency-advisory-caveat) records unresolved server-side Next.js/sharp findings separately from the static Pages deployment. Passing tests are not a clean dependency audit.
+
+Source checks, a browser read and the historical mainnet lifecycle are different evidence. This repository does not claim a third-party audit or production readiness. Multi-unit token launches would need new allocation and settlement contracts and are outside the current deployment.
+
+## Privacy limits
+
+Bids are public after reveal. Deposits, withdrawals, timing, bid count, equal collateral, settlement, direct account calls and open-note edges remain observable. Channel setup and distinctive activity can create links between otherwise private actions. STRK20 also has its own screening and selective-disclosure policy.
+
+Wallet, prover, relayer, screening and RPC availability are external dependencies. No custom prover or privacy cryptography is implemented here. See the [project security context](../context/security.md) and [privacy context](../context/privacy.md) for the complete boundary.

docs/evidence/README.md

@@ -54,6 +54,8 @@ Sepolia evidence is rehearsal evidence only. It does not establish mainnet priva
 
 ## Submission controls
 
+The [organizer hub readback](submission/hub-status.md) resolves the earlier indexing-pending status. The hub marks CipherBid finished with demo, video and mainnet requirements satisfied; this does not establish an award.
+
 | Artifact                                                               | Scope                                                              |
 | ---------------------------------------------------------------------- | ------------------------------------------------------------------ |
 | [`hackathon-requirements-matrix.md`](hackathon-requirements-matrix.md) | Official requirement-to-evidence mapping and truthfulness controls |

docs/evidence/hackathon-requirements-matrix.md

@@ -1,5 +1,7 @@
 # CipherBid Official Hackathon Requirement Matrix
 
+Current organizer readback: the hub lists CipherBid as `finished` with demo, video and mainnet requirements satisfied. See [the dated, revision-pinned readback](submission/hub-status.md). This resolves the earlier refresh-pending status; it is not an award claim.
+
 **Status:** Official-source and evidence-routing baseline
 
 **Official-source snapshot verified:** 2026-08-27T10:12:47Z
@@ -72,11 +74,11 @@ Planned evidence summaries are reviewed, secret-free indexes of public facts. Ra
 | `TX-04`       | Official          | If project contracts are listed, each qualifying transaction must carry an event from one of those contracts; touching the pool only through someone else's contract is insufficient.[5]              | List the deployed CipherBid auction house and decode its ABI-frozen event from every applicable candidate transaction.                                                                                                                            | `E-DEPLOY`, `E-TX`                                        | Receipt includes a matching event whose emitter is the listed CipherBid auction-house address.        | Satisfied                      |
 | `TX-05`       | CipherBid control | Applicable listed transactions must emit the lifecycle-specific CipherBid auction-house event and produce the expected state delta.                                                                   | Both private ingresses must emit the accepted-bid event; the qualifying claim must emit its claim event. Exact event names/selectors are frozen with the final ABI rather than invented here.                                                     | `E-TX`, `E-LIFECYCLE`                                     | Emitter, selector, decoded fields, auction ID, and post-state all agree with the expected transition. | Satisfied                      |
 | `CONTRACT-01` | Official          | `contracts` is optional, but listed deployed addresses are detected and shown with their network.[4][5]                                                                                               | List the verified AuctionHouse and DemoERC721 only after class/config/source identity readback.                                                                                                                                                   | `E-DEPLOY`, root `strk20.json` `contracts`                | Both addresses exist on mainnet and match the reviewed artifacts/configuration.                       | Satisfied                      |
-| `DEMO-01`     | Official          | `demo_url` is optional only when the hub discovers the demo automatically; discovery preference is explicit `strk20.json`, GitHub Pages, repository Website, then latest successful deployment.[4][5] | Set the repository Website and also set `demo_url` for deterministic discovery before closure.                                                                                                                                                    | `E-DEMO`                                                  | Hub row links to the intended public production demo.                                                 | Satisfied; hub refresh pending |
+| `DEMO-01`     | Official          | `demo_url` is optional only when the hub discovers the demo automatically; discovery preference is explicit `strk20.json`, GitHub Pages, repository Website, then latest successful deployment.[4][5] | Set the repository Website and also set `demo_url` for deterministic discovery before closure.                                                                                                                                                    | `E-DEMO`                                                  | Hub row links to the intended public production demo.                                                 | Satisfied (hub readback) |
 | `PAYOUT-01`   | Official          | A winning team must provide one payout address.[4]                                                                                                                                                    | Designate one public payout address through organizer communication only after operator review.                                                                                                                                                   | `E-PAYOUT`                                                | Exactly one address is supplied; no signing or recovery material is disclosed.                        | Pending organizer request      |
 | `DOC-01`      | Official          | README coverage should explain what the project does, why privacy is needed, how to run it locally, and the mainnet contract addresses.[5]                                                            | The root README documents architecture, exact STRK20 integration, browser-wallet flow, setup, deployment, demo, threat model, privacy boundary, and limitations.                                                                                  | `E-DOCS`, `E-DEPLOY`                                      | A clean checkout can follow setup/build instructions and find verified mainnet addresses.             | Satisfied                      |
 | `LINK-01`     | Official          | Every public URL must be link-checked before submission.[5]                                                                                                                                           | Validate repository, demo, video, explorer, contract, transaction, and documentation links from a clean unauthenticated browser/session.                                                                                                          | `E-DEMO`, `E-VIDEO`, public evidence                      | All required URLs return the intended public resource.                                                | Satisfied                      |
-| `INDEX-01`    | Official          | The hub automatically shows missing demo, video, and mainnet requirements.[4][5]                                                                                                                      | Treat hub requirements as a final independent readback, not as the source of transaction truth.                                                                                                                                                   | Public hub row plus `E-DEMO`, `E-VIDEO`, `E-TX`           | Hub reports demo, video, and mainnet requirements satisfied after final refresh.                      | Pending                        |
+| `INDEX-01`    | Official          | The hub automatically shows missing demo, video, and mainnet requirements.[4][5]                                                                                                                      | Treat hub requirements as a final independent readback, not as the source of transaction truth.                                                                                                                                                   | Public hub row plus `E-DEMO`, `E-VIDEO`, `E-TX`           | Hub reports demo, video, and mainnet requirements satisfied after final refresh.                      | Satisfied (hub readback)                        |
 
 ## Scoring matrix
 
@@ -125,7 +127,7 @@ CipherBid is submission-ready only when all rows below are true simultaneously:
 - [x] Canonical seller/two-bidder/observer lifecycle and value conservation are independently verified.
 - [x] README, setup, threat model, privacy limitations, demo, and mainnet addresses are complete.
 - [x] All public links and final quality/security gates pass on the exact final commit.
-- [ ] The hub reports demo, video, and mainnet requirements satisfied after refresh.
+- [x] The hub reports demo, video, and mainnet requirements satisfied after refresh; see the later [dated readback](submission/hub-status.md).
 - [x] All required evidence is present before **August 31, 2026 at 23:59 UTC**.
 
 ## Program facts that are not implementation gates

docs/evidence/submission/hub-status.md

@@ -0,0 +1,25 @@
+# Organizer hub readback
+
+Public readback on September 24, 2026, from the STRK20 Private Sprint organizer repository:
+
+- [Project index at `4c625bec`](https://github.com/starkience/strk20-hackathon/blob/4c625becb6b366ce3c26c7f6dc9b43bd320198f3/projects.json)
+- [Registration source](https://github.com/starkience/strk20-hackathon/blob/4c625becb6b366ce3c26c7f6dc9b43bd320198f3/registry.json)
+
+The entry for `https://github.com/SourceSenseiTheRealOne/cipherbid` reports:
+
+| Field | Observed value |
+| --- | --- |
+| Status | `finished` |
+| Demo requirement | `true` |
+| Video requirement | `true` |
+| Mainnet requirement | `true` |
+| Verified transactions | `5` |
+| Indexed project revision | `13f25cc56ce8a45fa9646365dd923508835f3b16` |
+| Demo | `https://sourcesenseitherealone.github.io/cipherbid/auction/?id=1788040057342` |
+| Video | `https://youtu.be/pYZk6KXko7o` |
+
+The transaction list contains five unique hashes, each marked `ok`, `pool` and `mine`. They match the qualifying bid and claim transactions in [`strk20.json`](../../../strk20.json) and the [mainnet ledger](../mainnet/transactions.md).
+
+This later readback resolves the old “hub refresh pending” entries in the [requirements matrix](../hackathon-requirements-matrix.md). It records the organizer's published status; it does not establish prize placement, an audit, production readiness or new blockchain execution. The original August deployment and transaction evidence retains its original dates and identities.
+
+The public homepage and settled auction were also opened in a clean browser during this review. Both returned HTTP 200 without page errors. The auction displayed sold state, a `2 STRK` clearing price, verified NFT custody and claimed seller proceeds. No wallet was connected and no transaction was submitted.