diff --git a/chain/BRIDGE_SECURITY_RESEARCH.md b/chain/BRIDGE_SECURITY_RESEARCH.md index 7dba2f12..b8771a93 100644 --- a/chain/BRIDGE_SECURITY_RESEARCH.md +++ b/chain/BRIDGE_SECURITY_RESEARCH.md @@ -4,6 +4,14 @@ Status: research gate, no bridge implementation The local FlowMemory devnet has no live bridge and no live Base settlement. `AnchorBatchToBasePlaceholder` only models compact anchor payloads for future review. +## Relationship To FlowChain Gates + +| Gate | Status | Bridge meaning | +| --- | --- | --- | +| Local/private testnet | Local-alpha target | Bridge work is limited to no-value anchor placeholders, replay-boundary docs, and fixture checks. No asset movement. | +| Public devnet | Later research, Blocked | Public devnet may test no-value messages only after DA, replay, finality, monitoring, and emergency controls are documented. | +| Public L1/mainnet | Explicitly later, Blocked | Any value-bearing bridge requires independent bridge/security review, incident response drills, and an accepted production decision record. | + ## Bridge Assumptions To Resolve Later Before any appchain can carry value, FlowMemory must define: diff --git a/docs/DECISIONS/2026-05-13-flowchain-deployment-gates.md b/docs/DECISIONS/2026-05-13-flowchain-deployment-gates.md new file mode 100644 index 00000000..4dd9749d --- /dev/null +++ b/docs/DECISIONS/2026-05-13-flowchain-deployment-gates.md @@ -0,0 +1,56 @@ +# FlowChain Deployment Gates + +Date: 2026-05-13 + +## Status + +Accepted for research and future implementation gating. + +## Context + +FlowMemory has merged V0 launch-core contracts, crypto helpers, fixture-first services, a dashboard, a no-value local devnet prototype, and guarded Base canary evidence. The research packet also includes Noesis, Rootflow, Claude/RD, Octra, FlowMemory, and FlowChain ideas that could easily be over-scoped into a public L1, token, bridge, or proof-system project before the local object model is proven. + +The current Ralph loop needs builders to know what is allowed now and what is later. + +## Decision + +FlowChain work must use three deployment gates: + +1. **Local/private testnet**: local-alpha target. This is a no-value, second-computer-validatable package for FlowMemory object-state testing. It may harden the local runtime, API, workbench, explorer, provenance, crypto vectors, operator-vault boundary, release manifest, and smoke flow after the relevant implementation agents accept scope. +2. **Public devnet**: later research and blocked until the local/private testnet package is reproducible, monitored, exportable/importable, and reviewed. Public devnet planning may document operator roles, DA assumptions, monitoring, reset/halt policy, and threat models. It may not introduce tokenomics. +3. **Public L1/mainnet**: explicitly later and blocked. A production or value-bearing chain requires a separate readiness program, independent reviews, bridge/DA/security work, production verifier design, incident response, governance/upgrade policy, and explicit accepted decisions. + +The current research task does not authorize implementation outside `research/`, `chain/` docs, or `docs/DECISIONS/`. + +## Alternatives Considered + +- **Start public devnet work immediately**: rejected because the local/private object model, challenge/finality flow, private-state boundary, and release package are not proven. +- **Treat the Base canary as production readiness**: rejected because the canary is V0 testing evidence only. +- **Skip local/private testnet and choose an L1 framework now**: rejected because the project has not proven that receipt, memory, dependency, verifier, challenge, and finality objects must be native chain state. + +## Consequences + +- Builders can target a local/private no-value package without importing public-network scope. +- Public devnet and public L1/mainnet work remain blocked behind named evidence. +- Octra-level control-plane lessons become local acceptance criteria, not a reason to chase bridge or encrypted-coprocessor scope. +- The master L1 question remains unresolved until local evidence proves native receipt/memory state is stronger than app-level logs on an existing chain. + +## Scope Boundaries + +This decision does not approve: + +- production validators or sequencers; +- tokenomics, staking, rewards, fees, slashing, or validator economics; +- public L1/mainnet launch planning; +- value-bearing bridge work; +- production encrypted compute; +- production proof systems; +- production Uniswap v4 hook deployment; +- hardware validator, sequencer, DA, or bridge roles. + +## Follow-Ups + +- Use `research/flowchain-local-alpha/L1_GO_NO_GO_GATES.md` as the gate checklist. +- Use `research/flowchain-local-alpha/OCTRA_COMPETENCY_BAR.md` for the local control-plane bar. +- Use `research/flowchain-local-alpha/BLOCKED_AND_LATER.md` before assigning implementation work. +- Create separate implementation issues only after the owning agents accept folder scope and tests. diff --git a/docs/DECISIONS/2026-05-13-flowchain-local-alpha-control-plane-boundary.md b/docs/DECISIONS/2026-05-13-flowchain-local-alpha-control-plane-boundary.md new file mode 100644 index 00000000..d321fa63 --- /dev/null +++ b/docs/DECISIONS/2026-05-13-flowchain-local-alpha-control-plane-boundary.md @@ -0,0 +1,64 @@ +# FlowChain Local Alpha Control-Plane Boundary + +Date: 2026-05-13 + +## Status + +Accepted for research and implementation gating. + +## Context + +The Octra comparison showed that an advanced chain feels credible only when its local developer and operator control plane is coherent. FlowMemory should absorb that lesson without copying Octra's bridge, token, encrypted-coprocessor, or public-network ambitions into Local Alpha. + +FlowMemory already has launch-core fixtures, local verifier reports, a fixture-backed dashboard, a no-value local devnet prototype, and guarded canary evidence. The missing local-alpha surface is a unified way to inspect and operate receipts, memory lineage, artifacts, verifier reports, dependencies, challenges, finality, provenance, and releases. + +## Decision + +FlowChain Local Alpha must treat the local control plane as a requirement before public appchain or L1 work resumes. + +The accepted local/private surface bar is: + +- **Wallet/operator vault**: local encrypted boundary for operator, agent, test wallet, API, hardware, and private-reference secrets. +- **Local API**: one versioned local interface for receipts, memory, artifacts, verifiers, challenges, dependencies, finality, devnet state, and releases. +- **Explorer/workbench**: local UI surface that explains lineage, artifact state, verifier decisions, challenge state, dependency roots, and finality without raw JSON inspection. +- **Devnet/runtime**: deterministic no-value runtime with reset, fixture import/export, state-root visibility, failure fixtures, and release handoff. +- **Source/provenance**: schemas, verifier modules, generated reports, fixtures, canary artifacts, release outputs, and dashboard data identify source paths, versions, hashes, and commands. +- **Crypto vectors**: accepted ids and hashes have deterministic vectors, negative vectors, domain separation, and replay-boundary tests before library promotion. +- **Release packaging**: local-alpha releases include commit, hashes, reproduction commands, migration notes, known limitations, and non-claims. + +This decision makes those surfaces Local Alpha requirements. It does not authorize implementation in this research task. + +## Alternatives Considered + +- **Choose an L1 framework first**: rejected because framework choice is premature until the local object model and control plane prove useful. +- **Build only a chain CLI without workbench/API requirements**: rejected because receipts, memory lineage, dependencies, and challenge/finality state must be explainable to builders and reviewers. +- **Copy Octra's bridge/encrypted-compute ambitions**: rejected because FlowMemory's near-term edge is proof-carrying memory and receipt provenance, not broad encrypted-chain parity. + +## Consequences + +- Future local/private testnet work has concrete surface acceptance criteria. +- Public devnet and public L1 decisions remain gated behind local evidence. +- Operator vault and private-reference work can be scoped as local safety infrastructure, not production wallet or encrypted-compute work. +- API, explorer, provenance, vectors, and release packaging become part of the go/no-go bar, not optional polish. + +## Scope Boundaries + +This decision does not approve: + +- implementation outside an explicitly assigned folder and issue; +- production wallet or custody product work; +- hosted production APIs; +- public RPC; +- public validators or sequencers; +- tokenomics, fees, rewards, staking, or slashing; +- bridges or value movement; +- encrypted compute; +- production proof systems; +- production L1/mainnet launch planning. + +## Follow-Ups + +- Use `research/flowchain-local-alpha/OCTRA_COMPETENCY_BAR.md` as the surface checklist. +- Use `research/flowchain-local-alpha/L1_GO_NO_GO_GATES.md` before approving implementation scope. +- Draft separate schemas for vault, private references, challenge/finality, dependency roots, and release manifests before code work. +- Require `git diff --check` and area-specific tests in any future implementation PR. diff --git a/docs/DECISIONS/2026-05-13-flowchain-proof-private-state-boundary.md b/docs/DECISIONS/2026-05-13-flowchain-proof-private-state-boundary.md new file mode 100644 index 00000000..9358e440 --- /dev/null +++ b/docs/DECISIONS/2026-05-13-flowchain-proof-private-state-boundary.md @@ -0,0 +1,59 @@ +# FlowChain Proof And Private-State Boundary + +Date: 2026-05-13 + +## Status + +Accepted for research and implementation gating. + +## Context + +The FlowMemory research packet contains advanced ideas: Process-Witness, SEAL/dependency privacy, Synthetic Non-Amplification, proof-carrying receipts, private evidence, encrypted compute, bridge security, and future validator/sequencer economics. These ideas matter for long-term coherence, but none of them are production-ready protocol surfaces in the current repo. + +FlowMemory already has V0 hashes, schemas, receipts, verifier reports, local fixtures, and a no-value devnet prototype. Those are deterministic local/test artifacts, not trustless proof systems or production private compute. + +## Decision + +FlowChain may use advanced research only as gated vocabulary until prerequisites are accepted: + +- **Process-Witness** remains later research. Local/private work may name process obligations and verifier-module metadata, but may not build cognitive proof circuits or claim the chain proves cognition, truth, or model correctness. +- **SEAL/dependency privacy** remains later research. Local/private work may model dependency atoms, dependency roots, dependence classes, completeness attestations, and omitted-dependency challenges in verifier-attested form before any ZK dependence proof. +- **Synthetic Non-Amplification** is a local-alpha invariant. Synthetic data can create hypotheses, counterexamples, challenge debt, scrutiny, or validation requirements. It must not increase empirical certainty or memory trust without real-world validation, except for formal deterministic claims checked by deterministic verifiers. +- **Proof-carrying receipts** remain later research. Local/private work should preserve stable receipt/report hashes and public-input candidates, but production circuits, contract proof verification, and trustless receipt claims are blocked. +- **Advanced encrypted compute** is explicitly later. FHE, MPC, TEE, encrypted coprocessors, encrypted mempools, and private inference are blocked until public/private state, key custody, leakage, DA, auditability, and incident-response requirements are reviewed. +- **Bridge security** is explicitly later for value movement. Local work may model no-value anchor placeholders and replay boundaries only. +- **Validator/sequencer economics** are explicitly later and blocked. Non-economic operator roles may be documented for future public devnet research; staking, rewards, fees, slashing, token mechanics, or revenue claims require a separate approved scope. + +## Alternatives Considered + +- **Implement proof systems now**: rejected because public inputs, witness formats, setup assumptions, cost model, negative vectors, and challenge semantics are not accepted. +- **Use encrypted compute to solve privacy early**: rejected because the basic public/private data model and local vault/reference boundary must come first. +- **Treat verifier attestations as trustless proofs**: rejected because V0 verifier reports are deterministic and replayable but remain claims. +- **Add economics to solve public operator behavior**: rejected because tokenomics is forbidden in the current scope and would obscure missing security design. + +## Consequences + +- Local/private testnet work can stay practical: deterministic fixtures, vectors, verifier reports, private references, challenges, and provenance before advanced proofs. +- Public devnet and L1/mainnet work cannot rely on research primitives until they have accepted specs and reviews. +- Scientific, biological, or empirical settlement claims remain blocked until real-world evidence gates and dependency policies exist. +- The crypto library should only accept versioned, vector-backed schemas; speculative primitives stay in research. + +## Scope Boundaries + +This decision does not authorize: + +- crypto implementation; +- proof circuits; +- production encrypted compute; +- bridge deployment; +- tokenomics; +- verifier economics; +- validator or sequencer economics; +- production L1/mainnet launch planning. + +## Follow-Ups + +- Draft dependency atom/root schemas before any dependency proof work. +- Draft challenge/finality transitions before any downgrade-sensitive receipt implementation. +- Keep proof public-input candidates aligned with V0 receipt and verifier report hashes. +- Require a separate decision record before any research primitive moves into `crypto/`, `contracts/`, `services/`, `apps/`, or `crates/`. diff --git a/research/flowchain-local-alpha/ARCHITECTURE_REFERENCE.md b/research/flowchain-local-alpha/ARCHITECTURE_REFERENCE.md new file mode 100644 index 00000000..d8705179 --- /dev/null +++ b/research/flowchain-local-alpha/ARCHITECTURE_REFERENCE.md @@ -0,0 +1,160 @@ +# FlowChain Local Alpha Architecture Reference + +Last updated: 2026-05-13 + +Status: research reference, not an implementation plan and not a production L1 approval. + +## Purpose + +FlowChain is used here as a working research name for the future chain-shaped direction of FlowMemory. This document defines the research-to-build boundary for FlowChain Local Alpha. + +The Local Alpha goal is not to launch a public chain. The goal is to make the FlowMemory object model concrete enough that builders can implement local workbench, API, devnet, explorer, provenance, and release workflows without importing production validator, token, bridge, or advanced encrypted-compute scope. + +## Status Vocabulary + +Every major claim in this reference uses one of these labels: + +- **Implemented**: merged into the current FlowMemory repo as of `docs/CURRENT_STATE.md` dated 2026-05-13 or confirmed from `origin/main` on 2026-05-13. +- **Local-alpha target**: appropriate to specify and later build for FlowChain Local Alpha, but not implemented by this research task. +- **Later research**: useful direction, but blocked behind review, proof, product, or security gates. +- **Blocked**: cannot move to implementation until named prerequisites are met. +- **Explicitly later**: intentionally not part of Local Alpha. + +## Source Map + +| Source | Status | How it should influence Local Alpha | +| --- | --- | --- | +| FlowMemory built state | Implemented | Use the merged launch-core V0 stack, schemas, fixture-backed dashboard, local no-value devnet, crypto V0 helpers, and chain docs as the factual baseline. | +| Octra comparison | Local-alpha target | Copy the discipline of a coherent local control plane, stable API, recoverable local state, source visibility, and explorer observability. Do not copy bridge, token, or encrypted-coprocessor ambition into Local Alpha. | +| Noesis / Flow Chain research | Later research | Treat AI Work Receipts, ModelPassports, AgentAccounts, MemoryCells, verifier modules, Process-Witness, and cognitive proof primitives as candidate long-term native objects and proof families. | +| Claude crypto research | Later research | Treat SEAL/dependency proofs, Synthetic Non-Amplification, proof-carrying receipts, and private evidence as research directions that inform boundaries before they become protocol code. | +| `chain/` docs | Implemented as research docs | Keep Base anchors, bridge security, hardware node roles, DA, and L1/appchain work gated. | + +## Current Implemented Baseline + +| Area | Status | Current fact | +| --- | --- | --- | +| FlowPulse event spine | Implemented | Contracts define FlowPulse V0 event semantics and the launch fixture path. Hooks still cannot know final `txHash` or `logIndex`; indexers derive those after receipts and logs exist. | +| Hook-adjacent swap signal path | Implemented | `FlowMemoryHookAdapter` remains a dependency-light V0 scaffold and now includes a Uniswap v4-shaped `afterSwap` callback surface. It is still not a production Uniswap v4 hook. | +| Rootfield and compact registries | Implemented | Local/test skeleton contracts exist for roots, artifacts, cursors, work receipts, verifier reports, workers, verifiers, and work state. They are not production protocol surfaces. | +| Crypto V0 foundation | Implemented | Keccak-based typed helpers, domains, receipt/report/root/artifact/work helpers, fixtures, and vectors exist under `crypto/`. Proof systems do not exist. | +| Indexer/verifier fixture path | Implemented | Fixture-first services produce local observations, cursors, duplicate/reject states, and verifier reports. They are not a production verifier network. | +| Flow Memory and Rootflow launch objects | Implemented | `MemorySignal`, `MemoryReceipt`, `RootflowTransition`, `RootfieldBundle`, and `AgentMemoryView` schemas and generated fixtures exist. | +| Dashboard V0 | Implemented | The dashboard renders generated fixture state for Flow Memory, Rootflow, FlowPulse, Rootfields, receipts, reports, devnet blocks, hardware nodes, alerts, and raw JSON. It is fixture-backed. | +| Local no-value devnet | Implemented | Rust prototype models deterministic local transactions, blocks, state roots, and handoff output. It is not consensus, validators, a token system, or a bridge. | +| Base canary | Implemented as test evidence | A small Base mainnet canary exists for V0 testing only. A guarded canary reader and separate canary dashboard dataset now exist for known addresses and small explicit block ranges. They do not change production guardrails. | + +## Local Alpha Definition + +**Local-alpha target**: FlowChain Local Alpha is a receipt-native local control plane for FlowMemory state, not a public chain. + +It should prove that the following can be inspected, replayed, tested, and released locally: + +- Work receipts and memory receipts. +- Rootflow transitions and parent/child state. +- Artifact commitments and availability status. +- Verifier reports and verifier module provenance. +- Challenge windows, finality state, and downgrade paths. +- Dependency roots and declared evidence relationships. +- Local devnet blocks, state roots, and Base anchor placeholders. +- Private references only as local encrypted references, not private computation. + +## Gate Map + +| Gate | Status | Architecture meaning | +| --- | --- | --- | +| Local/private testnet | Local-alpha target | A no-value second-computer package that uses the existing launch-core, local devnet, fixture pipeline, API/workbench target, provenance, and release manifest to prove the object model locally. | +| Public devnet | Later research, Blocked | A public experimental network can be considered only after the local/private package is reproducible, monitored, and reviewed. | +| Public L1/mainnet | Explicitly later, Blocked | A production or value-bearing chain requires a separate readiness program, independent review, bridge/DA/security work, and explicit accepted decisions. | + +Only the local/private testnet gate may be used as near-term implementation guidance. Public devnet and public L1/mainnet language is boundary-setting research only. + +## Architecture Layers + +| Layer | Status | Local Alpha responsibility | Boundary | +| --- | --- | --- | --- | +| Object model | Local-alpha target | Define the objects that would justify a future appchain: `WorkReceipt`, research `AIWorkReceipt`, `MemoryCell`, `ArtifactAvailabilityProof`, `VerifierModule`, `Challenge`, `FinalityReceipt`, and `DependencyRoot`. | Do not claim these are all implemented as chain-native state. | +| Local workbench | Local-alpha target | Provide a local operator/developer surface for receipts, memory lineage, artifacts, verifier reports, challenges, dependency roots, finality, fixtures, and devnet state. | Not a wallet-first product, not a hosted production service. | +| Local API | Local-alpha target | Expose predictable local read/write/introspection methods for the workbench, agents, dashboard, and tests. | No production API or hosted persistence until separately scoped. | +| Devnet | Implemented foundation, Local-alpha target for hardening | Keep the no-value deterministic devnet as the local execution model and fixture handoff source. | No validators, sequencers, consensus claims, bridge, token, or public network. | +| Explorer | Implemented foundation, Local-alpha target for richer observability | Extend the fixture-backed dashboard/explorer concept so every receipt, verifier report, challenge, lineage edge, and finality status can be inspected without raw JSON. | Explorer views must not imply production finality or trustless verification. | +| Provenance | Local-alpha target | Make schemas, verifier modules, generated reports, fixture sources, deployment artifacts, and release manifests source-visible and hash-addressed. | Provenance is evidence and reproducibility, not proof of truth. | +| Releases | Local-alpha target | Ship versioned local-alpha releases with fixture snapshots, schema versions, migration notes, known limitations, and reproducibility checks. | No mainnet, token, bridge, validator, or encrypted-compute release narrative. | +| Proof systems | Later research | Map future proof-carrying receipts, SEAL/dependency proofs, and Process-Witness primitives to exact public inputs and witness privacy rules. | No production circuits until accepted schemas, vectors, costs, and review gates exist. | +| L1/appchain | Later research | Decide whether native receipt and memory state is meaningfully stronger than app-level logs on Base or another chain. | Public L1/appchain is blocked until go/no-go gates are met. | + +## Native Object Model Direction + +| Object | Status | Local Alpha meaning | Later L1 question | +| --- | --- | --- | --- | +| `WorkReceipt` | Implemented foundation, Local-alpha target | Current contracts and schemas already model compact work receipt commitments. Local Alpha should make lifecycle, provenance, challenge, and finality inspectable. | Should work receipts be native state or app-level logs? | +| `AIWorkReceipt` | Later research | Research name for AI-specific work involving model, prompt/input, output, tools, memory delta, artifacts, environment, dependencies, verifier decisions, and finality. | Is AI-specific receipt state essential enough to justify a chain? | +| `MemoryCell` | Local-alpha target | Durable memory unit with lineage to receipts, roots, artifacts, dependency declarations, status, and challenge/finality state. | Should memory cells be native state rather than derived indexer state? | +| `ArtifactAvailabilityProof` | Local-alpha target | Structured commitment or report about artifact root, manifest, locator policy, availability checks, and challenge response. | What availability guarantees are required before value-bearing work? | +| `VerifierModule` | Local-alpha target | Source-visible verifier policy/module with schema hash, version, check set, expected inputs, and deterministic report rules. | Can verifier modules become chain-native without central trust? | +| `Challenge` | Local-alpha target | Explicit state for disputed receipts, unavailable artifacts, omitted dependencies, stale finality, or failed verifier checks. | What challenge/finality model is safe for public appchain use? | +| `FinalityReceipt` | Local-alpha target | Reportable status that says what became accepted, rejected, unresolved, downgraded, superseded, or finalized and why. | Can finality be native while remaining downgradeable for dependency omissions? | +| `DependencyRoot` | Local-alpha target | Commitment to declared evidence, tool, data, model, lab, worker, or pipeline dependencies. | When, if ever, does SEAL-style private dependency proof become required? | + +## Local Alpha Data Flow + +1. **Implemented**: A local fixture, test contract, or constrained testnet reader produces FlowPulse observations and compact contract state. +2. **Implemented**: The indexer derives observation identity from receipts and logs after execution. +3. **Implemented**: The verifier produces deterministic local reports from fixture evidence. +4. **Implemented**: Launch-core generators produce Flow Memory and Rootflow fixtures. +5. **Local-alpha target**: The local API exposes receipt, memory, artifact, verifier, challenge, dependency, and finality resources with stable error shapes and pagination. +6. **Local-alpha target**: The workbench/explorer lets a builder inspect the whole path from pulse to receipt to verifier report to memory/root transition. +7. **Local-alpha target**: Provenance records tie every receipt/report to schema hashes, verifier module hashes, fixture/release hashes, and source references. +8. **Later research**: Proof-carrying receipts or appchain-native state replace some deterministic verifier claims only after review gates. + +## Build Boundary + +| Allowed for Local Alpha planning | Status | Not allowed in this task | +| --- | --- | --- | +| Research docs under `research/flowchain-local-alpha/` | Local-alpha target | Contract, service, app, crypto, hardware, production chain, bridge, tokenomics, or mainnet implementation. | +| Object model and acceptance criteria | Local-alpha target | Any claim that Local Alpha is a public chain. | +| API, workbench, explorer, provenance, and release requirements | Local-alpha target | Hosted production API or production dashboard work. | +| Go/no-go gates for future L1/appchain work | Local-alpha target | Validator set design, staking, sequencer operations, governance, fees, or token design. | +| Crypto research map and private-state roadmap | Local-alpha target | ZK circuits, encrypted compute runtime, threshold crypto, or production proof systems. | + +## What FlowChain Should Be At Octra-Level + +| Competency | Status | FlowChain Local Alpha bar | +| --- | --- | --- | +| Local workbench | Local-alpha target | A coherent local surface for receipt/memory/artifact/verifier/challenge/finality workflows. | +| API | Local-alpha target | Stable local methods and schemas that agents, workbench, explorer, and tests can share. | +| Devnet | Implemented foundation, Local-alpha target for polish | Deterministic no-value execution, reset, fixture import/export, state-root inspection, and reproducible handoff. | +| Explorer | Implemented foundation, Local-alpha target for completeness | Observability for lineage, verifier decisions, artifact state, dependency roots, challenges, and finality. | +| Provenance | Local-alpha target | Hash-addressed schema, verifier module, fixture, report, and release evidence. | +| Object model | Local-alpha target | WorkReceipt, MemoryCell, artifact proof, verifier module, challenge, finality receipt, dependency root, and research AIWorkReceipt vocabulary. | +| Releases | Local-alpha target | Versioned local-alpha bundles with schemas, fixtures, release manifest, reproducibility commands, limitations, and migration notes. | + +## Explicitly Later + +| Topic | Status | Reason | +| --- | --- | --- | +| Production validators | Explicitly later | Local Alpha has no consensus or public validator network. | +| Public L1 | Explicitly later | The native receipt/memory state model must prove useful locally first. | +| Tokenomics | Explicitly later | Value-bearing mechanics would distort Local Alpha and require separate security/economic review. | +| Bridges | Explicitly later | Bridge design requires DA, replay, finality, custody, emergency pause, monitoring, and independent review. | +| Advanced encrypted compute | Later research | Private state starts with local secrets and private references; encrypted compute requires cryptographic and systems review. | +| Production proof systems | Later research | Proof systems need exact public inputs, witness formats, setup assumptions, costs, and challenge semantics before implementation. | + +## Decision Rule For Future L1/Appchain Work + +**Later research**: FlowChain should move beyond Local Alpha only if the answer is yes to this question: + +```text +Would FlowMemory be meaningfully weaker if work receipts, memory cells, dependency roots, verifier decisions, challenges, and finality receipts were only app-level logs on another chain? +``` + +If the answer is no, the correct path is to keep building on Base or another existing settlement layer and improve the local product, API, and verifier experience first. + +## Non-Negotiable Guardrails + +- **Implemented boundary**: Heavy AI, model, memory, media, artifact, and evidence data stays off-chain. +- **Implemented boundary**: Transaction hashes and log indexes are derived by indexers after receipts and logs exist. +- **Local-alpha target**: Public receipt metadata must be separated from private artifact references and local secret material. +- **Local-alpha target**: Synthetic evidence must never increase empirical certainty without real-world validation. +- **Local-alpha target**: Dependency omission must remain challengeable; polished proofs cannot hide incomplete provenance. +- **Explicitly later**: Production validator, bridge, token, mainnet, and encrypted-compute work stays out until separate go/no-go decisions approve it. diff --git a/research/flowchain-local-alpha/BLOCKED_AND_LATER.md b/research/flowchain-local-alpha/BLOCKED_AND_LATER.md new file mode 100644 index 00000000..32d1482f --- /dev/null +++ b/research/flowchain-local-alpha/BLOCKED_AND_LATER.md @@ -0,0 +1,70 @@ +# FlowChain Blocked And Later List + +Last updated: 2026-05-13 + +Status: research gate. This document does not authorize implementation outside research and decision docs. + +## Purpose + +This list turns the FlowChain research packet into explicit stop signs. A builder should be able to tell whether a claim is implemented, a local/private testnet target, later research, blocked, or explicitly later. + +## Status Vocabulary + +- **Implemented**: merged into FlowMemory as of `docs/CURRENT_STATE.md` dated 2026-05-13 or confirmed from `origin/main` on 2026-05-13. +- **Local-alpha target**: safe to specify now and build later for the local/private no-value testnet after owner agents accept the implementation scope. +- **Later research**: useful direction, but not ready for implementation. +- **Blocked**: cannot move to implementation until named prerequisites are met. +- **Explicitly later**: intentionally outside Local Alpha and outside the current Ralph loop. + +## Allowed Now + +| Item | Status | Allowed action | +| --- | --- | --- | +| Research gate docs | Local-alpha target | Continue docs under `research/flowchain-local-alpha/`. | +| Chain research docs | Local-alpha target | Clarify local/private, public devnet, bridge, DA, hardware observer, and Base anchor boundaries in `chain/` docs. | +| Decision records | Local-alpha target | Record accepted boundaries under `docs/DECISIONS/`. | +| Local/private testnet requirements | Local-alpha target | Specify second-computer acceptance, object model, API/workbench, devnet/runtime, provenance, crypto vectors, release packaging, and smoke requirements. | + +## Blocked Before Local/Private Testnet Implementation + +| Item | Status | Blocker | Smallest useful next step | +| --- | --- | --- | --- | +| Local operator vault | Local-alpha target, Blocked for code until accepted | No accepted vault file/envelope format, no locked/unlocked API semantics, and no no-plaintext-log tests. | Draft vault schema, error semantics, and test cases. | +| Private artifact references | Local-alpha target, Blocked for code until accepted | No accepted encrypted locator envelope, resolver policy, disclosure event, or export policy. | Draft private reference schema and disclosure states. | +| Challenge/finality state machine | Local-alpha target, Blocked for code until accepted | Challenge reason codes, response states, expiry, downgrade, and recompute rules are not accepted. | Draft status transition table and fixture cases. | +| Dependency roots | Local-alpha target, Blocked for code until accepted | Dependency atom schema, dependence classes, completeness scope, and omission-challenge semantics are not accepted. | Draft dependency vocabulary and negative fixtures. | +| Release manifest | Local-alpha target, Blocked for code until accepted | Manifest fields, hash set, compatibility policy, and reproduction commands are not accepted. | Draft local-alpha release manifest schema. | + +## Later Research Before Public Devnet + +| Item | Status | Blocker | Smallest useful next step | +| --- | --- | --- | --- | +| Public devnet | Later research, Blocked | Local/private testnet package is not yet reproducible and reviewed. | Finish Gate 3 evidence first. | +| Public operator roles | Later research | Validator/sequencer/operator responsibilities, failure handling, monitoring, halt/reset policy, and onboarding are not accepted. | Draft public-devnet operator role document without economics. | +| DA and reconstruction | Later research | Public data source, retention, missing-data behavior, and reconstruction tests are not accepted. | Extend DA requirements from `chain/BRIDGE_SECURITY_RESEARCH.md`. | +| Public monitoring | Later research | Indexer lag, verifier outage, missing artifacts, challenge response, reorg, and incident dashboards are not specified. | Draft monitoring matrix and incident states. | +| External security review | Later research | No review plan exists for public-network threat assumptions. | Open review tasks after local/private testnet release evidence exists. | + +## Explicitly Later Or Blocked From Public L1/Mainnet + +| Item | Status | Why blocked | +| --- | --- | --- | +| Production L1/mainnet | Explicitly later, Blocked | Requires public devnet evidence, independent audits, governance, DA, bridge/security review, production verifier design, monitoring, and incident response. | +| Tokenomics | Explicitly later, Blocked | User scope forbids tokenomics; economics would require separate legal/economic/security scope. | +| Validator/sequencer economics | Explicitly later, Blocked | No staking, rewards, fee market, slashing, or revenue design until non-economic roles and public devnet risks are accepted. | +| Production bridge | Explicitly later, Blocked | Requires deposit/withdrawal formats, replay protection, finality, DA, custody, emergency pause, upgrade delay, monitoring, recovery, and independent review. | +| Production proof systems | Later research, Blocked | Requires exact public inputs, witnesses, setup assumptions, cost model, negative vectors, challenge semantics, and independent crypto review. | +| Process-Witness circuits | Later research, Blocked | Research primitives are not accepted as predicates, circuits, or security claims. | +| SEAL ZK dependency proofs | Later research, Blocked | Dependency schemas, completeness warranties, omission challenges, downgrade semantics, and proof rules are not accepted. | +| Advanced encrypted compute | Explicitly later, Blocked | FHE, MPC, TEE, encrypted coprocessors, encrypted mempools, and private inference need a stable object model, key custody, leakage review, and security review. | +| Production Uniswap v4 hook | Explicitly later, Blocked | Current adapter is hook-shaped but not a permission-mined, PoolManager-wired production hook. | +| Hardware validator role | Explicitly later, Blocked | FlowRouter and LoRa sidecars are observers/control signaling only, not validators, sequencers, DA providers, or bridge operators. | + +## Non-Negotiable Claims + +- **Implemented boundary**: Heavy AI, model, memory, media, artifact, and evidence data stays off-chain. +- **Implemented boundary**: Contracts do not know final `txHash` or `logIndex`; indexers derive them after receipts and logs exist. +- **Local-alpha target**: Public receipt metadata must be separated from private references and secrets. +- **Local-alpha target**: Synthetic outputs can create hypotheses, counterexamples, scrutiny, debt, or challenge requirements, but cannot increase empirical certainty without real-world evidence. +- **Blocked**: Dependency omissions must remain challengeable; no proof can hide an incomplete provenance story. +- **Explicitly later**: Public L1/mainnet, production validators, tokenomics, production bridges, and production encrypted compute are not part of Local Alpha. diff --git a/research/flowchain-local-alpha/CRYPTOGRAPHY_RESEARCH_MAP.md b/research/flowchain-local-alpha/CRYPTOGRAPHY_RESEARCH_MAP.md new file mode 100644 index 00000000..a2bb2a1c --- /dev/null +++ b/research/flowchain-local-alpha/CRYPTOGRAPHY_RESEARCH_MAP.md @@ -0,0 +1,225 @@ +# FlowChain Cryptography Research Map + +Last updated: 2026-05-13 + +Status: research map. This document does not implement cryptography, proof systems, encrypted compute, verifier economics, or production chain code. + +## Purpose + +FlowChain Local Alpha needs enough cryptography direction to avoid chaos, but not so much ambition that research ideas become premature protocol claims. This map connects Process-Witness, SEAL/dependency proofs, Synthetic Non-Amplification, proof-carrying receipts, and the R&D/crypto library boundary to the current FlowMemory V0 foundation. + +## Status Vocabulary + +- **Implemented**: merged into FlowMemory as of `docs/CURRENT_STATE.md` dated 2026-05-13 or confirmed from `origin/main` on 2026-05-13. +- **Local-alpha target**: safe to specify for Local Alpha and later build behind fixtures/tests. +- **Later research**: not ready for Local Alpha implementation. +- **Blocked**: cannot move to implementation until named prerequisites are met. +- **No-go**: condition that blocks implementation or stronger claims. + +## Current Crypto Baseline + +| Area | Status | Current fact | +| --- | --- | --- | +| Keccak typed helpers | Implemented | The `crypto/` package has V0 hash helpers, typed domains, receipt/report/root/artifact/work helpers, attestations, fixtures, and test vectors. | +| Observation identity | Implemented foundation | The system separates contract `pulseId`, indexer-derived observation identity, and verifier report identity in V0 docs and fixtures. | +| Deterministic verifier reports | Implemented foundation | Local verifier reports exist as signed or structured claims from fixture evidence, not trustless proofs. | +| Proof systems | Later research | No production proof circuits, GPU proofs, verifier networks, or proof economics exist. | +| Private state | Local-alpha target, Later research | Local secret handling and private references are future Local Alpha work; encrypted compute is later research. | + +## Research Track Summary + +| Track | Status | Local Alpha treatment | Later gate | +| --- | --- | --- | --- | +| Process-Witness | Later research | Map candidate primitives to receipt obligations and verifier-module metadata. Do not build cognitive proof circuits. | Exact predicates, public inputs, witnesses, adversary model, cost model, and independent crypto review. | +| SEAL/dependency proofs | Later research, Local-alpha target for vocabulary | Define dependency atoms, dependency roots, dependence classes, completeness attestations, and omitted-dependency challenges in plain verifier-attested form first. | ZK dependency proofs only after dependency schemas, completeness warranties, and challenge windows are accepted. | +| Synthetic Non-Amplification | Local-alpha target | Enforce as an invariant in receipts, verifier reports, memory lineage, and explorer state: synthetic data cannot increase empirical certainty. | Domain-specific review before biological/scientific settlement claims. | +| Proof-carrying receipts | Later research | Keep V0 receipt/report hashes stable and define candidate public inputs. Continue using deterministic verifier reports for Local Alpha. | Circuit implementation only after exact public inputs, witness privacy rules, proof system choice, setup assumptions, and cost model. | +| R&D/crypto library boundary | Local-alpha target | Research proposes candidates; the crypto library implements only accepted schemas with vectors and tests. | No speculative primitives enter production libraries without decision record and review. | + +## Implementation Promotion Gates + +These are the minimum gates before the research tracks below may enter implementation work. + +| Track | Local/private testnet allowance | Public devnet requirement | Public L1/mainnet requirement | +| --- | --- | --- | --- | +| Process-Witness | Local-alpha target: name process obligations and verifier-module metadata only. | Later research: exact predicates, public inputs, witness formats, adversary model, cost model, failure modes, and independent crypto review. | Blocked: production cognition proof claims need audits, reproducible vectors, challenge semantics, and a separate accepted decision. | +| SEAL/dependency privacy | Local-alpha target: dependency atoms, roots, dependence classes, completeness attestations, and omission challenges in plain verifier-attested form. | Later research: ZK proof rules, completeness warranties, downgrade semantics, revocation roots, witness privacy rules, and review. | Blocked: production dependence-proof claims or evidence-merge finality before circuits and challenge economics are reviewed. | +| Synthetic Non-Amplification | Local-alpha target: status invariant and fixture/test requirement. | Later research: domain-specific policy review for any public scientific or empirical workflow. | Blocked: public empirical-certainty, biological, or scientific settlement claims without real-world evidence gates. | +| Proof-carrying receipts | Local-alpha target: stable hashes, schemas, public-input candidates, and deterministic verifier reports. | Later research: proof system choice, setup assumptions, exact witnesses, proof costs, negative vectors, and verifier/challenge policy. | Blocked: contract proof verification or trustless receipt claims without independent audit. | +| Advanced encrypted compute | Explicitly later: no implementation; only threat-model vocabulary may be documented. | Later research: public/private state model, key custody, leakage analysis, DA/auditability, attestation semantics, and incident response review. | Blocked: FHE/MPC/TEE/coprocessor production claims without security review and operational policy. | + +## Process-Witness + +### Meaning + +**Later research**: Process-Witness is the Noesis/Flow Chain research family for certifying dimensions of AI cognition and behavior beyond "a computation matched a circuit." The review packet describes trajectory commitments, predicates over reasoning steps, concentration bounds, challenge sampling, sparse openings, composition rules, and proof/circuit paths. + +### Why It Matters + +**Later research**: Process-Witness is a possible long-range answer to why an AI-native chain might need native state. It could eventually bind progress, calibration, counterfactual robustness, replay resistance, refusal, inactivity, narrative/pragmatic structure, or other cognitive properties. + +### Local Alpha Boundary + +| Item | Status | Local Alpha handling | +| --- | --- | --- | +| Process obligation vocabulary | Local-alpha target | Allow a receipt or verifier module to name a process obligation such as replay resistance, calibration evidence, counterexample search, refusal evidence, or tool-trace completeness. | +| Process evidence reference | Local-alpha target | Store commitments or references to process evidence off-chain; do not store private reasoning traces on-chain. | +| Verifier module declaration | Local-alpha target | A verifier module may say it checks a process obligation deterministically from fixture evidence. | +| Cognitive proof circuit | Later research | Do not implement for Local Alpha. | +| Halo2/Pasta/Poseidon2-style production path | Later research | Treat as unaccepted until public inputs, witnesses, setup assumptions, and review exist. | + +### No-Go Conditions + +- **No-go**: Claiming the chain proves cognition, truth, intelligence, or model correctness. +- **No-go**: Building proof circuits before the receipt schema, public inputs, witness format, and verifier module semantics are accepted. +- **No-go**: Treating private reasoning traces as public artifacts. +- **No-go**: Making Process-Witness a dependency for Local Alpha launch. + +## SEAL And Dependency Proofs + +### Meaning + +**Later research**: SEAL is the Claude research direction for typed evidence attestation and dependence proofs. Its strongest concept is a causal separation or dependency certificate that says whether evidence objects may be combined under a declared dependence class. + +### Why It Matters + +**Local-alpha target**: FlowMemory memory and receipts should not double-count evidence that shares a hidden dataset, model, lab, vendor, prompt, tool, worker, or analysis pipeline. Dependency handling protects the credibility of memory lineage and scientific claims. + +### Local Alpha Vocabulary + +| Concept | Status | Local Alpha meaning | +| --- | --- | --- | +| Dependency atom | Local-alpha target | A typed declaration of a dependency such as dataset, model lineage, tool, prompt family, lab, worker, provider, hardware source, or analysis pipeline. | +| Dependency root | Local-alpha target | Commitment to a set of dependency atoms or hidden dependency commitments. | +| Dependence class | Local-alpha target | Plain label such as independent, block-independent, exchangeable, arbitrary, synthetic-only, or unknown. | +| Completeness attestation | Local-alpha target | Issuer/verifier claim about dependency coverage, with scope and expiry. | +| Omitted-dependency challenge | Local-alpha target | Challenge that introduces a missing dependency and can downgrade finality or recompute merge status. | +| Causal separation certificate | Later research | ZK or formal proof that dependency footprints satisfy an allowed class. Not Local Alpha. | +| MergeCapability | Later research | Proof-carrying authorization to merge evidence under a dependence class. Can be mocked as verifier-attested policy in Local Alpha research only. | + +### Local Alpha Rule + +**Local-alpha target**: Dependency declarations can be verifier-attested before they are ZK-proven. The system should show dependency assumptions and challenge windows clearly, and should downgrade affected memory or receipt finality when omitted dependencies are accepted. + +### No-Go Conditions + +- **No-go**: Claiming independence when dependencies are unknown. +- **No-go**: Treating a dependency proof as sound if the issuer never warranted completeness. +- **No-go**: Allowing a dependency omission to be hidden after finality. +- **No-go**: Presenting SEAL as implemented cryptography before circuits, proof rules, and challenge semantics exist. + +## Synthetic Non-Amplification + +### Meaning + +**Local-alpha target**: Synthetic Non-Amplification is the rule that synthetic data, simulations, model-generated evidence, and counterworlds can increase debt, risk, scrutiny, challenge windows, or discriminator requirements, but cannot increase empirical certainty without real-world validation. + +### Local Alpha Invariant + +| Claim type | Status | Allowed synthetic effect | Forbidden synthetic effect | +| --- | --- | --- | --- | +| Formal deterministic claim | Local-alpha target | Synthetic or generated examples may be accepted if a deterministic verifier checks the formal property. | Calling unchecked generation proof of correctness. | +| Empirical/scientific claim | Local-alpha target | Synthetic evidence may create hypotheses, counterexamples, challenge debt, or validation requirements. | Increasing clean empirical support or finality. | +| Memory quality claim | Local-alpha target | Synthetic counterexamples may mark memory as needs-review, challenged, or downgraded. | Making memory more trusted solely from synthetic support. | +| Model lineage claim | Later research | Model lineage commitments can help detect reused synthetic sources. | Claiming independence without lineage/dependency review. | + +### No-Go Conditions + +- **No-go**: Synthetic outputs become empirical support mass. +- **No-go**: A model-generated counterworld is treated as lab evidence. +- **No-go**: A memory cell becomes more final because generated data agrees with it. +- **No-go**: Biological or scientific settlement claims are made without real-world evidence gates. + +## Proof-Carrying Receipts + +### Current Boundary + +**Implemented foundation**: V0 uses deterministic hashes, schemas, fixtures, and verifier reports. These are replayable claims, not trustless proofs. + +**Later research**: Proof-carrying receipts may later attach zero-knowledge or succinct proofs to stable receipt/report hashes. + +### Candidate Public Inputs + +**Later research**: Future proof-carrying receipts should preserve the V0 receipt hash as a public input candidate. + +Candidate public inputs: + +- `schemaId` +- `chainId` +- `observationId` +- `eventArgsHash` +- `receiptHash` +- `artifactRoot` +- `storageReceiptCommitment` +- `verifierPolicyHash` +- `reportSchemaHash` +- `dependencyRoot` +- `finalityPolicyHash` + +Candidate witnesses: + +- Event args. +- Artifact manifest. +- Merkle opening path. +- Storage receipt opening. +- Check result details. +- Worker signature preimage. +- Verifier signature preimage. +- Dependency atom openings. + +### Local Alpha Treatment + +| Capability | Status | Treatment | +| --- | --- | --- | +| Receipt internal consistency | Local-alpha target | Keep deterministic replay and vector tests; define public inputs for later proofs. | +| Artifact Merkle inclusion | Later research | Good first proof candidate, but Local Alpha can use deterministic verifier reports. | +| Verifier-report consistency | Later research | Candidate circuit only after report schema and check set stabilize. | +| Rootflow aggregation | Later research | Candidate recursive aggregation path after receipt lifecycle stabilizes. | +| Chain receipt/log canonicality | Later research | Harder proof candidate; do not depend on it for Local Alpha. | + +### No-Go Conditions + +- **No-go**: Building circuits before accepted observation identity, receipt/report schemas, vectors, witness privacy rules, and cost model. +- **No-go**: Treating verifier attestations as trustless proofs. +- **No-go**: Forcing private artifact bytes public unless challenge or disclosure policy requires it. +- **No-go**: Adding proof verification to contracts before public inputs and threat model are accepted. + +## R&D / Crypto Library Boundary + +### Boundary Statement + +**Local-alpha target**: Research and development can propose candidate primitives, object models, and go/no-go criteria. The crypto library should implement only accepted, versioned, test-vector-backed schemas. + +### Ownership Split + +| Work type | Status | Owner boundary | +| --- | --- | --- | +| Research vocabulary | Local-alpha target | `research/` may define concepts, risks, gates, and candidate data shapes. | +| Accepted schema | Implemented foundation, Local-alpha target | `crypto/` may implement only after the schema is accepted or explicitly marked candidate with tests. | +| Test vectors | Implemented foundation, Local-alpha target | Any library behavior needs deterministic vectors and negative cases. | +| Proof circuits | Later research | Must remain out of production code until go/no-go gates approve exact public inputs, witnesses, setup assumptions, and costs. | +| Private-state crypto | Later research | Local vault can use reviewed existing libraries later; custom cryptography requires review. | +| Protocol contracts | Explicitly outside this task | Contracts must not import speculative crypto primitives from research docs. | + +### Promotion Checklist + +Before a research primitive can move toward library implementation: + +1. **Local-alpha target**: Define the object and threat model. +2. **Local-alpha target**: Define canonical serialization and domain separation. +3. **Local-alpha target**: Define replay boundaries. +4. **Local-alpha target**: Define public and private fields. +5. **Local-alpha target**: Define test vectors and negative vectors. +6. **Local-alpha target**: Define status semantics and failure behavior. +7. **Later research**: Define proof public inputs and witnesses if proofs are involved. +8. **Later research**: Get independent cryptography review for new proof claims. +9. **No-go**: Do not implement if the primitive requires tokenomics, bridge assumptions, production validators, or encrypted compute to be meaningful. + +## Builder Guidance + +- **Implemented**: Use current V0 crypto helpers and schemas as the factual baseline. +- **Local-alpha target**: Prefer deterministic verifier reports and challengeable provenance before proofs. +- **Local-alpha target**: Keep dependency declarations visible even when private details are hidden. +- **Local-alpha target**: Treat synthetic evidence as risk/debt unless real-world evidence validates it. +- **Later research**: Add proof-carrying receipts only after the receipt lifecycle is stable and the cost/benefit beats ordinary verifier replay. +- **No-go**: Do not let research novelty become a product security claim. diff --git a/research/flowchain-local-alpha/L1_GO_NO_GO_GATES.md b/research/flowchain-local-alpha/L1_GO_NO_GO_GATES.md new file mode 100644 index 00000000..4e3e0012 --- /dev/null +++ b/research/flowchain-local-alpha/L1_GO_NO_GO_GATES.md @@ -0,0 +1,250 @@ +# FlowChain L1 And Appchain Go/No-Go Gates + +Last updated: 2026-05-13 + +Status: research gate. This document does not approve production validators, a public L1, tokenomics, bridges, mainnet deployment, or production proof systems. + +## Purpose + +FlowChain should become chain-shaped only if the local object model proves that AI work, memory, artifacts, verifier decisions, dependencies, challenges, and finality are meaningfully stronger as native state than as app-level logs. + +## Status Vocabulary + +- **Implemented**: merged into FlowMemory as of `docs/CURRENT_STATE.md` dated 2026-05-13 or confirmed from `origin/main` on 2026-05-13. +- **Local-alpha target**: required before serious L1/appchain work resumes. +- **Later research**: useful future work behind explicit review. +- **Blocked**: cannot move to implementation until named prerequisites are met. +- **No-go**: condition that blocks advancement. +- **Explicitly later**: outside Local Alpha. + +## Master Decision Question + +**Later research**: A custom appchain or L1 is justified only if the project can answer yes: + +```text +Would FlowMemory be meaningfully weaker if work receipts, memory cells, artifact proofs, dependency roots, verifier decisions, challenges, and finality receipts were only app-level logs on Base or another existing chain? +``` + +If the answer is no, the go decision is to keep building product, verifier, dashboard, and Base settlement paths first. + +## Named Build Gates + +These are the gates builders should use when deciding what may move from research into implementation. + +| Gate | Status | Meaning | Allowed now | Blocked | +| --- | --- | --- | --- | --- | +| Local/private testnet | Local-alpha target | A no-value, local/private, second-computer-validatable package for FlowMemory object-state testing. | Research gates, object model specs, local control-plane acceptance criteria, fixture/release requirements, and later implementation by the owning agents after Gate 1 and Gate 2 pass. | Public validators, public sequencers, tokenomics, bridge value movement, production proof systems, production encrypted compute, or public mainnet claims. | +| Public devnet | Later research, Blocked | A public no-value, resettable experimental network where external operators may run nodes or inspect state. | Requirements drafting and threat-model review only. | Any public-network launch until the local/private testnet package is reproducible, monitored, and reviewed. | +| Public L1/mainnet | Explicitly later, Blocked | A production or value-bearing chain/network claim. | None beyond documenting blockers and review requirements. | Implementation, launch planning, validator economics, bridge deployment, token mechanics, or production proof claims. | + +The local/private testnet gate is the only gate that can be targeted by the current Ralph loop. Public devnet and public L1/mainnet remain research gates. + +## Gate 0: Local Alpha Research Boundary + +Status: **Local-alpha target**. + +Gate 0 is passed when the research-to-build boundary is clear enough for builders to implement local features without importing forbidden scope. + +Required evidence: + +| Requirement | Status | Pass condition | +| --- | --- | --- | +| Architecture reference | Local-alpha target | Local workbench, API, devnet, explorer, provenance, object model, releases, and later work are defined. | +| Octra competency bar | Local-alpha target | Control-plane parity is translated into FlowMemory-specific acceptance criteria. | +| L1 gates | Local-alpha target | Go/no-go gates exist before validator, public chain, token, bridge, or proof work. | +| Crypto research map | Local-alpha target | Process-Witness, SEAL, Synthetic Non-Amplification, proof-carrying receipts, and R&D/library boundaries are mapped. | +| Private state roadmap | Local-alpha target | Local vault, private references, dependency privacy, and encrypted compute sequence is explicit. | + +No-go conditions: + +- **No-go**: The docs imply production L1, validator, token, bridge, or encrypted-compute approval. +- **No-go**: The docs blur implemented V0 facts with later research. +- **No-go**: The docs authorize implementation outside the assigned research scope. + +## Gate 1: Local Object Model Acceptance + +Status: **Local-alpha target**. + +Gate 1 is passed when FlowMemory can show that the native objects are useful locally before choosing any production chain framework. + +Required evidence: + +| Object or workflow | Status | Pass condition | +| --- | --- | --- | +| WorkReceipt lifecycle | Implemented foundation, Local-alpha target | Submit/import, index, verify, challenge, accept/reject, finalize, and recompute after dependency change. | +| MemoryCell lineage | Local-alpha target | Memory can be traced to source receipts, Rootflow transitions, artifacts, dependencies, verifier reports, and finality state. | +| Artifact availability | Implemented foundation, Local-alpha target | Missing, changed, duplicated, expired, and recovered artifacts have deterministic states. | +| Verifier module provenance | Local-alpha target | Reports identify source-visible module, schema, version, hash, and reproducible command. | +| Challenge state | Local-alpha target | Challenges can be opened, responded to, resolved, expired, or used to downgrade finality. | +| Dependency declarations | Local-alpha target | Evidence/tool/model/data dependencies can be declared, rooted, displayed, challenged, and recomputed. | +| Synthetic Non-Amplification | Local-alpha target | Synthetic outputs cannot increase empirical certainty without real-world validation. | +| Workbench/explorer explanation | Local-alpha target | A builder can inspect why a memory exists and what would invalidate it. | + +No-go conditions: + +- **No-go**: Receipts cannot be replayed or explained from source observations and artifacts. +- **No-go**: Memory updates can be accepted from rejected, stale, or unavailable sources without clear status. +- **No-go**: Verifier reports are opaque and cannot be reproduced from declared modules and schemas. +- **No-go**: Synthetic evidence is treated as empirical support. +- **No-go**: Dependency omissions have no challenge or downgrade path. + +## Gate 2: Local Control Plane Acceptance + +Status: **Local-alpha target**. + +Gate 2 is passed when the local workbench, API, devnet, explorer, provenance, and release machinery can be used by builders without reading raw JSON for ordinary workflows. + +Required evidence: + +| Competency | Status | Pass condition | +| --- | --- | --- | +| Local vault | Local-alpha target | Local secrets are encrypted at rest, recoverable, rotatable, and never written to normal logs or committed fixtures. | +| Local API | Local-alpha target | Stable versioned methods exist for receipts, memory, artifacts, verifiers, challenges, dependencies, devnet, and releases. | +| Devnet | Implemented foundation, Local-alpha target | Deterministic no-value reset, submit-fixture, run-block, inspect-state, and export-fixture flows are covered by golden tests. | +| Explorer | Implemented foundation, Local-alpha target | Every lifecycle state is visible with clear local/test labels. | +| Provenance | Local-alpha target | Schemas, verifier modules, reports, receipts, artifacts, and releases are hash-addressed and source-visible. | +| Releases | Local-alpha target | Local-alpha releases include manifests, fixture hashes, limitations, migration notes, and reproduction commands. | + +No-go conditions: + +- **No-go**: Local secrets appear in logs, URIs, fixtures, public receipts, or chain data. +- **No-go**: API error shapes or ids are unstable enough that agents cannot rely on them. +- **No-go**: Explorer views hide challenge, unresolved, unsupported, reorged, or downgraded states. +- **No-go**: Releases cannot be reproduced from committed commands and fixtures. + +## Gate 3: Local/Private Testnet Gate + +Status: **Local-alpha target, blocked until Gates 1 and 2 pass**. + +Gate 3 is the first gate that can move from research to implementation. It creates a no-value local/private testnet package that a clean second computer can clone, initialize, run, inspect, smoke-test, export, import, and rerun deterministically. + +This gate is allowed to harden the current local no-value devnet and FlowMemory control plane. It is not allowed to create a public chain, validator market, bridge, token, or production proof system. + +Required evidence: + +| Requirement | Status | Pass condition | +| --- | --- | --- | +| Second-computer path | Local-alpha target | Clone, install, initialize local/private state, run node/runtime, run demo, run smoke, export state, import state, and rerun deterministically. | +| Object model freeze | Local-alpha target | Local Alpha has a stable receipt/memory/challenge/dependency state model with migration notes. | +| Local operator vault boundary | Local-alpha target | Local secrets are encrypted, unlock state is explicit, and normal logs/fixtures/public receipts never contain private material. | +| Data reconstruction plan | Local-alpha target | A new local/private node can reconstruct public state from defined fixture/devnet data or mark missing data unresolved. | +| Base anchor placeholder model | Implemented research placeholder, Local-alpha target | Anchor fields are reviewed for state-root, receipt-root, verifier-report-root, artifact-root, previous-anchor, finality, and replay semantics. | +| Framework trade study | Local-alpha target | Current custom Rust devnet, OP Stack/Base Appchain-style devnet, and app-level Base settlement are compared against object-model needs before replacing the current prototype. | +| Security review plan | Local-alpha target | Bridge, DA, replay, key custody, emergency pause, monitoring, and incident response review tasks are opened, even if marked later. | +| Release package | Local-alpha target | Release manifest includes commit, fixture hashes, schema hashes, verifier module hashes, local commands, limitations, and non-claims. | + +No-go conditions: + +- **No-go**: Appchain work would require raw memory, artifacts, model outputs, media, or secrets on-chain. +- **No-go**: Anchor roots cannot be reconciled by indexers. +- **No-go**: Verifier reports can be marked verified without available evidence. +- **No-go**: The team cannot explain inherited proof, DA, and finality assumptions of the selected framework. +- **No-go**: A local/private release requires a public RPC, production wallet, bridge, or deployed public network to pass. + +## Gate 4: Public Devnet Gate + +Status: **Later research, Blocked until Gate 3 passes**. + +Gate 4 is the earliest gate where a public no-value, resettable devnet can be discussed. It is not approved by Local Alpha. It requires the local/private testnet package to be reproducible first. + +Required evidence: + +| Requirement | Status | Pass condition | +| --- | --- | --- | +| Local/private release evidence | Later research | Gate 3 has a reproducible release, smoke test, export/import path, and known-limitation manifest. | +| Independent architecture review | Later research | Object model, state transition rules, DA assumptions, finality, and challenge semantics are reviewed. | +| Threat model update | Later research | The cryptography, verifier, appchain, bridge, private state, hardware observer, and operator threat models are current. | +| Public inputs and witnesses | Later research | Any proof-carrying receipt or dependency proof has exact public inputs, witness formats, privacy rules, and cost model. | +| Validator/sequencer role analysis | Later research | Roles, failures, monitoring, handoff, equivocation handling, and governance are documented without tokenomics. | +| Validator/sequencer economics boundary | Blocked | Public devnet may document cost and abuse constraints, but staking, rewards, fees, slashing, or token mechanics remain blocked until a separate economics decision exists. | +| Operational monitoring plan | Later research | Indexer lag, verifier outage, reorg, missing data, and challenge response workflows are observable. | +| Public operator policy | Later research | Key custody, source verification, release signing, operator onboarding, and incident response are documented. | + +No-go conditions: + +- **No-go**: Production validators are proposed before local object-model acceptance. +- **No-go**: Tokenomics, rewards, staking, or slashing are introduced as a workaround for missing security design. +- **No-go**: Public chain claims rely on unreviewed Process-Witness, SEAL, encrypted compute, or proof systems. +- **No-go**: Hardware observers are treated as validators, sequencers, DA providers, or bridge operators. +- **No-go**: The public devnet cannot be reset, halted, rolled back, or labeled experimental without confusing users. + +## Gate 5: Public L1/Mainnet Or Value-Bearing Production + +Status: **Explicitly later, Blocked**. + +Gate 5 is blocked until a separate production-readiness program exists. Local Alpha and the local/private testnet loop must not plan, imply, or market this gate. + +Required before this gate can even be drafted: + +- **Later research**: Gate 4 public devnet evidence and incident-history review. +- **Later research**: Bridge design review. +- **Later research**: DA review and reconstruction tests. +- **Later research**: Replay-protection review. +- **Later research**: Key custody review. +- **Later research**: Governance and upgrade policy. +- **Later research**: Emergency pause policy. +- **Later research**: Monitoring and incident response drill. +- **Later research**: Independent cryptography and contract audits. +- **Later research**: Production verifier network design. +- **Later research**: Legal and economic review if value or token mechanics are proposed. +- **Blocked**: Validator/sequencer economics, staking, rewards, fees, or slashing until a separate token/economics scope is explicitly approved. + +Immediate no-go conditions from the existing chain research: + +- **No-go**: Unclear withdrawal finality. +- **No-go**: Unclear DA source or retention. +- **No-go**: No replay protection. +- **No-go**: No emergency pause policy. +- **No-go**: No independent bridge/security review. +- **No-go**: Anchor roots cannot be reconciled by indexers. +- **No-go**: Verified status can be assigned without available evidence. +- **No-go**: Appchain value requires moving raw memory, artifacts, or evidence on-chain. + +## Topic Boundary Table + +| Topic | Status | Allowed next action | Blocked action | +| --- | --- | --- | --- | +| Local workbench | Local-alpha target | Specify and later build receipt/memory/artifact/verifier/challenge views. | Claim hosted production product readiness. | +| Local API | Local-alpha target | Specify stable local resource methods and schemas. | Launch production API. | +| No-value devnet | Implemented foundation, Local-alpha target | Harden deterministic fixtures and handoff outputs. | Public validator or sequencer deployment. | +| Base anchors | Implemented placeholder, Later research | Review compact anchor fields and reconciliation. | Production settlement or bridge claim. | +| Process-Witness | Later research | Map candidate primitives to receipt obligations and proof candidates. | Build production cognition proof system. | +| SEAL/dependency proofs | Later research | Define dependency vocabulary and challenge model. | Claim ZK dependence proofs are available. | +| Synthetic Non-Amplification | Local-alpha target | Enforce as a state invariant in specs and tests. | Let synthetic data increase empirical certainty. | +| Private state | Local-alpha target, Later research | Start with local vault and private artifact references. | Build encrypted compute. | +| Tokenomics | Explicitly later | None in Local Alpha. | Any fee, staking, reward, token, or slashing design. | +| Bridges | Explicitly later | Keep bridge security research gates. | Bridge deployment or value movement. | +| Production proof systems | Later research | Define public inputs, witnesses, setup assumptions, costs, and review gates. | Production circuits or verifier economics. | + +## Requirements Before Moving Research Topics To Implementation + +Status: **Local-alpha target for vocabulary, Blocked or Later research for protocol implementation**. + +These topics may shape local/private testnet schemas and fixtures, but they do not move to production code merely because they appear in research docs. + +| Topic | Current status | Minimum before implementation | Implementation still blocked from | +| --- | --- | --- | --- | +| Process-Witness | Later research | Accepted receipt obligation vocabulary, exact predicates, public inputs, witness formats, adversary model, cost model, and independent crypto review. | Cognitive proof circuits, claims that the chain proves intelligence/truth, or mandatory dependency for Local Alpha. | +| SEAL/dependency privacy | Later research; local vocabulary target | Dependency atom schema, dependency root format, completeness attestation scope, omitted-dependency challenge flow, downgrade semantics, public inputs, witness privacy rules, and review. | ZK dependence claims, hidden dependency omissions, or evidence independence claims without completeness warranties. | +| Synthetic Non-Amplification | Local-alpha target | Receipt/report/memory status rules that mark synthetic outputs as hypothesis, counterexample, challenge debt, or validation requirement unless deterministic formal verification applies. | Empirical certainty increases, biological/scientific finality, or memory trust upgrades based only on generated data. | +| Proof-carrying receipts | Later research | Stable receipt/report schemas, canonical vectors, exact proof public inputs, witness privacy rules, proof system choice, setup assumptions, challenge semantics, and cost model versus replay. | Production circuits, contract proof verification, or replacing deterministic verifier reports before review. | +| Advanced encrypted compute | Explicitly later, Blocked | Stable public/private data model, local vault, private reference envelope, threat model, key custody, side-channel/leakage review, DA/auditability policy, incident response, and independent security review. | FHE/MPC/TEE/coprocessor runtime, encrypted mempool, private inference, or production encrypted smart-contract claims. | +| Bridge security | Explicitly later, Blocked | Deposit/withdrawal messages, nonce/replay rules, source/destination binding, withdrawal finality, DA source, emergency pause, upgrade delay, monitoring, recovery, and independent review. | Value movement, production bridge deployment, public withdrawal claims, or any bridge that can move assets. | +| Validator/sequencer economics | Explicitly later, Blocked | Non-economic role analysis first: responsibilities, failures, equivocation, monitoring, governance, emergency operations, and public-devnet operating constraints. Separate economics/token scope required after that. | Tokenomics, staking, rewards, fee markets, slashing, validator incentives, or revenue claims. | + +## Minimum Go Packet For Any Future Appchain Discussion + +Status: **Later research**. + +A future appchain discussion should include: + +1. Gate 1 and Gate 2 evidence. +2. A precise state-machine diff showing what cannot be represented well as app-level Base logs. +3. A data availability and reconstruction plan. +4. A finality and downgrade model. +5. A challenge state machine. +6. A public input and witness map for any proofs. +7. A bridge/security non-goal statement if no bridge is proposed. +8. A release and rollback plan. +9. A claim guardrail review. +10. A list of independent reviewers needed before public testnet. diff --git a/research/flowchain-local-alpha/OCTRA_COMPETENCY_BAR.md b/research/flowchain-local-alpha/OCTRA_COMPETENCY_BAR.md new file mode 100644 index 00000000..a54c84e2 --- /dev/null +++ b/research/flowchain-local-alpha/OCTRA_COMPETENCY_BAR.md @@ -0,0 +1,219 @@ +# Octra Competency Bar For FlowChain Local Alpha + +Last updated: 2026-05-13 + +Status: comparison-derived research reference. The Octra material is treated as a user-supplied design reference, not as an independently re-crawled live audit. + +## Purpose + +The Octra comparison is useful because it highlights an alpha-stage chain pattern: ambitious cryptography becomes credible only when the local control plane is coherent. FlowChain Local Alpha should copy that discipline, not Octra's product category or bridge/encrypted-coprocessor ambition. + +## Status Vocabulary + +- **Implemented**: merged into FlowMemory as of `docs/CURRENT_STATE.md` dated 2026-05-13 or confirmed from `origin/main` on 2026-05-13. +- **Local-alpha target**: required bar for a future FlowChain Local Alpha build. +- **Later research**: useful later, blocked behind review. +- **Blocked**: cannot move to implementation until named prerequisites are met. +- **Explicitly later**: outside Local Alpha. + +## Competency Matrix + +| Octra signal | FlowChain interpretation | Status | Local Alpha evidence required | +| --- | --- | --- | --- | +| Local encrypted wallet/vault | FlowMemory needs a local secret vault for agent keys, wallet keys, API keys, hardware keys, and private receipt workspaces. | Local-alpha target | Import, export, unlock, rotate, lock, corrupt-file recovery, and no plaintext secret persistence in logs or fixtures. | +| Unified JSON-RPC/control API | FlowMemory needs one local API for receipt, memory, artifact, verifier, challenge, dependency, finality, and devnet resources. | Local-alpha target | Versioned schemas, idempotent commands, pagination, retry semantics, stable error shapes, and compatibility snapshots. | +| Public and encrypted state lanes | FlowMemory must separate public receipt metadata from private artifact references and secret material. | Local-alpha target | Public receipt views show commitments and statuses; private views require local vault unlock and never publish locators by accident. | +| Stealth/discovery/claim lifecycle | FlowMemory equivalent is artifact and memory discovery, selection, finalization, and reconciliation. | Local-alpha target | Workbench can show discovered references, claim/reconcile status, missing evidence, and finality changes. | +| Source-visible compile/tool pipeline | FlowMemory equivalent is source-visible schemas, verifier modules, generated reports, and fixture pipelines. | Local-alpha target | Every report names schema hash, verifier module hash, fixture/release hash, and deterministic command path. | +| Integrated browser workbench | FlowMemory needs a receipt and memory workbench before broad app ecosystem claims. | Local-alpha target | A user can inspect the full path from FlowPulse observation to receipt to verifier report to memory/root transition. | +| Source verification/provenance registry | FlowMemory needs artifact and verifier provenance. | Local-alpha target | Registry or manifest links objects to source path, version, hash, schema, generated artifact, and release bundle. | +| Explorer/history observability | FlowMemory must make lineage, challenge state, artifact state, verifier reports, dependency roots, and finality visible. | Implemented foundation, Local-alpha target for completeness | Dashboard/explorer shows every lifecycle state without requiring raw JSON inspection. | +| Bridge orchestration | FlowMemory should not attempt production bridge parity yet. | Explicitly later | Only no-value Base anchor placeholders and bridge-security research docs are acceptable in Local Alpha. | +| Node role topology | FlowMemory needs explicit local node, indexer, verifier, dashboard, hardware observer, and review roles. | Implemented foundation, Local-alpha target for polish | Topology docs and release manifests tell operators which role does what and what it cannot claim. | + +## Concrete Surface Bar + +This is the Octra-level comparison reduced to the surfaces FlowMemory actually needs. These are local/private testnet targets, not public chain claims. + +The accepted control-plane boundary is recorded in `docs/DECISIONS/2026-05-13-flowchain-local-alpha-control-plane-boundary.md`. + +| Surface | Status | Local/private testnet bar | Later or blocked boundary | +| --- | --- | --- | --- | +| Wallet/operator vault | Local-alpha target | Local operator secrets, agent keys, test wallet keys, API credentials, hardware channel keys, and private reference keys are encrypted at rest, unlockable, lockable, exportable only through explicit encrypted export, rotatable, and recoverable after corrupt-file detection without silent identity replacement. | Not a production wallet, MPC system, custody product, token wallet, or public validator key manager. | +| Local API | Local-alpha target | One versioned local API exposes receipts, memory cells/views, artifacts, verifier modules/reports, challenges, dependencies, finality, devnet state, release manifests, stable ids, pagination, retries, and typed errors. | Not a hosted production API or public RPC. | +| Explorer/workbench | Implemented foundation, Local-alpha target | A builder can inspect the path from FlowPulse observation to receipt, verifier report, Rootflow transition, memory lineage, artifact state, dependency root, challenge, and finality without raw JSON inspection. | Not a public validator explorer, bridge explorer, token explorer, or production encrypted-compute console. | +| Devnet/runtime | Implemented foundation, Local-alpha target | The no-value runtime supports deterministic genesis/reset, fixture import/export, submit/run/inspect flows, state-root and block-hash visibility, Base anchor placeholders, and failure fixtures. | Not production consensus, public sequencer operation, value movement, or bridge settlement. | +| Source/provenance | Local-alpha target | Schemas, verifier modules, generated reports, deployment/canary artifacts, fixture inputs, release outputs, and dashboard data identify source paths, versions, hashes, commands, and compatibility notes. | Provenance is reproducibility evidence, not proof of truth or trustless verification. | +| Crypto vectors | Implemented foundation, Local-alpha target | Accepted object ids and hashes have deterministic vectors, negative vectors, cross-language checks where practical, schema ids, domain separation, and replay-boundary tests before library promotion. | No speculative Process-Witness, SEAL, encrypted compute, or proof-carrying receipt primitives enter production libraries without accepted decisions and review. | +| Release packaging | Local-alpha target | A local-alpha release includes git commit, fixture hashes, schema hashes, verifier module hashes, generated output hashes, devnet handoff hash, reproduction commands, migration notes, known limitations, and non-claims. | Not a public devnet, public L1, mainnet, bridge, token, validator, or production proof release. | + +## 1. Local Workbench + +**Local-alpha target**: The workbench is the center of FlowChain Local Alpha. It should be a receipt and memory control plane, not a wallet-first marketing surface. + +Minimum workbench areas: + +| Area | Status | Required behavior | +| --- | --- | --- | +| Accounts and local vault | Local-alpha target | Manage local accounts, agent identities, hardware links, and secrets through an encrypted vault boundary. | +| Work receipts | Implemented foundation, Local-alpha target | List, inspect, submit/import fixtures, replay verification, and show status transitions. | +| Memory lineage | Implemented foundation, Local-alpha target | Show memory objects, parent receipts, root transitions, source observations, and stale/rejected dependencies. | +| Artifact availability | Implemented foundation, Local-alpha target | Show artifact roots, manifests/references, availability reports, missing evidence, and challenge state. | +| Verifier modules and reports | Implemented foundation, Local-alpha target | Show verifier identity, module provenance, report digest, check list, status, evidence commitment, and reproducibility path. | +| Challenges and finality | Local-alpha target | Show open, responded, upheld, dismissed, expired, superseded, downgraded, and finalized states. | +| Dependency roots | Local-alpha target | Show declared dependencies and dependency-class assumptions without implying SEAL ZK proofs exist. | +| Fixture runner and devnet state | Implemented foundation, Local-alpha target | Run or inspect deterministic no-value fixtures, local blocks, state roots, and Base anchor placeholders. | + +Acceptance evidence: + +- **Local-alpha target**: A builder can answer "why does this memory exist?" from the workbench. +- **Local-alpha target**: A builder can answer "which verifier accepted this receipt and under what module?" from the workbench. +- **Local-alpha target**: A builder can answer "what happens if this artifact is missing or this dependency is rejected?" from the workbench. +- **Explicitly later**: The workbench does not need public validator management, token management, bridge withdrawals, or encrypted compute jobs. + +## 2. API + +**Local-alpha target**: The local API should be the shared control plane for agents, the workbench, explorer, tests, and release tooling. + +Minimum resource families: + +| Resource family | Status | Required local methods | +| --- | --- | --- | +| Receipts | Implemented foundation, Local-alpha target | create/import, get, list, replay, attach artifact, attach verifier report, transition status. | +| Memory | Implemented foundation, Local-alpha target | get cell/view, list lineage, explain source receipts, mark stale/downgraded, export capsule. | +| Artifacts | Implemented foundation, Local-alpha target | register commitment, attach manifest/reference, check availability, challenge missing or changed data. | +| Verifiers | Implemented foundation, Local-alpha target | register module metadata, run deterministic check, get report, list module provenance. | +| Challenges | Local-alpha target | open, respond, resolve, expire, recompute affected receipt/memory state. | +| Dependencies | Local-alpha target | declare dependency atoms, group by root, set dependence class, mark omission challenge. | +| Devnet | Implemented foundation, Local-alpha target | reset, submit fixture, run block, inspect state, export handoff, inspect anchor placeholder. | +| Releases | Local-alpha target | produce manifest, verify fixture hash, check schema compatibility, list known limitations. | + +API acceptance rules: + +- **Local-alpha target**: Methods are deterministic against the same fixture inputs. +- **Local-alpha target**: Errors are typed and stable enough for agents and tests to consume. +- **Local-alpha target**: API results include status labels that distinguish observed, pending, verified, failed, unresolved, unsupported, reorged, challenged, downgraded, and finalized states. +- **Explicitly later**: No hosted production API is implied. + +## 3. Devnet + +**Implemented foundation**: The current Rust local devnet already provides deterministic local transactions, blocks, state roots, block hashes, and handoff fixtures. + +**Local-alpha target**: FlowChain Local Alpha should harden the devnet into a reliable object-model test rig. + +Required capabilities: + +- Deterministic genesis and reset. +- Fixture import and export for indexer, verifier, dashboard, and workbench. +- Explicit no-value transaction types for receipts, memory transitions, verifier reports, challenges, artifact commitments, and dependency declarations. +- State-root and block-hash inspection. +- Base anchor placeholder inspection. +- Golden fixture snapshots for releases. +- Failure fixtures for malformed receipt, missing artifact, stale verifier report, reorged observation, dependency omission, and challenge downgrade. + +Forbidden claims: + +- **Explicitly later**: No production consensus. +- **Explicitly later**: No public validators. +- **Explicitly later**: No sequencer or validator economics. +- **Explicitly later**: No bridge or value movement. +- **Explicitly later**: No mainnet-readiness claim. + +## 4. Explorer + +**Implemented foundation**: Dashboard V0 already renders fixture-backed views across Flow Memory, Rootflow, FlowPulse, Rootfields, receipts, reports, devnet blocks, hardware nodes, alerts, and raw JSON. + +**Local-alpha target**: The explorer should become the public truth table for local state, while still labeling local/test data clearly. + +Explorer requirements: + +- Receipt lifecycle timeline. +- Memory lineage graph or table. +- Artifact state and availability history. +- Verifier report checks and provenance. +- Challenge windows and outcomes. +- Dependency roots and declared dependence class. +- Finality and downgrade history. +- Devnet block/state-root view. +- Release manifest and schema compatibility view. + +Explorer non-goals: + +- **Explicitly later**: Public network validator explorer. +- **Explicitly later**: Bridge explorer. +- **Explicitly later**: Token or fee explorer. +- **Explicitly later**: Production encrypted compute job explorer. + +## 5. Provenance + +**Local-alpha target**: Provenance is the anti-chaos layer. Every important local-alpha object should say what produced it. + +Minimum provenance fields: + +| Object | Status | Provenance fields | +| --- | --- | --- | +| Schema | Implemented foundation, Local-alpha target | schema id, version, hash, source path, compatibility notes. | +| Verifier module | Local-alpha target | module id, source path, version, hash, input schemas, output schemas, deterministic command. | +| Verifier report | Implemented foundation, Local-alpha target | report id, verifier id, module id/hash, schema hash, evidence commitment, command/version, result status. | +| Receipt | Implemented foundation, Local-alpha target | receipt id/hash, schema hash, source observation, artifact root, dependency root, parent receipt, verifier reports. | +| Artifact reference | Local-alpha target | artifact root, manifest hash, locator policy, privacy class, availability checks, challenge state. | +| Release | Local-alpha target | release id, git commit, fixture hashes, schema hashes, verifier module hashes, generated output hashes, known limitations. | + +Provenance limits: + +- **Local-alpha target**: Provenance proves reproducibility and lineage, not truth. +- **Later research**: Proof-carrying provenance can replace some verifier claims only after public inputs, witnesses, costs, and challenge rules are reviewed. + +## 6. Object Model + +**Local-alpha target**: FlowChain should be judged by whether its object model is useful before any L1/appchain work resumes. + +Minimum Local Alpha objects: + +- `WorkReceipt`: compact record of work claim, roots, artifact, parent receipt, status, and verifier reports. +- `MemoryCell`: memory unit derived from receipts, Rootflow transitions, dependency declarations, and finality. +- `ArtifactAvailabilityProof`: availability claim or report tied to artifact root, manifest, locator policy, and challenge status. +- `VerifierModule`: source-visible check policy that produces deterministic reports. +- `Challenge`: state object for disputes, missing artifacts, dependency omissions, stale finality, or invalid reports. +- `FinalityReceipt`: status explanation for accepted, rejected, unresolved, downgraded, superseded, or finalized outcomes. +- `DependencyRoot`: declared evidence/tool/model/data dependency commitment. +- `AIWorkReceipt`: research-specific extension of `WorkReceipt`; useful in research docs, not required as product naming. + +## 7. Releases + +**Local-alpha target**: Local Alpha releases should be reproducible, not aspirational. + +Release bundle requirements: + +- Git commit and branch. +- Schema versions and hashes. +- Fixture input and generated output hashes. +- Devnet handoff output hash. +- Verifier module hashes. +- Dashboard/workbench data snapshot hash. +- Migration notes from prior local-alpha release. +- Known limitations and non-claims. +- Reproduction commands. +- `git diff --check` and area checks used for that release. + +Release non-claims: + +- **Explicitly later**: No production mainnet. +- **Explicitly later**: No public L1. +- **Explicitly later**: No production validators. +- **Explicitly later**: No tokenomics. +- **Explicitly later**: No production bridge. +- **Explicitly later**: No production proof system. + +## Competency Bar Summary + +FlowChain Local Alpha reaches the Octra-level bar when a local developer can: + +1. **Local-alpha target**: unlock local secrets without leaking them to logs, fixtures, public receipts, or chain data. +2. **Local-alpha target**: use one local API to create or inspect receipts, memory, artifacts, verifier reports, challenges, dependencies, and devnet state. +3. **Local-alpha target**: run deterministic no-value fixtures and inspect resulting state roots. +4. **Local-alpha target**: open an explorer/workbench and understand lineage, challenge state, and finality without reading raw JSON. +5. **Local-alpha target**: verify which source, schema, verifier module, and release produced each object. +6. **Local-alpha target**: ship a reproducible local-alpha release that says exactly what is implemented and what is not. + +If these are not true, FlowMemory should not resume serious public L1/appchain work. diff --git a/research/flowchain-local-alpha/PRIVATE_STATE_ROADMAP.md b/research/flowchain-local-alpha/PRIVATE_STATE_ROADMAP.md new file mode 100644 index 00000000..d2a1f625 --- /dev/null +++ b/research/flowchain-local-alpha/PRIVATE_STATE_ROADMAP.md @@ -0,0 +1,251 @@ +# FlowChain Private State Roadmap + +Last updated: 2026-05-13 + +Status: research roadmap. This document does not implement private state, encrypted compute, wallet code, vault code, proof systems, contracts, or production APIs. + +## Purpose + +FlowChain Local Alpha needs private-state discipline before it needs advanced encrypted compute. The correct sequence is: + +1. Local secret vault first. +2. Private artifact references second. +3. SEAL/dependency privacy third. +4. Encrypted compute later only after review. + +## Status Vocabulary + +- **Implemented**: merged into FlowMemory as of `docs/CURRENT_STATE.md` dated 2026-05-13 or confirmed from `origin/main` on 2026-05-13. +- **Local-alpha target**: appropriate to specify and later build for Local Alpha. +- **Later research**: blocked behind cryptography, product, and security review. +- **Blocked**: cannot move to implementation until named prerequisites are met. +- **No-go**: condition that blocks implementation or stronger claims. + +## Current Private-State Baseline + +| Area | Status | Current fact | +| --- | --- | --- | +| Public commitments | Implemented foundation | Current contracts and fixtures store or emit compact roots, commitments, receipts, reports, and advisory URI strings. | +| Secret storage | Local-alpha target | No production local vault exists in the current state summary; a local vault remains a future Local Alpha implementation target. | +| Private artifact references | Local-alpha target | Current `metadataURI` and `evidenceURI` style values are arbitrary caller-supplied log strings and do not enforce privacy, length, format, or resolver behavior. | +| Dependency privacy | Later research | SEAL/dependency privacy is research only. | +| Encrypted compute | Later research | No production encrypted compute exists and none is approved for Local Alpha. | + +## Roadmap Summary + +| Phase | Status | Goal | Explicit boundary | +| --- | --- | --- | --- | +| 1. Local secret vault | Local-alpha target | Protect local operator, agent, wallet, API, hardware, and private workspace secrets. | Not on-chain, not a production wallet, not MPC, not threshold crypto. | +| 2. Private artifact references | Local-alpha target | Separate public receipt metadata from encrypted local/private locators and artifact reference envelopes. | Not private compute and not a data availability guarantee. | +| 3. SEAL/dependency privacy | Later research, Local-alpha target for vocabulary | Hide sensitive dependency details while preserving challengeable dependency roots and completeness claims. | No ZK dependence claims until proof rules and challenge windows are reviewed. | +| 4. Encrypted compute | Later research | Explore encrypted execution, coprocessors, FHE/MPC/TEE, or private inference only after object model and threat model stabilize. | Not part of Local Alpha. | + +## Gate Relationship + +| Gate | Status | Private-state requirement | +| --- | --- | --- | +| Local/private testnet | Local-alpha target | Local vault and private artifact reference boundaries may move to implementation after schemas, tests, no-plaintext-log checks, and recovery behavior are accepted. Dependency privacy remains verifier-attested vocabulary only. | +| Public devnet | Later research, Blocked | Public operator key policy, release signing, disclosure logs, omission-challenge handling, and privacy threat model must be reviewed before any public network. | +| Public L1/mainnet | Explicitly later, Blocked | Production custody, encrypted compute, private evidence, and dependency privacy require independent security/crypto review, incident response policy, and explicit accepted decisions. | + +## Phase 1: Local Secret Vault First + +### Scope + +**Local-alpha target**: The vault is a local boundary for secrets needed by operators and agents. + +Candidate secret classes: + +- Local agent signing keys. +- Local wallet keys for test/dev workflows. +- API keys or RPC credentials. +- Hardware sidecar/channel keys. +- Private artifact locator decryption keys. +- Local workbench session secrets. +- Recovery/export passphrases. + +### Requirements + +| Requirement | Status | Acceptance condition | +| --- | --- | --- | +| Encrypted at rest | Local-alpha target | Secrets are encrypted in a local file or platform keystore-backed envelope using reviewed libraries. | +| Unlock/lock lifecycle | Local-alpha target | Workbench and API can distinguish locked, unlocked, expired, and unavailable vault states. | +| Import/export | Local-alpha target | Export is explicit, encrypted, and never part of normal logs or fixtures. | +| Rotation | Local-alpha target | Keys can be rotated or retired with downstream receipts showing superseded status where needed. | +| Corrupt-file recovery | Local-alpha target | Failure states are clear and do not silently create new identities. | +| No plaintext logs | Local-alpha target | Tests check that secrets do not appear in normal logs, fixtures, generated JSON, or public receipt data. | +| Local-only default | Local-alpha target | Vault material never syncs or publishes unless a separate explicit export action is performed. | + +### No-Go Conditions + +- **No-go**: Secrets appear in `metadataURI`, `evidenceURI`, receipts, fixtures, dashboard data, workbench logs, devnet state, or chain events. +- **No-go**: Vault unlock state is ambiguous to the API or workbench. +- **No-go**: A lost or corrupt vault causes silent identity replacement. +- **No-go**: Custom cryptography is introduced where a reviewed existing library or platform keystore should be used. + +## Phase 2: Private Artifact References Second + +### Scope + +**Local-alpha target**: Private artifact references keep public receipts useful without leaking sensitive locations, identifiers, or evidence. + +Public receipt metadata should contain: + +- Receipt id/hash. +- Artifact root or manifest hash. +- Storage or locator commitment. +- Evidence commitment. +- Privacy class. +- Availability status. +- Challenge/finality status. + +Private reference material may contain: + +- Encrypted locator. +- Access token reference. +- Private storage provider path. +- Decryption key reference. +- Retention policy detail. +- Private manifest fields. +- Local operator notes. + +### Requirements + +| Requirement | Status | Acceptance condition | +| --- | --- | --- | +| Public/private split | Local-alpha target | Public views show commitments and status, not raw locators or secrets. | +| Encrypted locator envelope | Local-alpha target | Private locators are encrypted under vault-managed keys or an explicitly reviewed envelope. | +| Resolver policy | Local-alpha target | API says whether a reference is local-only, shared-with-verifier, shared-with-agent, or public. | +| Availability checks | Local-alpha target | Missing, changed, expired, duplicated, or inaccessible artifacts produce deterministic status. | +| Challenge opening | Local-alpha target | Opening a private reference for a challenge is explicit and logged as a disclosure event. | +| Export controls | Local-alpha target | Release bundles and fixtures exclude private locator material by default. | + +### No-Go Conditions + +- **No-go**: Raw artifact bytes, model outputs, media, secrets, or private locators are placed on-chain. +- **No-go**: URI strings are treated as private or safe by default. +- **No-go**: A verifier report claims availability without evidence or defined access policy. +- **No-go**: Private references are required to reconstruct public state roots. + +## Phase 3: SEAL And Dependency Privacy Third + +### Scope + +**Later research**: SEAL-style dependency privacy aims to prove or attest dependency relationships without exposing all sensitive provenance. + +**Local-alpha target for vocabulary**: Before proofs, Local Alpha can model dependency roots, declared dependence classes, completeness attestations, and omitted-dependency challenges. + +### Local Alpha Vocabulary + +| Concept | Status | Private-state role | +| --- | --- | --- | +| Dependency atom | Local-alpha target | Typed dependency that may be public, private, salted, or committed. | +| Dependency root | Local-alpha target | Commitment to dependency atoms or hidden dependency commitments. | +| Completeness attestation | Local-alpha target | Issuer/verifier claim that a dependency set is complete for a declared scope. | +| Omitted-dependency challenge | Local-alpha target | Mechanism to reveal or prove a missing dependency and downgrade affected finality. | +| Causal separation proof | Later research | ZK proof that dependency footprints satisfy an admissible class. | +| MergeCapability | Later research | Proof-carrying permission to merge evidence under a dependence class. | + +### Requirements Before ZK Dependency Proofs + +- **Later research**: Exact dependency schema. +- **Later research**: Completeness warranty model. +- **Later research**: Omitted-dependency challenge state machine. +- **Later research**: Public inputs and witness privacy rules. +- **Later research**: Revocation and downgrade semantics. +- **Later research**: Independent cryptography review. +- **Later research**: Cost model versus deterministic verifier replay. + +### No-Go Conditions + +- **No-go**: Claiming independence without declared dependency scope. +- **No-go**: Hiding dependency omissions behind zero knowledge. +- **No-go**: Finality that cannot be downgraded after a valid omitted-dependency challenge. +- **No-go**: Treating private dependency proofs as implemented before proof rules and circuits exist. + +## Phase 4: Encrypted Compute Later Only After Review + +### Scope + +**Later research**: Encrypted compute includes FHE, MPC, TEE-backed private execution, encrypted coprocessor models, encrypted mempools, private inference, or generalized private smart contract execution. + +### Why It Is Later + +Encrypted compute has difficult dependencies: + +- Stable object model. +- Stable local API and private reference model. +- Clear threat model. +- Key custody design. +- Side-channel and leakage analysis. +- Data availability and auditability rules. +- Proof or attestation semantics. +- Incident response and downgrade paths. +- Independent security review. + +### No-Go Conditions + +- **No-go**: Encrypted compute is used to compensate for unclear public/private data modeling. +- **No-go**: A TEE, MPC, FHE, or coprocessor claim is made without specifying trust assumptions and leakage. +- **No-go**: Private computation output becomes final without verifier, challenge, or disclosure policy. +- **No-go**: Production encrypted compute is bundled with Local Alpha. + +## Public And Private State Boundary + +| Data | Status | Public receipt/root? | Private vault/reference? | +| --- | --- | --- | --- | +| Receipt hash | Implemented foundation | Yes | No secret. | +| Observation identity | Implemented foundation | Yes, after receipt/log observation. | No secret. | +| Artifact root | Implemented foundation | Yes | No secret if root is salted or high entropy where needed. | +| Raw artifact bytes | Implemented boundary | No | Local/private storage only. | +| Artifact locator | Local-alpha target | Commitment or encrypted envelope only. | Yes. | +| API/RPC credential | Local-alpha target | No | Yes. | +| Agent signing key | Local-alpha target | Public key may be public; private key never public. | Yes. | +| Hardware channel key | Local-alpha target | No | Yes. | +| Dependency root | Local-alpha target | Yes | Openings may be private. | +| Dependency atoms | Local-alpha target, Later research | Public only if safe; otherwise committed/salted/encrypted. | Yes where sensitive. | +| Verifier report | Implemented foundation | Public report/digest/status can be public. | Private evidence openings may be vault-gated. | +| Synthetic evidence | Local-alpha target | Status and commitments may be public. | Raw generated datasets may be private/off-chain. | + +## Workbench And API Responsibilities + +**Local-alpha target**: The workbench and API should make privacy state explicit. + +Required labels: + +- public +- local-only +- private-reference +- shared-with-verifier +- shared-with-agent +- challenge-disclosed +- redacted +- unavailable +- expired +- superseded + +Required behaviors: + +- Public views must not require vault unlock. +- Private reference views must require vault unlock. +- Disclosure for a challenge must create an auditable local event. +- Exported fixtures must exclude private fields unless explicitly requested into an encrypted export. +- Explorer must distinguish commitment, locator, artifact, proof, and verifier claim. + +## Recommended Implementation Order For A Future Build + +1. **Local-alpha target**: Define vault file/envelope format and tests. +2. **Local-alpha target**: Define API locked/unlocked error semantics. +3. **Local-alpha target**: Add no-plaintext-secrets fixture/log tests. +4. **Local-alpha target**: Define private artifact reference envelope. +5. **Local-alpha target**: Add availability and challenge disclosure states. +6. **Local-alpha target**: Define dependency root and dependency atom vocabulary. +7. **Later research**: Add completeness attestations and omitted-dependency challenge fixtures. +8. **Later research**: Evaluate SEAL-style ZK dependency proofs. +9. **Later research**: Evaluate encrypted compute only after independent review. + +## Bottom Line + +**Local-alpha target**: FlowChain private state starts as local secret management plus private artifact references. + +**Later research**: Hidden dependency proofs and encrypted compute can matter later, but only after the basic public/private data model, challenge model, and verifier/release machinery are clear. diff --git a/research/flowchain-local-alpha/README.md b/research/flowchain-local-alpha/README.md new file mode 100644 index 00000000..a52a9075 --- /dev/null +++ b/research/flowchain-local-alpha/README.md @@ -0,0 +1,42 @@ +# FlowChain Local Alpha Research Pack + +Last updated: 2026-05-13 + +Status: research gate index. This package does not authorize product code, public networks, tokenomics, bridges, production proof systems, encrypted compute, or production deployment. + +## Purpose + +This directory turns the FlowMemory, Rootflow, Noesis/Flow Chain, Claude/RD, and Octra research into practical gates for the local/private FlowChain testnet direction. + +The only near-term build target this pack supports is a no-value local/private testnet package that proves the FlowMemory object model on a second computer. + +## Source Status + +Use GitHub as source of truth. This worktree is behind `origin/main` by two commits at the time of this pass, so implemented facts may be sourced from either local `docs/CURRENT_STATE.md` or `origin/main` on 2026-05-13. + +## Reading Order + +1. `ARCHITECTURE_REFERENCE.md`: local-alpha architecture boundary and object model direction. +2. `L1_GO_NO_GO_GATES.md`: local/private, public devnet, and public L1/mainnet gates. +3. `OCTRA_COMPETENCY_BAR.md`: concrete local-control-plane surface bar. +4. `CRYPTOGRAPHY_RESEARCH_MAP.md`: Process-Witness, SEAL, Synthetic Non-Amplification, proof-carrying receipt, and crypto-library boundaries. +5. `PRIVATE_STATE_ROADMAP.md`: vault, private references, dependency privacy, and encrypted-compute sequence. +6. `BLOCKED_AND_LATER.md`: explicit stop list and smallest useful next steps. + +## Current Gate Summary + +| Gate | Status | Builder meaning | +| --- | --- | --- | +| Local/private testnet | Local-alpha target | Requirements may move to implementation only in the owning folders after accepted schemas, tests, and issue scope exist. | +| Public devnet | Later research, Blocked | Requirements drafting and threat modeling only; no public launch. | +| Public L1/mainnet | Explicitly later, Blocked | No implementation, launch planning, tokenomics, bridge deployment, or production proof claims. | + +## Decision Records + +- `docs/DECISIONS/2026-05-13-flowchain-deployment-gates.md` +- `docs/DECISIONS/2026-05-13-flowchain-proof-private-state-boundary.md` +- `docs/DECISIONS/2026-05-13-flowchain-local-alpha-control-plane-boundary.md` + +## Non-Negotiable Boundary + +Every future claim must be labeled as implemented, local-alpha target, later research, blocked, or explicitly later. Unlabeled public-chain, production-proof, token, bridge, validator, encrypted-compute, or mainnet claims should be treated as blocked.