Skip to content

Commit b9d9048

Browse files
FlowmemoryAIFlowmemoryAI
committed
Add pre-production hardening and Base Sepolia reader
1 parent 2441896 commit b9d9048

26 files changed

Lines changed: 1219 additions & 41 deletions

‎.github/workflows/ci.yml‎

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,11 @@ jobs:
1717
- name: Checkout
1818
uses: actions/checkout@v4
1919

20+
- name: Set up Node
21+
uses: actions/setup-node@v4
22+
with:
23+
node-version: "24"
24+
2025
- name: Check required bootstrap paths
2126
shell: bash
2227
run: |
@@ -87,6 +92,9 @@ jobs:
8792
fi
8893
done
8994
95+
- name: Check launch claim guardrails
96+
run: node infra/scripts/check-unsafe-claims.mjs
97+
9098
contracts:
9199
name: Contracts
92100
runs-on: ubuntu-latest
@@ -97,8 +105,8 @@ jobs:
97105
- name: Install Foundry
98106
uses: foundry-rs/foundry-toolchain@v1
99107

100-
- name: Run Foundry tests
101-
run: forge test
108+
- name: Run contract hardening baseline
109+
run: bash infra/scripts/contracts-static-analysis.sh
102110

103111
services:
104112
name: Services and launch core

‎.slither.config.json‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
{
2+
"filter_paths": "(cache|out|node_modules|lib)"
3+
}

‎README.md‎

Lines changed: 22 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
FlowMemory is a Base-native AI memory, neural-geometry, reliability, decentralized hardware, and future appchain/L1 research project.
44

5-
This repository has completed the initial bootstrap and contracts-foundation passes. It contains project context, collaboration rules, planning documents, GitHub templates, a CI scaffold, worktree setup, placeholder work areas, and an initial FlowPulse/Rootfield contracts foundation. Do not treat the current repo as containing production product features yet.
5+
This repository contains the FlowMemory V0 foundation: project operating docs, local/test contracts, fixture-first services, Rootflow and Flow Memory launch-core generation, a fixture-backed dashboard, crypto helpers, a local no-value devnet prototype, and FlowRouter hardware POC materials. Do not treat the current repo as containing production product features yet.
66

77
## What FlowMemory Is Exploring
88

@@ -41,7 +41,9 @@ Every contributor and agent should read:
4141
5. `docs/ROOTFLOW_V0.md`
4242
6. `docs/FLOW_MEMORY_V0.md`
4343
7. `docs/V0_LAUNCH_ACCEPTANCE.md`
44-
8. `docs/DAILY_HQ_RUNBOOK.md` if operating HQ or coordinating agents
44+
8. `docs/PRODUCTION_READINESS_CHECKLIST.md`
45+
9. `docs/MARKETING_CLAIMS_GUARDRAILS.md`
46+
10. `docs/DAILY_HQ_RUNBOOK.md` if operating HQ or coordinating agents
4547

4648
Then work only inside the assigned scope.
4749

@@ -55,6 +57,8 @@ FlowMemory is managed as a multi-agent program. The management layer is part of
5557
- `docs/reviews/OPEN_PR_MERGE_READINESS.md`: historical merge-readiness evidence for the merged V0 foundation PRs
5658
- `docs/PR_PROCESS.md`: branch, draft PR, review, merge, conflict, and issue-closing rules
5759
- `docs/DAILY_HQ_RUNBOOK.md`: morning review, triage, agent launch, PR monitoring, merge order, and handoff
60+
- `docs/PRODUCTION_READINESS_CHECKLIST.md`: blocking checklist before any production language is allowed
61+
- `docs/MARKETING_CLAIMS_GUARDRAILS.md`: allowed and blocked launch claims for docs and marketing
5862
- `infra/scripts/status-report.ps1`: read-only local worktree, PR, and issue status report
5963

6064
Immediate major milestone: build the Rootflow V0 and Flow Memory V0 launch core. This means local contracts/tests, FlowPulse fixtures, Rootflow transitions, Flow Memory schemas, verifier reports, crypto fixtures, dashboard-readable state, and local smoke-test gates. It does not mean production deployment.
@@ -70,6 +74,7 @@ This regenerates local/test Rootflow and Flow Memory V0 fixtures, including `fix
7074
## What Not To Claim
7175

7276
- Do not claim FlowMemory has production contracts or deployment automation.
77+
- Do not claim FlowMemory is production-ready or mainnet-ready.
7378
- Do not claim Uniswap v4 hook integration exists yet.
7479
- Do not claim explorer, hardware console, production FlowRouter hardware, or Meshtastic integration exists yet.
7580
- Do not claim cryptographic proof systems, tokenomics, or appchain/L1 implementation exists yet.
@@ -86,6 +91,7 @@ This regenerates local/test Rootflow and Flow Memory V0 fixtures, including `fix
8691
- `inbox/`: staging area for imported prompts, notes, and unsorted context
8792
- `research/`: future AI memory, neural geometry, and appchain/L1 research
8893
- `services/`: future indexer, verifier, worker, and API services
94+
- `schemas/flowmemory/`: canonical Flow Memory and Rootflow JSON schemas
8995

9096
## Implemented Foundation
9197

@@ -95,20 +101,29 @@ This regenerates local/test Rootflow and Flow Memory V0 fixtures, including `fix
95101
- Worktree setup script
96102
- `contracts/FlowPulse.sol`
97103
- `contracts/RootfieldRegistry.sol`
104+
- contract skeletons for artifacts, cursors, workers, verifiers, receipts, verifier reports, hook adapter, and work scheduling
105+
- contracts hardening docs and static-analysis runner
98106
- `contracts/FLOWPULSE_SCHEMA.md`
99107
- `tests/RootfieldRegistry.t.sol`
100-
- Initial Foundry tests for the Rootfield registry foundation
108+
- Foundry tests for the Rootfield registry foundation and live V0 contract package
109+
- fixture-first indexer/verifier packages and local launch-core generation
110+
- Base Sepolia reader path with explicit RPC URL and durable checkpoint output
111+
- Flow Memory V0 schemas and generated Rootflow transition fixtures
112+
- fixture-backed dashboard V0
113+
- crypto helper package and test vectors
114+
- local no-value devnet prototype
115+
- FlowRouter hardware POC docs, schemas, and simulator fixture
101116
- Documented URI/log-data limitations for the current contract skeleton
102117

103118
## Still Conceptual
104119

105120
- Uniswap v4 hook integration
106-
- Indexer and verifier services
107-
- Complete Rootflow runtime implementation
108-
- Complete Flow Memory runtime implementation
121+
- Production indexer and verifier services
122+
- Production Rootflow runtime implementation
123+
- Production Flow Memory runtime implementation
109124
- FlowRouter hardware implementation
110125
- Meshtastic integration
111-
- Dashboard, explorer, and hardware console applications
126+
- Explorer and hardware console applications
112127
- Cryptographic proof systems
113128
- Appchain/L1 design and implementation
114129

‎contracts/ACCESS_CONTROL_REVIEW.md‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
# Contracts Access-Control Review
2+
3+
Status: V0 launch hardening review.
4+
5+
## Summary
6+
7+
The current contracts use simple ownership or self-registration patterns. They do not implement staking, slashing, token custody, rewards, production governance, verifier consensus, or upgrade admin controls.
8+
9+
## RootfieldRegistry
10+
11+
Owner model: each `rootfieldId` has one owner.
12+
13+
Owner-gated functions:
14+
15+
- `submitRoot`
16+
- `deactivateRootfield`
17+
- `transferRootfieldOwnership`
18+
19+
Current protections:
20+
21+
- zero rootfield id rejected
22+
- duplicate rootfield id rejected
23+
- zero root rejected
24+
- inactive rootfield blocks root submission and transfer
25+
- zero new owner rejected
26+
- ownership transfer emits both a FlowPulse status event and a dedicated ownership event
27+
28+
Launch risk to watch:
29+
30+
- current ownership transfer uses `parentPulseId = bytes32(0)` by design; future versions may require explicit parent linkage.
31+
- URI fields are advisory event data, not trusted storage pointers.
32+
33+
## Owner-Allowlist Registries
34+
35+
Contracts:
36+
37+
- `VerifierReportRegistry`
38+
- `WorkReceiptRegistry`
39+
40+
Owner-gated functions:
41+
42+
- `setVerifierAuthorization`
43+
- `setWorkerAuthorization`
44+
45+
Submitter-gated functions:
46+
47+
- `submitVerifierReport` requires an authorized verifier.
48+
- `submitWorkReceipt` requires an authorized worker.
49+
50+
Current protections:
51+
52+
- zero worker/verifier rejected
53+
- duplicate report/receipt id rejected
54+
- invalid report status rejected
55+
- invalid work lane rejected
56+
- zero target or commitment fields rejected
57+
58+
Launch risk to watch:
59+
60+
- deployer is permanent owner in V0; there is no multisig, timelock, or owner transfer.
61+
- allowlists are coordination controls, not decentralized verifier consensus.
62+
63+
## Self-Registration Registries
64+
65+
Contracts:
66+
67+
- `WorkerRegistry`
68+
- `VerifierRegistry`
69+
70+
Owner model: the registering address controls its own metadata lifecycle.
71+
72+
Current protections:
73+
74+
- duplicate registration rejected
75+
- zero operator id rejected
76+
- zero role rejected
77+
- inactive records cannot update again
78+
79+
Launch risk to watch:
80+
81+
- registration does not prove work quality, correctness, identity, or stake.
82+
83+
## Per-Record Owner Registries
84+
85+
Contracts:
86+
87+
- `ArtifactRegistry`
88+
- `CursorRegistry`
89+
90+
Owner-gated functions:
91+
92+
- `deprecateArtifact`
93+
- `advanceCursor`
94+
95+
Current protections:
96+
97+
- zero ids and zero commitments rejected
98+
- duplicate records rejected
99+
- only the stored owner can mutate the record
100+
101+
Launch risk to watch:
102+
103+
- advisory URI strings are emitted as logs and are not validated content availability proofs.
104+
105+
## Open Submission Contracts
106+
107+
Contracts:
108+
109+
- `ReceiptVerifier`
110+
- `WorkDebtScheduler`
111+
- `FlowMemoryHookAdapter`
112+
113+
Current boundary:
114+
115+
- `ReceiptVerifier` accepts first-writer receipt-report commitments and does not cryptographically verify receipts.
116+
- `WorkDebtScheduler` allows any scheduler to assign work to a nonzero worker and allows scheduler or worker to mark completion.
117+
- `FlowMemoryHookAdapter` validates nonzero inputs and emits an observation event; it is not a production Uniswap v4 hook.
118+
119+
Launch risk to watch:
120+
121+
- open submission is acceptable for V0 commitments only if docs and demos treat outputs as untrusted until off-chain verifier reports exist.
122+
123+
## Required Review Before Expanding
124+
125+
Before adding rewards, staking, slashing, custody, dynamic fees, production hook permissions, or appchain/L1 settlement:
126+
127+
- create a threat model issue
128+
- require a separate review worktree
129+
- require event tests for every state transition
130+
- require static analysis with Slither
131+
- update this access-control review

‎contracts/DEPLOYMENT_BOUNDARY.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
# Contracts Deployment Boundary
2+
3+
Status: V0 local and Base Sepolia readiness boundary.
4+
5+
## Allowed Now
6+
7+
- Local Foundry tests.
8+
- Local fixture generation and indexer/verifier/dashboard flows.
9+
- Base Sepolia deployment preparation for the current V0 contracts.
10+
- Base Sepolia reads from explicit RPC URLs.
11+
- Public docs that describe emitted events, roots, receipts, and off-chain verification paths.
12+
13+
## Not Allowed Yet
14+
15+
- Base mainnet deployment claims.
16+
- Production-mainnet readiness claims.
17+
- Production L1 claims.
18+
- Token launch, rewards, slashing, or fee-market mechanics.
19+
- Dynamic Uniswap v4 fee hooks.
20+
- Custody of user tokens.
21+
- Claims that contracts can know `txHash` or `logIndex` during execution.
22+
- Claims that on-chain storage is free or that arbitrary AI data is stored on-chain.
23+
24+
## Deployment Inputs Required
25+
26+
Before a Base Sepolia deployment transaction is sent, the PR or issue must record:
27+
28+
- target chain: Base Sepolia, chain id `84532`
29+
- exact contract names and constructor arguments
30+
- deployer account address
31+
- compiled bytecode hash or Foundry build commit
32+
- expected event signatures
33+
- post-deploy verification steps
34+
- rollback or redeploy plan
35+
36+
Private keys must not be committed to the repo, copied into docs, or stored in generated artifacts.
37+
38+
## Current Contract Set
39+
40+
- `RootfieldRegistry`: Rootfield namespaces and root commitment pulses.
41+
- `FlowMemoryHookAdapter`: dependency-light hook-adapter event scaffold, not a production Uniswap hook.
42+
- `ReceiptVerifier`: compact receipt-report commitments, not cryptographic receipt verification.
43+
- `VerifierReportRegistry`: owner-authorized verifier report commitments.
44+
- `WorkReceiptRegistry`: owner-authorized worker receipt commitments.
45+
- `WorkerRegistry`: self-registration for worker identity metadata.
46+
- `VerifierRegistry`: self-registration for verifier identity metadata.
47+
- `ArtifactRegistry`: artifact commitment metadata.
48+
- `CursorRegistry`: off-chain cursor commitment metadata.
49+
- `WorkDebtScheduler`: work-state commitments without token debt.
50+
51+
## Post-Deploy Checks
52+
53+
- Verify source on the explorer when possible.
54+
- Emit one small test event per deployed event source where safe.
55+
- Run the Base Sepolia indexer reader over the deployment block range.
56+
- Confirm persisted indexer state and checkpoint exist.
57+
- Confirm dashboard fixtures can read the generated state.
58+
- Update `docs/CURRENT_STATE.md` with what is deployed and what remains local-only.

‎contracts/STATIC_ANALYSIS.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# Contracts Static Analysis
2+
3+
Status: pre-production hardening setup.
4+
5+
This repository now has one standard command for contract hardening checks:
6+
7+
```powershell
8+
.\infra\scripts\contracts-static-analysis.ps1
9+
```
10+
11+
On bash-compatible shells:
12+
13+
```bash
14+
bash infra/scripts/contracts-static-analysis.sh
15+
```
16+
17+
The command runs:
18+
19+
- `forge build`
20+
- `forge test`
21+
- `slither . --config-file .slither.config.json` when Slither is installed
22+
23+
Formatting can be checked explicitly:
24+
25+
```powershell
26+
.\infra\scripts\contracts-static-analysis.ps1 -CheckFormat
27+
```
28+
29+
```bash
30+
CHECK_FORGE_FMT=1 bash infra/scripts/contracts-static-analysis.sh
31+
```
32+
33+
Audit environments should require Slither explicitly:
34+
35+
```powershell
36+
.\infra\scripts\contracts-static-analysis.ps1 -RequireSlither
37+
```
38+
39+
```bash
40+
REQUIRE_SLITHER=1 bash infra/scripts/contracts-static-analysis.sh
41+
```
42+
43+
## Current Boundary
44+
45+
The contracts are V0 launch foundations for FlowPulse, Rootfield, receipts, workers, verifiers, cursors, and hook-adapter events. They are not a production L1, production verifier network, token system, custody system, fee system, or production Uniswap v4 hook deployment.
46+
47+
Static-analysis findings should be triaged into:
48+
49+
- blocker: unsafe access control, broken event schema, corrupted state transition, or deploy-time risk
50+
- launch-v0 fix: issue that matters for Base Sepolia/demo correctness
51+
- future hardening: useful improvement that does not block the V0 launch boundary
52+
53+
## Required Before Any Public Testnet Deployment
54+
55+
- All Foundry tests pass.
56+
- `forge fmt --check` passes or a deliberate formatting-normalization PR is opened.
57+
- Slither is run and findings are attached to the PR or issue.
58+
- Access-control changes are reviewed against [ACCESS_CONTROL_REVIEW.md](./ACCESS_CONTROL_REVIEW.md).
59+
- Deployment scope is reviewed against [DEPLOYMENT_BOUNDARY.md](./DEPLOYMENT_BOUNDARY.md).

0 commit comments

Comments
 (0)