# Vaultfire Key Protocol (VKP) — Architecture

## Problem

Every AI agent framework requires a private key to sign on-chain transactions.
That key is typically stored in plaintext in environment variables, config files,
or passed directly to LLMs. One prompt injection, one leaked log, one careless
output, and the key is compromised — funds are gone.

## Solution

VKP is encrypted key delegation tied to on-chain identity. Like XMTP is for
messages, VKP is for keys. It enables agents to:

1. **Protect their own keys** with on-chain spending policies
2. **Delegate scoped signing authority** to other verified agents
3. **Auto-revoke** if trust conditions change (bond slashed, reputation drops)
4. **Never expose raw keys** — everything is encrypted to ERC-8004 identities

## Architecture

### Layer 1: KeyVault (Smart Contract)

The KeyVault is a smart contract wallet wrapper that enforces policies on-chain.
Any agent can wrap their wallet in a KeyVault to get:

- **Spending limits**: Per-tx, hourly, daily caps (no prompt injection can override)
- **Contract allowlists**: Only interact with approved contract addresses
- **Emergency freeze**: Auto-freezes if spending exceeds threshold
- **Time locks**: Require delay before large transfers execute

```
Agent Key → KeyVault Contract → Policy Check → Execute or Reject
```

The KeyVault is owned by the agent's ERC-8004 identity. Only registered,
bonded agents can create one.

### Layer 2: SessionKeyManager (Smart Contract)

Session keys are time-limited, permission-scoped signing keys that an agent
can create for specific tasks. They expire automatically.

- **Scoped permissions**: Which contracts, which functions, what value limits
- **Time-bounded**: Expires after N minutes/hours/days
- **Revocable**: Owner can revoke any session key instantly
- **Auditable**: All session key usage is logged on-chain

```
Agent creates session key → Scoped to specific task → Auto-expires
```

### Layer 3: DelegationRegistry (Smart Contract)

This is the "XMTP for keys" layer. Agents can delegate signing authority
to other verified agents, encrypted to their identity.

- **Identity-gated**: Only delegate to ERC-8004 registered agents
- **Bond-gated**: Require minimum bond amount before delegation
- **Reputation-gated**: Require minimum reputation score
- **Encrypted handoff**: Delegation details encrypted to recipient's identity
- **On-chain audit trail**: Who delegated what, to whom, when, with what limits

```
Agent A → Creates delegation → Encrypted to Agent B's identity
Agent B → Accepts delegation → Executes within scoped limits
        → Exceeds limits    → Bond slashed, delegation revoked
```

### SDK (Python)

Clean Python SDK that wraps all three layers:

```python
from vkp import VaultfireKeyProtocol

vkp = VaultfireKeyProtocol(provider_url, identity_address)

# Protect your own key
vault = vkp.create_keyvault(
    spending_limit_daily="1.0",    # 1 ETH/day max
    allowed_contracts=["0x..."],    # Only these contracts
    emergency_threshold="0.5",      # Freeze at 50% balance
)

# Create a session key for a specific task
session = vkp.create_session_key(
    allowed_contracts=["0xUniswap"],
    max_value="0.1",
    expires_in_hours=24,
)

# Delegate to another verified agent
delegation = vkp.delegate(
    to_agent="0xAgentB",
    min_bond="0.01",
    min_reputation=50,
    max_value="0.5",
    expires_in_hours=48,
)

# Emergency revoke
vkp.revoke_all()
```

## Security Model

1. **Raw keys never leave the owner** — VKP wraps keys, doesn't store them
2. **On-chain policy enforcement** — No client-side check can be bypassed
3. **Identity-bound** — All operations require ERC-8004 registration
4. **Bond-backed** — Delegates must have skin in the game
5. **Auto-expiry** — All delegations and sessions expire by default
6. **Emergency stop** — One-call revocation of everything

## Integration with Vaultfire

VKP builds directly on top of the existing Vaultfire Protocol:

- Identity Registry → Who can create vaults and receive delegations
- Accountability Bonds → Minimum bond requirements for delegation
- Partnership Bonds → Mutual trust for bidirectional delegation
- Reputation Registry → Score thresholds for receiving delegations
- VNS → Resolve agent names to delegation endpoints
