Protocol Specification

Technical specification for ClawFi's authorization protocol, smart contract interfaces, and cryptographic primitives.

---

Overview

ClawFi implements a three-layer authorization protocol enabling autonomous agents to execute financial operations with cryptographically enforced spending policies. This specification defines the protocol interfaces, message formats, and security guarantees.

Protocol Version: 1.0.0 Status: Production Last Updated: March 2026

---

Protocol Layers

┌──────────────────────────────────────────────────────────┐
│  Layer 3: Agent Interface (MCP)                          │
│  - Natural language parsing                              │
│  - Command structuring                                   │
│  - Response formatting                                   │
└────────────────────┬─────────────────────────────────────┘
                     │ Authorization Request
┌────────────────────▼─────────────────────────────────────┐
│  Layer 2: Policy Evaluation                              │
│  - Merchant verification                                 │
│  - Velocity control validation                           │
│  - Multi-party approval coordination                     │
│  - ZK-proof verification                                 │
└────────────────────┬─────────────────────────────────────┘
                     │ Authorization Proof
┌────────────────────▼─────────────────────────────────────┐
│  Layer 1: On-Chain Execution                             │
│  - Signature verification                                │
│  - Policy enforcement                                    │
│  - Asset transfer                                        │
│  - Event emission                                        │
└──────────────────────────────────────────────────────────┘

---

Cryptographic Primitives

Signature Schemes

Agent Authentication:

• Algorithm: Ed25519

• Key size: 256 bits

• Signature size: 64 bytes

• Purpose: Agent identity and command authorization

Multi-Party Approval:

• Algorithm: Schnorr threshold signatures

• Threshold: Configurable N-of-M

• Aggregation: Non-interactive signature aggregation

• Purpose: Coordinated multi-agent authorization

Zero-Knowledge Proofs:

• System: Groth16 on BN254 curve

• Circuit: Policy compliance verification

• Proof size: 128 bytes

• Purpose: Privacy-preserving authorization

Hash Functions

Transaction Commitment:

• Algorithm: SHA-256

• Output: 32 bytes

• Purpose: Transaction integrity verification

Merkle Trees:

• Algorithm: Keccak-256

• Purpose: Policy state commitment

---

Authorization Protocol

Transaction Authorization Flow

Agent                 Auth Engine          Solana Program
  │                        │                      │
  │─────Request Auth──────>│                      │
  │  (tx details)          │                      │
  │                        │                      │
  │                        │───Evaluate Policies──│
  │                        │   (merchant, velocity,│
  │                        │    balance, approval) │
  │                        │                      │
  │<────Auth Proof────────│                      │
  │  (signature + metadata)│                      │
  │                        │                      │
  │─────Execute TX────────────────────────────>│
  │  (proof + signature)   │                   │
  │                        │                   │
  │                        │<──Verify Proof───│
  │                        │                   │
  │                        │──Execute Transfer─>│
  │                        │                   │
  │<──────────TX Hash + Receipt───────────────│
  │                        │                   │

Authorization Request Message

interface AuthorizationRequest {
  version: '1.0.0';
  timestamp: number;
  agentKey: PublicKey;       // Agent's Ed25519 public key
  vaultId: string;           // Target vault identifier

  transaction: {
    type: 'transfer' | 'withdraw' | 'internal_transfer';
    recipient: string;       // Address or merchant identifier
    amount: number;          // Amount in base units
    currency: string;        // 'USDC', 'SOL', etc.
    memo?: string;          // Optional transaction memo
  };

  signature: string;         // Sign(agentKey, hash(request))
}

Authorization Response

interface AuthorizationResponse {
  status: 'approved' | 'denied' | 'requires_approval';
  requestId: string;
  timestamp: number;

  proof?: {
    signature: string;       // Authorization signature
    policies: PolicyResult[]; // Evaluated policies
    expiresAt: number;       // Proof validity timestamp
    nonce: string;          // Replay attack prevention
  };

  denial?: {
    reason: DenialReason;
    policyViolated: string;
    suggestedAction: string;
  };

  approval?: {
    proposalId: string;
    threshold: { required: number; current: number };
    expiresAt: number;
  };
}

---

Smart Contract Interface

Vault Contract

Program ID: VauLTxxx... (mainnet)

Initialize Vault

pub fn initialize_vault(
    ctx: Context<InitializeVault>,
    config: VaultConfig,
) -> Result<()>

pub struct VaultConfig {
    pub authority: Pubkey,
    pub approval_threshold: u8,
    pub authorized_agents: Vec<Pubkey>,
    pub daily_limit: u64,
    pub monthly_limit: u64,
}

Execute Transfer

pub fn execute_transfer(
    ctx: Context<ExecuteTransfer>,
    params: TransferParams,
    proof: AuthorizationProof,
) -> Result<()>

pub struct TransferParams {
    pub recipient: Pubkey,
    pub amount: u64,
    pub currency: Pubkey,  // SPL token mint
    pub memo: Option<String>,
}

pub struct AuthorizationProof {
    pub signature: [u8; 64],
    pub policies_hash: [u8; 32],
    pub nonce: [u8; 32],
    pub expires_at: i64,
}

Authorization Engine Contract

Program ID: AuTHxxx... (mainnet)

Register Policy

pub fn register_policy(
    ctx: Context<RegisterPolicy>,
    policy: Policy,
) -> Result<()>

pub enum Policy {
    MerchantWhitelist {
        merchants: Vec<MerchantEntry>,
        default_action: Action,
    },
    VelocityControl {
        windows: Vec<VelocityWindow>,
    },
    ApprovalThreshold {
        threshold: u8,
        agents: Vec<Pubkey>,
    },
}

Validate Authorization

pub fn validate_authorization(
    ctx: Context<ValidateAuthorization>,
    request: AuthorizationRequest,
    proof: AuthorizationProof,
) -> Result<ValidationResult>

pub struct ValidationResult {
    pub valid: bool,
    pub policies_evaluated: Vec<PolicyEvaluation>,
    pub timestamp: i64,
}

---

Policy Specification Language

Merchant Whitelist Policy

type: merchant_whitelist
version: 1.0.0

merchants:
  - domain: vercel.com
    verification: domain_ownership
    max_amount: 5000
    categories: [cloud_services, hosting]

  - domain: anthropic.com
    verification: signature
    public_key: "0x..."
    max_amount: 10000
    categories: [ai_services, compute]

default_action: deny
require_approval_above: 1000

Velocity Control Policy

type: velocity_control
version: 1.0.0

windows:
  - duration: 1h
    max_transactions: 50
    max_amount: 5000

  - duration: 1d
    max_transactions: 500
    max_amount: 10000

  - duration: 1w
    max_transactions: 2000
    max_amount: 50000

  - duration: 1m
    max_transactions: 10000
    max_amount: 200000

enforcement: hard_limit
cooldown_on_exceed: 3600  # seconds

Multi-Party Approval Policy

type: multi_party_approval
version: 1.0.0

threshold: 2  # N-of-M signatures required

authorized_agents:
  - agent_key: "ak_live_agent1..."
    weight: 1
    permissions: [transfer, policy_update]

  - agent_key: "ak_live_agent2..."
    weight: 1
    permissions: [transfer, approve]

  - agent_key: "ak_live_agent3..."
    weight: 1
    permissions: [approve]

routing:
  - condition: amount > 5000
    required_signatures: 2

  - condition: merchant not_in whitelist
    required_signatures: 3

proposal_timeout: 86400  # seconds

---

Message Formats

Transaction Request

syntax = "proto3";

message TransactionRequest {
  string version = 1;
  int64 timestamp = 2;
  bytes agent_key = 3;
  string vault_id = 4;

  Transaction transaction = 5;
  bytes signature = 6;
}

message Transaction {
  enum Type {
    TRANSFER = 0;
    WITHDRAW = 1;
    INTERNAL_TRANSFER = 2;
  }

  Type type = 1;
  string recipient = 2;
  uint64 amount = 3;
  string currency = 4;
  string memo = 5;
}

Authorization Proof

message AuthorizationProof {
  bytes signature = 1;
  bytes policies_hash = 2;
  bytes nonce = 3;
  int64 expires_at = 4;

  repeated PolicyResult policies = 5;
}

message PolicyResult {
  string policy_type = 1;
  bool approved = 2;
  string reason = 3;
  map<string, string> metadata = 4;
}

---

Security Model

Threat Model

In Scope:

• Unauthorized transaction execution

• Policy bypass attempts

• Replay attacks

• Man-in-the-middle attacks

• Agent key compromise

Out of Scope:

• Solana consensus failures

• Cryptographic primitive breaks (Ed25519, SHA-256)

• Physical compromise of hardware security modules

Security Guarantees

Authorization Integrity:

• Every transaction requires valid authorization proof

• Proofs expire after configurable timeout (default: 300 seconds)

• Nonces prevent replay attacks

• Policies enforced at both off-chain and on-chain layers

Agent Authentication:

• Ed25519 signatures verify agent identity

• Keys rotatable without vault redeployment

• Compromised keys revocable within 1 block time

• Multi-signature required for high-value operations

Policy Enforcement:

• Policies committed to Merkle tree on-chain

• Policy updates require multi-party approval

• Policy evaluation deterministic and auditable

• Failed authorization attempts logged immutably

---

Performance Specifications

Latency Targets

Operation	Target	Measured (p99)
Authorization Request	< 50ms	45ms
Policy Evaluation	< 30ms	28ms
On-Chain Verification	< 100ms	85ms
Transaction Finality	< 400ms	380ms
End-to-End Latency	< 500ms	485ms

Throughput Targets

Metric	Target	Measured
Authorization Requests/sec	50,000+	62,000
On-Chain Transactions/sec	2,000+	2,400
Concurrent Agents	10,000+	15,000
Concurrent Vaults	100,000+	120,000

---

Protocol Extensions

Zero-Knowledge Proof Extension

Enable privacy-preserving authorization where policy compliance is proven without revealing transaction details.

Circuit Specification:

Public Inputs:
- policies_commitment: Hash of applicable policies
- vault_public_key: Vault's public key

Private Inputs:
- transaction_amount: Transaction amount
- merchant_id: Merchant identifier
- velocity_state: Current spending velocity

Constraints:
1. amount < daily_limit
2. merchant_id ∈ whitelist
3. velocity_state + amount < velocity_limit

Output:
- proof: ZK-SNARK proof of policy compliance

Usage:

const proof = await generateZKProof({
  transaction: {
    amount: 1000,
    merchant: 'confidential'
  },
  policies: vaultPolicies,
  privateInputs: {
    merchantId: 'actual_merchant_id',
    velocityState: currentSpending
  }
});

// Submit proof instead of plaintext authorization
await vault.executeTransferWithZKProof(proof);

---

Versioning & Upgrades

Protocol Versioning

Version Format: MAJOR.MINOR.PATCH

• MAJOR: Breaking changes to protocol interfaces

• MINOR: Backward-compatible feature additions

• PATCH: Bug fixes and performance improvements

Current Version: 1.0.0

Upgrade Path

Smart Contracts:

• Proxy pattern for non-breaking upgrades

• 7-day timelock for major upgrades

• Multi-signature governance required

• Backward compatibility maintained for 2 versions

Authorization Protocol:

• Version negotiation during handshake

• Parallel support for N and N-1 versions

• 6-month deprecation notice for major changes

---

Compliance & Auditability

Audit Log Format

interface AuditLogEntry {
  timestamp: number;
  eventType: 'authorization_request' | 'policy_evaluation' | 'transaction_execution';
  agentKey: PublicKey;
  vaultId: string;

  request: {
    transactionHash: string;
    amount: number;
    recipient: string;
  };

  evaluation: {
    policiesEvaluated: PolicyResult[];
    decision: 'approved' | 'denied' | 'requires_approval';
    latency: number;
  };

  execution?: {
    transactionSignature: string;
    blockHeight: number;
    finalityLatency: number;
  };

  signature: string;  // Log entry integrity signature
}

On-Chain Event Emission

#[event]
pub struct TransactionExecuted {
    pub vault: Pubkey,
    pub agent: Pubkey,
    pub recipient: Pubkey,
    pub amount: u64,
    pub currency: Pubkey,
    pub policies_hash: [u8; 32],
    pub timestamp: i64,
}

#[event]
pub struct PolicyUpdated {
    pub vault: Pubkey,
    pub policy_type: String,
    pub new_hash: [u8; 32],
    pub approvers: Vec<Pubkey>,
    pub timestamp: i64,
}

---

Reference Implementations

TypeScript SDK

import { ClawFiProtocol } from '@clawfi/protocol';

const protocol = new ClawFiProtocol({
  network: 'mainnet',
  authEngine: 'https://auth.useclawfi.com'
});

// Request authorization
const authResponse = await protocol.requestAuthorization({
  vaultId: 'vault_xyz789',
  transaction: {
    type: 'transfer',
    recipient: 'vercel.com',
    amount: 127.50,
    currency: 'USDC'
  },
  agentKey: loadAgentKey()
});

// Execute if approved
if (authResponse.status === 'approved') {
  const tx = await protocol.executeTransaction(
    authResponse.proof
  );
  console.log(`Transaction: ${tx.signature}`);
}

Rust SDK

use clawfi_protocol::{Protocol, AuthorizationRequest};

let protocol = Protocol::new(Config {
    network: Network::Mainnet,
    auth_engine: "https://auth.useclawfi.com",
})?;

let auth_response = protocol.request_authorization(
    AuthorizationRequest {
        vault_id: "vault_xyz789",
        transaction: Transaction {
            recipient: "vercel.com",
            amount: 127_500_000, // Microunits
            currency: "USDC",
        },
    }
).await?;

if auth_response.approved() {
    let tx = protocol.execute(auth_response.proof()).await?;
    println!("Transaction: {}", tx.signature);
}

---

Test Vectors

Ed25519 Signature Verification

Private Key: a0b1c2d3e4f5...
Public Key: 0x742d35Cc...
Message: {"vault":"vault_xyz","amount":100}
Signature: 0x8d9e1f2a...

Expected Result: VALID

Policy Hash Calculation

Policy JSON:
{
  "type": "velocity_control",
  "daily_limit": 10000,
  "merchants": ["vercel.com"]
}

SHA-256 Hash:
0x3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a

---

Changelog

v1.0.0 (March 2026)

• Initial production release

• Core authorization protocol

• Smart contract deployment

• MCP integration

v0.9.0 (February 2026)

• Beta release on devnet

• Authorization engine testing

• Performance benchmarking

---

References

• Solana Documentation: docs.solana.com

• Ed25519 Specification: RFC 8032

• JSON-RPC 2.0: jsonrpc.org

• MCP Specification: modelcontextprotocol.io

---

Protocol Version: 1.0.0 Last Updated: March 2026 Status: Production Maintainer: ClawFi Protocol Team