Skip to content

Commit 624e443

Browse files
FlowmemoryAIFlowmemoryAI
committed
Merge remote-tracking branch 'origin/agent/flowchain-local-alpha-crypto-rd' into release/flowchain-private-testnet
2 parents 44db984 + e0a3ddb commit 624e443

30 files changed

Lines changed: 3587 additions & 13 deletions

‎crypto/FLOWCHAIN_LOCAL_ALPHA_OBJECTS.md‎

Lines changed: 248 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,248 @@
1+
# FlowChain Local Alpha Object Identity
2+
3+
Status: local/test V0.
4+
5+
This document defines the canonical cryptographic IDs for the FlowChain Local
6+
Alpha object model. These IDs are the crypto package boundary that devnet,
7+
control-plane, API, verifier, and dashboard agents should consume. Do not invent
8+
alternate hash formats for these objects.
9+
10+
## RD Crypto Boundary
11+
12+
The user noted that the RD library is for cryptography. I inspected this
13+
workspace and nearby `E:\FlowMemory` research paths.
14+
15+
No RD-named cryptography library exists inside this worktree. The current
16+
authoritative FlowMemory crypto package is:
17+
18+
```text
19+
E:\FlowMemory\flowmemory-crypto\crypto
20+
```
21+
22+
Nearby research/RD crypto sources do exist:
23+
24+
```text
25+
E:\FlowMemory\github-research-sources\noesis-l1\crates\noesis-crypto
26+
E:\FlowMemory\github-research-sources\noesis-l1\crates\noesis-zk
27+
E:\FlowMemory\github-research-sources\noesis-l1\crates\flowchain-pw
28+
E:\FlowMemory\github-research-sources\FlowMemory-2026-05-11\projects\noesis-l1\crates\noesis-crypto
29+
```
30+
31+
Those crates are useful RD references for object vocabulary, future proof
32+
interfaces, and Process-Witness research. They are not consumed directly by this
33+
package because the current `noesis-crypto` crate uses SHA-256 prototype object
34+
hashes, and `noesis-zk` explicitly marks production proof systems and
35+
commitment schemes as scaffolded. FlowChain Local Alpha IDs use the existing
36+
FlowMemory rule:
37+
38+
```text
39+
keccak256(abi.encode(TYPEHASH, field_1, field_2, ...))
40+
TYPEHASH = keccak256(bytes(type_string))
41+
```
42+
43+
FlowChain should consume the nearby RD libraries as research inputs only until a
44+
separate compatibility issue accepts a cross-language adapter and vectors that
45+
match the Keccak typed hashes in this package.
46+
47+
## Object IDs
48+
49+
All object IDs are bytes32 Keccak typed hashes. Variable-length names, policy
50+
documents, manifests, source code, response bodies, and dependency sets must be
51+
pre-hashed before entering the typed object.
52+
53+
| Object | ID field | Type string key | Domain string key | Helper |
54+
| --- | --- | --- | --- | --- |
55+
| AgentAccount | `agentId` | `agentAccountV0` | `agentAccountId` | `agentAccountId` |
56+
| ModelPassport | `modelId` | `modelPassportV0` | `modelPassportId` | `modelPassportId` |
57+
| WorkReceipt | `workReceiptId` | `workReceiptV0` | `workReceiptId` | `workReceiptId` |
58+
| ArtifactAvailabilityProof | `proofId` | `artifactAvailabilityProofV0` | `artifactAvailabilityProofId` | `artifactAvailabilityProofId` |
59+
| VerifierModule | `moduleId` | `verifierModuleV0` | `verifierModuleId` | `verifierModuleId` |
60+
| VerifierReport | `reportId` | `verifierReportV0` | `verifierReportDigest` | `verifierReportHash` |
61+
| MemoryCell | `memoryCellId` | `memoryCellV0` | `memoryCellId` | `memoryCellId` |
62+
| Challenge | `challengeId` | `challengeV0` | `challengeId` | `challengeId` |
63+
| FinalityReceipt | `finalityReceiptId` | `finalityReceiptV0` | `finalityReceiptId` | `finalityReceiptId` |
64+
| HardwareSignalEnvelope | `hardwareSignalEnvelopeId` | `hardwareSignalEnvelopeV0` | `hardwareSignalEnvelopeId` | `hardwareSignalEnvelopeId` |
65+
| Control-plane provenance response | `provenanceResponseId` | `controlPlaneProvenanceResponseV0` | `controlPlaneProvenanceResponseId` | `controlPlaneProvenanceResponseId` |
66+
67+
`WorkReceipt` and `VerifierReport` intentionally reuse the existing
68+
FlowMemory V0 domains, `flowmemory.v0.work.receipt-id` and
69+
`flowmemory.v0.verifier.report-digest`. The other Local Alpha object domains
70+
use `flowchain.local-alpha.v0.*`. This keeps the local testnet vocabulary
71+
compatible with the existing receipt/report package instead of creating a
72+
second receipt/report identity system.
73+
74+
`LocalSignatureEnvelope` uses `localSignatureEnvelopeV0` and
75+
`localSignatureEnvelopeHash`. It signs the object ID, object schema hash,
76+
domain separator, signer ID, signer key ID, signer role, sequence, validity
77+
window, and nonce. The signing digest is the local EIP-712 style digest over
78+
that struct hash and the object domain separator.
79+
80+
Runnable definitions live in `crypto/src/objects.js`.
81+
82+
Canonical object fixtures live in:
83+
84+
```text
85+
crypto/fixtures/local-alpha-objects.json
86+
```
87+
88+
Package-level vectors are pinned in:
89+
90+
```text
91+
crypto/fixtures/vectors.json
92+
```
93+
94+
The Local Alpha JSON Schemas live in:
95+
96+
```text
97+
schemas/flowmemory/agent-account.schema.json
98+
schemas/flowmemory/model-passport.schema.json
99+
schemas/flowmemory/work-receipt.schema.json
100+
schemas/flowmemory/memory-cell.schema.json
101+
schemas/flowmemory/artifact-availability-proof.schema.json
102+
schemas/flowmemory/verifier-module.schema.json
103+
schemas/flowmemory/verifier-report.schema.json
104+
schemas/flowmemory/challenge.schema.json
105+
schemas/flowmemory/finality-receipt.schema.json
106+
schemas/flowmemory/hardware-signal-envelope.schema.json
107+
schemas/flowmemory/local-signature-envelope.schema.json
108+
schemas/flowmemory/control-plane-provenance-response.schema.json
109+
```
110+
111+
## Local Signature Envelope Rules
112+
113+
Local Alpha accepts four signer roles:
114+
115+
| Role | Intended signer | Boundary |
116+
| --- | --- | --- |
117+
| `operator` | local operator process or operator-vault adapter | No value-bearing wallet claim. The fixture keys are deterministic no-value test keys. |
118+
| `agent` | registered `AgentAccount` local key | Signs local work receipts, memory cells, challenges, or agent-scoped provenance. |
119+
| `verifier` | local verifier module/report signer | Signs verifier modules, verifier reports, and finality receipts as testnet statements, not trustless proofs. |
120+
| `hardware` | FlowRouter or simulator device key | Signs low-bandwidth control envelopes only. Heavy payloads remain off-chain. |
121+
122+
Envelope validation requires:
123+
124+
- `objectSchema`, `objectType`, and `objectTypeHash` match the document schema.
125+
- `objectId` matches the recomputed document ID.
126+
- `domain` and `domainSeparator` match the canonical object domain.
127+
- `signerId`, `signerKeyId`, `publicKey`, and `signature` are present.
128+
- signer role is allowed for the object type.
129+
- `envelopeId` and `signingDigest` recompute from the envelope fields.
130+
- the secp256k1 signature verifies against the signing digest and public key.
131+
- the caller supplies replay context and rejects repeated signer/domain/sequence tuples.
132+
- critical object hashes are nonzero, dependency roots are well-formed, parent/root relationships are coherent, and the object type is not swapped.
133+
134+
The fixture validator covers invalid vectors for replay, wrong domain, missing
135+
signer, bad signature, zero hash, malformed ID, malformed dependency, bad
136+
parent/root, and wrong object type. Every Local Alpha object envelope also has a
137+
valid fixture and a bad-signature invalid fixture.
138+
139+
## Consumer Rules
140+
141+
Chain/devnet:
142+
143+
- Use these IDs as local transaction/object keys.
144+
- Reject malformed IDs, zero critical roots, bad parent/root transitions,
145+
wrong object types, and replayed signer/domain/sequence tuples before state
146+
mutation.
147+
- Do not treat signatures as production wallet custody or value-bearing
148+
authorization.
149+
150+
Services/control plane:
151+
152+
- Import the crypto package or reproduce the type strings and vectors exactly.
153+
- Run `validateLocalAlphaEnvelope` before accepting local object documents from
154+
transactions, APIs, fixtures, or hardware packets.
155+
- Store validation errors explicitly instead of silently coercing objects.
156+
157+
Dashboard/workbench:
158+
159+
- Display object IDs, domains, signer role, status label, and validation errors.
160+
- Show verifier reports and finality receipts as local/test statements unless a
161+
later proof/enforcement path is accepted.
162+
163+
Hardware:
164+
165+
- Use `HardwareSignalEnvelope` for compact control signals only.
166+
- Treat LoRa and Meshtastic fields as low-bandwidth control provenance, not as
167+
artifact transport or internet replacement.
168+
- Keep raw hardware payloads off-chain and bind them through `signalRoot`.
169+
170+
## What V0 Proves
171+
172+
V0 proves deterministic identity and tamper-evident binding for the typed fields
173+
included in each object ID. If any included field changes, the ID changes.
174+
175+
V0 also proves:
176+
177+
- field-order compatibility with the FlowMemory Keccak ABI typed-hash rule;
178+
- domain/type-string separation for each object class;
179+
- malformed hex rejection for bytes32/address fields;
180+
- canonical JSON stability for pre-hashed control-plane response bodies;
181+
- duplicate ID detection in fixture validation;
182+
- explicit finality and challenge state labels for local/test consumers.
183+
184+
## What V0 Does Not Prove
185+
186+
V0 does not prove that an AI model output is correct, that a verifier is honest,
187+
that storage remains available forever, that hidden dependencies are complete,
188+
or that a challenge outcome is economically secure.
189+
190+
V0 does not implement production proof circuits, GPU proofs, verifier
191+
economics, encrypted compute, production consensus, or a public L1. The object
192+
IDs are stable commitments and provenance handles, not a trustless proof system.
193+
194+
## Explicit RD Gates
195+
196+
These tracks are gated and must not be treated as implemented by this package:
197+
198+
- Process-Witness: research input only until public inputs, witness format,
199+
replay policy, privacy boundaries, and cross-language vectors are accepted.
200+
- SEAL/dependency privacy: attach through `dependencyRoot` and challenge roots
201+
only until dependency atom schemas, disclosure policy, and verifier checks are
202+
accepted.
203+
- Synthetic Non-Amplification: no claims until there is a formal rule, fixture
204+
corpus, verifier module, and dashboard/status vocabulary.
205+
- Advanced encrypted compute: no runtime or security claim until threat model,
206+
key lifecycle, leakage policy, and deterministic verifier boundary exist.
207+
- GPU proofs: no proof claim until proof system, public inputs, cost model,
208+
verifier module, and reproducible local vectors exist.
209+
- Audited production proof systems: no audit or production-readiness claim until
210+
a named audit artifact, issue/decision record, and enforcement path are merged.
211+
212+
## Dependency And SEAL Mapping
213+
214+
The Local Alpha object model leaves a forward-compatible slot for future SEAL or
215+
dependency-atom work:
216+
217+
- `MemoryCell.dependencyRoot` commits to the dependency atoms or dependency
218+
certificate set that a memory update relies on.
219+
- `ControlPlaneProvenanceResponse.dependencyRoot` lets an API response cite the
220+
same dependency state without embedding private dependency atoms.
221+
- `Challenge.challengeType = dependency_omission` gives omitted-dependency
222+
challenges a canonical local/test object ID.
223+
- `VerifierModule.supportedChallengeTypesRoot` and `supportedModesRoot` can
224+
commit to future verifier support for SEAL, dependency separation, or
225+
completeness checks.
226+
- `FinalityReceipt.challengeRoot` keeps finality downgradeable if a later
227+
dependency challenge succeeds.
228+
229+
Future SEAL objects should hash their own public inputs into roots and attach
230+
through these fields. They should not mutate the V0 object ID type strings.
231+
232+
## Future Proof-Carrying Receipts
233+
234+
Proof-carrying receipts can be added without breaking V0 IDs by treating proofs
235+
as new linked objects rather than new bytes inside existing ID preimages.
236+
237+
The stable path is:
238+
239+
1. Keep V0 IDs unchanged.
240+
2. Define a new proof object with its own schema, type string, public inputs,
241+
proof system id, verifier module id, and proof artifact commitment.
242+
3. Link that proof object to `receiptId`, `reportId`, `challengeId`,
243+
`finalityReceiptId`, or `dependencyRoot`.
244+
4. If a breaking receipt hash is needed later, create a V1 type string instead
245+
of changing V0.
246+
247+
This lets Local Alpha dashboards and APIs rely on V0 IDs while future proof
248+
systems attach stronger evidence as additional commitments.

‎crypto/FLOWMEMORY_CRYPTO_SPEC.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -103,6 +103,16 @@ verifierIdentity
103103
merkleLeaf
104104
merkleInternalNode
105105
devnetBlockHash
106+
agentAccountId
107+
modelPassportId
108+
memoryCellId
109+
artifactAvailabilityProofId
110+
verifierModuleId
111+
challengeId
112+
finalityReceiptId
113+
hardwareSignalEnvelopeId
114+
controlPlaneProvenanceResponseId
115+
localSignatureEnvelope
106116
```
107117

108118
## Versioning Strategy
@@ -128,6 +138,8 @@ The current package implements:
128138
- deterministic verifier reports
129139
- verifier signature envelopes
130140
- reorg-aware status handling
141+
- FlowChain Local Alpha object identity for agent accounts, model passports, work receipts, artifact availability proofs, verifier modules, verifier reports, memory cells, challenges, finality receipts, hardware signal envelopes, and control-plane provenance responses
142+
- Local Alpha operator, agent, verifier, and hardware signature envelope payloads and validators for replay, wrong domain, missing signer, zero hash, malformed id, malformed dependency, bad parent/root, and wrong object type checks
131143
- test vectors and cross-language conformance tests
132144

133145
The runnable package in `crypto/src/` currently implements the v0 hash utilities and tests them against fixtures in `crypto/fixtures/`.
@@ -139,6 +151,7 @@ MVP should remain verifier-attested for:
139151
- storage provider claims
140152
- model or worker behavior
141153
- final status labels before proof systems exist
154+
- local operator-vault policy; current fixture keys are deterministic no-value test keys and do not represent wallet custody, production account control, or transferable value
142155

143156
## Future Split
144157

@@ -176,3 +189,4 @@ Searches for `Claw` and `claw` in repository issues and code returned no matchin
176189
- Define key registry and verifier set root governance.
177190
- Define challenge evidence and response envelopes.
178191
- Produce a decision record before CursorRegistry or proof-carrying receipts are implemented.
192+
- Decide when, if ever, the nearby Noesis/FlowChain RD crypto crates should receive a Keccak compatibility adapter for these V0 object IDs.

‎crypto/README.md‎

Lines changed: 24 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -33,24 +33,32 @@ Validate all package-level vector fixtures:
3333
npm run validate:vectors
3434
```
3535

36+
Validate the Local Alpha object and signature-envelope fixtures against the
37+
canonical JSON Schemas:
38+
39+
```powershell
40+
npm run validate:local-alpha
41+
```
42+
3643
## Read Order
3744

3845
1. `FLOWMEMORY_CRYPTO_SPEC.md`
3946
2. `OBSERVATION_IDENTITY.md`
4047
3. `RECEIPT_HASHING.md`
4148
4. `MERKLE_AND_ROOTS.md`
4249
5. `ATTESTATIONS.md`
43-
6. `TEST_VECTORS.md`
50+
6. `FLOWCHAIN_LOCAL_ALPHA_OBJECTS.md`
51+
7. `TEST_VECTORS.md`
4452

45-
Runnable fixtures live in `fixtures/`. `fixtures/vectors.json` contains the current 21 package-level vectors. Supporting cross-language vectors live in `test-vectors/`.
53+
Runnable fixtures live in `fixtures/`. `fixtures/vectors.json` contains the current 33 package-level vectors. `fixtures/local-alpha-objects.json` contains positive and negative Local Alpha object and signed-envelope fixtures. Supporting cross-language vectors live in `test-vectors/`.
4654

4755
Validate the current vector set with:
4856

4957
```powershell
5058
python validate_test_vectors.py
5159
```
5260

53-
The Python validator is a cross-check for the FlowPulse aggregate vector. The production-candidate package paths are `npm test` and `npm run validate:vectors`.
61+
The Python validator is a cross-check for the FlowPulse aggregate vector. The primary local/test package paths are `npm test`, `npm run validate:vectors`, and `npm run validate:local-alpha`.
5462

5563
## Core Vocabulary
5664

@@ -60,10 +68,12 @@ The Python validator is a cross-check for the FlowPulse aggregate vector. The pr
6068
- `artifactRoot`: commitment to off-chain artifact bytes and metadata.
6169
- `reportId`: deterministic identifier for a verifier report.
6270
- `attestation`: signed worker or verifier envelope over a receipt, report, artifact, or root.
71+
- Local Alpha object IDs: canonical IDs for `AgentAccount`, `ModelPassport`, `WorkReceipt`, `ArtifactAvailabilityProof`, `VerifierModule`, `VerifierReport`, `MemoryCell`, `Challenge`, `FinalityReceipt`, hardware signal envelopes, and control-plane provenance responses.
72+
- Local Alpha signature envelopes: local operator, agent, verifier, and hardware secp256k1 test signatures over typed object IDs. These are no-value local/test keys and are not wallet custody or production key-management claims.
6373

6474
## Implemented Helpers
6575

66-
The package exports Keccak helpers, canonical JSON hashing, typed hash utilities, FlowPulse observation ids, cursor ids, report digests, receipt hashes, artifact/root commitments, work receipt ids, Merkle roots, worker/verifier signature payloads, verifier attestation envelope hashes, and local secp256k1 sign/verify helpers for tests.
76+
The package exports Keccak helpers, canonical JSON hashing, typed hash utilities, FlowPulse observation ids, cursor ids, report digests, receipt hashes, artifact/root commitments, work receipt ids, Local Alpha object ids, hardware signal envelope ids, Local Alpha signature envelope payloads, envelope validators, Merkle roots, worker/verifier signature payloads, verifier attestation envelope hashes, and local secp256k1 sign/verify helpers for tests.
6777

6878
The implementation is ESM JavaScript with `src/index.d.ts` declarations for TypeScript consumers.
6979

@@ -77,9 +87,18 @@ Future work may add proof-carrying receipts, zk circuits for receipt consistency
7787

7888
## Integration Notes
7989

80-
There is no `services/shared/` package in this repository yet. Until one exists, services should either:
90+
There is a fixture-first `services/shared/` package in this repository, but the crypto package remains the authoritative source for the hash formats in this directory. Services should either:
8191

8292
- import this package directly from `crypto/` in local development, or
8393
- mirror the exported functions from `crypto/src/index.js` with tests against `crypto/fixtures/`.
8494

8595
Indexer and verifier services must not hand-roll different hash formats. If a service cannot import this package, it should copy the type strings and vectors exactly and prove compatibility by passing the same fixture hashes.
96+
97+
Nearby Noesis/FlowChain RD crates under `E:\FlowMemory\github-research-sources\noesis-l1\crates\` are research inputs only for this package. They should not replace these Keccak typed-hash vectors unless a compatibility adapter and matching cross-language vectors are accepted.
98+
99+
## Downstream Consumption
100+
101+
- Chain/devnet agents should use the object ID helpers as transaction/object keys and reject zero roots, malformed IDs, wrong object types, replayed signer sequences, and bad parent/root relationships before state updates.
102+
- Services and verifiers should use `validateLocalAlphaEnvelope` before accepting object documents from local transactions, API calls, hardware packets, or fixture imports.
103+
- Dashboard/workbench agents should display IDs, domains, signer roles, status labels, and validation errors from these fixtures without implying production proof security.
104+
- Hardware agents should treat hardware signal envelopes as low-bandwidth authenticated control messages only; payloads remain off-chain and signal roots are commitments, not radio bandwidth or field-deployment claims.

0 commit comments

Comments
 (0)