Add FlowChain local wallet envelopes

Author: FlowmemoryAI

crypto/.gitignore

@@ -1,3 +1,6 @@
 node_modules/
 coverage/
 .nyc_output/
+.wallet/
+*.vault.local.json
+*.wallet.local.json

crypto/FLOWCHAIN_LOCAL_ALPHA_OBJECTS.md

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

crypto/FLOWMEMORY_CRYPTO_SPEC.md

@@ -110,9 +110,16 @@ artifactAvailabilityProofId
 verifierModuleId
 challengeId
 finalityReceiptId
+bridgeDepositId
+bridgeCreditId
+bridgeWithdrawalId
+localAccountBalanceId
+localSignerId
+localSignerKeyId
 hardwareSignalEnvelopeId
 controlPlaneProvenanceResponseId
 localSignatureEnvelope
+localTransactionEnvelope
 ```
 
 ## Versioning Strategy
@@ -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/`.
@@ -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
 

crypto/README.md

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

crypto/TEST_VECTORS.md

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