# BACKSTOP Master Development Plan

**Roadmap authority:** Gates A–G below replace earlier version/gate labels. Work proceeds in order; a gate is complete only when its acceptance evidence is recorded. Gate B3 is accepted locally as of 2 November 2026; see [B3 acceptance evidence and limitations](BACKSTOP-B3-UI-UX-AUDIT.md). Hosted verification and external deployment remain separate.

## Current evidence

- **Gate A — Engineering Foundation:** baseline evidence is recorded in prior release notes; hosted CI remains pending external verification because no hosted run is evidenced.
- **Gate B — Website, Developer Docs and Sandbox/Web3 Application:** B1/B2 build on the loopback API, SQLite ledger, role permissions, provider mock and dispute/reconciliation logic; B3 covers the product UI, website, docs and accessibility. No wallet or SQLite/EVM bridge is included.
- **B1/B2 local evidence:** the browser sandbox completed payment, pool reservation, merchant onward transfer, buyer claim, independent review, pool refund and read-only reconciliation. The local verification suite passes 144 Node tests and 15 Solidity tests, and the static frontend/docs checks pass. This does not constitute hosted CI or testnet evidence.
- Browser verification exposed and fixed a reconciliation false positive during legitimate active disputes, plus stale-session recovery when the in-memory sandbox restarts. Regression tests cover both behaviors.
- The project contains a Node.js/SQLite simulator, a separate local Hardhat vault with Mock-USDC, a Node/Ethers vault adapter, a static marketing website, a versioned API/OpenAPI document, demos and automated tests.
- The sandbox API's source-of-truth for simulated balances is SQLite; the protocol's payment/case projection remains local application state. The local EVM contract is a separate system.
- **B3 accepted locally:** nine actual Chromium acceptance groups passed, including the complete role flow, 32 responsive page/workspace combinations, measured accessibility semantics/contrast, keyboard navigation, API outage/retry and stale-session recovery. The full local verifier passed 144 Node tests and 15 Solidity tests, build/docs/secret checks and a zero-finding dependency audit. See the B3 report for accessibility exclusions; this is not formal certification or deployment.
- **Gate C — accepted locally:** persistent backend/chain protection lifecycle, canonical journals, read-only reconciliation and signed operator recovery passed 159 Node tests, 38 Contract/integration tests and ten Chromium acceptance groups. See [Gate C evidence](BACKSTOP-GATE-C-ACCEPTANCE.md). **Next gate: D**, wallet/testnet integration; no testnet deployment is claimed or performed.

## Product architecture

| Surface | Responsibility | Authority and boundary |
|---|---|---|
| Backstop website | Product model, factual capability status and links to source docs | Static HTML/CSS/JS; not an authenticated payment application |
| Backstop app | Guided buyer, merchant, provider and reviewer sandbox flow | Local-only test UI; each mutation invokes an existing role-protected API operation |
| Developer docs | Sandbox setup, API roles, lifecycle, pool rules, known limits | Repository-maintained Markdown plus generated OpenAPI |
| API client | Same-origin JSON, short-lived sandbox persona sessions, stable idempotency keys and explicit error reporting | Browser receives only opaque local test session tokens; no provider private keys |
| Blockchain adapter and local lifecycle relay | Durable journal, confirmation-gated payment/dispute/refund/release, reconciliation and signed recovery | Local test signers only; browser wallet, testnet and production operations remain later gates |
| Shared deployment/feature config | The local sandbox endpoint publishes a fixed `LOCAL SANDBOX` mode, asset, decimals, pool and enabled test personas | No dynamic network selection, wallet enablement or deployment keys |

The current frontend uses native browser JavaScript rather than introducing a framework or monorepo. Its static build is assembled and checked by `npm run build:web`. React/TypeScript/Wagmi/Viem should be selected only if a later gated requirement needs their runtime or type safety; the current UI does not sign transactions.

## Gate sequence and acceptance criteria

### Gate A — Engineering Foundation

**Scope:** local Git baseline, secret exclusions, reproducible lockfile installation, CI configuration, tests/builds, release verification and implementation/gap evidence.

**Acceptance:** clean local baseline evidence; `npm ci`; `npm run verify`; secret checks over intended changes; CI uses restricted permissions and no deployment secrets. Hosted CI is separately marked pending until a real authorized remote run is observed.

### Gate B — Website, Developer Docs and Sandbox/Web3 Application

**Scope:** separate accurate website and developer guidance from the runnable local app; prove the complete local role-checked flow without database access.

**B1 — Technical foundation acceptance**

- One maintainable frontend/API structure with a same-origin API client and a fixed, explicit deployment mode.
- Local UI assets have a reproducible build and secure HTTP headers.
- Test personas can only be issued by the opt-in loopback sandbox harness; ordinary API mode exposes no persona bootstrap or simulation controls.
- Every financial command remains authorized by the existing API; no browser private keys, free role selector or public financial admin endpoint.
- OpenAPI and role docs describe the actually available routes and errors.

**B2 — Functional sandbox acceptance**

- Pool total, available and reserved coverage are read from the ledger-backed API.
- Buyer terms acceptance and authorization, provider reservation and signed local provider settlement produce the existing protocol/ledger transitions.
- Merchant can view and transfer received test balance to the simulated external account.
- Buyer can open a timely claim; support assigns triage and two independent reviewers decide through existing endpoints.
- The protocol deadline settles the approved local refund from the pool; merchant funds are not debited by the refund.
- Read-only reconciliation is accessible only to the scoped sandbox pool operator, shows critical findings and never repairs state.
- Automated tests cover normal and rejected role/idempotency/coverage cases plus HTTP/network failure states. Browser operation is exercised against the loopback server.

**B3 — Website, UI/UX and documentation acceptance**

- Website explains Backstop Recover, provider pools, exchange/wallet/payment-provider concepts, security/trust, ecosystem and roadmap without implying unavailable integrations.
- App presents separate buyer, merchant, pool, case-review and reconciliation workspaces while preserving API-backed mutations and fixed local test identities.
- Repository-maintained docs cover quickstart, lifecycle, pools, claims/refunds, ledger/reconciliation, API, Solidity vault, security boundaries and roadmap; examples match implementation.
- Responsive layouts, keyboard operation, focus, semantic status/error feedback, themes and reduced-motion behavior are tested. Browser acceptance exercises the actual loopback flow and documents any unsupported API-failure scenario.
- Gate B3 passes only after full local verify and real browser acceptance evidence; visual rendering or smoke tests alone are insufficient.

**Out of scope for B:** wallet signing, public login, real tokens/funds, on-chain payment, durable SQLite/EVM transaction journal and deployment.

### Gate C — Persistent Blockchain/Backend Integration

**Accepted locally, 2 November 2026:** persistent API/outbox-to-vault lifecycle, confirmation-gated financial posting, canonical event/reorg handling, stable read-only reconciliation and signed two-operator recovery. Full local verifier and separate Chromium acceptance passed. See [Gate C acceptance and exact boundaries](BACKSTOP-GATE-C-ACCEPTANCE.md).

**Scope:** design the SQLite transactional-outbox to chain boundary with durable transaction/idempotency journal, confirmed receipts, event cursor, restart resume, failure handling and reorg-safe reconciliation.

**Acceptance:** tests prove retries after uncertain submission, duplicate event processing, restart, insufficient confirmations, reverted receipts, reorgs and manual fail-closed handling. No off-chain status is treated as chain truth; no automatic financial correction.

### Gate D — Base Sepolia Testnet Product

**In progress:** D1 adds explicit read-only browser wallet connection, provider selection and Base Sepolia switching; the Chrome connection fix was confirmed by the user. D2 has a locally tested read-only configuration/network/mock-token preflight; a live run awaits approved configuration. Transaction signing, verified testnet deployment and actual testnet receipts remain pending. See [Gate D progress](BACKSTOP-GATE-D-PROGRESS.md). Gate D is not accepted.

**Scope:** approved testnet deployment and end-to-end operation with test-only assets after Gate C.

**Acceptance:** explicit operator approval, chain ID 84532, verified contract/token addresses and source, test token provenance, transaction/receipt/finality evidence, no mainnet RPC or real USDC, plus rollback/incident procedures. A script or local Hardhat test alone is not testnet verification.

### Gate E — Financial Security, Risk and Operations

**Scope:** independent security review, financial and operational controls, reconciliation monitoring, alerting, recovery, key governance, limits and risk policies.

**Acceptance:** no unresolved critical/high findings for the approved threat model; documented authorization matrix, solvency proof, independent review, tested backups/restores and incident exercises. No audit certification is inferred from internal review.

### Gate F — Provider Network and Pilot Integration

**Scope:** named provider, legal/operational roles, sandbox integration, partner identity/key management, support and a bounded pilot.

**Acceptance:** provider contract and test evidence for settlement, duplicate, contradictory state, timeout, key rotation, restart, reconciliation and incident handling. Pilot requires explicit approval and Gate E sign-off.

### Gate G — Ecosystem Expansion

**Scope:** only evidence-backed expansion to Backstop Recover, wallet/payment integrations, multi-chain adapters, risk/operations modules and other ecosystem services.

**Acceptance:** each module has a separate owner, threat model, authorization/data boundary, measurable tests, rollout gates and non-overstated public status. AI or risk automation never receives direct refund/release rights.

## Existing components and data authority

| Component | Present behavior | Gate boundary |
|---|---|---|
| `src/protocol.js` | Offer, accept, authorize, reserve, signed provider settlement, dispute, reviewer vote and expiry transitions | Local TEST-USD simulation; source of protocol rules, not a production payment service |
| `src/ledger.js` | SQLite double-entry accounts and unique reservation lifecycle | Local financial record; no chain custody proof |
| `src/reconciliation.js` | Read-only checks for ledger, pools, reservations, settlements, events and jobs | Local evidence only; cannot repair and cannot prove external payment/finality |
| `src/api/` | Versioned loopback API, bearer sessions, role/object authorization, request idempotency | No public login or production TLS/identity provisioning |
| `fixtures/api.js`, `src/mock-provider.js` | Fixed test parties, test balances, signed local provider simulation | Test fixtures only; keys stay in the local process |
| `web/` | Static marketing site plus same-origin local sandbox page/client | No browser wallet or production UI |
| `contracts/USDCProtectionVault.sol` | Local vault; linked to the opt-in payment fixture through confirmed receipts | No testnet deployment, independent audit or real funds |
| `src/blockchain/` | Durable local protection lifecycle, reconciliation and signed operator recovery | Browser signing, testnet and production custody remain later gates |
| `scripts/`, `test/`, `solidity-test/` | Reproducible local demos and automated checks | Passing tests are not audit or external verification |

## Working sequence

1. Keep changes scoped to the current gate and preserve the source-of-truth/role boundaries.
2. Read the baseline, capability matrix and gap report before asserting availability.
3. Implement the smallest complete user flow on existing domain logic.
4. Add API, ledger, frontend and security regression coverage at the same time.
5. Run targeted tests, frontend build, browser exercise, then `npm run verify`.
6. Update implementation matrix, known limits and docs only from verified results.
7. Leave external deployment/push/hosted verification pending unless explicitly authorized and evidenced.