Skip to content

[real-value/wallet] add pilot proof command #143

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 14, 2026
Merged

[real-value/wallet] add pilot proof command #143

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
21 changes: 21 additions & 0 deletions crypto/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,27 @@ The wallet commands are for local/private testnet smoke use only. Public exports
contain signer metadata and public keys; private keys, mnemonics, seed material,
and ciphertext are not exported as public metadata.

Run the capped real-value pilot wallet/operator E2E:

```powershell
npm run wallet:pilot-e2e
```

Pilot helper commands:

```powershell
npm run wallet:pilot-config -- --out ..\devnet\local\pilot-wallet\operator-config.local.json
npm run wallet:pilot-metadata -- --config ..\devnet\local\pilot-wallet\operator-config.local.json --vault ..\devnet\local\pilot-wallet\operator-vault.json
npm run wallet:pilot-sign -- --config ..\devnet\local\pilot-wallet\operator-config.local.json --vault ..\devnet\local\pilot-wallet\operator-vault.json --document .\fixtures\pilot-release-evidence.json --nonce 1
npm run wallet:pilot-verify -- --config ..\devnet\local\pilot-wallet\operator-config.local.json --document .\fixtures\pilot-release-evidence.json --envelope .\out\pilot-release-envelope.json
npm run wallet:pilot-next -- --config ..\devnet\local\pilot-wallet\operator-config.local.json
```

The pilot commands stay command-line only. Runtime and control-plane consumers
that only need public verification can import
`@flowmemory/crypto/pilot-envelope-validation`; that subpath does not import
encrypted vault creation, unlock, or signing helpers.

## Read Order

1. `FLOWMEMORY_CRYPTO_SPEC.md`
Expand Down
12 changes: 11 additions & 1 deletion crypto/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,10 @@
".": {
"types": "./src/index.d.ts",
"default": "./src/index.js"
},
"./pilot-envelope-validation": {
"types": "./src/pilot-envelope-validation.d.ts",
"default": "./src/pilot-envelope-validation.js"
}
},
"scripts": {
Expand All @@ -26,7 +30,13 @@
"wallet:add-account": "node src/wallet-cli.js add-account",
"wallet:rotate": "node src/wallet-cli.js rotate",
"wallet:sign": "node src/wallet-cli.js sign",
"wallet:verify": "node src/wallet-cli.js verify"
"wallet:verify": "node src/wallet-cli.js verify",
"wallet:pilot-config": "node src/pilot-wallet-cli.js config-from-env",
"wallet:pilot-metadata": "node src/pilot-wallet-cli.js metadata",
"wallet:pilot-sign": "node src/pilot-wallet-cli.js sign",
"wallet:pilot-verify": "node src/pilot-wallet-cli.js verify",
"wallet:pilot-next": "node src/pilot-wallet-cli.js next-commands",
"wallet:pilot-e2e": "node src/pilot-wallet-e2e.js"
},
"dependencies": {
"@noble/hashes": "2.2.0",
Expand Down
15 changes: 15 additions & 0 deletions crypto/src/constants.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -79,6 +79,16 @@ export const TYPE_STRINGS = Object.freeze({
"FlowChainProductBridgeCreditAckV0(bytes32 creditId,bytes32 depositId,bytes32 accountId,bytes32 assetId,uint256 amount,uint64 acknowledgedAtBlockNumber,uint64 accountNonce)",
bridgeWithdrawalIntentV0:
"FlowChainBridgeWithdrawalIntentV0(bytes32 creditId,bytes32 depositId,uint256 sourceChainId,uint256 destinationChainId,address token,uint256 amount,bytes32 flowchainAccount,address baseRecipient,bytes32 statusHash,bytes32 requestedAtHash,uint8 testMode,uint8 broadcast,bytes32 releasePolicyHash,uint8 productionReady)",
pilotCapV0:
"FlowChainPilotCapV0(bytes32 capId,bytes32 assetId,uint256 maxAmount,uint256 usedAmount,bytes32 unitHash,uint64 windowStartsAtUnixMs,uint64 windowEndsAtUnixMs,uint8 realValuePilot,uint8 productionReady)",
pilotBridgeCreditAckV0:
"FlowChainPilotBridgeCreditAckV0(uint256 chainId,address contractAddress,bytes32 operatorId,bytes32 creditId,bytes32 depositId,bytes32 accountId,bytes32 assetId,uint256 amount,uint64 acknowledgedAtBlockNumber,uint64 accountNonce,uint64 issuedAtUnixMs,uint64 expiresAtUnixMs,bytes32 capHash)",
pilotWithdrawalIntentV0:
"FlowChainPilotWithdrawalIntentV0(uint256 sourceChainId,uint256 destinationChainId,address contractAddress,bytes32 operatorId,bytes32 creditId,bytes32 depositId,address token,uint256 amount,bytes32 flowchainAccount,address baseRecipient,bytes32 statusHash,bytes32 requestedAtHash,uint64 accountNonce,uint64 issuedAtUnixMs,uint64 expiresAtUnixMs,bytes32 capHash)",
pilotReleaseEvidenceV0:
"FlowChainPilotReleaseEvidenceV0(uint256 chainId,address contractAddress,bytes32 operatorId,bytes32 withdrawalIntentId,bytes32 releaseTxHash,uint32 releaseLogIndex,address token,uint256 amount,address recipient,uint64 releasedAtBlockNumber,uint64 releasedAtUnixMs,bytes32 evidenceHash,uint64 issuedAtUnixMs,uint64 expiresAtUnixMs,bytes32 capHash)",
pilotEmergencyControlV0:
"FlowChainPilotEmergencyControlV0(uint256 chainId,address contractAddress,bytes32 operatorId,bytes32 actionHash,bytes32 targetSignerId,bytes32 reasonHash,uint64 issuedAtUnixMs,uint64 expiresAtUnixMs,bytes32 nonce,bytes32 capHash)",
hardwareSignalEnvelopeV0:
"FlowChainHardwareSignalEnvelopeV0(bytes32 deviceId,bytes32 signalRoot,bytes32 previousSignalEnvelopeId,bytes32 channelRoot,uint64 sequence,uint64 observedAtUnixMs,uint8 transport,bytes32 nonce)",
controlPlaneProvenanceResponseV0:
Expand Down Expand Up @@ -124,6 +134,11 @@ export const DOMAIN_STRINGS = Object.freeze({
productSwapId: "flowchain.product-testnet.v1.swap.id",
productBridgeCreditAckId: "flowchain.product-testnet.v1.bridge-credit-ack.id",
bridgeWithdrawalIntentId: "flowchain.product-testnet.v1.bridge-withdrawal-intent.id",
pilotCapId: "flowchain.real-value-pilot.v0.cap.id",
pilotBridgeCreditAckId: "flowchain.real-value-pilot.v0.bridge-credit-ack.id",
pilotWithdrawalIntentId: "flowchain.real-value-pilot.v0.withdrawal-intent.id",
pilotReleaseEvidenceId: "flowchain.real-value-pilot.v0.release-evidence.id",
pilotEmergencyControlId: "flowchain.real-value-pilot.v0.emergency-control.id",
hardwareSignalEnvelopeId: "flowchain.local-alpha.v0.hardware-signal-envelope.id",
controlPlaneProvenanceResponseId: "flowchain.local-alpha.v0.control-plane-provenance-response.id",
localSignatureEnvelope: "flowchain.local-alpha.v0.local-signature-envelope",
Expand Down
115 changes: 115 additions & 0 deletions crypto/src/index.d.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -405,6 +405,84 @@ export interface BridgeWithdrawalIntentInput {
productionReady: boolean;
}

export interface PilotCapInput {
capId: Bytes32;
assetId: Bytes32;
maxAmount: number | bigint | string;
usedAmount: number | bigint | string;
unit: string;
windowStartsAtUnixMs: number | bigint | string;
windowEndsAtUnixMs: number | bigint | string;
realValuePilot: boolean;
productionReady: boolean;
}

export interface PilotBridgeCreditAckInput {
chainId: number | bigint | string;
contractAddress: Address;
operatorId: Bytes32;
creditId: Bytes32;
depositId: Bytes32;
accountId: Bytes32;
assetId: Bytes32;
amount: number | bigint | string;
acknowledgedAtBlockNumber: number | bigint | string;
accountNonce: number | bigint | string;
issuedAtUnixMs: number | bigint | string;
expiresAtUnixMs: number | bigint | string;
pilotCap: PilotCapInput;
}

export interface PilotWithdrawalIntentInput {
sourceChainId: number | bigint | string;
destinationChainId: number | bigint | string;
contractAddress: Address;
operatorId: Bytes32;
creditId: Bytes32;
depositId: Bytes32;
token: Address;
amount: number | bigint | string;
flowchainAccount: Bytes32;
baseRecipient: Address;
status: string;
requestedAt: string;
accountNonce: number | bigint | string;
issuedAtUnixMs: number | bigint | string;
expiresAtUnixMs: number | bigint | string;
pilotCap: PilotCapInput;
}

export interface PilotReleaseEvidenceInput {
chainId: number | bigint | string;
contractAddress: Address;
operatorId: Bytes32;
withdrawalIntentId: Bytes32;
releaseTxHash: Bytes32;
releaseLogIndex: number | bigint | string;
token: Address;
amount: number | bigint | string;
recipient: Address;
releasedAtBlockNumber: number | bigint | string;
releasedAtUnixMs: number | bigint | string;
evidenceHash: Bytes32;
issuedAtUnixMs: number | bigint | string;
expiresAtUnixMs: number | bigint | string;
pilotCap: PilotCapInput;
}

export interface PilotEmergencyControlInput {
chainId: number | bigint | string;
contractAddress: Address;
operatorId: Bytes32;
action: string;
targetSignerId: Bytes32;
reasonHash: Bytes32;
issuedAtUnixMs: number | bigint | string;
expiresAtUnixMs: number | bigint | string;
nonce: Bytes32;
pilotCap: PilotCapInput;
}

export interface ControlPlaneProvenanceResponseInput {
requestId: Bytes32;
subjectId: Bytes32;
Expand Down Expand Up @@ -588,6 +666,11 @@ export function productRemoveLiquidityId(input: ProductRemoveLiquidityInput): By
export function productSwapId(input: ProductSwapInput): Bytes32;
export function productBridgeCreditAckId(input: ProductBridgeCreditAckInput): Bytes32;
export function bridgeWithdrawalIntentId(input: BridgeWithdrawalIntentInput): Bytes32;
export function pilotCapHash(input: PilotCapInput): Bytes32;
export function pilotBridgeCreditAckId(input: PilotBridgeCreditAckInput): Bytes32;
export function pilotWithdrawalIntentId(input: PilotWithdrawalIntentInput): Bytes32;
export function pilotReleaseEvidenceId(input: PilotReleaseEvidenceInput): Bytes32;
export function pilotEmergencyControlId(input: PilotEmergencyControlInput): Bytes32;
export function hardwareSignalEnvelopeId(input: HardwareSignalEnvelopeInput): Bytes32;
export function controlPlaneProvenanceResponseId(input: ControlPlaneProvenanceResponseInput): Bytes32;
export function localSignatureEnvelopeHash(input: LocalSignatureEnvelopeInput): Bytes32;
Expand Down Expand Up @@ -676,3 +759,35 @@ export function verifyLocalTransactionSignature(input: {
envelope: Record<string, unknown>;
context?: Record<string, unknown>;
}): LocalAlphaEnvelopeValidationResult;

export const PILOT_MESSAGE_SCHEMAS: readonly string[];
export function validatePilotOperatorEnvelope(input: {
document: Record<string, unknown>;
envelope: Record<string, unknown>;
context?: {
chainId?: number | bigint | string;
expectedChainId?: number | bigint | string;
expectedDestinationChainId?: number | bigint | string;
expectedContractAddress?: string;
expectedOperatorId?: Bytes32;
expectedNonce?: number | bigint | string;
expectedSignerId?: Bytes32;
seenNonces?: Set<string>;
nowUnixMs?: number | bigint | string;
};
}): LocalAlphaEnvelopeValidationResult;
export function pilotEnvelopeReplayKey(envelope: Record<string, unknown>): string;
export function assertPublicPilotMetadataContainsNoSecrets(value: unknown): void;
export function createPilotOperatorConfigFromEnv(input?: {
env?: Record<string, string | undefined>;
createdAtUnixMs?: number | bigint | string;
}): Record<string, unknown>;
export function buildPilotNextCommands(config: Record<string, unknown>): string[];
export function exportPilotPublicMetadata(input: {
config: Record<string, unknown>;
walletMetadata: Record<string, unknown>;
}): Record<string, unknown>;
export function buildPilotBridgeCreditAckDocument(input: PilotBridgeCreditAckInput): Record<string, unknown>;
export function buildPilotWithdrawalIntentDocument(input: PilotWithdrawalIntentInput): Record<string, unknown>;
export function buildPilotReleaseEvidenceDocument(input: PilotReleaseEvidenceInput): Record<string, unknown>;
export function buildPilotEmergencyControlDocument(input: PilotEmergencyControlInput): Record<string, unknown>;
2 changes: 2 additions & 0 deletions crypto/src/index.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,5 +6,7 @@ export * from "./flowpulse.js";
export * from "./hashes.js";
export * from "./merkle.js";
export * from "./objects.js";
export * from "./pilot-envelope-validation.js";
export * from "./pilot-operator.js";
export * from "./transactions.js";
export * from "./wallet.js";
Loading
Loading