Skip to content

[codex] add FlowChain local wallet envelopes #115

New issue

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

Sign up for GitHub

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

Already on GitHub? Sign in to your account

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

[codex] add FlowChain local wallet envelopes #115

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
3 changes: 3 additions & 0 deletions crypto/.gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,6 @@
node_modules/
coverage/
.nyc_output/
.wallet/
*.vault.local.json
*.wallet.local.json
60 changes: 60 additions & 0 deletions crypto/FLOWCHAIN_LOCAL_ALPHA_OBJECTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -61,6 +61,10 @@ pre-hashed before entering the typed object.
| MemoryCell | `memoryCellId` | `memoryCellV0` | `memoryCellId` | `memoryCellId` |
| Challenge | `challengeId` | `challengeV0` | `challengeId` | `challengeId` |
| FinalityReceipt | `finalityReceiptId` | `finalityReceiptV0` | `finalityReceiptId` | `finalityReceiptId` |
| BridgeDeposit | `depositId` | `bridgeDepositV0` | `bridgeDepositId` | `bridgeDepositId` |
| BridgeCredit | `creditId` | `bridgeCreditV0` | `bridgeCreditId` | `bridgeCreditId` |
| BridgeWithdrawal | `withdrawalId` | `bridgeWithdrawalV0` | `bridgeWithdrawalId` | `bridgeWithdrawalId` |
| LocalAccountBalance | `balanceId` | `localAccountBalanceV0` | `localAccountBalanceId` | `localAccountBalanceId` |
| HardwareSignalEnvelope | `hardwareSignalEnvelopeId` | `hardwareSignalEnvelopeV0` | `hardwareSignalEnvelopeId` | `hardwareSignalEnvelopeId` |
| Control-plane provenance response | `provenanceResponseId` | `controlPlaneProvenanceResponseV0` | `controlPlaneProvenanceResponseId` | `controlPlaneProvenanceResponseId` |

Expand All @@ -77,6 +81,20 @@ 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.

`LocalTransactionEnvelope` uses `localTransactionEnvelopeV0` and
`localTransactionEnvelopeHash`. It signs the chain id, nonce, signer ID, signer
key ID, signer role, canonical payload hash, validity window, and transaction
domain separator. The JSON payload preserves `payload.tx` so the existing
devnet transaction model can unwrap and submit the same transaction object after
envelope validation.

`BridgeDeposit` intentionally keeps the existing
`flowmemory.bridge_deposit.v0` schema used by the bridge observer. The crypto
ID is a typed hash over the Base source chain id, source contract, tx hash,
log index, token, amount, sender, FlowChain recipient, nonce, and metadata
hash. `BridgeCredit` and `BridgeWithdrawal` are local FlowChain objects that
record no-production bridge accounting for private/local testing only.

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

Canonical object fixtures live in:
Expand All @@ -103,8 +121,14 @@ 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/bridge-deposit.schema.json
schemas/flowmemory/bridge-credit.schema.json
schemas/flowmemory/bridge-withdrawal.schema.json
schemas/flowmemory/local-account-balance.schema.json
schemas/flowmemory/hardware-signal-envelope.schema.json
schemas/flowmemory/local-signature-envelope.schema.json
schemas/flowmemory/local-transaction-envelope.schema.json
schemas/flowmemory/local-wallet-public-metadata.schema.json
schemas/flowmemory/control-plane-provenance-response.schema.json
```

Expand Down Expand Up @@ -136,6 +160,41 @@ 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.

Local transaction envelope validation additionally requires:

- `domain` and `domainSeparator` match `flowchain.local.v0.transaction-envelope`.
- the context-supplied chain id matches the envelope chain id.
- `payloadHash` recomputes from canonical JSON.
- `signerId` and `signerKeyId` derive from the public key and signer role.
- the caller supplies replay context and rejects repeated signer/domain/nonce tuples.
- object documents embedded under `payload.object` pass the same object ID and root checks.
- the secp256k1 signature verifies against the transaction signing digest.

The transaction vectors cover wrong chain id, wrong domain, wrong signer,
replayed nonce, malformed roots, malformed bridge deposit, and changed object
type.

## Local Wallet Boundary

`crypto/src/wallet.js` provides an encrypted local vault for no-value test keys.
It supports create, unlock, list public accounts, sign transaction, verify
transaction, public metadata import/export, and rotate/create additional
accounts. The vault uses scrypt plus AES-256-GCM and stores private keys only in
the encrypted blob. The export shape is
`flowchain.local_wallet_public_metadata.v0`, which contains public account IDs,
signer IDs, key IDs, roles, public keys, labels, and nonces only.

The CLI entry point is `crypto/src/wallet-cli.js` and is exposed through:

```powershell
npm run wallet:create --prefix crypto
npm run wallet:sign --prefix crypto
npm run wallet:verify --prefix crypto
```

Set `FLOWCHAIN_WALLET_PASSWORD` for non-interactive use. The default vault path
is `crypto/.wallet/flowchain-wallet.local.json`, which is ignored by git.

## Consumer Rules

Chain/devnet:
Expand Down Expand Up @@ -178,6 +237,7 @@ V0 also proves:
- 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;
- local wallet-signed transaction envelope verification without exposing private keys;
- duplicate ID detection in fixture validation;
- explicit finality and challenge state labels for local/test consumers.

Expand Down
13 changes: 11 additions & 2 deletions crypto/FLOWMEMORY_CRYPTO_SPEC.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -110,9 +110,16 @@ artifactAvailabilityProofId
verifierModuleId
challengeId
finalityReceiptId
bridgeDepositId
bridgeCreditId
bridgeWithdrawalId
localAccountBalanceId
localSignerId
localSignerKeyId
hardwareSignalEnvelopeId
controlPlaneProvenanceResponseId
localSignatureEnvelope
localTransactionEnvelope
```

## Versioning Strategy
Expand All @@ -138,8 +145,10 @@ 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
- FlowChain Local Alpha object identity for agent accounts, model passports, work receipts, artifact availability proofs, verifier modules, verifier reports, memory cells, challenges, finality receipts, bridge deposits, bridge credits, bridge withdrawals, local account balances, 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
- local transaction envelopes that bind domain, chain id, nonce, signer, payload hash, validity window, and signature while preserving `payload.tx` for devnet consumers
- encrypted local wallet/vault helpers for no-value test keys with public metadata import/export and rotation
- 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 @@ -151,7 +160,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
- local operator-vault policy; current fixture keys and local wallet keys are deterministic or generated no-value test keys and do not represent production wallet custody, production account control, or transferable value

## Future Split

Expand Down
24 changes: 21 additions & 3 deletions crypto/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,20 @@ canonical JSON Schemas:
npm run validate:local-alpha
```

Create and use a local encrypted no-value wallet vault:

```powershell
$env:FLOWCHAIN_WALLET_PASSWORD = "replace-with-local-test-password"
npm run wallet:create
npm run wallet:sign
npm run wallet:verify
```

The default vault and generated envelopes live under `crypto/.wallet/`, which is
ignored by git. Use `wallet:list`, `wallet:unlock`, `wallet:rotate`,
`wallet:export-public`, and `wallet:import-public` for public account metadata
and additional local accounts.

## Read Order

1. `FLOWMEMORY_CRYPTO_SPEC.md`
Expand All @@ -50,7 +64,7 @@ npm run validate:local-alpha
6. `FLOWCHAIN_LOCAL_ALPHA_OBJECTS.md`
7. `TEST_VECTORS.md`

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/`.
Runnable fixtures live in `fixtures/`. `fixtures/vectors.json` contains the current 41 package-level vectors. `fixtures/local-alpha-objects.json` contains positive and negative Local Alpha object and signed-envelope fixtures. `fixtures/local-transaction-vectors.json` contains wallet-signed local transaction envelopes and negative transaction vectors. Supporting cross-language vectors live in `test-vectors/`.

Validate the current vector set with:

Expand All @@ -68,12 +82,14 @@ 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 object IDs: canonical IDs for `AgentAccount`, `ModelPassport`, `WorkReceipt`, `ArtifactAvailabilityProof`, `VerifierModule`, `VerifierReport`, `MemoryCell`, `Challenge`, `FinalityReceipt`, `BridgeDeposit`, `BridgeCredit`, `BridgeWithdrawal`, local account balances, 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.
- Local transaction envelopes: wallet-signed wrappers that bind domain separation, chain id, nonce, signer, payload hash, validity window, and signature while preserving `payload.tx` for devnet/control-plane consumers.
- Local wallet vault: AES-256-GCM encrypted local test-key storage with public metadata export. It is not a production wallet or custody system.

## 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, 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 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, bridge/account-balance ids, hardware signal envelope ids, Local Alpha signature envelope payloads, local transaction envelope payloads, wallet vault helpers, 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 @@ -99,6 +115,8 @@ Nearby Noesis/FlowChain RD crates under `E:\FlowMemory\github-research-sources\n
## 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.
- Chain/devnet agents can consume wallet-signed transaction envelopes by validating the envelope and then reading the existing devnet transaction object at `payload.tx`.
- Services and verifiers should use `validateLocalAlphaEnvelope` before accepting object documents from local transactions, API calls, hardware packets, or fixture imports.
- Control-plane agents should display only `flowchain.local_wallet_public_metadata.v0` account metadata and never vault ciphertext or private keys.
- 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.
19 changes: 13 additions & 6 deletions crypto/TEST_VECTORS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,15 +2,18 @@

Status: draft v0.

The test vectors are synthetic and contain no production secrets or signatures.
The test vectors are synthetic and contain no production secrets. Signatures are
no-value local/test signatures with public keys only; private keys are not
committed in fixtures or public exports.

## Vector Files

- `fixtures/sample-flowpulse.json`: FlowPulse event args and expected `pulseId` / `eventArgsHash`.
- `fixtures/sample-observation.json`: observation metadata, artifact/storage inputs, and expected `observationId` / `receiptHash`.
- `fixtures/sample-report.json`: verifier report, worker signature payload, verifier signature payload, and attestation envelope expectations.
- `fixtures/local-alpha-objects.json`: positive and negative fixtures for FlowChain Local Alpha object identity, signed-envelope validation, and schema validation.
- `fixtures/vectors.json`: 33 package-level vectors for domains, canonical JSON, observation ids, receipts, artifacts, Merkle roots, reports, attestations, cursors, identities, root commitments, work receipts, devnet block hashes, Local Alpha object ids, hardware signal envelopes, and local signature envelopes.
- `fixtures/local-transaction-vectors.json`: wallet-signed local transaction envelopes, public wallet metadata, and negative vectors for chain id, domain, signer, nonce replay, malformed roots, malformed bridge deposits, and changed object type.
- `fixtures/vectors.json`: 41 package-level vectors for domains, canonical JSON, observation ids, receipts, artifacts, Merkle roots, reports, attestations, cursors, identities, root commitments, work receipts, devnet block hashes, Local Alpha object ids, bridge/account objects, signer IDs, local transaction payloads, hardware signal envelopes, and local signature envelopes.
- `test-vectors/flowpulse-observation-v0.json`: FlowPulse-specific observation, receipt, artifact, report, worker signature digest, and verifier signature digest.

## FlowPulse Observation Vector Highlights
Expand Down Expand Up @@ -50,8 +53,9 @@ An implementation should reproduce:
- Merkle root and artifact root
- deterministic verifier report id
- EIP-712 signing digests without requiring test private keys
- Local Alpha object IDs for AgentAccount, ModelPassport, WorkReceipt, ArtifactAvailabilityProof, VerifierModule, VerifierReport, MemoryCell, Challenge, FinalityReceipt, hardware signal envelopes, and control-plane provenance responses
- Local Alpha object IDs for AgentAccount, ModelPassport, WorkReceipt, ArtifactAvailabilityProof, VerifierModule, VerifierReport, MemoryCell, Challenge, FinalityReceipt, BridgeDeposit, BridgeCredit, BridgeWithdrawal, local account balance, hardware signal envelopes, and control-plane provenance responses
- Local Alpha signature envelope IDs and signing digests for local operator, agent, verifier, and hardware no-value test keys
- Local transaction envelope IDs, payload hashes, signing digests, and public signer metadata

Run the package test suite:

Expand All @@ -69,7 +73,7 @@ npm run validate:vectors
Expected output:

```text
FLOWMEMORY_CRYPTO_VECTORS_OK 33
FLOWMEMORY_CRYPTO_VECTORS_OK vectors=41 localTransactionPositive=2 localTransactionNegative=7
```

Validate the Local Alpha object documents and signature envelopes against the
Expand All @@ -82,7 +86,7 @@ npm run validate:local-alpha
Expected output:

```text
FLOWCHAIN_LOCAL_ALPHA_FIXTURES_OK documents=11 envelopes=11 schemas=12
FLOWCHAIN_LOCAL_ALPHA_FIXTURES_OK documents=15 envelopes=11 schemas=16
```

Print the sample vector summary:
Expand Down Expand Up @@ -116,11 +120,14 @@ FLOWPULSE_VECTOR_RECOMPUTE_OK
- duplicate Local Alpha object IDs should be rejected by fixture validation
- canonical JSON key order should not change the control-plane provenance response body hash
- replayed Local Alpha signer/domain/sequence tuples should be rejected
- replayed local transaction signer/domain/nonce tuples should be rejected
- wrong local transaction chain id, domain, and signer should be rejected
- malformed bridge deposits inside local transaction payloads should be rejected
- wrong signature domains should be rejected
- missing local operator/agent/verifier/hardware signer fields should be rejected
- each Local Alpha object envelope has a bad-signature invalid vector
- zero critical hashes, malformed object IDs, malformed dependency roots, bad parent/root relationships, and wrong object types should be rejected
- expired worker signature should be rejected by verifier policy
- reorged observation should not mutate into a verified report

The package tests cover the hash, schema, malformed hex, duplicate, type-string, canonical JSON, signed-envelope, replay, wrong-domain, missing-signer, bad-signature, zero-hash, malformed-dependency, bad-parent/root, and wrong-object-type checks. Expiry and reorg-to-report policy are verifier-service responsibilities because they require policy context, not just hash recomputation.
The package tests cover the hash, schema, malformed hex, duplicate, type-string, canonical JSON, signed-envelope, transaction-envelope, wallet public-metadata, replay, wrong-chain-id, wrong-domain, wrong-signer, missing-signer, bad-signature, zero-hash, malformed-dependency, malformed-root, malformed bridge-deposit, bad-parent/root, and wrong-object-type checks. Expiry and reorg-to-report policy are verifier-service responsibilities because they require policy context, not just hash recomputation.
Loading
Loading