ClawPay Smart Contracts

Solidity smart contracts for ClawPay's authorization-based onchain banking infrastructure

Overview

This directory contains the production-ready smart contracts that power ClawPay's programmable treasury system. The contracts implement a pull-based authorization model where every transaction requires explicit cryptographic approval, eliminating the risks associated with unlimited token approvals.

Architecture

┌─────────────────────────────────────────────────────────────┐
│                     ClawPay Protocol                        │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌──────────────┐    ┌──────────────────┐    ┌───────────┐  │
│  │VaultFactory  │───▶│ Vault            │◀───│CardManager│  │
│  │              │    │ (Treasury)       │    │           │  │
│  └──────────────┘    └──────────────────┘    └───────────┘  │
│                              │                       │      │
│                              ▼                       ▼      │
│                      ┌────────────────────────────────┐     │
│                      │  AuthorizationEngine           │     │
│                      │  (Policy Enforcement)          │     │
│                      └────────────────────────────────┘     │
│                              │                              │
│                              ▼                              │
│                      ┌────────────────────────────────┐     │
│                      │  MultiPartyApproval            │     │
│                      │  (Multi-sig Workflows)         │     │
│                      └────────────────────────────────┘     │
│                                                             │
│  ┌───────────────────────────────────────────────────────┐  │
│  │          TransferManager (Network Settlement)         │  │
│  └───────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

Contract Overview

Core Contracts

1. Vault.sol

The primary treasury contract that holds digital assets (USDC, SOL, etc.).

Key Features:

• Multi-token support via ERC20 standard
• Programmable authorization policies
• Role-based access control (Owner, Admin, Manager, Viewer)
• Freeze/unfreeze capabilities
• Metadata storage for organization
• Card authorization management

Main Functions:

function deposit(uint256 amount) external
function withdraw(address to, uint256 amount) external
function freeze(string calldata reason) external
function setAuthorizationPolicy(address policy) external
function authorizeCard(address cardAddress) external

2. AuthorizationEngine.sol

Validates all transactions against programmable spending rules.

Key Features:

• Multiple policy types (Whitelist, Multi-party, Velocity, Time-based, Geographic)
• Spending limit enforcement (daily, weekly, monthly)
• Merchant/category whitelisting
• Zero-knowledge proof validation support
• Real-time policy evaluation

Policy Types:

• WhitelistOnly: Only approved merchants
• MultiParty: Requires multiple approvers
• VelocityControl: Rate limiting
• TimeRestricted: Business hours only
• Geographic: Location-based restrictions

Main Functions:

function authorize(TransactionRequest calldata request) external returns (AuthorizationResult memory)
function createPolicy(address vaultAddress, Policy calldata policy) external
function updatePolicy(address policyAddress, Policy calldata policy) external

3. CardManager.sol

Manages virtual debit cards linked to vaults.

Key Features:

• Instant card issuance
• Per-card spending limits
• Daily/monthly spending tracking
• Card lifecycle management (freeze, unfreeze, cancel)
• Transaction processing with authorization checks

Main Functions:

function createCard(address vaultAddress, uint256 dailyLimit, uint256 monthlyLimit) external returns (address)
function processTransaction(address cardAddress, uint256 amount, string calldata merchant) external returns (bool)
function freezeCard(address cardAddress, string calldata reason) external
function updateSpendingLimits(address cardAddress, uint256 dailyLimit, uint256 monthlyLimit) external

4. TransferManager.sol

Handles instant settlement between vaults and external transfers.

Key Features:

• Internal vault-to-vault transfers (instant settlement)
• External blockchain transfers
• Fee management (configurable basis points)
• Transfer tracking and history
• Multi-token support

Main Functions:

function createInternalTransfer(address source, address dest, uint256 amount, string calldata memo) external returns (bytes32)
function createExternalTransfer(address source, address dest, uint256 amount, address token, string calldata memo) external returns (bytes32)

5. MultiPartyApproval.sol

Implements threshold-based multi-signature approval workflows.

Key Features:

• Configurable approval thresholds
• Multiple proposal types (Transaction, Policy Change, Membership, Emergency)
• Time-based expiration
• Approval/rejection tracking with reasons
• Pending proposal queries

Main Functions:

function createProposal(address vault, ProposalType type, bytes calldata data, uint256 amount, string calldata desc) external returns (bytes32)
function approveProposal(bytes32 proposalId, string calldata reason) external
function rejectProposal(bytes32 proposalId, string calldata reason) external
function executeProposal(bytes32 proposalId) external

6. VaultFactory.sol

Factory contract for standardized vault deployment.

Key Features:

• Centralized vault creation
• Vault registry and tracking
• Initial deposit support
• Integration with authorization engine
• User vault enumeration

Main Functions:

function createVault(string calldata name, address owner) external returns (address)
function createVaultWithDeposit(string calldata name, address owner, uint256 initialDeposit) external returns (address)
function getUserVaults(address user) external view returns (address[] memory)

Libraries

AuthorizationLib.sol

Utility library for authorization logic.

Features:

• Spending tracker management
• Time-based limit calculations (daily/weekly/monthly)
• Merchant/category validation
• Velocity checks
• Helper functions for policy evaluation

Interfaces

• IVault.sol: Vault interface
• IAuthorizationEngine.sol: Authorization engine interface
• ICardManager.sol: Card manager interface

Security Features

1. Pull-Based Authorization

Unlike traditional push-based approvals, ClawPay requires explicit authorization for every transaction.

2. Multi-Layer Protection

• Card-level spending limits
• Vault-level authorization policies
• Multi-party approval for high-value transactions
• Time-based and velocity controls

3. Access Control

• OpenZeppelin's Ownable for ownership
• Role-based permissions (Owner, Admin, Manager, Viewer)
• Per-card authorization

4. Reentrancy Protection

• ReentrancyGuard on all state-changing functions
• SafeERC20 for token transfers

5. Zero-Knowledge Proofs

• Optional ZK-proof validation for privacy
• Proof verification without revealing transaction details
• Support for multiple proof systems (Groth16, PLONK, STARK)

Usage Examples

Creating a Vault

// Deploy factory
VaultFactory factory = new VaultFactory(usdcAddress, authEngineAddress, owner);

// Create vault
address vault = factory.createVault("Company Treasury", msg.sender);

// Create with initial deposit
address vault2 = factory.createVaultWithDeposit(
    "Marketing Budget",
    msg.sender,
    50000 * 10**6 // 50,000 USDC
);

Setting Authorization Policy

IAuthorizationEngine.Policy memory policy = IAuthorizationEngine.Policy({
    policyType: IAuthorizationEngine.PolicyType.WhitelistOnly,
    dailyLimit: 5000 * 10**6,
    weeklyLimit: 30000 * 10**6,
    monthlyLimit: 100000 * 10**6,
    whitelistedMerchants: ["aws.amazon.com", "vercel.com"],
    allowedCategories: ["cloud_services"],
    zkProofRequired: false,
    approvalThreshold: 10000 * 10**6,
    approvers: [cfo, cto, ceo],
    minApprovers: 2,
    approvalTimeoutMinutes: 60
});

authEngine.createPolicy(vaultAddress, policy);

Creating and Using a Card

// Create card
address card = cardManager.createCard(
    vaultAddress,
    1000 * 10**6,  // $1,000 daily limit
    25000 * 10**6  // $25,000 monthly limit
);

// Process transaction
bool success = cardManager.processTransaction(
    card,
    49.99 * 10**6, // $49.99
    "aws.amazon.com"
);

Multi-Party Approval Workflow

// Set approval policy
MultiPartyApproval.ApprovalPolicy memory policy = MultiPartyApproval.ApprovalPolicy({
    approvers: [cfo, cto, ceo],
    requiredApprovals: 2,
    timeoutMinutes: 60,
    requireReason: true
});

multiParty.setApprovalPolicy(vaultAddress, policy);

// Create proposal for large transaction
bytes32 proposalId = multiParty.createProposal(
    vaultAddress,
    MultiPartyApproval.ProposalType.Transaction,
    abi.encode(recipient, 15000 * 10**6),
    15000 * 10**6,
    "Q1 Infrastructure Payment"
);

// Approvers vote
multiParty.approveProposal(proposalId, "Approved for cloud costs");
multiParty.approveProposal(proposalId, "Budget approved");

// Execute when threshold met
multiParty.executeProposal(proposalId);

Deployment

Prerequisites

• Solidity ^0.8.20
• OpenZeppelin Contracts
• Hardhat or Foundry for deployment

Installation

npm install @openzeppelin/contracts

Deployment Order

1. Deploy USDC token contract (or use existing)
2. Deploy AuthorizationEngine
3. Deploy MultiPartyApproval
4. Deploy CardManager (with AuthEngine reference)
5. Deploy TransferManager
6. Deploy VaultFactory (with USDC and AuthEngine)
7. Deploy individual Vault contracts via factory

Configuration

const authEngine = await AuthorizationEngine.deploy(owner);
const multiParty = await MultiPartyApproval.deploy(owner);
const cardManager = await CardManager.deploy(authEngine.address, owner);
const transferManager = await TransferManager.deploy(feeCollector, owner);
const factory = await VaultFactory.deploy(usdc.address, authEngine.address, owner);

// Configure
await factory.updateCardManager(cardManager.address);
await factory.updateTransferManager(transferManager.address);
await transferManager.addSupportedToken(usdc.address);

Testing

Comprehensive test coverage includes:

• Vault creation and management
• Authorization policy enforcement
• Card transaction processing
• Multi-party approval workflows
• Transfer execution
• Edge cases and attack vectors

Gas Optimization

• Efficient storage packing
• Minimal storage reads/writes
• Batch operations where possible
• Optimized loops and conditionals

Upgradability

Current contracts are non-upgradable for security. Future versions will implement:

• Proxy patterns for upgradability
• Governance-based upgrade mechanisms
• Migration tools

Security Audits

Status: Pending external audit

Recommendations:

• Complete security audit before mainnet deployment
• Bug bounty program
• Gradual rollout with rate limiting

License

All rights reserved © 2026 ClawPay Inc.

Support

• Documentation: docs.useclawpay.app
• Discord: Join our community
• Security Issues: security@useclawpay.app

Acknowledgments

Built with:

• OpenZeppelin Contracts - Secure smart contract library
• Solidity - Smart contract language