MagicWebb

MagicWebb — system breakdown (v3.6)

The picture book. ARCHITECTURE.md is the map and the reference tables; this document is every mechanism drawn out — where the code runs, what a request touches, how the indexer and keeper loop turns chain events into a live page, the exact state machines behind listings, auctions and offers, who may do what, how control of the contracts moves and ends, how a badge is decided, and what the product looks like. Diagrams are Mermaid; GitHub renders them, and the copy served by the app at /docs/system renders them in the browser in the active colour scheme. This page is generated from docs/SYSTEM_BREAKDOWN.md (python tools/mirror-system-doc.py); the screenshot gallery lives there.

Companions: USER_CAPABILITIES.md / /docs/capabilities (what each user can do), NETWORKS.md (provisioning), MONITORING.md (metrics + alerts), UPGRADE_RUNBOOK.md (upgrades, admin rotation, Safe, sealing), DEPLOY_CHECKLIST.md, RUNBOOK_RESTORE.md, DESIGN.md.

1. Deployment topology

One Docker image, built once per push to main, runs three times — one process per network. Nothing is shared between networks except the image and the code paths; every app has its own Postgres, its own optional Redis, its own keeper wallet and its own contract set (or none, in read-only mode).

flowchart TB
  subgraph GH["GitHub · push to main"]
    CI["ci.yml<br/>go build/vet/race · forge · slither · gitleaks<br/>astro check · vitest · Playwright<br/>proto-drift · governance check"]
    DEP["deploy.yml<br/>build ONCE → image sha-{commit}<br/>matrix deploy · ghcr mirror (non-fatal)"]
  end
  subgraph FLY["Fly.io · region sin · one machine per app by design<br/>(Flare + Songbird run two today, pending owner decision)"]
    A1["magicwebb<br/>Coston2 · 114 · TRADING"]
    A2["magicwebb-songbird<br/>Songbird · 19 · read-only"]
    A3["magicwebb-flare<br/>Flare · 14 · trading"]
  end
  DEP -->|"same image · env from deployments/*.json"| A1
  DEP --> A2 & A3
  A1 --- D1[("Neon<br/>still-mountain")]
  A2 --- D2[("Neon<br/>bitter-pond")]
  A3 --- D3[("Neon<br/>royal-paper")]
  A1 -.-> R1[("Redis (optional)<br/>mw:114:*")]
  A1 --> K1["keeper wallet<br/>KEEPER_KEY Fly secret"]
  A1 -->|"RPC rotation"| C2["Coston2 contracts · block 34905078<br/>Marketplace · AuctionHouse · OfferBook (UUPS)<br/>MarketplaceManager (plain v3.4 — proxied v3.7 after the DeployManager migration)"]
  K1 -->|"settle · refundLosers<br/>forceCancel · fee sweep"| C2
  A1 <-.->|"NETWORK_URLS"| A2
  A1 <-.-> A3
Network Chain App Status Contracts Data
Coston2 (testnet) 114 magicwebb.fly.dev trading deployments/coston2.json (v3.5 set, 2026-09-04) Neon still-mountain-83246431
Songbird 19 magicwebb-songbird.fly.dev read-only none (browse-only by owner decision) Neon bitter-pond-73256956
Flare 14 magicwebb-flare.fly.dev trading deployments/flare.json (2026-09-11, block 69547144): marketplace 0xa85a798a5cfe104ff6409e649ec4937ed6b947dc, auctionHouse 0xcb1d58454a1adda5257b34b5b492bf6859f09250, offerBook 0x1c3d20f2ee3e61f7c0e433ada4c39f3e7aef8b78, marketplaceManager 0x71be8838d2952e02015f594506eeee23b7ec90cc Neon royal-paper-82216877

What “read-only” means: the binary boots, serves the UI, API, wallet connect and cross-network profiles; the indexer, keepers and verifier idle; the UI shows a dismissible browse-only banner and empty states that point at the trading origin. Filling deployments/<network>.json and setting <NET>_ENABLED=true in CI is the entire enable procedure (NETWORKS.md).

Per-network tuning — finality depth, poll cadence, keeper tick, gas caps, default RPCs, rate-limit tier, faucet, identity — lives in backend/internal/chain/profile/{coston2,songbird,flare}.go and is validated at boot (Validate() — bad values fail the process, not a request). The browser mirror is app/src/lib/chains/; a Go test keeps the two and the deployment records in agreement.

2. The request path (one origin)

flowchart TB
  UI["Browser · Astro static pages · Svelte 5 islands<br/>React wallet island (Reown AppKit · wagmi · viem)"]
  UI -->|"HTTPS · WSS"| SEC["Fly edge · TLS · Fly-Client-IP<br/>security headers · CSP · HSTS<br/>rate limit (tier from profile · /api/v1 per machine<br/>· /auth/* shared Postgres counters)"]
  subgraph FACES["one Go process · one chain"]
    ST["embedded dist/<br/>pages · assets · /docs"]
    REST["/api/v1 REST<br/>listings · auctions · offers · token<br/>collections · search · trending · activity<br/>profile · wallet · server-time · governance"]
    IMG["/api/v1/img/:sha256<br/>content-addressed image store"]
    OBS["POST /api/v1/tx/observe<br/>instant lane"]
    AUTH["/auth · SIWE → JWT<br/>saved searches · notifications<br/>profile edits · webhooks"]
    WS["/ws hub<br/>token: collection: user: tx: activity<br/>retry {from_seq} replay"]
    GQL["/graphql · /graphql/ws<br/>gqlgen queries + subscriptions"]
    CN["Connect / gRPC MarketplaceService<br/>unary + Subscribe* streams"]
    HP["/healthz · /readyz<br/>/internal/metrics (METRICS_TOKEN)"]
    ST ~~~ OBS ~~~ GQL
    REST ~~~ AUTH ~~~ CN
    IMG ~~~ WS ~~~ HP
  end
  SEC --> FACES
  REST -->|"read cache · memory or Redis<br/>(cache.Key chain-namespaced)"| DB[("Neon Postgres<br/>reader pool · writer pool")]
  IMG & AUTH & GQL & CN --> DB
  OBS --> IDX["indexer.ObserveTx<br/>receipt logs → same handlers"] --> DB
  IDX --> BC[("sse.Broadcaster<br/>seq · replay ring · gRPC mesh")]
  BC --> WS & GQL & CN & WH["webhooks"]

GraphQL walletNFTs(owner, first, after) is paginated: first is the page size (1-50, default 50; anything else is an error, never a silent clamp) and is what the query’s complexity cost bills for; each OwnedNFT carries an opaque cursor, and passing the last row’s cursor as after returns the rows that follow it. A page shorter than first is the last one. Pages walk the wallet’s 500 most recently changed holdings (newest first, the same ceiling as REST /api/v1/wallet/{addr}/nfts); a cursor whose token has left the wallet since the previous page is rejected, and the client restarts without after.

Every write is a wallet transaction; the backend never holds a user key. The page simulates the call first (custom errors decode to plain-language titles), opens the wallet on a Review step, and after one confirmation posts the hash to the instant lane. ObserveTx fetches the receipt and dispatches its logs through the same idempotent handlers the watcher uses, publishes tx-indexed, and the page’s optimistic state settles with one refetch. The instant lane’s writes are provisional: the watcher (the ordered lane) applies the same logs again, in chain order, ReorgSafety blocks later. For most rows that second pass rewrites what is already there, but it is not a blanket no-op. ERC-1155 balance deltas (TransferSingle / TransferBatch) are never applied by the instant lane at all, so the ordered lane is their first and only application (each log is claimed once in applied_transfer_logs). And the writes that close or replace a row are gated on chain position (block, log index): a replayed Cancelled, Bought, OfferRefunded or OfferAccepted closes only the listing or offer that existed at that position, and a replayed Listed or OfferMade never overwrites a later one.

sequenceDiagram
  participant P as Page (TxModal / runTx)
  participant W as Wallet
  participant C as Contract
  participant B as Backend
  participant S as /ws
  P->>P: requireWallet · simulateContract (errors decoded early)
  P->>P: Review step — you pay / seller receives / refundable
  P->>W: writeContract → "Confirm in your wallet"
  W-->>P: tx hash → "Pending on Coston2 (~2s)"
  P->>S: subscribe tx:{hash}
  C-->>P: receipt (1 confirmation) → "Done" · optimistic reducer applied
  P->>B: POST /api/v1/tx/observe {hash}
  B->>C: eth_getTransactionReceipt
  B->>B: handlers upsert (tx_hash, log_index) · Publish tx-indexed
  S-->>P: tx-indexed → settleAfterTx: one refetch → "Live on the marketplace"

3. Indexer + keeper loop

All long-lived workers run inside the single server process under supervise() — a panicking worker is logged with its stack and restarted after a short delay; a worker that returns cleanly (no keeper key, read-only network) stays stopped. The keeper workers additionally pass through a single-flight gate: with two or more machines, internal/keeper’s gRPC election (lowest instance UUID leads, 1 s heartbeat, three missed beats fail over) guarantees exactly one broadcaster per network.

flowchart TB
  RPC["rpcpool · failover rotation · eth_getLogs"]
  subgraph WATCH["watcher (poll = profile.PollInterval, head − profile.ReorgSafety)"]
    F["filter: 3 cores + manager + tracked collections<br/>topics: trading · governance · Transfer*"]
    H["handlers · idempotent upserts keyed (tx_hash, log_index)"]
  end
  RPC --> F --> H
  H --> DB[("Postgres · 54 goose migrations at boot<br/>(numbered to 055, 031 skipped)")]
  H --> BC[("sse.Broadcaster")]
  BC --> OUT["/ws · GraphQL subs · Connect streams · webhooks · notifications"]
  subgraph WORK["supervised workers"]
    META["metadata → tokenURI → fetch (SSRF-safe)<br/>→ sniff → sha256 → image store → image_uri"]
    RETRY["image retry"]
    VER["verifier · ERC-165 + metadata<br/>⇒ collections.verified"]
    SCORE["score → trending"]
    LEXP["listing expiry sweeper · active=false<br/>(off-chain; buy reverts Expired on-chain)"]
    OEXP["offer expiry sweeper"]
    WDR["withdrawal sweeper · pendingReturns()<br/>→ pending_withdrawals + notification"]
    OWN["ownership repair<br/>stale nft_ownership vs on-chain holder"]
    GOV["governance events → governance_events<br/>counter · SSE governance · security alerts"]
    META ~~~ SCORE ~~~ WDR
    RETRY ~~~ LEXP ~~~ OWN
    VER ~~~ OEXP ~~~ GOV
  end
  DB --> WORK
  subgraph KEEP["keeper workers (KEEPER_KEY · single-flight)"]
    AK["auction keeper · every KeeperTick (1s / 2s)<br/>settle ended auctions · forceCancel after 3 days"]
    LR["loser refund sweeper<br/>refundLosers in batches"]
    FEE["fee sweeper · Safe Allowance Module<br/>(probe bytecode first)"]
    OPS["ops health · keeper balance + fee cap<br/>head-lag alert · image-store gauge + LRU eviction"]
    CLEAN["expired-listing clean · every 2nd KeeperTick<br/>Marketplace.cleanExpired per row (chain_cleaned=false)"]
    AK ~~~ FEE
    LR ~~~ OPS
  end
  DB --> KEEP
  WORK ~~~ KEEP
  KEEP -->|"signed tx via keeper key"| RPC
  OPS --> AL["alerts · Discord · Prometheus Alertmanager · SMTP · hourly cooldown"]
Worker Cadence Source
watcher PollInterval (profile), ReorgSafety behind head indexer/runner.go runWatcher
instant lane on demand (POST /tx/observe) indexer/observe.go
metadata / image retry continuous / periodic indexer/metadata.go
verifier VerifierTick (profile) internal/verifier
score (trending) periodic runner.go runScoreWorker
listing / offer expiry sweepers 1 s (DB flips only) runner.go
withdrawal sweeper RefundTick (profile; default 30 s) runner.go runWithdrawalSweeper
ownership repair periodic indexer/ownership_repair.go
auction keeper KeeperTick (1 s / 2 s) runner.go runAuctionKeeper
expired-listing clean (on-chain cleanExpired) every 2nd KeeperTick runner.go cleanExpiredListings
loser refunds RefundTick (profile; default 45 s) indexer/keeper_refund.go
fee sweeper FeeSweepTick (5 min / 10 min) indexer/keeper_feesweep.go
keeper-health · lag-alert · image-store FeeSweepTick · 15 s · 5 min indexer/ops_health.go
governance with the watcher indexer/governance.go

4. State machines

Money never depends on the keeper: every terminal state has a self-service exit (withdrawRefund, refundLosers — permissionless after settlement, withdrawLoserFunds — non-leaders before settlement, refundExpiredOffer, settle, forceCancel). The keeper only makes those exits happen sooner.

4.1 Listing (non-custodial — the NFT stays in the seller’s wallet)

stateDiagram-v2
  [*] --> Active: list · list1155 · batchList ≤50 (duration → expiresAt on-chain, free)
  Active --> Active: editPrice (seller)
  Active --> Sold: buy (msg.value == price · NFT → buyer · 98% → seller · 1.5% platform · 0.5% keeper)
  Active --> Cancelled: cancel (seller)
  Active --> Expired: block.timestamp > expiresAt (buy reverts Expired · keeper calls cleanExpired)
  Sold --> [*]
  Cancelled --> [*]
  Expired --> [*]

Off-chain the expiry sweeper flips listings.active=false every second so the UI stops showing it, and the keeper drives the on-chain Marketplace.cleanExpired (keeper-gated) every second KeeperTick for rows with chain_cleaned=false — owner decision 2026-08-31, everything that expires is handled instantly; the resulting Cancelled event marks the row so it is never re-sent. A stale ownership row that would block buy preflight is repaired by the ownership worker against the live holder. Transfers of a listed NFT (seen via Transfer) deactivate the seller’s own listing.

4.2 Auction (escrowed, cumulative bids, flat +1 native increment)

stateDiagram-v2
  [*] --> Live: create · create1155 (reserve ≥ 1 native · duration)
  Live --> Live: bid (must beat reserve or leader + 1 native, else BidTooLow reverts — nothing is parked)
  Live --> Live: anti-snipe — a lead-changing bid in the last 3 min resets endsAt to now + 3 min (leader top-ups do not extend) · hard cap originalEndsAt + 30 min (AuctionExtended)
  Live --> Live: withdrawLoserFunds (non-leader self-service, only before settlement)
  Live --> Cancelled: cancelEarly (seller, only while no bid leads)
  Live --> SellerDefaulted: claimSellerDefault — leader only, before endsAt, only when the collection answers that the seller no longer holds the token(s) or this contract lost its approval (leader escrow returned, no fee)
  Live --> Ended: endsAt reached (no transaction)
  Ended --> Settled: settle — keeper within ~1 tick · or seller · or winner
  Ended --> ForceCancelled: forceCancel after endsAt + 3 days — keeper · seller · winner (everyone refunded)
  Settled --> Settled: refundLosers batches — permissionless (the keeper drives it every RefundTick, and any loser can call it with their own address)
  Settled --> [*]
  Cancelled --> [*]
  SellerDefaulted --> [*]
  ForceCancelled --> [*]

Payout is pull-safe: if pushing proceeds to the seller fails (PushFailed) the amount lands in pendingReturns, which the profile’s Refunds card reads directly on-chain (the withdrawal sweeper separately re-verifies bidders seeded by LoserRefunded and AuctionSettlementFailed, with PushFailed marking a push that fell back to pendingReturns, and sends a “refund” notification). Every credit therefore has an event: AuctionSettlementFailed for a winner’s returned escrow, PushFailed for any other push that fell back to pendingReturns, and RefundWithdrawn when the holder calls withdrawRefund. AuctionSettlementFailed is the other outcome: the NFT could not be delivered (seller moved it or revoked approval), so no fee is taken, the seller is paid nothing, the winner’s escrow is pushed back (pull fallback) and the row is marked cancelled. The leader does not have to wait for endsAt to get there: claimSellerDefault(id) lets the current leader end the auction early with the same outcome (same event, whole escrow returned, no fee, losers then use refundLosers), but only when the collection positively answers that the seller no longer holds the token(s) or no longer approves the contract; a probe that reverts or runs out of gas is not evidence (SellerCanStillDeliver). Meeting the reserve is therefore not a binding commitment by the seller: the token stays in the seller’s wallet until settlement, and a seller who moves it or revokes the approval walks away at no cost beyond gas. The bidders lose nothing (every escrow comes back in full), but they cannot force the sale. One exception (v3.8): when a CONTRACT wins an ERC-1155 auction and its receiver refuses the delivery while the seller still holds the units and the approval, AuctionWinnerRejected is emitted first. The normal 2% fee is then taken (1.5% platform, 0.5% keeper), the rest is credited to the winner’s pendingReturns (never pushed back to the refusing contract), and the seller still receives nothing. A collection that refuses contract recipients counts as a refusal too. bid() only admits contracts that can receive ERC-1155 (ERC-165 IERC1155Receiver, or a static dry-run of onERC1155Received), so an honest contract wallet is refused up front (ReceiverNotSupported) rather than charged later. A losing bidder can pull escrow with withdrawLoserFunds while the auction is live and is never locked behind a position that cannot win. DB auction_status: active → settled | cancelled, plus losers_refunded.

4.3 Offer (escrowed native, fee only at accept)

stateDiagram-v2
  [*] --> Gate: collection owner (ERC-173) setOfferEligible(true) — otherwise OffersNotEligible
  Gate --> Pending: makeOffer · makeOffer1155 (escrow + duration)
  Pending --> Pending: makeOffer again edits the position — old principal refunded, new one escrowed, original expiry kept
  Pending --> Accepted: acceptOffer (owner · NFT → bidder · escrow − 2% → owner)
  Pending --> Cancelled: cancelOffer (bidder · full refund)
  Pending --> Rejected: rejectOffer (owner · full refund)
  Pending --> Expired: expiresAt passed → refundExpiredOffer (bidder self-service, or the keeper sweep)
  Accepted --> [*]
  Cancelled --> [*]
  Rejected --> [*]
  Expired --> [*]

acceptOffer re-checks that the offer’s principal still matches (PrincipalChanged) and that the acceptor still owns and has approved the token. DB offer_status: pending → accepted | cancelled | expired.

5. Role × action matrix

Three visitors, and a person is all three at different moments: Viewer (no wallet), Buyer (wallet on this network, does not own the NFT), Seller / owner (owns the NFT or created the listing / auction). Every write is a wallet transaction on the network you are viewing.

Action Viewer Buyer (wallet) Seller / owner
Browse, search, view token / collection / profile / activity ✓ ✓ ✓
Buy a listing connect prompt ✓ hidden on own
List (721 / 1155 units), 15 durations, min 1 native — — ✓ owner
Batch list up to 50 — — ✓ 721 only
Change price / cancel listing — — ✓ seller
Start auction (721 / 1155) — — ✓ owner
Bid (+1 native over the lead, cumulative) connect prompt ✓ (not seller) —
Withdraw when outbid — ✓ any time —
Cancel auction — — ✓ only with no bids
Settle after end — ✓ winner ✓ seller (+ keeper auto, 1 s Coston2 / 2 s mainnets)
Cancel & refund everyone (3 d after end) — ✓ winner ✓ seller (+ keeper auto)
Make offer (if the collection allows) connect prompt ✓ —
Raise / withdraw own offer (full refund) — ✓ —
Accept / decline an offer — — ✓ owner
Reclaim own expired offer (full refund) — ✓ bidder (+ keeper auto) —
Enable offers for a collection — — ✓ ERC-173 owner
Search, trending, activity, collection traits ✓ ✓ ✓
Save search / notifications / security alerts (SIWE) disabled + hint ✓ ✓
Edit own profile — name, bio, links, tag (SIWE, shared across networks) — ✓ ✓
See who controls the contracts (/status, /api/v1/governance) ✓ ✓ ✓
Switch network (keeps the path; reconnect on arrival) ✓ ✓ ✓
Theme: System / Light / Dark ✓ ✓ ✓
Anything admin none exists none none

No admin page, no login form, no roles in the product. The only privileged key is the per-network on-chain admin (upgrades + keeper rotation) held by the owner — see §6.

6. Governance lifecycle

One MarketplaceManager per network holds exactly two addresses: keeper (settle · refund · clean — can never move or block funds) and admin (setKeeper, instant UUPS upgrades with upgradeDelay() == 0, two-step rotation, renounceAdmin). There is no grant path and no pause switch. Until renounceAdmin() is called the admin is root upgrade authority, so an admin-signed manager upgrade can halt new sales; it can never trap funds.

stateDiagram-v2
  [*] --> AdminHeld: DeployV34 — ADMIN_ADDR (EOA on testnet, Safe on mainnet) · KEEPER_ADDR · FEE_RECIPIENT_ADDR
  AdminHeld --> AdminHeld: setKeeper (KeeperSet)
  AdminHeld --> AdminHeld: queueUpgrade → upgradeTo back-to-back (UpgradeQueued · Upgraded) · cancelUpgrade · 7-day queue expiry
  AdminHeld --> PendingTransfer: transferAdmin(new) (AdminTransferStarted)
  PendingTransfer --> AdminHeld: acceptAdmin from the NEW key (AdminTransferred) — e.g. hand-off to a Safe
  PendingTransfer --> AdminHeld: cancelAdminTransfer (AdminTransferCancelled)
  AdminHeld --> Sealed: renounceAdmin (AdminRenounced) — one way, wipes any pending offer
  Sealed --> Sealed: no upgrades · no keeper rotation · users keep every exit

The trail is public. The watcher indexes nine governance topics into governance_events; GET /api/v1/governance returns the live admin, pending_admin, keeper, upgrade_delay, admin_is_contract, renounced, the current implementation per proxy, the last 50 events and keeper_health; /status shows “Admin & upgrades” tiles with a per-proxy pending-upgrade warning; every signed-in wallet that has not opted out of security_alerts receives a notification when control changes; operators get Discord / Prometheus / SMTP alerts. tools/check-governance.sh reads the chain in CI, cmd/reindexgov backfills the trail, and tools/upgrade-cores.sh <network> performs a full three-core upgrade (deploy impls with immutables read from the proxies → queue + install with ADMIN_KEY → verify → record impls / superseded_impls). Mainnets deploy with a Gnosis Safe as admin from block one (UPGRADE_RUNBOOK.md → “Safe as admin”).

7. Badge decision tree

Two NFT-level signals, computed in one place (backend/internal/db/badge.go) for every row type, plus the collection tier on detail headers. No badge is ever granted by hand.

flowchart TB
  N["NFT row (listing · auction · offer · search · collection token · token page)"]
  N --> Q1{"collection verified?<br/>verifier: ERC-165 says 721/1155 AND metadata resolved"}
  Q1 -->|no| R1["reason unverified_collection"]
  Q1 -->|yes| Q2{"token has a name?"}
  Q2 -->|no| R2["reason no_metadata"]
  Q2 -->|yes| Q3{"image served from our store?<br/>/api/v1/img/{sha256} or inline data:"}
  Q3 -->|no| R3["reason image_missing"]
  Q3 -->|yes| Q4{"holder known?"}
  Q4 -->|no| R4["reason owner_unknown"]
  Q4 -->|yes| V["✓ Verified — verified=true, verified_reason=[]"]
  R1 & R2 & R3 & R4 --> NV["no checkmark — verified_reason names each unmet check so the UI can say why"]
  N --> S1{"holder == collection creator?<br/>(ERC-173 owner / deployer)"}
  S1 -->|no| NS["no ★"]
  S1 -->|yes| S2{"nft_tokens.minter == creator?<br/>(first Transfer from 0x0, migration 044)"}
  S2 -->|no| NS
  S2 -->|yes| ST["★ Creator — creator_is_owner=true"]
Signal Where it shows Source fields
✓ (sky check) glyph on every card, text + Hint on token / auction / collection headers verified, verified_reason[]
★ Creator creator’s profile header (“Creator of …”), collection header next to “Created by”, an NFT whose holder is the creator and minted it creator_is_owner, /token → minter, creator{address, display_name, tag}
Collection pill (Listed collection → Verified → Authentic) detail headers collections.verified, verified_reason{standard_ok, metadata_ok, creator_known}
Holder tag token page profile tag, else derived from the address

Activity rows carry no collection_verified column, so the checkmark is withheld there rather than guessed; offers imply a holder, so ✓ answers but ★ never applies.

8. Real-time: one spine, three faces

sse.Broadcaster is the only publisher (sequence-numbered, replay ring, fanned across machines over the gRPC mesh). Consumers:

Face For Shape
/ws the product UI channels token: collection: user: tx: activity, retry {from_seq} replay from the seq-numbered ring; islands subscribe only to what they show (TokenPage: its token + collection; NFTGrid: listing changes, page 1 refetch)
GraphQL subscriptions (/graphql/ws) third-party dashboards hydrated objects, cost-limited
Connect server streams bots and keepers SubscribeListings SubscribeAuctions SubscribeActivity SubscribeNotifications (SIWE), declared in marketplace.proto, regenerated with a pinned toolchain, CI proto-drift gate
Webhooks integrations per-type subscriptions incl. governance

window.MW_BLOCK_TIME_MS / MW_CONFIRMATIONS (from /api/v1/server-time, per profile) drive the pending ETA copy; optimistic reducers (app/src/lib/optimistic.ts) apply the expected row change at “Done” and settleAfterTx refetches once when tx-indexed arrives (or after 2 s).

9. Ops health and observability

Endpoint What it answers
/healthz liveness
/readyz readiness: DB ping + RPC head (3 s each, cached 5 s, 30/min per IP)
/api/v1/indexer/slo head lag in blocks (text)
/api/v1/governance control + keeper_health
/internal/metrics Prometheus (METRICS_TOKEN; required in production, 404 without it) — magicwebb_keeper_balance_wei, _balance_level{level}, _underpriced_total, _feecap_below_network_ticks, magicwebb_head_lag_blocks, _head_lag_alerting, magicwebb_imagestore_bytes / _cap_bytes / _evicted_total, governance counters
/status the human page: build SHA (X-MW-Build-SHA), indexer lag, automation costs, keeper balance, admin & upgrades

Alerts (MONITORING.md → “Ops health”): KeeperBalanceLow (warning below KEEPER_MIN_BALANCE_WEI, critical below 20 % of it), KeeperFeeCapBelowNetwork (three ticks with eth_gasPrice above the keeper’s cap — the 2026-08-31 starvation signature), IndexerHeadLag (> 30 blocks for 2 min, with a resolved notice), ImageStoreNearCap (only after LRU eviction of unreferenced blobs from 80 % down to 70 %). Backups and the quarterly restore drill: RUNBOOK_RESTORE.md.

10. The product (screenshots)

Desktop and phone, light and dark, for every page — captured from the live app with npm run shots and kept in the repository: docs/SYSTEM_BREAKDOWN.md §10.

11. Where the code is

See ARCHITECTURE.md §7 for the repository map. The short version: contracts/ (Foundry, four UUPS proxies — three cores + the v3.7 manager — script/DeployV34.s.sol, DeployManager.s.sol, DeploySafe.s.sol), backend/ (Go 1.26 + Fiber; cmd/server boots migrate → connect → guard → indexer → http; internal/chain/profile is the per-network table; internal/ops the health snapshot), app/ (Astro 7 + Svelte 5 islands + one React wallet island; src/lib/tx write flows, src/lib/ws, src/lib/chains, src/lib/optimistic.ts), deployments/ (address records — the source of truth), tools/ (upgrade-cores, check-governance, check-deployments), .github/workflows (ci · deploy · nightly · audit · sast).