Open Wallet Standard

To maintain interoperability between conforming implementations, ensure the following behaviors are consistent when exchanging artifacts:

• Wallet files: Must be parsed and validated consistently.
• API key files: Must be resolvable consistently by token hash.
• Policy files: Must produce the same allow or deny result for the same PolicyContext.
• Identifiers: Canonical chain and account identifiers must be preserved without lossy conversion.

Conforming implementations SHOULD ship or consume machine-readable test vectors for wallet encryption/decryption, API key resolution, policy evaluation, address derivation, and signing.

OWS follows a security-first architecture designed for local key custody and policy enforcement:

1. Access Layer: The caller (Agent/CLI/App) invokes a signing method.
2. Policy Engine: Before decryption, the engine evaluates pre-signing policies (e.g., for API tokens).
3. Signing Core: If authorized, keys are decrypted inside hardened in-process memory.
4. Execution: The transaction is signed.
5. Cleanup: Key material is wiped from memory immediately after use.
6. Output: The signature is returned to the caller.

Crucially, the OWS API never returns raw private keys. Keys are stored in the Wallet Vault (typically ~/.ows/wallets/).

All signing operations are recorded in an append-only JSONL file located at ~/.ows/logs/audit.jsonl. This log provides a verifiable history of wallet activity.

Log Format:

{
  "timestamp": "2026-02-27T10:35:22Z",
  "wallet_id": "3198bc9c-6672-5ab3-d995-4942343ae5b6",
  "operation": "broadcast_transaction",
  "chain_id": "eip155:8453",
  "details": "tx_hash=0xabc123..."
}

Key Properties:

• Append-only: Implementations MUST NOT allow deletion or modification of existing entries.
• Operations tracked: Includes create_wallet, import_wallet, export_wallet, broadcast_transaction, delete_wallet, and rename_wallet.
• Rotation: Log rotation (e.g., monthly archives) is permitted.

The OWS policy engine supports several declarative rule types to restrict signing requests:

• Time-limited access: Use the expires_at rule type with an ISO-8601 timestamp.
• Chain restriction: Use the allowed_chains rule type with an array of CAIP-2 chain IDs.
• EIP-712 contract restriction: Use the allowed_typed_data_contracts rule type with an array of contract addresses.

Note: When multiple policies are attached to a single key, they follow AND semantics—all policies must allow the request for it to proceed.

// Example: Chain restriction + expiry
{
  "id": "base-limits",
  "name": "Base Agent Safety Limits",
  "version": 1,
  "created_at": "2026-01-01T00:00:00Z",
  "rules": [
    { "type": "allowed_chains", "chain_ids": ["eip155:8453", "eip155:84532"] },
    { "type": "expires_at", "timestamp": "2026-12-31T23:59:59Z" }
  ],
  "action": "deny"
}

The OWS CLI manages data within the ~/.ows/ directory. Understanding this structure helps you locate your wallets, keys, and logs:

• ~/.ows/bin/ows: The CLI binary.
• ~/.ows/wallets/: Contains encrypted wallet files (<uuid>.json) using AES-256-GCM and scrypt.
• ~/.ows/policies/: Contains non-secret policy definitions (<id>.json).
• ~/.ows/keys/: Contains API key files (<uuid>.json) with restricted 0600 permissions.
• ~/.ows/logs/audit.jsonl: The audit log file in JSONL format.

The OWS security model ensures that an agent or application never sees the actual private keys. The workflow follows these steps:

1. Request: The Agent/CLI calls a signing method (e.g., ows.sign()).
2. Policy Evaluation: The Policy Engine evaluates any attached rules (e.g., chain allowlists, expiration).
3. Decryption: If allowed, the Signing Enclave (an isolated process) decrypts the key.
4. Signing: The transaction is signed within the isolated enclave.
5. Cleanup: The key is wiped from memory immediately after use.
6. Return: The signature is returned to the agent.

Components:

• Policy Engine: Pre-signing validation layer.
• Signing Enclave: Isolated process for cryptographic operations.
• Wallet Vault: Secure storage located at ~/.ows/wallets/.

OWS uses two layers of versioning: specification documents (for behavior) and schema versions (embedded in artifacts for compatibility).

Current Version Markers:

• Wallet file schema: ows_version = 2
• Policy schema: version = 1

Implementation Requirements:

• You MUST reject unknown required schema fields.
• You MUST reject schema versions that you do not understand.
• You MAY accept older schema versions if you have documented how you handle compatibility.

The upto (usage-based) settlement pattern is used for agent payments where the final cost is unknown until a task completes. This pattern allows an agent to authorize a maximum amount (a cap) before work begins, and the service settles only the actual cost upon completion.

Lifecycle of an upto payment:

1. Agent authorizes max amount: The service begins work once the cap is authorized.
2. Service completes task: The service settles the actual amount used.
3. Remaining headroom released: The wallet balance is updated to reflect the unused portion of the authorized cap.