Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -117,6 +117,15 @@ npm run flowchain:full-smoke
npm run flowchain:product-e2e
```

Run the capped owner pilot dry-run before any Base `8453` pilot action:

```powershell
npm run flowchain:real-value-pilot:ops
```

Owner pilot coordination and go/no-go criteria live in
`docs/FLOWCHAIN_REAL_VALUE_PILOT.md`.

Run the existing dashboard as the local workbench:

```powershell
Expand Down
9 changes: 9 additions & 0 deletions docs/EASY_SECOND_COMPUTER_SETUP.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,15 @@ npm run flowchain:product-e2e
That gate must pass before the setup should be treated as ready for a local
second-computer test.

Before any capped Base `8453` owner pilot action, run the ops dry-run proof:

```powershell
npm run flowchain:real-value-pilot:ops
```

Then follow `docs/FLOWCHAIN_REAL_VALUE_PILOT.md` for owner go/no-go criteria,
emergency stop, evidence export, and restart recovery commands.

## Already Cloned Setup

If the repo is already cloned:
Expand Down
10 changes: 10 additions & 0 deletions docs/FLOWCHAIN_OPERATOR_CHECKLIST.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,16 @@ npm run flowchain:export
Run `npm run flowchain:full-smoke` when the machine has the full prerequisite set,
including Foundry, Python, dashboard dependencies, and crypto dependencies.

Capped owner pilot preflight:

```powershell
npm run flowchain:real-value-pilot:ops
```

Do not run live pilot actions until the owner has reviewed
`docs/FLOWCHAIN_REAL_VALUE_PILOT.md` and supplied the required env vars in a
local shell only.

## Launch Demo Day

Primary script: `docs/LAUNCH_DEMO_RUNBOOK.md`.
Expand Down
79 changes: 61 additions & 18 deletions docs/FLOWCHAIN_REAL_VALUE_PILOT.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,8 +19,8 @@ approval.

## Current Baseline

Current `main` after PR #142 merged at
`c4959f8223c491f5a45c6b7d572707420457b743`:
Current `main` after PR #143 merged at
`a16fb9a7ce817b8c32d4641610c35e559a6c444c`:

- `npm run flowchain:product-e2e` exists as the local product testnet gate.
- `npm run flowchain:full-smoke` exists as the private/local L1 baseline gate.
Expand All @@ -31,6 +31,8 @@ Current `main` after PR #142 merged at
gate. It fails by default while required subsystem proof commands are missing.
- `npm run flowchain:real-value-pilot:control-dashboard` exists on `main`
after PR #142 merged.
- `npm run flowchain:real-value-pilot:wallet` exists on `main` after PR
#143 merged.

GitHub source-of-truth state checked for this pass:

Expand All @@ -41,8 +43,10 @@ GitHub source-of-truth state checked for this pass:
policy while keeping `contracts:hardening:slither` as the explicit audit gate.
- Issue #137 is closed; PR #142 merged the control-plane/dashboard pilot
proof command.
- Issues #133, #138, #134, #136, and #135 remain the open subsystem proof
blockers for strict pilot-gate pass.
- Issue #136 is closed; PR #143 merged the wallet/operator pilot proof
command.
- Issues #133, #138, #134, and #135 remain the open subsystem proof blockers
for strict pilot-gate pass.

## Final Gate

Expand All @@ -67,6 +71,45 @@ devnet/local/real-value-pilot/flowchain-real-value-pilot-e2e-report.json
The report must show `status: "passed"` before the owner can mark the capped
pilot go. Until then, missing proof rows are blockers, not warnings.

## Ops Command Surface

The ops proof command is branch-local until issue #135 merges:

```powershell
npm run flowchain:real-value-pilot:ops
```

It verifies that the owner-pilot scripts parse, dry-run mode needs no live RPC
URL or private key, live mode refuses missing acknowledgement/env values,
emergency stop prints the pause recovery command, and evidence export excludes
secret-shaped files.

Live owner actions require explicit local shell env vars and are not run by the
proof command. The command surface is:

```powershell
npm run flowchain:real-value-pilot -- --Mode Live --Action Deploy
npm run flowchain:real-value-pilot -- --Mode Live --Action Deploy -Execute
npm run flowchain:real-value-pilot -- --Mode Live --Action Observe
npm run flowchain:real-value-pilot -- --Mode Live --Action Credit
npm run flowchain:real-value-pilot -- --Mode Live --Action Withdraw
npm run flowchain:real-value-pilot:emergency-stop
npm run flowchain:real-value-pilot -- --Mode Live --Action Resume -Execute
npm run flowchain:real-value-pilot:export
npm run flowchain:real-value-pilot -- --Mode Live --Action Restart
```

Set live env vars only in a local shell or ignored env file. The minimum
operator acknowledgement is:

```powershell
$env:FLOWCHAIN_PILOT_OPERATOR_ACK="I_UNDERSTAND_THIS_IS_CAPPED_BASE8453_OWNER_PILOT"
```

The ops wrapper also requires action-specific Base `8453` RPC, lockbox,
owner/release/submitter/recipient, block range, and tiny cap env values before
any live action proceeds.

## Release-Gate Boundary

This section is the issue #130 boundary for real-value pilot PRs. It does not
Expand All @@ -93,18 +136,18 @@ the proof is branch-local or verified from `main`.
| --- | --- | --- | --- |
| Existing product testnet gate remains green. | HQ/Ops | `npm run flowchain:product-e2e` | Existing command; run before PR when practical. |
| L1 baseline gate remains green. | HQ/Ops | `npm run flowchain:l1-e2e` | Exists on `main` as current alias to `flowchain:full-smoke`; latest local main-equivalent run passed. |
| 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. |
| 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. |
| 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` | Contracts and bridge commands are still missing; ops branch command added here pending PR merge. |
| 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` | Contracts command is still missing; ops branch command added here pending PR merge. |
| 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. |
| Deposit observation writes deterministic observation, credit, and evidence files. | Bridge relayer | `npm run flowchain:real-value-pilot:bridge` | Missing dedicated pilot command. |
| 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. |
| 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. |
| 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` | Branch command added here; local proof passes, pending PR merge. |
| 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` | Branch command added here; local proof passes, pending PR merge. |
| 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` | Merged on `main` by PR #143; latest local main-equivalent proof passed. |
| 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` | Merged on `main` by PR #143; latest local main-equivalent proof passed. |
| 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` | Merged on `main` by PR #142; latest local main-equivalent proof passed. |
| 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` | Merged on `main` by PR #142; latest local main-equivalent proof passed. |
| 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` | Control-dashboard proof is merged; wallet branch proof passes, pending PR merge. |
| 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. |
| 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` | Control-dashboard and wallet proofs are merged. |
| 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` | Branch command added here; local proof passes, pending PR merge. |
| Final pilot gate runs baseline commands plus every available dedicated proof command. | HQ/Ops | `npm run flowchain:real-value-pilot:e2e` | Exists on `main`; strict mode still fails until subsystem commands land. |

## In-Flight Implementation Status
Expand All @@ -116,12 +159,12 @@ from `main`.

| Area | In-flight branch state | Required next step |
| --- | --- | --- |
| Contracts | `agent/real-value-pilot-contracts` checklist reports the contracts proof complete, including hardening, deploy dry-run, and product E2E. | Rebase onto `c4959f8`, expose `flowchain:real-value-pilot:contracts`, rerun evidence, and open a PR. |
| Bridge relayer | `agent/real-value-pilot-bridge` checklist reports the bridge proof complete; service-local `pilot:e2e` exists. | Rebase onto `c4959f8`, expose `flowchain:real-value-pilot:bridge`, rerun evidence, and open a PR. |
| Chain runtime | `agent/real-value-pilot-chain` checklist reports runtime credit/replay/restart/export proof complete through the direct wrapper; root package command is missing. | Rebase onto `c4959f8`, expose `flowchain:real-value-pilot:runtime`, rerun evidence, and open a PR. |
| Wallet/operator | `agent/real-value-pilot-wallet` is rebased onto `c4959f8`; checklist reports wallet/operator schemas, signing, validation, negative cases, scans, product evidence, and branch-local `flowchain:real-value-pilot:wallet` complete. | Open a PR for issue #136 so the proof command lands on `main`. |
| Contracts | `agent/real-value-pilot-contracts` checklist reports the contracts proof complete, including hardening, deploy dry-run, and product E2E. | Rebase onto `a16fb9a`, expose `flowchain:real-value-pilot:contracts`, rerun evidence, and open a PR. |
| Bridge relayer | `agent/real-value-pilot-bridge` checklist reports the bridge proof complete; service-local `pilot:e2e` exists. | Rebase onto `a16fb9a`, expose `flowchain:real-value-pilot:bridge`, rerun evidence, and open a PR. |
| Chain runtime | `agent/real-value-pilot-chain` checklist reports runtime credit/replay/restart/export proof complete through the direct wrapper; root package command is missing. | Rebase onto `a16fb9a`, expose `flowchain:real-value-pilot:runtime`, rerun evidence, and open a PR. |
| Wallet/operator | `flowchain:real-value-pilot:wallet` merged on `main` through PR #143 and closed issue #136. | No wallet/operator blocker remains for the final pilot gate. |
| Control plane/dashboard | `flowchain:real-value-pilot:control-dashboard` merged on `main` through PR #142 and closed issue #137. | No control-dashboard blocker remains for the final pilot gate. |
| Ops/installer | `agent/real-value-pilot-ops` checklist reports ops proof complete; root lifecycle commands exist branch-locally, but `flowchain:real-value-pilot:ops` is missing. | Rebase onto `c4959f8`, expose `flowchain:real-value-pilot:ops`, rerun evidence, and open a PR. |
| Ops/installer | This branch adapts `agent/real-value-pilot-ops` work onto `a16fb9a` and exposes branch-local `flowchain:real-value-pilot:ops`. | Open a PR for issue #135 so the proof command lands on `main`. |

## Owner Go/No-Go Checklist

Expand Down Expand Up @@ -151,9 +194,9 @@ in committed files, or if any document presents the pilot as public readiness.
- Dedicated real-value contracts gate does not exist; tracked by issue #133.
- Dedicated real-value bridge relayer gate does not exist; tracked by issue #138.
- Dedicated real-value runtime gate does not exist; tracked by issue #134.
- Dedicated real-value wallet/operator gate exists branch-locally and passes; tracked by issue #136 until merged.
- Dedicated real-value wallet/operator gate is merged on `main`; issue #136 is closed by PR #143.
- Dedicated real-value control-plane/dashboard gate is merged on `main`; issue #137 is closed by PR #142.
- Dedicated real-value ops/installer gate does not exist; tracked by issue #135.
- Dedicated real-value ops/installer gate exists branch-locally and passes; tracked by issue #135 until merged.
- Issue #130 is closed by PR #132; the release-gate boundary is now on `main`.
- Issue #131 is closed by PR #132; default `contracts:hardening` skips optional
Slither unless the audit gate is explicitly requested.
Expand All @@ -167,7 +210,7 @@ in committed files, or if any document presents the pilot as public readiness.
| Contracts | #133 | `npm run flowchain:real-value-pilot:contracts` |
| Bridge relayer | #138 | `npm run flowchain:real-value-pilot:bridge` |
| Chain runtime | #134 | `npm run flowchain:real-value-pilot:runtime` |
| Wallet/operator | #136 | `npm run flowchain:real-value-pilot:wallet` |
| Wallet/operator | #136, closed by PR #143 | `npm run flowchain:real-value-pilot:wallet` |
| Control plane/dashboard | #137, closed by PR #142 | `npm run flowchain:real-value-pilot:control-dashboard` |
| Ops/installer | #135 | `npm run flowchain:real-value-pilot:ops` |
| Release-gate boundary | #130, closed by PR #132 | `npm run flowchain:real-value-pilot:e2e -- -AllowIncomplete` until proofs land |
Expand Down
18 changes: 18 additions & 0 deletions docs/FLOWCHAIN_SECOND_COMPUTER_SETUP.md
Original file line number Diff line number Diff line change
Expand Up @@ -120,6 +120,15 @@ npm run flowchain:full-smoke
npm run flowchain:product-e2e
```

Run the capped owner pilot ops dry-run before any Base `8453` pilot action:

```powershell
npm run flowchain:real-value-pilot:ops
```

The full owner pilot coordination checklist is
`docs/FLOWCHAIN_REAL_VALUE_PILOT.md`.

Run the local workbench in a separate PowerShell window:

```powershell
Expand Down Expand Up @@ -156,6 +165,8 @@ Expected current result:
local account funding, token launch, pool creation, liquidity, swap receipts,
bridge-test credit visibility, control-plane query surfaces, workbench
product surfaces, and no-secret response boundaries.
- `npm run flowchain:real-value-pilot:ops` is the dry-run ops proof for the
capped owner pilot. It uses no live RPC URL or private key.
- `npm run workbench:dev` opens the existing dashboard as the local workbench.

Current stop point: if a second computer needs production custody, production
Expand All @@ -180,6 +191,7 @@ npm run flowchain:start
npm run control-plane:serve
npm run workbench:dev
npm run flowchain:product-e2e
npm run flowchain:real-value-pilot:ops
npm run flowchain:export
```

Expand All @@ -206,6 +218,9 @@ npm run flowchain:demo
npm run flowchain:smoke
npm run flowchain:full-smoke
npm run flowchain:product-e2e
npm run flowchain:real-value-pilot:ops
npm run flowchain:real-value-pilot:emergency-stop
npm run flowchain:real-value-pilot:export
npm run flowchain:export
npm run workbench:dev
```
Expand All @@ -222,6 +237,9 @@ Current status:
| `npm run flowchain:smoke` | Implemented for current private/local surfaces | Runs service tests, crypto validation, launch candidate, devnet tests, control-plane smoke, deterministic replay, dashboard build, hardware fixture, unsafe-claim scan, and no-secret export scan. |
| `npm run flowchain:full-smoke` | Implemented acceptance gate | Wraps smoke, wallet CLI sign/verify, full-smoke report, no-secret scan, and `git diff --check`. |
| `npm run flowchain:product-e2e` | Implemented product testnet gate | Wraps the full smoke and proves local account funding, token launch, DEX pool/liquidity/swap receipts, bridge-test records, control-plane product queries, workbench product surfaces, and no-secret API boundaries. |
| `npm run flowchain:real-value-pilot:ops` | Branch-local dry-run pilot ops proof | Parser-checks pilot scripts, proves dry-run needs no RPC or keys, verifies missing live env refusal, checks emergency-stop dry-run, and writes sanitized evidence export. |
| `npm run flowchain:real-value-pilot:emergency-stop` | Branch-local guarded pause wrapper | Routes to the live `Pause` action after explicit acknowledgement, Base `8453` chain check, cap check, lockbox address check, and owner key check. |
| `npm run flowchain:real-value-pilot:export` | Branch-local pilot evidence exporter | Writes a sanitized ignored bundle excluding Git metadata, dependency folders, build targets, local vaults, private-key files, and env files. |
| `npm run flowchain:export` | Implemented | Writes ignored export directory and zip bundle. |
| `npm run flowchain:import -- --BundlePath <zip> -Force` | Implemented script path | Restores local state from an exported bundle. |
| `npm run workbench:dev` | Implemented | Wraps `npm run dev --prefix apps/dashboard`. |
Expand Down
Loading
Loading