Skip to content

Commit b25b4d0

Browse files
FlowmemoryAIFlowmemoryAI
committed
Add Base Sepolia public-agent deployment path
1 parent 2c388e8 commit b25b4d0

15 files changed

Lines changed: 1652 additions & 12 deletions

‎README.md‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,7 @@ FlowMemory currently ships a local/test implementation of the main protocol surf
4242
| Repository | Public and launch-polished | `README.md`, `docs/PUBLIC_REPO_GUIDE.md` |
4343
| Public test lanes | Reproducible from a clean clone | `npm run public:test:all` |
4444
| Agent Bonds | Local/test accountability, recourse, and reputation flows | `docs/AGENT_BONDS_PHASE2_ARCHITECTURE.md` |
45-
| Public agent network | Local/test contracts and e2e path | `npm run public-agent-network:contracts`, `npm run public-agent-network:local-e2e` |
45+
| Public agent network | Local/test contracts, e2e path, and Base Sepolia operator plan/readback tooling | `npm run public-agent-network:contracts`, `npm run public-agent-network:local-e2e`, `npm run public-agent-network:base-sepolia:plan` |
4646
| Mobile operator layer | Android shell committed; iOS product track documented | `docs/MOBILE_APPS.md`, `apps/dashboard/WALLET_DISTRIBUTION.md` |
4747
| Production / real-value claims | Still intentionally gated | `docs/MARKETING_CLAIMS_GUARDRAILS.md`, `docs/PRODUCTION_READINESS_CHECKLIST.md` |
4848

@@ -112,6 +112,14 @@ npm run public-agent-network:contracts
112112
npm run public-agent-network:local-e2e
113113
```
114114

115+
Prepare the public-safe Base Sepolia operator plan:
116+
117+
```powershell
118+
npm run public-agent-network:base-sepolia:plan -- --deployer-address 0x69F55917209C446bf9d31D2903e01966B75a8cDe --json
119+
```
120+
121+
Dry run, broadcast, and readback require local operator credentials and are documented in `docs/DEPLOYMENTS/BASE_SEPOLIA_PUBLIC_AGENT_NETWORK.md`.
122+
115123
## Mobile Apps: The Operator Layer
116124

117125
The iOS and Android app track is a major part of the AI infrastructure network. FlowMemory is not only backend protocol machinery; operators need a pocket control plane for agents.

‎docs/CURRENT_STATE.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ A local/test Agent Bonds v1 accountability surface exists for objective off-chai
1616

1717
On 2026-05-13 a small Base mainnet canary deployment was broadcast for V0 testing. It is documented in `docs/DEPLOYMENTS/2026-05-13-base-canary-v0.md`. A guarded Base mainnet canary reader now exists for those known canary addresses and small explicit block ranges. This is not a production launch and does not change the production/mainnet-readiness guardrails.
1818

19-
On 2026-05-21 the repo gained a public-agent local/test stack: shared `BaseOnchainAgentMemory` runtime integration, public agent class/tool/profile/lineage/fuel/bond/receipt contracts, `AgentFactory`, swarm policy/registry/budget/factory contracts, deterministic public launch helpers, control-plane and SDK/CLI discovery/preview methods, direct calldata builders for `AgentFactory.launchAgent(...)` and `SwarmFactory.createSwarm(...)`, dashboard projection, Foundry tests, and a local Foundry e2e script. This is public for review and local experimentation only; it is not a production launch or audited runtime.
19+
On 2026-05-21 the repo gained a public-agent local/test stack: shared `BaseOnchainAgentMemory` runtime integration, public agent class/tool/profile/lineage/fuel/bond/receipt contracts, `AgentFactory`, swarm policy/registry/budget/factory contracts, deterministic public launch helpers, control-plane and SDK/CLI discovery/preview methods, direct calldata builders for `AgentFactory.launchAgent(...)` and `SwarmFactory.createSwarm(...)`, dashboard projection, Foundry tests, a local Foundry e2e script, and Base Sepolia public-agent deployment/readback tooling with a configured public testnet deployer plan. This is public for review and local/testnet experimentation only; it is not a production launch or audited runtime.
2020

2121
The public-facing app story includes the mobile operator layer. The shared dashboard surface is packaged as browser/desktop and a committed Android Capacitor shell, while iOS remains an explicitly documented product track until an Xcode project and CI lane are added. Mobile is positioned as the always-available operator console for Agent Bonds, receipts, recourse, wallet/budget state, public-agent monitoring, and future alerting.
2222

@@ -86,8 +86,8 @@ Public-agent stack:
8686
- Shared `BaseOnchainAgentMemory` runtime integration exists.
8787
- Public agent class/tool/profile/lineage/fuel/bond/receipt contracts and `AgentFactory` exist.
8888
- Swarm policy/registry/budget/factory contracts exist.
89-
- Deterministic public launch helpers, control-plane discovery/preview methods, SDK/CLI smoke lanes, direct calldata builders, dashboard projection, Foundry tests, and a local Foundry e2e script exist.
90-
- This is public for review and local experimentation only; it is not a production launch or audited runtime.
89+
- Deterministic public launch helpers, control-plane discovery/preview methods, SDK/CLI smoke lanes, direct calldata builders, dashboard projection, Foundry tests, a local Foundry e2e script, and Base Sepolia public-agent deploy/readback tooling exist.
90+
- This is public for review and local/testnet experimentation only; it is not a production launch or audited runtime.
9191

9292
Mobile operator layer:
9393

‎docs/DEPLOYMENTS/BASE_SEPOLIA_PUBLIC_AGENT_NETWORK.md‎

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
# Base Sepolia Public Agent Network Rehearsal
2+
3+
Status: operator runbook and non-secret plan for issue #164.
4+
5+
This is a Base Sepolia public testnet rehearsal path. It is not production, not mainnet readiness, not an audit result, and not approval for uncapped value-bearing use.
6+
7+
## Configured Deployer
8+
9+
The current public testnet deployer address is:
10+
11+
```text
12+
0x69F55917209C446bf9d31D2903e01966B75a8cDe
13+
```
14+
15+
Explorer:
16+
17+
```text
18+
https://sepolia.basescan.org/address/0x69F55917209C446bf9d31D2903e01966B75a8cDe
19+
```
20+
21+
Only the public address belongs in Git. Never include private keys, RPC URLs, explorer API keys, `.env` content, seed phrases, or wallet secrets in docs, GitHub issues, PR comments, screenshots, or committed artifacts.
22+
23+
## What The Rehearsal Deploys
24+
25+
`script/DeployPublicAgentNetworkBaseSepolia.s.sol` deploys and smoke-exercises:
26+
27+
- `BaseOnchainAgentMemory`
28+
- `AgentClassRegistry`
29+
- `ToolRegistry`
30+
- `AgentProfileRegistry`
31+
- `AgentLaunchBondEscrow`
32+
- `AgentMemoryFuelVault`
33+
- `AgentLineageRegistry`
34+
- `AgentReceiptAnchor`
35+
- `AgentShellFactory`
36+
- `AgentFactory`
37+
- `SwarmPolicyRegistry`
38+
- `SwarmRegistry`
39+
- `SwarmBudgetVault`
40+
- `SwarmFactory`
41+
- `PublicNetworkBaseSepoliaToken` test token
42+
43+
The script then emits public-safe evidence for class/tool registration, launch bond policy, memory fuel policy, one deployer-owned task-scout agent launch, one receipt anchor, one research swarm, and the swarm budget deposit/line/reserve/release/spend path.
44+
45+
## Plan-Only Command
46+
47+
This writes the committed non-secret plan artifact and does not require a private key:
48+
49+
```powershell
50+
npm run public-agent-network:base-sepolia:plan -- --deployer-address 0x69F55917209C446bf9d31D2903e01966B75a8cDe --json
51+
```
52+
53+
Default output:
54+
55+
```text
56+
fixtures/deployments/public-agent-network-base-sepolia-plan.json
57+
```
58+
59+
## Required Local Environment For Dry Run Or Broadcast
60+
61+
```powershell
62+
$env:BASE_SEPOLIA_RPC_URL="<base-sepolia-rpc-url>"
63+
$env:BASE_SEPOLIA_DEPLOYER_KEY_HEX="<0x-prefixed-32-byte-testnet-key>"
64+
$env:BASE_SEPOLIA_PUBLIC_AGENT_DEPLOYER_ADDRESS="0x69F55917209C446bf9d31D2903e01966B75a8cDe"
65+
```
66+
67+
Optional source-verification key:
68+
69+
```powershell
70+
$env:BASE_SEPOLIA_BASESCAN_API_KEY="<basescan-api-key>"
71+
```
72+
73+
The Foundry script derives the address from `BASE_SEPOLIA_DEPLOYER_KEY_HEX` and rejects the run if it does not equal `BASE_SEPOLIA_PUBLIC_AGENT_DEPLOYER_ADDRESS`.
74+
75+
## Dry Run
76+
77+
Run this before any broadcast:
78+
79+
```powershell
80+
npm run public-agent-network:base-sepolia -- --json
81+
```
82+
83+
Default dry-run artifact:
84+
85+
```text
86+
fixtures/deployments/public-agent-network-base-sepolia.latest.json
87+
```
88+
89+
## Broadcast
90+
91+
Broadcast only after the deployer is funded on Base Sepolia and the operator accepts testnet gas spend:
92+
93+
```powershell
94+
npm run public-agent-network:base-sepolia:broadcast -- --json
95+
```
96+
97+
After broadcast, keep the Foundry `broadcast/` folder ignored. Copy only non-secret facts into the deployment artifact or dated evidence doc:
98+
99+
- deployer address;
100+
- contract names and addresses;
101+
- deploy and smoke transaction hashes;
102+
- deployment and smoke blocks;
103+
- readback report paths;
104+
- source-verification status per contract.
105+
106+
## Bounded Readback
107+
108+
Read back only explicit addresses and a bounded block range:
109+
110+
```powershell
111+
npm run public-agent-network:base-sepolia:readback -- --rpc-url $env:BASE_SEPOLIA_RPC_URL --deployment-artifact fixtures/deployments/public-agent-network-base-sepolia.latest.json --from-block <deployBlock> --to-block <latestBlock>
112+
```
113+
114+
Default outputs:
115+
116+
```text
117+
fixtures/deployments/public-agent-network-base-sepolia-readback.latest.json
118+
fixtures/deployments/public-agent-network-base-sepolia-readback.latest.md
119+
```
120+
121+
The readback script requires Base Sepolia chain id `84532`, rejects broad scans, writes no RPC URLs or secrets, and fails unless it observes all required event groups:
122+
123+
- registry;
124+
- launch;
125+
- fuel;
126+
- bond;
127+
- swarm.
128+
129+
## Source Verification
130+
131+
Use the explorer key from local env only:
132+
133+
```powershell
134+
forge verify-contract --watch --chain-id 84532 <address> <fully-qualified-contract> --etherscan-api-key $env:BASE_SEPOLIA_BASESCAN_API_KEY
135+
```
136+
137+
Use the Foundry broadcast metadata for constructor arguments. Record `submitted`, `verified`, or `pending` for every deployed contract in the final evidence.
138+
139+
## Acceptance Checklist
140+
141+
- `npm run public-agent-network:base-sepolia:plan -- --deployer-address 0x69F55917209C446bf9d31D2903e01966B75a8cDe --json` writes the non-secret plan.
142+
- Dry run rejects the wrong chain id and mismatched deployer key/address.
143+
- Broadcast emits public-agent registry, launch, fuel, bond, receipt, and swarm events.
144+
- Readback observes required event groups over an explicit bounded block range.
145+
- Source verification is submitted or explicitly marked pending per contract.
146+
- No private keys, RPC URLs, explorer API keys, or `.env` files are committed.
147+
- Docs continue to state that this is Base Sepolia testnet evidence only.

‎docs/PUBLIC_AGENT_NETWORK_RELEASE.md‎

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,14 +21,16 @@ The current public-agent network stack includes:
2121
- public swarm preview, launch intent, replay, prototype projection methods, and direct create-call builders;
2222
- public SDK and CLI wrappers for discovery, public launch/swarm projections, and local CLI smoke;
2323
- dashboard public-network view backed by deterministic local data;
24-
- Foundry tests for public contracts and a local script that exercises agent launch plus swarm budget lifecycle.
24+
- Foundry tests for public contracts and a local script that exercises agent launch plus swarm budget lifecycle;
25+
- Base Sepolia public-agent deployment, source-verification, and bounded event-readback tooling with a configured public testnet deployer plan in `fixtures/deployments/public-agent-network-base-sepolia-plan.json`.
2526

2627
## Verification Commands
2728

2829
```powershell
2930
npm run public-agent-network:contracts
3031
npm run public-agent-network:local-e2e
3132
npm run public:test:quick
33+
npm run public-agent-network:base-sepolia:plan -- --deployer-address 0x69F55917209C446bf9d31D2903e01966B75a8cDe --json
3234
npm test --prefix services/control-plane
3335
npm test --prefix services/agent-memory-sdk
3436
npm test --prefix apps/dashboard
@@ -45,6 +47,17 @@ npm run public-agent-network:local-e2e
4547

4648
It runs `script/RunPublicAgentNetworkLocalE2E.s.sol:RunPublicAgentNetworkLocalE2E`, deploys the public-agent and swarm contracts in a local Foundry script simulation, signs a deterministic public launch intent, creates an agent, creates a swarm with that agent as a member, reserves and releases budget, and spends from a budget line.
4749

50+
The Base Sepolia operator rehearsal path is:
51+
52+
```powershell
53+
npm run public-agent-network:base-sepolia:plan -- --deployer-address 0x69F55917209C446bf9d31D2903e01966B75a8cDe --json
54+
npm run public-agent-network:base-sepolia -- --json
55+
npm run public-agent-network:base-sepolia:broadcast -- --json
56+
npm run public-agent-network:base-sepolia:readback -- --rpc-url $env:BASE_SEPOLIA_RPC_URL --deployment-artifact fixtures/deployments/public-agent-network-base-sepolia.latest.json --from-block <deployBlock> --to-block <latestBlock>
57+
```
58+
59+
The plan command is public-safe and committed. Dry run, broadcast, and readback require explicit local operator environment values and must not write RPC URLs, private keys, or explorer API keys.
60+
4861
## What This Is Not
4962

5063
This release does not claim:

‎docs/PUBLIC_AGENT_NETWORK_TECHNICAL_GUIDE.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -140,6 +140,17 @@ npm run public-agent-network:local-e2e
140140

141141
The e2e script deploys the local public-agent stack, signs a deterministic launch intent, creates an agent, creates a swarm with the agent as a member, creates a budget line, reserves and releases budget, and records a spend.
142142

143+
Base Sepolia public-agent rehearsal tooling:
144+
145+
```powershell
146+
npm run public-agent-network:base-sepolia:plan -- --deployer-address 0x69F55917209C446bf9d31D2903e01966B75a8cDe --json
147+
npm run public-agent-network:base-sepolia -- --json
148+
npm run public-agent-network:base-sepolia:broadcast -- --json
149+
npm run public-agent-network:base-sepolia:readback -- --rpc-url $env:BASE_SEPOLIA_RPC_URL --deployment-artifact fixtures/deployments/public-agent-network-base-sepolia.latest.json --from-block <deployBlock> --to-block <latestBlock>
150+
```
151+
152+
The committed plan lives at `fixtures/deployments/public-agent-network-base-sepolia-plan.json`; the operator runbook is `docs/DEPLOYMENTS/BASE_SEPOLIA_PUBLIC_AGENT_NETWORK.md`. Dry run, broadcast, and readback require explicit local environment values. The deploy script verifies that `BASE_SEPOLIA_DEPLOYER_KEY_HEX` derives `BASE_SEPOLIA_PUBLIC_AGENT_DEPLOYER_ADDRESS`, and the readback script fails unless bounded Base Sepolia logs include registry, launch, fuel, bond, and swarm event groups.
153+
143154
The broader local/test gate remains:
144155

145156
```powershell

‎docs/PUBLIC_RELEASE_GAPS.md‎

Lines changed: 5 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -10,15 +10,14 @@ These are not hidden defects. They are the remaining work required before FlowMe
1010

1111
Tracking issue: https://github.com/FlowmemoryAI/FlowMemory/issues/164
1212

13-
Current state: scripts and contract stack exist, but no full public-agent network Base Sepolia broadcast/readback is committed for this release.
13+
Current state: public-agent deployment, smoke-broadcast, source-verification, and bounded event-readback tooling now exists. The configured public testnet deployer address is recorded in `fixtures/deployments/public-agent-network-base-sepolia-plan.json` and `docs/DEPLOYMENTS/BASE_SEPOLIA_PUBLIC_AGENT_NETWORK.md`, but no full public-agent network Base Sepolia broadcast/readback evidence is committed yet.
1414

1515
Missing work:
1616

17-
- fund and configure a dedicated testnet deployer locally;
18-
- broadcast the public-agent and swarm stack to Base Sepolia;
19-
- read back emitted launch, registry, fuel, bond, and swarm events with bounded block ranges;
20-
- commit non-secret deployment/readback evidence;
21-
- source-verify deployed contracts where supported.
17+
- fund the dedicated Base Sepolia deployer and set local env without committed secrets;
18+
- run dry-run, broadcast, and bounded readback for the public-agent and swarm stack;
19+
- commit non-secret deployment/readback evidence with transaction hashes, contract addresses, and event-group counts;
20+
- source-verify deployed contracts where supported and record submitted/verified/pending status per contract.
2221

2322
### 2. Keeper / runtime automation
2423

‎docs/PUBLIC_REPO_GUIDE.md‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ The repository currently contains:
1414
- fixture-first indexer, verifier, Flow Memory, control-plane, SDK, and dashboard packages;
1515
- deterministic Rootflow and Flow Memory V0 fixtures;
1616
- signed Agent Bonds quote attestations, recourse-policy fixtures, and requester quote/create SDK helpers;
17-
- a public-agent launch and swarm stack with Foundry tests and a local e2e script;
17+
- a public-agent launch and swarm stack with Foundry tests, a local e2e script, and a Base Sepolia operator rehearsal plan/readback path;
1818
- a developing mobile operator surface, with an Android Capacitor shell committed today and iOS documented as a product track that still needs an Xcode project;
1919
- FlowRouter hardware/resilience research materials;
2020
- public docs that describe what exists, what works locally, and what must be verified before broader value-bearing claims are allowed.
@@ -84,6 +84,14 @@ npm run public:test:dashboard
8484
npm run public:test:cli
8585
```
8686

87+
For the Base Sepolia public-agent operator rehearsal, start with the public-safe plan:
88+
89+
```powershell
90+
npm run public-agent-network:base-sepolia:plan -- --deployer-address 0x69F55917209C446bf9d31D2903e01966B75a8cDe --json
91+
```
92+
93+
Dry run, broadcast, and event readback are documented in `docs/DEPLOYMENTS/BASE_SEPOLIA_PUBLIC_AGENT_NETWORK.md` and require local operator credentials that must never be committed.
94+
8795
The full public local pass is:
8896

8997
```powershell

‎docs/PUBLIC_TESTER_GUIDE.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,8 @@ This guide is for people who want to try something real in the public repo and r
1616
| Public hardening gate | Public docs, scripts, issue-template, and CI wiring | Node.js + npm | `npm run public:hardening` |
1717
| Full public local pass | All public tester lanes plus hardening and claim guardrails | Node.js + npm + Foundry | `npm run public:test:all` |
1818

19+
20+
Authorized operators can also rehearse the Base Sepolia public-agent deployment plan and bounded readback path. That lane is not required for normal public testers because dry run, broadcast, and readback require local RPC and deployer credentials.
1921
If you only have Node.js, run the quick JS smoke first. If you also have Foundry, run the contract and e2e lanes.
2022

2123
## Setup
@@ -166,6 +168,17 @@ Useful feedback:
166168
- Were field names understandable?
167169
- What should the CLI summarize for non-protocol users?
168170

171+
172+
## Authorized Operator Lane: Base Sepolia Public-Agent Rehearsal
173+
174+
Public-safe plan command:
175+
176+
```powershell
177+
npm run public-agent-network:base-sepolia:plan -- --deployer-address 0x69F55917209C446bf9d31D2903e01966B75a8cDe --json
178+
```
179+
180+
Operator-only dry run, broadcast, and readback commands are documented in `docs/DEPLOYMENTS/BASE_SEPOLIA_PUBLIC_AGENT_NETWORK.md`. Reports from that lane should include only public addresses, transaction hashes, contract addresses, bounded block ranges, event counts, and source-verification statuses. Never include private keys, RPC URLs, explorer API keys, or `.env` content.
181+
169182
## What To Report
170183
If you want the repo to generate most of the report body, run:
171184

0 commit comments

Comments
 (0)