Skip to content

[crypto] add FlowChain local object schemas and vectors #86

New issue

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

Sign up for GitHub

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

Already on GitHub? Sign in to your account

Merged
FlowmemoryAI merged 1 commit into from
May 13, 2026
Merged

[crypto] add FlowChain local object schemas and vectors #86

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
248 changes: 248 additions & 0 deletions crypto/FLOWCHAIN_LOCAL_ALPHA_OBJECTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,248 @@
# FlowChain Local Alpha Object Identity

Status: local/test V0.

This document defines the canonical cryptographic IDs for the FlowChain Local
Alpha object model. These IDs are the crypto package boundary that devnet,
control-plane, API, verifier, and dashboard agents should consume. Do not invent
alternate hash formats for these objects.

## RD Crypto Boundary

The user noted that the RD library is for cryptography. I inspected this
workspace and nearby `E:\FlowMemory` research paths.

No RD-named cryptography library exists inside this worktree. The current
authoritative FlowMemory crypto package is:

```text
E:\FlowMemory\flowmemory-crypto\crypto
```

Nearby research/RD crypto sources do exist:

```text
E:\FlowMemory\github-research-sources\noesis-l1\crates\noesis-crypto
E:\FlowMemory\github-research-sources\noesis-l1\crates\noesis-zk
E:\FlowMemory\github-research-sources\noesis-l1\crates\flowchain-pw
E:\FlowMemory\github-research-sources\FlowMemory-2026-05-11\projects\noesis-l1\crates\noesis-crypto
```

Those crates are useful RD references for object vocabulary, future proof
interfaces, and Process-Witness research. They are not consumed directly by this
package because the current `noesis-crypto` crate uses SHA-256 prototype object
hashes, and `noesis-zk` explicitly marks production proof systems and
commitment schemes as scaffolded. FlowChain Local Alpha IDs use the existing
FlowMemory rule:

```text
keccak256(abi.encode(TYPEHASH, field_1, field_2, ...))
TYPEHASH = keccak256(bytes(type_string))
```

FlowChain should consume the nearby RD libraries as research inputs only until a
separate compatibility issue accepts a cross-language adapter and vectors that
match the Keccak typed hashes in this package.

## Object IDs

All object IDs are bytes32 Keccak typed hashes. Variable-length names, policy
documents, manifests, source code, response bodies, and dependency sets must be
pre-hashed before entering the typed object.

| Object | ID field | Type string key | Domain string key | Helper |
| --- | --- | --- | --- | --- |
| AgentAccount | `agentId` | `agentAccountV0` | `agentAccountId` | `agentAccountId` |
| ModelPassport | `modelId` | `modelPassportV0` | `modelPassportId` | `modelPassportId` |
| WorkReceipt | `workReceiptId` | `workReceiptV0` | `workReceiptId` | `workReceiptId` |
| ArtifactAvailabilityProof | `proofId` | `artifactAvailabilityProofV0` | `artifactAvailabilityProofId` | `artifactAvailabilityProofId` |
| VerifierModule | `moduleId` | `verifierModuleV0` | `verifierModuleId` | `verifierModuleId` |
| VerifierReport | `reportId` | `verifierReportV0` | `verifierReportDigest` | `verifierReportHash` |
| MemoryCell | `memoryCellId` | `memoryCellV0` | `memoryCellId` | `memoryCellId` |
| Challenge | `challengeId` | `challengeV0` | `challengeId` | `challengeId` |
| FinalityReceipt | `finalityReceiptId` | `finalityReceiptV0` | `finalityReceiptId` | `finalityReceiptId` |
| HardwareSignalEnvelope | `hardwareSignalEnvelopeId` | `hardwareSignalEnvelopeV0` | `hardwareSignalEnvelopeId` | `hardwareSignalEnvelopeId` |
| Control-plane provenance response | `provenanceResponseId` | `controlPlaneProvenanceResponseV0` | `controlPlaneProvenanceResponseId` | `controlPlaneProvenanceResponseId` |

`WorkReceipt` and `VerifierReport` intentionally reuse the existing
FlowMemory V0 domains, `flowmemory.v0.work.receipt-id` and
`flowmemory.v0.verifier.report-digest`. The other Local Alpha object domains
use `flowchain.local-alpha.v0.*`. This keeps the local testnet vocabulary
compatible with the existing receipt/report package instead of creating a
second receipt/report identity system.

`LocalSignatureEnvelope` uses `localSignatureEnvelopeV0` and
`localSignatureEnvelopeHash`. It signs the object ID, object schema hash,
domain separator, signer ID, signer key ID, signer role, sequence, validity
window, and nonce. The signing digest is the local EIP-712 style digest over
that struct hash and the object domain separator.

Runnable definitions live in `crypto/src/objects.js`.

Canonical object fixtures live in:

```text
crypto/fixtures/local-alpha-objects.json
```

Package-level vectors are pinned in:

```text
crypto/fixtures/vectors.json
```

The Local Alpha JSON Schemas live in:

```text
schemas/flowmemory/agent-account.schema.json
schemas/flowmemory/model-passport.schema.json
schemas/flowmemory/work-receipt.schema.json
schemas/flowmemory/memory-cell.schema.json
schemas/flowmemory/artifact-availability-proof.schema.json
schemas/flowmemory/verifier-module.schema.json
schemas/flowmemory/verifier-report.schema.json
schemas/flowmemory/challenge.schema.json
schemas/flowmemory/finality-receipt.schema.json
schemas/flowmemory/hardware-signal-envelope.schema.json
schemas/flowmemory/local-signature-envelope.schema.json
schemas/flowmemory/control-plane-provenance-response.schema.json
```

## Local Signature Envelope Rules

Local Alpha accepts four signer roles:

| Role | Intended signer | Boundary |
| --- | --- | --- |
| `operator` | local operator process or operator-vault adapter | No value-bearing wallet claim. The fixture keys are deterministic no-value test keys. |
| `agent` | registered `AgentAccount` local key | Signs local work receipts, memory cells, challenges, or agent-scoped provenance. |
| `verifier` | local verifier module/report signer | Signs verifier modules, verifier reports, and finality receipts as testnet statements, not trustless proofs. |
| `hardware` | FlowRouter or simulator device key | Signs low-bandwidth control envelopes only. Heavy payloads remain off-chain. |

Envelope validation requires:

- `objectSchema`, `objectType`, and `objectTypeHash` match the document schema.
- `objectId` matches the recomputed document ID.
- `domain` and `domainSeparator` match the canonical object domain.
- `signerId`, `signerKeyId`, `publicKey`, and `signature` are present.
- signer role is allowed for the object type.
- `envelopeId` and `signingDigest` recompute from the envelope fields.
- the secp256k1 signature verifies against the signing digest and public key.
- the caller supplies replay context and rejects repeated signer/domain/sequence tuples.
- critical object hashes are nonzero, dependency roots are well-formed, parent/root relationships are coherent, and the object type is not swapped.

The fixture validator covers invalid vectors for replay, wrong domain, missing
signer, bad signature, zero hash, malformed ID, malformed dependency, bad
parent/root, and wrong object type. Every Local Alpha object envelope also has a
valid fixture and a bad-signature invalid fixture.

## Consumer Rules

Chain/devnet:

- Use these IDs as local transaction/object keys.
- Reject malformed IDs, zero critical roots, bad parent/root transitions,
wrong object types, and replayed signer/domain/sequence tuples before state
mutation.
- Do not treat signatures as production wallet custody or value-bearing
authorization.

Services/control plane:

- Import the crypto package or reproduce the type strings and vectors exactly.
- Run `validateLocalAlphaEnvelope` before accepting local object documents from
transactions, APIs, fixtures, or hardware packets.
- Store validation errors explicitly instead of silently coercing objects.

Dashboard/workbench:

- Display object IDs, domains, signer role, status label, and validation errors.
- Show verifier reports and finality receipts as local/test statements unless a
later proof/enforcement path is accepted.

Hardware:

- Use `HardwareSignalEnvelope` for compact control signals only.
- Treat LoRa and Meshtastic fields as low-bandwidth control provenance, not as
artifact transport or internet replacement.
- Keep raw hardware payloads off-chain and bind them through `signalRoot`.

## What V0 Proves

V0 proves deterministic identity and tamper-evident binding for the typed fields
included in each object ID. If any included field changes, the ID changes.

V0 also proves:

- field-order compatibility with the FlowMemory Keccak ABI typed-hash rule;
- domain/type-string separation for each object class;
- malformed hex rejection for bytes32/address fields;
- canonical JSON stability for pre-hashed control-plane response bodies;
- duplicate ID detection in fixture validation;
- explicit finality and challenge state labels for local/test consumers.

## What V0 Does Not Prove

V0 does not prove that an AI model output is correct, that a verifier is honest,
that storage remains available forever, that hidden dependencies are complete,
or that a challenge outcome is economically secure.

V0 does not implement production proof circuits, GPU proofs, verifier
economics, encrypted compute, production consensus, or a public L1. The object
IDs are stable commitments and provenance handles, not a trustless proof system.

## Explicit RD Gates

These tracks are gated and must not be treated as implemented by this package:

- Process-Witness: research input only until public inputs, witness format,
replay policy, privacy boundaries, and cross-language vectors are accepted.
- SEAL/dependency privacy: attach through `dependencyRoot` and challenge roots
only until dependency atom schemas, disclosure policy, and verifier checks are
accepted.
- Synthetic Non-Amplification: no claims until there is a formal rule, fixture
corpus, verifier module, and dashboard/status vocabulary.
- Advanced encrypted compute: no runtime or security claim until threat model,
key lifecycle, leakage policy, and deterministic verifier boundary exist.
- GPU proofs: no proof claim until proof system, public inputs, cost model,
verifier module, and reproducible local vectors exist.
- Audited production proof systems: no audit or production-readiness claim until
a named audit artifact, issue/decision record, and enforcement path are merged.

## Dependency And SEAL Mapping

The Local Alpha object model leaves a forward-compatible slot for future SEAL or
dependency-atom work:

- `MemoryCell.dependencyRoot` commits to the dependency atoms or dependency
certificate set that a memory update relies on.
- `ControlPlaneProvenanceResponse.dependencyRoot` lets an API response cite the
same dependency state without embedding private dependency atoms.
- `Challenge.challengeType = dependency_omission` gives omitted-dependency
challenges a canonical local/test object ID.
- `VerifierModule.supportedChallengeTypesRoot` and `supportedModesRoot` can
commit to future verifier support for SEAL, dependency separation, or
completeness checks.
- `FinalityReceipt.challengeRoot` keeps finality downgradeable if a later
dependency challenge succeeds.

Future SEAL objects should hash their own public inputs into roots and attach
through these fields. They should not mutate the V0 object ID type strings.

## Future Proof-Carrying Receipts

Proof-carrying receipts can be added without breaking V0 IDs by treating proofs
as new linked objects rather than new bytes inside existing ID preimages.

The stable path is:

1. Keep V0 IDs unchanged.
2. Define a new proof object with its own schema, type string, public inputs,
proof system id, verifier module id, and proof artifact commitment.
3. Link that proof object to `receiptId`, `reportId`, `challengeId`,
`finalityReceiptId`, or `dependencyRoot`.
4. If a breaking receipt hash is needed later, create a V1 type string instead
of changing V0.

This lets Local Alpha dashboards and APIs rely on V0 IDs while future proof
systems attach stronger evidence as additional commitments.
14 changes: 14 additions & 0 deletions crypto/FLOWMEMORY_CRYPTO_SPEC.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -103,6 +103,16 @@ verifierIdentity
merkleLeaf
merkleInternalNode
devnetBlockHash
agentAccountId
modelPassportId
memoryCellId
artifactAvailabilityProofId
verifierModuleId
challengeId
finalityReceiptId
hardwareSignalEnvelopeId
controlPlaneProvenanceResponseId
localSignatureEnvelope
```

## Versioning Strategy
Expand All @@ -128,6 +138,8 @@ The current package implements:
- deterministic verifier reports
- verifier signature envelopes
- reorg-aware status handling
- 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
- 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
- test vectors and cross-language conformance tests

The runnable package in `crypto/src/` currently implements the v0 hash utilities and tests them against fixtures in `crypto/fixtures/`.
Expand All @@ -139,6 +151,7 @@ MVP should remain verifier-attested for:
- storage provider claims
- model or worker behavior
- final status labels before proof systems exist
- 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

## Future Split

Expand Down Expand Up @@ -176,3 +189,4 @@ Searches for `Claw` and `claw` in repository issues and code returned no matchin
- Define key registry and verifier set root governance.
- Define challenge evidence and response envelopes.
- Produce a decision record before CursorRegistry or proof-carrying receipts are implemented.
- Decide when, if ever, the nearby Noesis/FlowChain RD crypto crates should receive a Keccak compatibility adapter for these V0 object IDs.
29 changes: 24 additions & 5 deletions crypto/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,24 +33,32 @@ Validate all package-level vector fixtures:
npm run validate:vectors
```

Validate the Local Alpha object and signature-envelope fixtures against the
canonical JSON Schemas:

```powershell
npm run validate:local-alpha
```

## Read Order

1. `FLOWMEMORY_CRYPTO_SPEC.md`
2. `OBSERVATION_IDENTITY.md`
3. `RECEIPT_HASHING.md`
4. `MERKLE_AND_ROOTS.md`
5. `ATTESTATIONS.md`
6. `TEST_VECTORS.md`
6. `FLOWCHAIN_LOCAL_ALPHA_OBJECTS.md`
7. `TEST_VECTORS.md`

Runnable fixtures live in `fixtures/`. `fixtures/vectors.json` contains the current 21 package-level vectors. Supporting cross-language vectors live in `test-vectors/`.
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/`.

Validate the current vector set with:

```powershell
python validate_test_vectors.py
```

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`.
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`.

## Core Vocabulary

Expand All @@ -60,10 +68,12 @@ The Python validator is a cross-check for the FlowPulse aggregate vector. The pr
- `artifactRoot`: commitment to off-chain artifact bytes and metadata.
- `reportId`: deterministic identifier for a verifier report.
- `attestation`: signed worker or verifier envelope over a receipt, report, artifact, or root.
- Local Alpha object IDs: canonical IDs for `AgentAccount`, `ModelPassport`, `WorkReceipt`, `ArtifactAvailabilityProof`, `VerifierModule`, `VerifierReport`, `MemoryCell`, `Challenge`, `FinalityReceipt`, hardware signal envelopes, and control-plane provenance responses.
- 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.

## Implemented Helpers

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.
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.

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

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

## Integration Notes

There is no `services/shared/` package in this repository yet. Until one exists, services should either:
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:

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

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.

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.

## Downstream Consumption

- 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.
- Services and verifiers should use `validateLocalAlphaEnvelope` before accepting object documents from local transactions, API calls, hardware packets, or fixture imports.
- Dashboard/workbench agents should display IDs, domains, signer roles, status labels, and validation errors from these fixtures without implying production proof security.
- 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.
Loading
Loading