Authorization Engine

Overview

The ClawBank authorization engine implements a pull-based validation model where transactions require explicit cryptographic approval before execution. Unlike push-based approval systems (ERC20 allowances), this architecture eliminates unlimited delegation risk through programmable spending policies enforced at both the smart contract layer and off-chain policy evaluation.

Architecture

Transaction Request
        │
        ▼
┌───────────────────┐
│ Policy Evaluation │
│   (Off-Chain)     │
└────────┬──────────┘
         │
    ┌────┴────┐
    │         │
    ▼         ▼
┌────────┐ ┌──────────────┐
│Merchant│ │   Velocity   │
│ Check  │ │   Control    │
└───┬────┘ └──────┬───────┘
    │             │
    └──────┬──────┘
           │
           ▼
    ┌──────────────┐
    │  ZK-Proof    │
    │  Validation  │
    └──────┬───────┘
           │
           ▼
    ┌──────────────┐
    │ Smart Contract│
    │  Execution   │
    └──────┬───────┘
           │
           ▼
    [ Approve/Decline ]

Policy Types

WhitelistOnly

Restrict transactions to pre-approved merchants or contract addresses.

await client.vaults.setAuthorizationPolicy(vaultId, {
  type: 'WhitelistOnly',
  dailyLimit: 5000_000_000, // 5000 USDC
  weeklyLimit: 30000_000_000,
  monthlyLimit: 100000_000_000,
  currency: 'USDC',
  merchants: [
    'aws.amazon.com',
    'openai.com',
    'anthropic.com',
    'vercel.com'
  ],
  categories: [
    'cloud_services',
    'software',
    'ai_infrastructure'
  ]
});

Use Case: Company treasury with strict vendor management

VelocityControl

Rate limiting per time window to prevent rapid transaction patterns.

await client.vaults.setAuthorizationPolicy(vaultId, {
  type: 'VelocityControl',
  maxTransactionsPerHour: 10,
  maxTransactionsPerDay: 50,
  maxAmountPerHour: 5000_000_000,
  minTimeBetween: 60, // seconds
  requireCoolingPeriod: {
    after: 5, // transactions
    cooldown: 300 // seconds
  }
});

Use Case: Fraud prevention and anomaly detection

MultiParty

Threshold-based multi-signature approval for high-value transactions.

await client.vaults.setAuthorizationPolicy(vaultId, {
  type: 'MultiParty',
  requiresApproval: {
    above: 10000_000_000, // 10,000 USDC
    minApprovers: 2,
    approvers: [
      '[email protected]',
      '[email protected]',
      '[email protected]'
    ],
    threshold: 2, // 2 of 3 signatures required
    timeoutMinutes: 60
  }
});

Implementation Flow:

1. Transaction over threshold held pending

2. Approval requests sent to designated approvers

3. Minimum signatures collected within timeout

4. Transaction executes or declines based on threshold

ZKProof

Zero-knowledge proof validation for transaction privacy.

await client.vaults.setAuthorizationPolicy(vaultId, {
  type: 'ZKProof',
  zkProofRequired: true,
  zkProofType: 'groth16', // or 'plonk', 'stark'
  publicInputs: ['merchant_category', 'amount_range'],
  privateInputs: ['exact_amount', 'merchant_name', 'vault_balance']
});

Privacy Guarantees:

• Transaction amounts remain private

• Merchant details encrypted

• Only proof of valid authorization is public

• Vault balances never revealed on-chain

Performance Comparison

Proof System	Generation	Verification	Proof Size	Gas Cost
Groth16	~2s	~5ms	128 bytes	Low
PLONK	~5s	~10ms	512 bytes	Medium
STARK	~10s	~20ms	45 KB	Higher

Policy Evaluation

Rule Processing

const evaluateTransaction = async (transaction, policy) => {
  const checks = [
    checkDailyLimit(transaction, policy),
    checkMerchantWhitelist(transaction, policy),
    checkCategoryAllowed(transaction, policy),
    checkVaultBalance(transaction, vault),
    checkTimeRestrictions(transaction, policy),
    checkVelocityLimits(transaction, card)
  ];

  const results = await Promise.all(checks);
  const allPassed = results.every(r => r.passed);

  if (policy.zkProofRequired) {
    const proofValid = await validateZKProof(transaction);
    return allPassed && proofValid;
  }

  return allPassed;
};

Decision Latency

• Off-chain evaluation: < 100ms

• On-chain verification: < 2s (Solana finality)

• Total authorization: < 240ms average

Combining Policies

Multiple policies evaluated simultaneously. Transaction must pass ALL checks:

await client.vaults.setAuthorizationPolicy(vaultId, {
  // Base limits
  dailyLimit: 5000_000_000,
  monthlyLimit: 100000_000_000,

  // Merchant controls
  type: 'WhitelistOnly',
  merchants: ['aws.amazon.com', 'vercel.com'],

  // Multi-party for large amounts
  requiresApproval: {
    above: 10000_000_000,
    minApprovers: 2,
    threshold: 2
  },

  // Time restrictions
  allowedHours: {
    start: '09:00',
    end: '17:00',
    timezone: 'America/New_York'
  },

  // Velocity controls
  maxTransactionsPerHour: 10,

  // Privacy layer
  zkProofRequired: true
});

Advanced Features

Dynamic Limits

Contextual limit adjustments based on conditions:

{
  type: 'DynamicLimits',
  baseDailyLimit: 1000_000_000,
  modifiers: [
    {
      condition: 'day_of_week',
      values: ['saturday', 'sunday'],
      multiplier: 0.5 // 50% limit on weekends
    },
    {
      condition: 'merchant_category',
      value: 'emergency_services',
      multiplier: 2.0 // 200% limit for emergencies
    },
    {
      condition: 'agent_risk_score',
      operator: 'lt',
      value: 0.3,
      multiplier: 1.5 // Higher limit for low-risk agents
    }
  ]
}

Contextual Authorization

ML-enhanced risk scoring with conditional rules:

{
  type: 'MLEnhanced',
  fraudThreshold: 0.75, // 0-1 risk score
  onHighRisk: 'require_approval',
  factors: [
    'transaction_amount',
    'merchant_reputation',
    'time_of_day',
    'location_anomaly',
    'velocity_pattern',
    'agent_behavior_history'
  ],
  rules: [
    {
      if: {
        merchantCategory: 'travel',
        amount: { gt: 500_000_000 }
      },
      then: {
        requireApproval: true,
        require2FA: true,
        notifyOwners: true
      }
    }
  ]
}

Smart Contract Integration

On-Chain Policy Enforcement

// Solana program (Rust)
pub fn validate_transaction(
    ctx: Context<ValidateTransaction>,
    amount: u64,
    merchant: Pubkey,
) -> Result<()> {
    let policy = &ctx.accounts.authorization_policy;
    
    // Check daily limit
    require!(
        policy.daily_spent + amount <= policy.daily_limit,
        ErrorCode::DailyLimitExceeded
    );
    
    // Verify merchant whitelist
    require!(
        policy.allowed_merchants.contains(&merchant),
        ErrorCode::MerchantNotWhitelisted
    );
    
    // Update spent tracking
    policy.daily_spent += amount;
    policy.last_transaction_time = Clock::get()?.unix_timestamp;
    
    Ok(())
}

Multi-Signature Validation

pub fn approve_transaction(
    ctx: Context<ApproveTransaction>,
    transaction_id: [u8; 32],
) -> Result<()> {
    let approval = &mut ctx.accounts.approval;
    let signer = ctx.accounts.signer.key();
    
    // Record approval
    approval.approvers.push(signer);
    approval.approval_count += 1;
    
    // Check if threshold met
    if approval.approval_count >= approval.threshold {
        // Execute transaction
        invoke_transaction(&ctx, transaction_id)?;
    }
    
    Ok(())
}

Monitoring & Analytics

Authorization Metrics

const metrics = await client.vaults.getAuthorizationMetrics(vaultId, {
  period: '30d'
});

console.log(`Approval rate: ${metrics.approvalRate}%`);
console.log(`Average decision time: ${metrics.avgDecisionTime}ms`);
console.log(`Policy effectiveness: ${metrics.fraudPrevented}`);

Decline Analysis

const analysis = await client.vaults.analyzeDeclines(vaultId, {
  period: '7d'
});

// {
//   daily_limit_exceeded: 5,
//   merchant_not_whitelisted: 12,
//   velocity_limit_hit: 3,
//   approval_timeout: 2
// }

Best Practices

1. Start Restrictive

// Week 1: Conservative policy
await client.vaults.setAuthorizationPolicy(vaultId, {
  dailyLimit: 1000_000_000,
  merchants: ['known_vendor_1', 'known_vendor_2']
});

// After observation: Gradual relaxation
await client.vaults.setAuthorizationPolicy(vaultId, {
  dailyLimit: 5000_000_000,
  categories: ['cloud_services', 'software']
});

2. Test in Sandbox

const sandboxClient = new ClawBank({
  apiKey: process.env.CLAWBANK_SANDBOX_KEY,
  environment: 'sandbox',
  network: 'solana-devnet'
});

await sandboxClient.vaults.setAuthorizationPolicy(vaultId, newPolicy);
// Verify behavior before production deployment

3. Monitor Effectiveness

async function reviewPolicy(vaultId: string) {
  const metrics = await client.vaults.getAuthorizationMetrics(vaultId, {
    period: '30d'
  });

  if (metrics.declineRate > 0.20) {
    console.warn('High decline rate - consider relaxing policy');
  }

  if (metrics.approvalLatency > 30000) {
    console.warn('Approval latency high - check approver availability');
  }
}

Troubleshooting

Transaction Declined

const txn = await client.transactions.retrieve(txnId);

console.log(`Decline reason: ${txn.declineReason}`);
console.log(`Failed check: ${txn.failedCheck}`);
console.log(`Policy ID: ${txn.policyId}`);

// Full evaluation details
const evaluation = await client.transactions.getAuthorizationEvaluation(txnId);
evaluation.checks.forEach(check => {
  console.log(`${check.name}: ${check.passed ? '✓' : '✗'} ${check.reason || ''}`);
});

Next Steps

• Treasury Vaults - Smart contract vault operations

• Programmable Spending - Card-based policies

• Real-Time Events - Authorization webhooks

• API Reference - Complete policy endpoints