Skip to content

Commit 14f378b

Browse files
FlowmemoryAIFlowmemoryAI
authored
Add real-value pilot HQ gate
Adds the capped real-value pilot HQ gate, release-boundary documentation, final gate scaffold, L1 alias, static-analysis default/audit split, and proof-command issue mappings. Product/L1 E2E pass on branch; final real-value pilot gate remains blocked until subsystem proof commands land.
1 parent 9b025c5 commit 14f378b

10 files changed

Lines changed: 905 additions & 5 deletions

‎docs/FLOWCHAIN_REAL_VALUE_PILOT.md‎

Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
# FlowChain Real-Value Pilot
2+
3+
Status: HQ coordination spec for a capped owner pilot.
4+
5+
Last updated: 2026-05-14.
6+
7+
## Purpose
8+
9+
The FlowChain real-value pilot is a capped owner-only bridge validation path
10+
that builds on the current local FlowChain product testnet and L1 baseline.
11+
It is meant to prove a tiny supported-asset deposit on Base public network
12+
chain ID `8453` can be observed, converted into a deterministic local credit,
13+
shown to the owner, and recovered or stopped with explicit evidence.
14+
15+
This is not a public launch, not open-validator readiness, not tokenomics, not
16+
a broad bridge readiness claim, and not a custody claim. It stays blocked until
17+
the proof rows below have owning agents, commands, evidence, and owner go/no-go
18+
approval.
19+
20+
## Current Baseline
21+
22+
Current `main` at the start of this HQ pass:
23+
24+
- `npm run flowchain:product-e2e` exists as the local product testnet gate.
25+
- `npm run flowchain:full-smoke` exists as the private/local L1 baseline gate.
26+
- `npm run flowchain:l1-e2e` is added here as the current L1 baseline alias to
27+
`flowchain:full-smoke`; it can be tightened by the ops branch when the
28+
dedicated L1 wrapper is merged.
29+
- `npm run flowchain:real-value-pilot:e2e` is added here as the final pilot
30+
gate. It fails by default while required subsystem proof commands are missing.
31+
32+
GitHub source-of-truth state checked for this pass:
33+
34+
- Draft PR #129 adds the copy-ready real-value pilot goal pack.
35+
- Issue #130 defines the required gate work before public-network pilot work.
36+
- Open PRs #110, #112 through #117, #71, and #73 remain useful context only
37+
until merged.
38+
39+
## Final Gate
40+
41+
Run the pilot gate from the repo root:
42+
43+
```powershell
44+
npm run flowchain:real-value-pilot:e2e
45+
```
46+
47+
During coordination, run the same gate in report-only mode:
48+
49+
```powershell
50+
npm run flowchain:real-value-pilot:e2e -- -AllowIncomplete
51+
```
52+
53+
The script writes:
54+
55+
```text
56+
devnet/local/real-value-pilot/flowchain-real-value-pilot-e2e-report.json
57+
```
58+
59+
The report must show `status: "passed"` before the owner can mark the capped
60+
pilot go. Until then, missing proof rows are blockers, not warnings.
61+
62+
## Release-Gate Boundary
63+
64+
This section is the issue #130 boundary for real-value pilot PRs. It does not
65+
approve live operation by itself; it defines the minimum evidence that must be
66+
present before a PR may claim a capped owner-pilot step is ready.
67+
68+
| Activity | Merge requirement before claiming ready | Approval owner |
69+
| --- | --- | --- |
70+
| Base public-network observer reads. | Observer command verifies `eth_chainId == 0x2105`, rejects broad ranges, rejects unapproved lockbox addresses, records confirmation depth, and writes no-secret evidence. | Bridge + Ops + HQ |
71+
| Supported-asset deposit. | Contracts prove allowlist, per-deposit cap, total pilot cap, pause, replay, and deterministic event inputs; ops proves tiny nonzero cap env and exact owner acknowledgement. | Contracts + Ops + Owner |
72+
| Bridge release or recovery path. | Contracts prove authorized release/recovery and replay blocking; wallet proves signed release evidence; ops proves emergency stop and revoke/recovery command path. | Contracts + Wallet + Ops + Owner |
73+
| Local credit application. | Runtime proves each pilot credit applies exactly once, duplicate replay is rejected or idempotent with evidence, and restart/export/import preserve deterministic roots. | Chain runtime + Bridge |
74+
| Control-plane and dashboard display. | API/dashboard prove capped owner labels, live/degraded/error state, exact next command, redaction, and no browser secret storage. | Control plane/dashboard + Wallet |
75+
| Token launch, tokenomics, broad DEX liquidity, or open swap claims. | Out of scope for the capped owner pilot. A separate accepted issue, docs update, threat model, and owner approval are required before any PR may make these claims. | Owner + HQ + Security |
76+
| Open validators, public L1/mainnet readiness, audited cryptography, or production bridge custody. | Out of scope for this pilot. A separate production-readiness review, security review, and accepted release plan are required before any PR may make these claims. | Owner + HQ + Security |
77+
78+
Every PR touching a pilot proof row must list the exact issue, allowed folders,
79+
forbidden folders, commands run, report paths, unresolved blockers, and whether
80+
the proof is branch-local or verified from `main`.
81+
82+
## Integration Matrix
83+
84+
| Required proof | Owning agent | Required command | Current state |
85+
| --- | --- | --- | --- |
86+
| Existing product testnet gate remains green. | HQ/Ops | `npm run flowchain:product-e2e` | Existing command; run before PR when practical. |
87+
| L1 baseline gate remains green. | HQ/Ops | `npm run flowchain:l1-e2e` | Added as current alias to `flowchain:full-smoke`. |
88+
| Base chain ID `8453` is verified before any live observer or deployment action. | Contracts + Bridge + Ops | `npm run flowchain:real-value-pilot:contracts`; `npm run flowchain:real-value-pilot:bridge`; `npm run flowchain:real-value-pilot:ops` | Missing dedicated pilot commands. |
89+
| Lockbox address is loaded from ignored local config or env, not hardcoded as a blanket endorsement. | Contracts + Ops | `npm run flowchain:real-value-pilot:contracts`; `npm run flowchain:real-value-pilot:ops` | Missing dedicated pilot commands. |
90+
| Per-deposit cap, total pilot cap, supported-asset allowlist, pause, release, recovery, and replay protection are covered by tests and dry-run deployment evidence. | Contracts | `npm run flowchain:real-value-pilot:contracts` | Missing dedicated pilot command. |
91+
| Deposit observation writes deterministic observation, credit, and evidence files. | Bridge relayer | `npm run flowchain:real-value-pilot:bridge` | Missing dedicated pilot command. |
92+
| Duplicate Base event replay is rejected or idempotent with explicit evidence. | Bridge relayer + Chain runtime | `npm run flowchain:real-value-pilot:bridge`; `npm run flowchain:real-value-pilot:runtime` | Missing dedicated pilot commands. |
93+
| Local runtime applies each pilot bridge credit exactly once and preserves state across restart/export/import. | Chain runtime | `npm run flowchain:real-value-pilot:runtime` | Missing dedicated pilot command. |
94+
| Operator wallet can sign pilot acknowledgements, withdrawal intents, release evidence, and emergency messages without committing secrets. | Wallet/operator | `npm run flowchain:real-value-pilot:wallet` | Missing dedicated pilot command. |
95+
| Wallet verification rejects wrong chain ID, wrong contract, wrong operator, mutated payload, replay nonce, expired message, and missing cap fields. | Wallet/operator | `npm run flowchain:real-value-pilot:wallet` | Missing dedicated pilot command. |
96+
| API exposes pilot status, observations, credits, withdrawal intents, release evidence, cap status, pause status, retry state, and emergency state. | Control plane/dashboard | `npm run flowchain:real-value-pilot:control-dashboard` | Missing dedicated pilot command. |
97+
| Dashboard labels the flow as capped owner testing and shows live/degraded/error state plus exact next operator commands. | Control plane/dashboard | `npm run flowchain:real-value-pilot:control-dashboard` | Missing dedicated pilot command. |
98+
| Browser stores no private keys or RPC credentials. | Control plane/dashboard + Wallet/operator | `npm run flowchain:real-value-pilot:control-dashboard`; `npm run flowchain:real-value-pilot:wallet` | Missing dedicated pilot commands. |
99+
| Ops path verifies required env, tiny caps, explicit owner ack, emergency stop, export evidence, restart recovery, and no-secret scans. | Ops/installer | `npm run flowchain:real-value-pilot:ops` | Missing dedicated pilot command. |
100+
| Final pilot gate runs baseline commands plus every available dedicated proof command. | HQ/Ops | `npm run flowchain:real-value-pilot:e2e` | Added here; expected incomplete until subsystem commands land. |
101+
102+
## In-Flight Implementation Status
103+
104+
This HQ branch has inspected the active pilot worktrees and found branch-local
105+
work that can feed future merges. None of the rows below is enough to mark the
106+
owner pilot `go`, because the final proof commands still need to exist and pass
107+
from `main`.
108+
109+
| Area | In-flight branch state | Required next step |
110+
| --- | --- | --- |
111+
| Contracts | `agent/real-value-pilot-contracts` reports passing contract tests, hardening, deploy dry-run, and product E2E after dependency install. | Merge reviewed contract work and expose a dedicated root pilot contracts proof command. |
112+
| Bridge relayer | `agent/real-value-pilot-bridge` contains Base `8453` observer and mock pilot E2E work, with verification rows still pending. | Finish bridge verification, then expose a dedicated root bridge proof command. |
113+
| Chain runtime | `agent/real-value-pilot-chain` contains bridge-credit runtime work in progress, with current pilot experiments still pending. | Finish runtime apply/replay/restart/export proof, then expose a dedicated root runtime proof command. |
114+
| Wallet/operator | `agent/real-value-pilot-wallet` contains pilot signing, validation, schema, and operator-doc work with test rows still pending. | Finish wallet negative vectors and public metadata checks, then expose a dedicated root wallet proof command. |
115+
| Control plane/dashboard | `agent/real-value-pilot-control-dashboard` contains pilot API/dashboard work and a service-local E2E, with checklist rows still incomplete. | Finish API/dashboard verification, then expose a dedicated root control-dashboard proof command. |
116+
| Ops/installer | `agent/real-value-pilot-ops` contains root pilot wrappers, emergency stop, sanitized export, and a passing local checklist after an ops-side static-analysis wrapper change. | Reconcile product E2E hardening policy and merge a reviewed ops proof command. |
117+
118+
## Owner Go/No-Go Checklist
119+
120+
The owner should mark the pilot `go` only when all rows are true:
121+
122+
- [ ] `npm run flowchain:product-e2e` passes from a clean `main` checkout.
123+
- [ ] `npm run flowchain:l1-e2e` passes from the same checkout.
124+
- [ ] `npm run flowchain:real-value-pilot:e2e` passes without `-AllowIncomplete`.
125+
- [ ] The pilot report has empty `missingProofs` and no failed command results.
126+
- [ ] Base chain ID `8453` is verified in the live observer path.
127+
- [ ] Per-deposit and total pilot caps are tiny, nonzero, enforced, and recorded.
128+
- [ ] Supported asset and lockbox address are read from explicit local config or env.
129+
- [ ] Pause, emergency stop, revoke, release, restart, and export evidence are tested.
130+
- [ ] Replay and duplicate-event behavior has deterministic evidence.
131+
- [ ] No committed file, report, export, local route, or dashboard payload contains
132+
a private key, seed phrase, mnemonic, RPC credential, API key, or webhook.
133+
- [ ] The owner has reviewed the exact commands and expected loss boundary for
134+
the tiny capped test amount.
135+
- [ ] A rollback/recovery note names the first command to run if the bridge,
136+
relayer, runtime, wallet, control plane, or dashboard enters a degraded state.
137+
138+
Mark the pilot `no-go` if any row is missing, if any command requires secrets
139+
in committed files, or if any document presents the pilot as public readiness.
140+
141+
## Current Blockers
142+
143+
- Dedicated real-value contracts gate does not exist; tracked by issue #133.
144+
- Dedicated real-value bridge relayer gate does not exist; tracked by issue #138.
145+
- Dedicated real-value runtime gate does not exist; tracked by issue #134.
146+
- Dedicated real-value wallet/operator gate does not exist; tracked by issue #136.
147+
- Dedicated real-value control-plane/dashboard gate does not exist; tracked by issue #137.
148+
- Dedicated real-value ops/installer gate does not exist; tracked by issue #135.
149+
- GitHub issue #130 must define and be accepted as the release-gate boundary before
150+
any owner pilot work is treated as more than capped validation.
151+
- GitHub issue #131 has a branch-local policy fix in this HQ PR: default
152+
`contracts:hardening` skips optional Slither unless the audit gate is
153+
explicitly requested. The issue remains open until the fix is reviewed and
154+
merged.
155+
156+
## Tracking Issues
157+
158+
| Area | Issue | Required command |
159+
| --- | --- | --- |
160+
| Contracts | #133 | `npm run flowchain:real-value-pilot:contracts` |
161+
| Bridge relayer | #138 | `npm run flowchain:real-value-pilot:bridge` |
162+
| Chain runtime | #134 | `npm run flowchain:real-value-pilot:runtime` |
163+
| Wallet/operator | #136 | `npm run flowchain:real-value-pilot:wallet` |
164+
| Control plane/dashboard | #137 | `npm run flowchain:real-value-pilot:control-dashboard` |
165+
| Ops/installer | #135 | `npm run flowchain:real-value-pilot:ops` |
166+
| Release-gate boundary | #130 | `npm run flowchain:real-value-pilot:e2e -- -AllowIncomplete` until proofs land |
167+
| Static-analysis policy | #131 | `npm run contracts:hardening`; `npm run contracts:hardening:slither` |
168+
169+
## Required PR Evidence
170+
171+
Every real-value pilot PR must include:
172+
173+
- linked issue or explicit HQ assignment;
174+
- allowed and forbidden folders;
175+
- exact worktree and branch;
176+
- commands run and report paths;
177+
- missing blockers, owner, and next action;
178+
- explicit statement that public launch, open-validator readiness, tokenomics,
179+
broad bridge readiness, and custody claims remain out of scope.

‎docs/agent-runs/real-value-pilot-hq/CHECKLIST.md‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
# Real-Value Pilot HQ Checklist
2+
3+
Status: active.
4+
5+
Last updated: 2026-05-14.
6+
7+
## Acceptance
8+
9+
- [x] Read required source-of-truth docs before editing.
10+
- [x] Confirm current `origin/main` before editing.
11+
- [x] Inspect requested active worktrees for reusable work.
12+
- [x] Check GitHub PR and issue source-of-truth state.
13+
- [x] Create `docs/FLOWCHAIN_REAL_VALUE_PILOT.md`.
14+
- [x] Add `npm run flowchain:real-value-pilot:e2e`.
15+
- [x] Make the pilot gate fail clearly until subsystem proof commands exist.
16+
- [x] Create an integration matrix mapping required proofs to owner and command.
17+
- [x] Create a pilot go/no-go checklist for the project owner.
18+
- [x] Keep public-readiness claims out of the docs.
19+
- [x] Run `node infra/scripts/check-unsafe-claims.mjs`.
20+
- [x] Run `git diff --check`.
21+
- [x] Run the new pilot gate in incomplete mode.
22+
- [x] Run `npm run flowchain:product-e2e`, or document why it was not practical.
23+
- [x] Open a draft PR with exact commands run and current blockers.
24+
25+
## Gate Blocker Rows
26+
27+
- [ ] Contracts (#133): chain ID `8453`, lockbox config, caps, allowlist, pause,
28+
release/recovery, replay protections, dry-run deploy, and source instructions.
29+
- [ ] Bridge relayer (#138): Base observation, confirmation depth, deterministic credit,
30+
duplicate handling, local handoff, withdrawal/release evidence.
31+
- [ ] Runtime (#134): apply pilot credit exactly once, receipt lookup, restart,
32+
export/import, deterministic roots.
33+
- [ ] Wallet/operator (#136): no-secret config, pilot message signing, negative vectors,
34+
public metadata export, next-command UX.
35+
- [ ] Control plane/dashboard (#137): pilot API, redaction, owner labels, live/degraded
36+
state, next operator commands, browser no-secret boundary.
37+
- [ ] Ops/installer (#135): env validation, tiny cap checks, explicit owner ack,
38+
emergency stop, evidence export, restart recovery, troubleshooting.
39+
40+
These remain unchecked because they are not merged into `main` as dedicated
41+
root proof commands. Current live worktree evidence is recorded in `PLAN.md`
42+
and `NOTES.md`.
43+
44+
## Owner Go/No-Go
45+
46+
- [ ] `npm run flowchain:product-e2e` passes on `main`.
47+
- [ ] `npm run flowchain:l1-e2e` passes on `main`.
48+
- [ ] `npm run flowchain:real-value-pilot:e2e` passes without
49+
`-AllowIncomplete`.
50+
- [ ] Pilot report has empty `missingProofs`.
51+
- [ ] No committed files, reports, exports, API payloads, or dashboard surfaces
52+
contain private keys, seed phrases, mnemonics, RPC credentials, API keys, or
53+
webhooks.
54+
- [ ] Owner has reviewed caps, stop/recovery path, and exact commands.
55+
56+
## Release-Gate Boundary
57+
58+
- [x] Branch documents issue #130 capped owner-pilot boundary in
59+
`docs/FLOWCHAIN_REAL_VALUE_PILOT.md`.
60+
- [ ] Issue #130 boundary is reviewed and accepted on GitHub.
61+
62+
## Baseline Check Result
63+
64+
`npm run flowchain:product-e2e` initially failed inside
65+
`npm run contracts:hardening` because local Slither reported existing findings
66+
in `contracts/bridge/BaseBridgeLockbox.sol`.
67+
68+
This branch now updates the allowed `infra/scripts/` static-analysis wrappers
69+
so default `contracts:hardening` matches the documented policy: Slither is
70+
optional by default and required only through `contracts:hardening:slither`,
71+
`-RequireSlither`, or `REQUIRE_SLITHER=1`.
72+
73+
Current branch result: `npm run contracts:hardening`,
74+
`npm run flowchain:product-e2e`, and `npm run flowchain:l1-e2e` pass locally.
75+
76+
GitHub blocker: https://github.com/FlowmemoryAI/FlowMemory/issues/131
77+
78+
Draft PR: https://github.com/FlowmemoryAI/FlowMemory/pull/132
79+
80+
## Completion Audit
81+
82+
Audit file: `docs/agent-runs/real-value-pilot-hq/COMPLETION_AUDIT.md`.
83+
84+
Result: not complete. `origin/main` lacks both new scripts, the default pilot
85+
gate fails with the intended missing-proof report, and local branch-only
86+
`flowchain:l1-e2e` evidence is not on `main`.

0 commit comments

Comments
 (0)