How It Works

Setting Up Your Identity

When you run vouch init, four things happen in order:

Step 1: Generate a wallet

A random private key is created (secp256k1 curve — same as Ethereum/Bitcoin). This derives your wallet address. The key is encrypted with AES-256-GCM and saved to disk.

Step 2: Save config

A config file is written to ~/.vouch/config.toml with your wallet address, network settings, and contract addresses.

Step 3: Link your identity

During init, you link your X account via OAuth. A trusted oracle verifies you own the account and signs an attestation. That attestation is submitted to the VouchHub smart contract on-chain (gasless — a relay pays the gas). After init, you can link additional identity providers with vouch link-github or vouch link-dns.

Step 4: Delegate a runtime key

A second private key is generated — the “runtime key.” Your wallet key signs a transaction authorizing this runtime key to sign on your behalf for 24 hours. This delegation is recorded on-chain, optionally with a scope restriction.

After init, you have two keys: your identity key (the boss) and your runtime key (the worker that expires).

Multi-Provider Identity

Vouch supports three identity providers. Each is independently verified and recorded on-chain. A single wallet can link multiple providers simultaneously — an agent identified by both GitHub and DNS is more trustworthy than one with a single provider.

On-chain, each identity is stored as a provider type (1=X, 2=GitHub, 4=DNS) and a providerId (the keccak256 hash of the raw identifier). The human-readable label (e.g., “alice” for GitHub, “stripe.com” for DNS) is stored on-chain in the VouchHub contract.

Verification passes if the wallet has any active identity — the system checks all linked providers, not just one.

Where Keys Are Stored

~/.vouch/
├── config.toml              # Settings (wallet address, network, providers)
└── keys/
    ├── 0x<wallet>.json      # Identity key (role: "identity")
    └── 0x<runtime>.json     # Runtime key (role: "runtime")

Each key file contains the address, encrypted private key (AES-256-GCM), a random salt, a nonce, and the key’s role. File permissions are set to 0600 (only you can read).

How Messages Are Signed

When your agent calls vouch sign:

1. Load and decrypt the runtime key from disk
2. Hash the payload: payloadHash = keccak256(canonical_json(message))
3. Build an envelope with metadata — agent_id, signer, timestamp, expiry, nonce, scope, payload_hash
4. Sign using EIP-712 (Ethereum typed structured data standard) with the runtime key
5. Output JSON with the envelope + signature + original payload

{
  "envelope": {
    "v": 1,
    "agent_id": "0x...",
    "signer": "0x...",
    "ts": 1234567890,
    "exp": 1234571490,
    "nonce": "0x...",
    "scope": "0x0000...0000",
    "payload_hash": "0x...",
    "sig": "0x..."
  },
  "payload": { "your": "message" }
}

The scope field is a bytes32 value. 0x0000...0000 (zero scope) means unrestricted. A non-zero value is the keccak256 hash of the scope string (e.g., keccak256("messaging")). See Scope Enforcement for matching rules and practical examples.

How Messages Are Verified

Anyone who receives a signed envelope can verify it. The verification runs these checks:

1. Not expired — current time ≤ expiry
2. Reasonable timestamp — not more than 5 min off (clock skew)
3. Nonce not reused — prevents replay attacks
4. Payload hash matches — re-hash the payload and compare
5. Decode fields — parse hex nonce, hash, signature
6. Rebuild EIP-712 structure — reconstruct what was signed (including scope)
7. Recover the signer — mathematically recover the public key from the signature
8. Recovered address matches claimed signer
9. Check delegation on-chain — query the VouchHub contract via RPC to confirm the delegation, identity (any active provider), and scope match
10. Track the nonce — remember it for 5 min to block replays

If all checks pass, the message is verified and trusted. The result includes all linked identities (X handle, GitHub username, domain, etc.) so the recipient knows exactly who sent it.

Agent-to-Agent Channels

Vouch provides a standard protocol for agents to exchange verified messages directly. A sender POSTs a signed envelope to the receiver’s endpoint, the receiver verifies it, and responds with accepted/rejected.

See Agent Commands for scaffolding, running, and deploying agents, or the CLI Reference for the full send, receive, and publish command details.

Component Map

Key Concepts