Skip to content

[codex] Extend local FlowChain control-plane API #114

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
FlowmemoryAI wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

[codex] Extend local FlowChain control-plane API #114

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
181 changes: 162 additions & 19 deletions docs/FLOWCHAIN_CONTROL_PLANE_API.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
# FlowChain Local Control Plane API

Status: local fixture-backed V0 contract.
Status: local runtime-backed V0 contract with deterministic fixture fallback.

This document defines the local JSON-RPC 2.0 API for the FlowChain / FlowMemory control-plane. It gives dashboard, agent, verifier, and devnet tooling one deterministic read surface for FlowMemory objects.
This document defines the local JSON-RPC 2.0 API for the FlowChain / FlowMemory control-plane. It gives dashboard, agent, verifier, bridge, and devnet tooling one deterministic local surface for FlowMemory objects.

It is not a production RPC endpoint, public L1 API, hosted service, wallet API, bridge API, token API, or verifier economics surface.
It is not a production RPC endpoint, public L1 API, hosted service, production wallet API, production bridge API, token API, or verifier economics surface.

## Runtime Boundary

Expand All @@ -21,13 +21,17 @@ npm run control-plane:test
npm run control-plane:demo
npm run control-plane:smoke
npm run control-plane:serve
npm run flowchain:full-smoke
```

The service uses deterministic local files only. It does not require secrets, wallets, RPC URLs, private keys, API keys, or production services.
The service reads ignored local runtime files first and falls back to committed deterministic fixtures. It does not require secrets, RPC URLs, private keys, API keys, or production services.

Primary data sources:

```text
devnet/local/state.json
devnet/local/launch-v0-state.json
devnet/local/handoff/generated/*.json
fixtures/launch-core/flowmemory-launch-v0.json
fixtures/launch-core/generated/devnet/state.json
fixtures/launch-core/generated/devnet/indexer-handoff.json
Expand All @@ -37,9 +41,12 @@ services/indexer/out/indexer-state.json
services/verifier/out/reports.json
services/verifier/fixtures/artifacts.json
fixtures/handoff/sample-txs.json
services/bridge-relayer/out/bridge-observation.json
services/bridge-relayer/out/control-plane-observations.json
fixtures/bridge/base-sepolia-mock-deposit.json
```

If the generated launch-core fixture is missing, the service rebuilds the in-memory view from indexer/verifier outputs or raw fixture receipts and artifact fixtures. This recovery path is local and read-only from the API caller perspective.
If the generated launch-core fixture is missing, the service rebuilds the in-memory view from indexer/verifier outputs or raw fixture receipts and artifact fixtures. This recovery path is local. Transaction and bridge observation write endpoints forward only into the existing local runtime or bridge-agent intake files.

## JSON-RPC Envelope

Expand Down Expand Up @@ -113,22 +120,51 @@ GET /health

Params: none.

Returns local stack status, fixture source status, block counters, object counters, capabilities, and limitations.
Returns local stack status, live/fixture source status, block counters, object counters, capabilities, and limitations.

Key result fields:

```json
{
"schema": "flowmemory.control_plane.chain_status.v0",
"chainId": "flowmemory-local-alpha",
"environment": "local-devnet-fixture",
"source": "fixture",
"chainId": "flowmemory-local-devnet-v0",
"environment": "private-local-devnet",
"source": "local-runtime-file",
"currentBlock": "123461",
"finalizedBlock": "123457",
"localOnly": true
}
```

### `node_status`

Params: none.

Returns bounded local runtime status, current block, state root, pending
transaction count, runtime mode, and source file. The current runtime reports
`longRunningNode: false` because it is still the deterministic Rust CLI, not a
daemon.

### `peer_list`

Params: none.

Returns the local self peer for the single-process runtime. LAN peer discovery
is not implemented in this package.

### `mempool_list`

Params:

```json
{
"limit": 50
}
```

Returns pending transaction envelopes from the local devnet state or
control-plane handoff.

### `devnet_state`

Params:
Expand Down Expand Up @@ -195,6 +231,55 @@ Params: one of:
{ "txHash": "0x..." }
```

### `transaction_submit`

Params: one of:

```json
{ "tx": { "type": "RegisterRootfield" } }
```

```json
{ "txs": [{ "type": "RegisterRootfield" }] }
```

```json
{ "signedTransaction": { "tx": { "type": "RegisterRootfield" }, "signature": "0x..." } }
```

The control-plane writes a local fixture under
`devnet/local/control-plane-intake/` and forwards it to the existing runtime
intake path:

```powershell
cargo run --manifest-path crates/flowmemory-devnet/Cargo.toml -- --state devnet/local/state.json submit-fixture --fixture <generated-fixture>
```

The endpoint queues transactions only. It does not produce a block by itself.
Payloads containing secret-bearing fields such as `privateKey`, `mnemonic`,
`seedPhrase`, `rpcUrl`, `apiKey`, or webhook credentials are rejected.

### `account_list` / `account_get`

Return local public account rows for operator key references and `AgentAccount`
objects. Balances are no-value local devnet balances.

### `balance_list` / `balance_get`

Return explicit zero/no-value balances. The private/local runtime has no token
value, gas accounting, staking, rewards, or faucet funds.

### `faucet_event_list` / `faucet_event_get`

Return a stable disabled faucet event explaining that the local devnet has no
token value or faucet funds.

### `wallet_metadata_list` / `wallet_metadata_get`

Return public operator key-reference metadata only: key reference ids, operator
ids, signature scheme labels, and verifier-set roots. No signing secret
material is returned.

### `rootfield_get`

Params:
Expand Down Expand Up @@ -443,6 +528,11 @@ Params: one of:

Returns an `AgentMemoryView` and linked `RootfieldBundle`.

### `agent_account_list` / `agent_account_get`

Return native private/local `AgentAccount` objects from the devnet runtime state
or handoff files.

### `agent_list`

Params:
Expand Down Expand Up @@ -483,6 +573,11 @@ Params: one of:
{ "rootfieldId": "0x..." }
```

### `model_passport_list` / `model_passport_get`

Return native private/local `ModelPassport` objects from the devnet runtime
state or handoff files.

### `challenge_get`

Params: one of:
Expand Down Expand Up @@ -556,6 +651,42 @@ Params:

All params are optional. Returns native finality receipts when present and projected local finality rows for launch-core receipts.

### `bridge_observation_submit`

Params: one of:

```json
{ "observation": { "schema": "flowmemory.bridge_deposit_observation.v0" } }
```

```json
{ "deposit": { "schema": "flowmemory.bridge_deposit.v0" } }
```

Stores local bridge-agent observations in
`services/bridge-relayer/out/control-plane-observations.json`. This is local
observation intake only; it does not custody funds, sign releases, or implement
production bridge security.

### `bridge_observation_list` / `bridge_observation_get`

Return bridge observations from bridge-relayer output, control-plane intake, or
the committed mock deposit fixture.

### `bridge_deposit_list` / `bridge_deposit_get`

Return bridge deposit rows derived from bridge observations.

### `bridge_credit_list` / `bridge_credit_get`

Return local bridge-credit projections for observed deposits. Pending credits do
not imply production bridge accounting.

### `withdrawal_list` / `withdrawal_get`

Return local withdrawal handoff rows when present. Without native withdrawal
handoff data, `withdrawal_get` returns a stable `not_opened` placeholder.

### `provenance_get`

Params: one of:
Expand Down Expand Up @@ -603,20 +734,32 @@ Allowed `source` values:
- `devnetVerifierHandoff`
- `devnetControlPlaneHandoff`
- `txFixtures`
- `bridgeObservation`
- `bridgeObservationIntake`
- `bridgeDepositFixture`

Returns the raw loaded local JSON object for dashboard/workbench debug views. It does not accept arbitrary filesystem paths.

## Dashboard Consumption Notes

Dashboard agents should prefer:

1. `health` and `chain_status` for source health and global counters.
2. `block_list` and `transaction_list` for chain/devnet tables.
3. `rootfield_list` and `rootfield_get` for Rootfield detail.
4. `work_receipt_list`, `receipt_list`, `verifier_module_list`, and `verifier_report_list` for lifecycle tables.
5. `receipt_get`, `work_receipt_get`, `verifier_report_get`, and `provenance_get` for detail drawers.
6. `artifact_availability_list`, `memory_cell_list`, `agent_list`, and `model_list` for dashboard/workbench panels.
7. `challenge_get`, `challenge_list`, `finality_get`, and `finality_list` for local fixture challenge/finality labels.
8. `raw_json_get` for raw JSON inspection.

The API is intentionally read-only for V0. Submit, challenge, wallet, live indexing, and production settlement methods require separate scoped work.
1. `health`, `chain_status`, and `node_status` for source health and global counters.
2. `block_list`, `transaction_list`, and `mempool_list` for chain/devnet tables.
3. `account_list`, `wallet_metadata_list`, `balance_list`, and `faucet_event_list` for local account panels.
4. `rootfield_list` and `rootfield_get` for Rootfield detail.
5. `agent_account_list`, `model_passport_list`, `work_receipt_list`, `receipt_list`, `verifier_module_list`, and `verifier_report_list` for lifecycle tables.
6. `receipt_get`, `work_receipt_get`, `verifier_report_get`, and `provenance_get` for detail drawers.
7. `artifact_availability_list`, `memory_cell_list`, `agent_list`, and `model_list` for dashboard/workbench panels.
8. `challenge_get`, `challenge_list`, `finality_get`, and `finality_list` for local challenge/finality labels.
9. `bridge_observation_list`, `bridge_deposit_list`, `bridge_credit_list`, and `withdrawal_list` for bridge-agent inspection.
10. `raw_json_get` for raw JSON inspection.

HTTP helpers are available for browser workbench reads at `/node/status`,
`/peers`, `/mempool`, `/blocks`, `/transactions`, `/accounts`, `/balances`,
`/faucet/events`, `/wallets`, `/agents`, `/models`, `/work-receipts`,
`/artifacts/availability`, `/verifier-modules`, `/verifier-reports`,
`/memory-cells`, `/challenges`, `/finality`, `/bridge/observations`,
`/bridge/deposits`, `/bridge/credits`, and `/withdrawals`. Write helpers are
available at `POST /transactions` and `POST /bridge/observations`; JSON-RPC
remains the canonical API envelope.
4 changes: 2 additions & 2 deletions docs/INDEXER_VERIFIER_MVP.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -270,7 +270,7 @@ Those are future protocol decisions, not part of this local package.

## Local Control Plane

`services/control-plane` exposes the fixture-backed FlowChain / FlowMemory JSON-RPC 2.0 read API documented in `docs/FLOWCHAIN_CONTROL_PLANE_API.md`.
`services/control-plane` exposes the FlowChain / FlowMemory JSON-RPC 2.0 API documented in `docs/FLOWCHAIN_CONTROL_PLANE_API.md`. It now reads ignored `devnet/local/` runtime state and handoff files first, then falls back to committed deterministic fixtures.

Run:

Expand All @@ -281,7 +281,7 @@ npm run control-plane:smoke
npm run control-plane:serve
```

The control-plane reads committed launch-core, indexer, verifier, artifact, transaction fixture, and local devnet handoff files first. If the generated launch-core fixture is missing, it rebuilds an in-memory view from deterministic indexer/verifier fixtures. It exposes read methods for health, chain status, blocks, transactions, rootfields, agents, models, work receipts, artifact availability, verifier modules, verifier reports, memory cells, challenges, finality, provenance, and raw JSON. It does not fetch production RPC data, store secrets, or make production API claims.
The control-plane exposes methods for health, chain status, node status, peers, mempool, blocks, transactions, transaction submission, accounts, balances, faucet status, wallet public metadata, rootfields, agents, agent accounts, models, model passports, work receipts, artifact availability, verifier modules, verifier reports, memory cells, challenges, finality, bridge observations/deposits/credits/withdrawals, provenance, and raw JSON. `transaction_submit` forwards local test transactions to the existing Rust devnet `submit-fixture` intake path. `bridge_observation_submit` stores bridge-agent observations under `services/bridge-relayer/out/`. The smoke client queries every lifecycle object and runs no-secret response scanning. The package does not fetch production RPC data, store secrets, or make production API claims.

## Open Questions

Expand Down
1 change: 1 addition & 0 deletions package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,7 @@
"flowchain:stop": "powershell -NoProfile -ExecutionPolicy Bypass -File infra/scripts/flowchain-stop.ps1",
"flowchain:demo": "powershell -NoProfile -ExecutionPolicy Bypass -File infra/scripts/flowchain-demo.ps1",
"flowchain:smoke": "powershell -NoProfile -ExecutionPolicy Bypass -File infra/scripts/flowchain-smoke.ps1",
"flowchain:full-smoke": "npm run flowchain:smoke && npm run control-plane:smoke",
"flowchain:export": "powershell -NoProfile -ExecutionPolicy Bypass -File infra/scripts/flowchain-export.ps1",
"flowchain:import": "powershell -NoProfile -ExecutionPolicy Bypass -File infra/scripts/flowchain-import.ps1",
"workbench:dev": "powershell -NoProfile -ExecutionPolicy Bypass -File infra/scripts/flowchain-workbench.ps1",
Expand Down
45 changes: 40 additions & 5 deletions services/control-plane/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# FlowChain Control Plane V0

This package exposes a local JSON-RPC 2.0 control-plane for FlowMemory and FlowChain fixture data. It is fixture-first, deterministic, and read-only.
This package exposes a local JSON-RPC 2.0 control-plane for FlowMemory and FlowChain runtime/fixture data. It reads ignored `devnet/local/` state first, falls back to committed deterministic fixtures, and forwards local write intake to the existing devnet and bridge-relayer paths.

It is not a production RPC endpoint, hosted service, wallet, sequencer, verifier network, token system, or production chain API.
It is not a production RPC endpoint, hosted service, production wallet, sequencer, verifier network, token system, production bridge, or production chain API.

## Commands

Expand All @@ -13,6 +13,7 @@ npm run control-plane:demo
npm run control-plane:test
npm run control-plane:smoke
npm run control-plane:serve
npm run flowchain:full-smoke
```

The demo and tests require no secrets, RPC URLs, wallets, or production services.
Expand All @@ -25,10 +26,22 @@ The dispatcher supports:
- `health`
- `chain_status`
- `devnet_state`
- `node_status`
- `peer_list`
- `mempool_list`
- `block_get`
- `block_list`
- `account_get`
- `account_list`
- `balance_get`
- `balance_list`
- `faucet_event_get`
- `faucet_event_list`
- `wallet_metadata_get`
- `wallet_metadata_list`
- `transaction_get`
- `transaction_list`
- `transaction_submit`
- `rootfield_get`
- `rootfield_list`
- `artifact_get`
Expand All @@ -46,20 +59,39 @@ The dispatcher supports:
- `memory_cell_list`
- `agent_get`
- `agent_list`
- `agent_account_get`
- `agent_account_list`
- `model_get`
- `model_list`
- `model_passport_get`
- `model_passport_list`
- `challenge_get`
- `challenge_list`
- `finality_get`
- `finality_list`
- `bridge_observation_submit`
- `bridge_observation_get`
- `bridge_observation_list`
- `bridge_deposit_get`
- `bridge_deposit_list`
- `bridge_credit_get`
- `bridge_credit_list`
- `withdrawal_get`
- `withdrawal_list`
- `provenance_get`
- `raw_json_get`

The API contract is documented in [docs/FLOWCHAIN_CONTROL_PLANE_API.md](../../docs/FLOWCHAIN_CONTROL_PLANE_API.md).

## Data Sources

The loader reads committed deterministic outputs first:
The loader reads ignored local runtime outputs first when they exist:

- `devnet/local/state.json`
- `devnet/local/launch-v0-state.json`
- `devnet/local/handoff/generated/*.json`

It then falls back to committed deterministic outputs:

- `fixtures/launch-core/flowmemory-launch-v0.json`
- `fixtures/launch-core/generated/devnet/state.json`
Expand All @@ -70,7 +102,10 @@ The loader reads committed deterministic outputs first:
- `services/verifier/out/reports.json`
- `services/verifier/fixtures/artifacts.json`
- `fixtures/handoff/sample-txs.json`
- `fixtures/bridge/base-sepolia-mock-deposit.json`

Bridge relayer output is read from `services/bridge-relayer/out/bridge-observation.json` and control-plane bridge intake is stored in `services/bridge-relayer/out/control-plane-observations.json`.

If the launch-core fixture is missing, the loader rebuilds the in-memory view from indexer/verifier outputs or the raw fixture receipts and artifact resolver. It does not fetch from live RPC or write production state.
If the launch-core fixture is missing, the loader rebuilds the in-memory view from indexer/verifier outputs or the raw fixture receipts and artifact resolver. It does not fetch from production RPC or write production state.

`npm run control-plane:smoke` runs an in-process JSON-RPC client over the complete local lifecycle surface: health, chain status, blocks, transactions, rootfields, agents, models, work receipts, artifact availability, verifier modules, verifier reports, memory cells, challenges, finality, provenance, and raw JSON.
`npm run control-plane:smoke` runs an in-process JSON-RPC client over the complete local lifecycle surface: health, chain status, node status, peers, mempool, blocks, transactions, transaction submission, accounts, balances, faucet status, wallet public metadata, rootfields, agents, agent accounts, models, model passports, work receipts, artifact availability, verifier modules, verifier reports, memory cells, challenges, finality, bridge observations/deposits/credits/withdrawals, provenance, raw JSON, and no-secret response scanning.
Loading
Loading