ClawBank Solana Smart Contracts

Financial infrastructure for autonomous AI operations. Built on Solana using the Anchor framework.

Architecture Overview

ClawBank's on-chain infrastructure enables AI agents to operate as independent economic entities with programmable authorization, cryptographic validation, and sub-second settlement finality.

Core Principles:

• Agent-Native Design: Smart contracts purpose-built for autonomous AI operations
• Programmable Authorization: Pull-based authorization engine with sophisticated spending policies
• Sub-Second Finality: Solana settlement with < 240ms latency
• Zero-Fee Internal: Vault-to-vault transfers with $0 fees
• Cryptographic Transparency: On-chain proof of every transaction

---

Smart Contract Architecture

1. Treasury Vault (treasury_vault.rs)

Purpose: Treasury management infrastructure for AI agent operations with velocity control and programmable spending policies.

Core Capabilities:

• Create isolated treasury vaults for AI agents
• Programmable spending limits with time-window velocity control
• Real-time balance tracking and transaction history
• Emergency freeze/unfreeze controls
• Owner withdrawal and vault lifecycle management

Key Instructions:

initialize_vault       // Create vault with agent_id and spending policy
fund_vault            // Deposit SOL into vault
execute_transaction   // Agent executes authorized transaction with velocity check
freeze_vault          // Emergency stop for agent operations
unfreeze_vault        // Resume agent operations
update_spending_policy // Modify spending limit and time window
withdraw_balance      // Owner withdrawal
close_vault          // Close empty vault and reclaim rent
get_vault_info       // Query vault statistics

Vault Account Structure:

pub struct Vault {
    pub owner: Pubkey,              // Human owner
    pub agent_id: String,           // AI agent identifier
    pub balance: u64,               // Current balance
    pub spending_limit: u64,        // Max per time window
    pub time_window: i64,           // Velocity control window
    pub spent_in_window: u64,       // Current window spend
    pub window_start: i64,          // Window reset timestamp
    pub status: VaultStatus,        // Active/Frozen
    pub transaction_count: u64,     // Total transactions
    pub total_spent: u64,           // Lifetime spending
}

Authorization Pattern:

• Pull-based validation (agent requests, contract validates)
• Velocity control prevents unlimited delegation risk
• Cryptographic authorization hash required per transaction
• Owner maintains ultimate control with freeze capability

PDA Seeds: ["vault", owner.key(), agent_id.bytes()]

---

2. Authorization Engine (authorization_engine.rs)

Purpose: Multi-agent coordination with programmable spending policies and threshold-based approval workflows.

Core Capabilities:

• Multi-agent authorization systems (N-of-M approval)
• Create programmable spending policies
• Merchant whitelisting for controlled spending
• Time-locked policy activation
• Policy approval/rejection workflows
• Dynamic agent management

Key Instructions:

initialize_engine      // Create authorization engine with agents and threshold
create_policy         // Define spending policy (WhitelistOnly, VelocityControl, etc.)
approve_policy        // Agent approves policy
reject_policy         // Agent rejects policy
activate_policy       // Activate approved policy (respects time lock)
validate_transaction  // Validate transaction against active policy
deactivate_policy     // Disable active policy
add_agent            // Add agent to engine
remove_agent         // Remove agent from engine
update_threshold     // Change approval threshold
get_engine_info      // Query engine statistics

Policy Types:

pub enum PolicyType {
    WhitelistOnly,      // Only allow whitelisted merchants
    VelocityControl,    // Rate limiting per time window
    MultiParty,         // Threshold-based approval
    Universal,          // No merchant restrictions
}

Spending Policy Structure:

pub struct SpendingPolicy {
    pub policy_type: PolicyType,
    pub merchant_whitelist: Vec<Pubkey>,
    pub max_amount: u64,
    pub time_lock: Option<i64>,      // Activation delay
    pub approvals: Vec<Pubkey>,      // Agent approvals
    pub status: PolicyStatus,        // Pending/Approved/Active/Rejected
    pub activated_at: Option<i64>,
}

Use Cases:

• Finance Agent + Purchasing Agent coordination
• Expense management with merchant restrictions
• Treasury operations requiring multiple agent approval
• Automated payroll with spending caps
• Subscription management with velocity limits

PDA Seeds:

• Engine: ["auth_engine", authority.key()]
• Policy: ["policy", engine.key(), policy_count.bytes()]

---

3. Transaction Validator (transaction_validator.rs)

Purpose: Cryptographic validation and on-chain recording of autonomous AI agent transactions.

Core Capabilities:

• Cryptographic authorization proof validation (keccak hash)
• On-chain transaction records with agent attribution
• Settlement tracking with finality proofs
• Failed transaction logging
• Proof verification system
• Validator statistics and analytics

Key Instructions:

initialize_validator   // Setup validator authority
validate_transaction  // Record transaction with cryptographic proof
settle_transaction    // Mark as settled with settlement hash
fail_transaction      // Record transaction failure
verify_proof          // Verify proof matches stored hash
get_transaction_info  // Query transaction details
get_validator_stats   // Get validation statistics
batch_validate        // Batch validation for performance
update_authority      // Rotate validator authority

Transaction Structure:

pub struct Transaction {
    pub auth_hash: [u8; 32],             // Keccak hash of authorization
    pub authorization_proof: String,      // Authorization proof data
    pub amount: u64,
    pub sender: Pubkey,
    pub recipient: Pubkey,
    pub agent_id: String,                // AI agent identifier
    pub vault_address: Pubkey,           // Source vault
    pub validated_at: i64,
    pub settlement_hash: Option<[u8; 32]>, // Finality proof
    pub status: TransactionStatus,       // Validated/Settled/Failed
}

Validation Flow:

1. Agent generates authorization proof
2. Contract computes keccak hash
3. Transaction recorded on-chain with agent attribution
4. Settlement hash added upon finality
5. Full transaction history available for audit

PDA Seeds: ["transaction", sender.key(), authorization_proof.bytes()]

---

4. Instant Settlement (instant_settlement.rs)

Purpose: Sub-second settlement network with $0 fees for internal vault-to-vault transfers.

Core Capabilities:

• Instant internal vault-to-vault transfers ($0 fees)
• External settlements to non-vault recipients
• Batch processing for high-throughput operations
• Settlement network analytics
• Sub-second Solana finality (~400ms)

Key Instructions:

initialize_network      // Create settlement network
internal_transfer       // Vault-to-vault transfer ($0 fees, sub-second)
external_settlement     // Vault to external recipient (Solana finality)
batch_internal_transfer // Batch process multiple transfers
get_network_stats       // Network statistics
update_authority        // Rotate network authority

Settlement Network Structure:

pub struct SettlementNetwork {
    pub authority: Pubkey,
    pub total_settlements: u64,
    pub total_volume: u64,
    pub internal_transfers: u64,     // $0 fee transfers
    pub external_transfers: u64,
}

Performance Characteristics:

• Internal transfers: < 240ms, $0 fees
• External settlements: ~400ms (Solana finality)
• Batch processing: Up to 10x throughput improvement
• On-chain transparency: All transfers recorded

Use Cases:

• Agent-to-agent treasury rebalancing
• Multi-agent payment coordination
• Instant settlement for autonomous operations
• External payouts with Solana-speed finality

PDA Seeds: ["settlement_network"]

---

Contract Integration

Multi-Contract Workflow Example

Scenario: AI Finance Agent executes autonomous payment with authorization policy

// 1. Create Treasury Vault
await treasuryVault.methods
  .initializeVault(
    "finance_agent_001",     // agent_id
    new BN(1000000000),      // initial_balance
    new BN(100000000),       // spending_limit: 0.1 SOL
    3600                     // time_window: 1 hour
  )
  .accounts({ vault, owner })
  .rpc();

// 2. Setup Authorization Engine with Policy
await authEngine.methods
  .initializeEngine(
    [agentPubkey1, agentPubkey2],  // Multi-agent
    2                               // 2-of-2 approval
  )
  .accounts({ engine, authority })
  .rpc();

await authEngine.methods
  .createPolicy(
    { whitelistOnly: {} },
    [merchant1, merchant2],  // Whitelisted merchants
    new BN(50000000),        // max_amount: 0.05 SOL
    null                     // no time lock
  )
  .accounts({ policy, engine, creator })
  .rpc();

// 3. Validate Transaction
const authProof = generateAuthProof(transaction);

await txValidator.methods
  .validateTransaction(
    authProof,
    amount,
    recipient,
    "finance_agent_001",
    vaultAddress
  )
  .accounts({ transaction, validator, sender })
  .rpc();

// 4. Execute from Vault (with velocity check)
await treasuryVault.methods
  .executeTransaction(
    amount,
    authHash
  )
  .accounts({ vault, recipient, agentAuthority })
  .rpc();

// 5. Settle Transaction
await instantSettlement.methods
  .externalSettlement(amount, recipient)
  .accounts({ network, sourceVault, recipient, authority })
  .rpc();

// 6. Record Settlement
await txValidator.methods
  .settleTransaction(settlementSignature)
  .accounts({ transaction, validator, authority })
  .rpc();

---

Prerequisites

1. Install Rust

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

2. Install Solana CLI

sh -c "$(curl -sSfL https://release.solana.com/stable/install)"

3. Install Anchor Framework

cargo install --git https://github.com/coral-xyz/anchor avm --locked --force
avm install latest
avm use latest

4. Configure Solana Wallet

solana-keygen new
solana config set --url devnet  # or mainnet-beta

---

Build & Deploy

Initialize Anchor Workspace

cd contracts
anchor init clawbank-contracts --no-git

Copy Contract Files

cp treasury_vault.rs clawbank-contracts/programs/clawbank-contracts/src/
cp authorization_engine.rs clawbank-contracts/programs/clawbank-contracts/src/
cp transaction_validator.rs clawbank-contracts/programs/clawbank-contracts/src/
cp instant_settlement.rs clawbank-contracts/programs/clawbank-contracts/src/

Update lib.rs

pub mod treasury_vault;
pub mod authorization_engine;
pub mod transaction_validator;
pub mod instant_settlement;

// Re-export for convenience
pub use treasury_vault::*;
pub use authorization_engine::*;
pub use transaction_validator::*;
pub use instant_settlement::*;

Build Contracts

cd clawbank-contracts
anchor build

Deploy to Devnet

# Configure for devnet
solana config set --url devnet

# Airdrop SOL for deployment (devnet only)
solana airdrop 2

# Deploy
anchor deploy

# Update declare_id! in each contract with deployed program IDs

Deploy to Mainnet

# Configure for mainnet
solana config set --url mainnet-beta

# Ensure sufficient SOL for deployment
solana balance

# Deploy (requires ~5-10 SOL for all contracts)
anchor deploy --provider.cluster mainnet

---

Testing

Run All Tests

anchor test

Test Specific Contract

anchor test -- --test treasury_vault
anchor test -- --test authorization_engine

Test on Devnet

anchor test --provider.cluster devnet

Write Custom Tests

import * as anchor from "@coral-xyz/anchor";
import { Program } from "@coral-xyz/anchor";
import { TreasuryVault } from "../target/types/treasury_vault";

describe("treasury_vault", () => {
  const provider = anchor.AnchorProvider.env();
  anchor.setProvider(provider);

  const program = anchor.workspace.TreasuryVault as Program<TreasuryVault>;

  it("Creates vault with spending policy", async () => {
    const vault = anchor.web3.Keypair.generate();

    await program.methods
      .initializeVault(
        "test_agent",
        new anchor.BN(1000000000),
        new anchor.BN(100000000),
        3600
      )
      .accounts({
        vault: vault.publicKey,
        owner: provider.wallet.publicKey,
        systemProgram: anchor.web3.SystemProgram.programId,
      })
      .signers([vault])
      .rpc();

    const vaultAccount = await program.account.vault.fetch(vault.publicKey);
    assert.equal(vaultAccount.agentId, "test_agent");
    assert.equal(vaultAccount.spendingLimit.toNumber(), 100000000);
  });
});

---

Security Considerations

1. Authorization Model

• Pull-based authorization: Eliminates unlimited delegation risk (unlike ERC20 allowances)
• Cryptographic proofs: Every transaction requires authorization hash
• Velocity controls: Time-window spending limits prevent abuse
• Emergency controls: Owner can freeze vault operations

2. PDA-Based Security

• All critical accounts use Program Derived Addresses (PDAs)
• No private keys required for program-controlled accounts
• Deterministic address generation prevents account hijacking

3. State Validation

• Strict status checks on all state transitions
• Amount validation (> 0, <= balance)
• Authorization validation on all protected operations
• Time-based controls for escrows and policies

4. Multi-Signature Protection

• Threshold-based approval for sensitive operations
• Agent coordination requires N-of-M signatures
• Dynamic threshold adjustment with safety checks

5. Audit Recommendations

• External security audit before mainnet deployment
• Formal verification of critical authorization logic
• Penetration testing of agent coordination workflows
• Load testing for batch operations

---

Integration with ClawBank Stack

Backend API Integration

The smart contracts integrate with the ClawBank REST API:

┌─────────────────┐
│  ClawBank API   │ ← MCP Server Interface
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Smart Contracts│ ← On-chain validation & settlement
│  (Solana)       │
└─────────────────┘
         │
         ▼
┌─────────────────┐
│   Settlement    │ ← Sub-second finality
│   Network       │
└─────────────────┘

Flow:

1. AI agent makes request via MCP interface
2. API validates authorization policy
3. Smart contract executes with cryptographic proof
4. Settlement network processes transfer
5. Transaction validator records on-chain
6. API returns confirmation to agent

Model Context Protocol (MCP) Integration

// MCP Server calls smart contracts
import { Connection, PublicKey } from "@solana/web3.js";
import { Program, AnchorProvider } from "@coral-xyz/anchor";

class ClawBankMCPServer {
  async executeAgentTransaction(
    agentId: string,
    amount: number,
    recipient: string,
    authProof: string
  ) {
    // 1. Validate with authorization engine
    await this.authEngine.methods
      .validateTransaction(recipient, amount)
      .accounts({ policy: policyPDA })
      .rpc();

    // 2. Execute from vault
    await this.treasuryVault.methods
      .executeTransaction(amount, authHash)
      .accounts({ vault: vaultPDA, recipient, agentAuthority })
      .rpc();

    // 3. Record validation
    await this.txValidator.methods
      .validateTransaction(authProof, amount, recipient, agentId, vaultPDA)
      .accounts({ transaction, validator })
      .rpc();

    return { success: true, txSignature };
  }
}

---

Performance Benchmarks

Transaction Latency

Operation	Latency	Fees
Vault-to-vault transfer	< 240ms	$0
External settlement	~400ms	~$0.00025
Authorization validation	~200ms	~$0.00015
Batch transfer (10x)	~600ms	~$0.00030

Throughput

• Solana theoretical: 65,000 TPS
• ClawBank contracts: 5,000+ agent transactions per second
• Batch processing: 50,000+ TPS for internal transfers

Cost Analysis

Operation	Rent	Transaction Fee	Total
Create vault	~0.002 SOL	~$0.00025	~$0.32
Fund vault	$0	~$0.00025	~$0.00025
Execute transaction	$0	~$0.00025	~$0.00025
Internal transfer	$0	$0	$0

---

PDA Reference

Treasury Vault

["vault", owner.key(), agent_id.bytes()]

Authorization Engine

["auth_engine", authority.key()]

Spending Policy

["policy", engine.key(), policy_count.to_le_bytes()]

Transaction Validator

["validator"]  // Global singleton
["transaction", sender.key(), auth_proof.bytes()]

Settlement Network

["settlement_network"]  // Global singleton

---

Roadmap

Phase 1: Core Infrastructure (Current)

• ✅ Treasury vault with velocity control
• ✅ Authorization engine with policies
• ✅ Transaction validator with cryptographic proofs
• ✅ Instant settlement network

Phase 2: Advanced Features

• Zero-knowledge proof support for private transactions
• Cross-chain bridge integration (Ethereum, Polygon)
• Advanced policy types (geographic restrictions, KYC validation)
• Decentralized oracle integration for exchange rates

Phase 3: Ecosystem Expansion

• Agent role templates (Finance, Purchasing, Treasury)
• Pre-built policy libraries
• Analytics dashboard smart contract
• Governance token integration

---

Additional Resources

• Anchor Documentation: https://www.anchor-lang.com/
• Solana Documentation: https://docs.solana.com/
• ClawBank API Docs: https://docs.clawbank.xyz
• MCP Protocol: https://modelcontextprotocol.io/

---

Support & Contributing

Getting Help

• Documentation: https://docs.clawbank.xyz
• GitHub Issues: https://github.com/clawbank/contracts
• Discord: https://discord.gg/clawbank
• Email: dev@clawbank.xyz

Contributing

1. Fork the repository
2. Create feature branch (git checkout -b feature/agent-coordination)
3. Write comprehensive tests
4. Ensure all tests pass (anchor test)
5. Submit pull request with detailed description

Security Issues

Report security vulnerabilities to security@clawbank.xyz (PGP key available)

---

License

Proprietary - All rights reserved

---

Built for the AI Economy

ClawBank smart contracts provide the foundational financial infrastructure that enables AI agents to operate as independent economic entities. Sub-second settlement, programmable authorization, and cryptographic transparency built on Solana.

The Financial Operating System for AI Agents.