Treasury Vault Operations

On-chain smart contract vaults for programmable treasury management.

Overview

Treasury vaults are Solana smart contracts that hold digital assets with programmable authorization policies. Each vault operates as an independent on-chain program with cryptographic access control, multi-signature support, and real-time settlement capabilities.

Key Characteristics:

• On-Chain: 100% Solana smart contract implementation

• Programmable: Authorization policies enforced at contract layer

• Sub-Second Settlement: < 2s finality on Solana

• Cryptographic Security: Multi-signature and threshold approvals

• Zero-Knowledge Privacy: Optional ZK-proof transaction encryption

Vault Architecture

Treasury Vault (Solana Program)
├── Program ID: Unique smart contract address
├── Deposit Address: SPL token account for USDC/SOL
├── Authorization Policy: On-chain spending rules
├── Signers: Multi-sig approval accounts
└── Transaction History: Immutable on-chain record

Creating Vaults

Basic Vault Creation

const vault = await client.vaults.create({
  name: 'AI Agent Treasury',
  currency: 'USDC',
  network: 'solana',
  initialDeposit: 10000_000_000 // 10,000 USDC (6 decimals)
});

console.log(`Vault ID: ${vault.id}`);
console.log(`Program ID: ${vault.programId}`);
console.log(`Deposit address: ${vault.depositAddress}`);
console.log(`Explorer: https://solscan.io/account/${vault.depositAddress}`);

Vault with Authorization Policy

const vault = await client.vaults.create({
  name: 'Operations Treasury',
  currency: 'USDC',
  network: 'solana',
  initialDeposit: 50000_000_000,
  authorizationPolicy: {
    type: 'WhitelistOnly',
    dailyLimit: 5000_000_000,
    merchants: ['aws.amazon.com', 'openai.com'],
    zkProofRequired: true
  },
  metadata: {
    department: 'Engineering',
    purpose: 'infrastructure_payments',
    fiscal_year: '2026'
  }
});

Vault Properties

interface Vault {
  id: string;                    // ClawBank vault ID
  programId: string;             // Solana program address
  depositAddress: string;        // SPL token account
  currency: 'USDC' | 'SOL';
  network: 'solana-mainnet' | 'solana-devnet';
  balance: {
    available: bigint;           // Available for spending
    pending: bigint;             // In-flight transactions
    total: bigint;               // Total balance
  };
  status: 'active' | 'frozen' | 'closed';
  authorizationPolicy?: AuthorizationPolicy;
  signers: PublicKey[];          // Multi-sig authorities
  createdAt: string;             // ISO 8601 timestamp
  updatedAt: string;
  metadata?: Record<string, any>;
}

Depositing Assets

On-Chain Deposit

Send USDC directly to vault's deposit address:

const vault = await client.vaults.retrieve('vault_abc123');

// Display deposit instructions
console.log(`Deposit USDC to: ${vault.depositAddress}`);
console.log(`Network: Solana ${vault.network}`);
console.log(`Minimum: 1 USDC (1_000_000 base units)`);

// Programmatic deposit via Solana
import { Connection, PublicKey } from '@solana/web3.js';
import { getAssociatedTokenAddress, createTransferInstruction } from '@solana/spl-token';

const connection = new Connection('https://api.mainnet-beta.solana.com');
const vaultTokenAccount = new PublicKey(vault.depositAddress);

// Transfer USDC to vault
const transferIx = createTransferInstruction(
  sourceTokenAccount,
  vaultTokenAccount,
  sourceAuthority,
  10000_000_000 // 10,000 USDC
);

Internal Transfer

Transfer between ClawBank vaults (instant, $0 fees):

const transfer = await client.transfers.create({
  sourceVaultId: 'vault_source',
  destinationVaultId: 'vault_destination',
  amount: 5000_000_000, // 5,000 USDC
  currency: 'USDC',
  memo: 'Q1 budget allocation'
});

console.log(`Transfer ID: ${transfer.id}`);
console.log(`Status: ${transfer.status}`); // 'completed' (instant)
console.log(`Fee: $0.00`);

Balance Queries

Real-Time Balance

const balance = await client.vaults.getBalance('vault_abc123');

console.log(`Available: ${balance.available / 1_000_000} USDC`);
console.log(`Pending: ${balance.pending / 1_000_000} USDC`);
console.log(`Total: ${balance.total / 1_000_000} USDC`);
console.log(`Last updated: ${balance.lastUpdated}`);

Balance History

const history = await client.vaults.getBalanceHistory('vault_abc123', {
  period: '30d',
  interval: 'daily'
});

history.snapshots.forEach(snapshot => {
  console.log(`${snapshot.date}: ${snapshot.balance / 1_000_000} USDC`);
});

Balance Alerts

await client.vaults.setAlerts('vault_abc123', {
  lowBalance: {
    threshold: 1000_000_000, // 1,000 USDC
    channels: ['email', 'webhook'],
    recipients: ['[email protected]']
  },
  highActivity: {
    transactionsPerHour: 20,
    channels: ['webhook'],
    webhookUrl: 'https://api.company.com/alerts'
  }
});

Authorization Policies

Set programmable spending rules enforced at smart contract layer.

Merchant Whitelist

await client.vaults.setAuthorizationPolicy('vault_abc123', {
  type: 'WhitelistOnly',
  dailyLimit: 5000_000_000,
  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'
  ]
});

Multi-Signature Approval

await client.vaults.setAuthorizationPolicy('vault_abc123', {
  type: 'MultiParty',
  requiresApproval: {
    above: 10000_000_000, // 10,000 USDC
    threshold: 2, // 2 of 3 signatures
    approvers: [
      '7xKXt...', // Solana public key
      '9yZAb...',
      '4wCDe...'
    ],
    timeoutMinutes: 60
  }
});

Time-Based Restrictions

await client.vaults.setAuthorizationPolicy('vault_abc123', {
  type: 'TimeRestricted',
  allowedDays: ['monday', 'tuesday', 'wednesday', 'thursday', 'friday'],
  allowedHours: {
    start: '09:00',
    end: '17:00',
    timezone: 'America/New_York'
  },
  blockHolidays: true,
  holidays: ['2026-12-25', '2026-01-01']
});

Vault Operations

Freezing Vaults

Temporarily halt all outgoing transactions:

await client.vaults.freeze('vault_abc123', {
  reason: 'Security audit',
  notifyOwners: true,
  allowDeposits: true
});

// Status check
const vault = await client.vaults.retrieve('vault_abc123');
console.log(vault.status); // 'frozen'

// Unfreeze
await client.vaults.unfreeze('vault_abc123');

Closing Vaults

Permanently close vault and withdraw remaining balance:

// Withdraw remaining balance
const balance = await client.vaults.getBalance('vault_abc123');

if (balance.available > 0) {
  await client.transfers.createExternal({
    sourceVaultId: 'vault_abc123',
    destinationAddress: 'your_solana_wallet_address',
    amount: balance.available,
    currency: 'USDC',
    network: 'solana'
  });
}

// Close vault (irreversible)
await client.vaults.close('vault_abc123');

Multi-Signature Management

Adding Signers

import { PublicKey } from '@solana/web3.js';

await client.vaults.addSigner('vault_abc123', {
  publicKey: new PublicKey('7xKXt...'),
  role: 'approver',
  permissions: ['approve_transactions', 'view_balance']
});

Removing Signers

await client.vaults.removeSigner('vault_abc123', {
  publicKey: new PublicKey('7xKXt...')
});

Updating Threshold

await client.vaults.updateSignatureThreshold('vault_abc123', {
  threshold: 3, // Require 3 of N signatures
  minSigners: 5 // Minimum signers required
});

Transaction History

Query Transactions

const transactions = await client.transactions.list({
  vaultId: 'vault_abc123',
  limit: 50,
  status: 'completed',
  startDate: '2026-02-01',
  endDate: '2026-02-28'
});

transactions.data.forEach(txn => {
  console.log(`${txn.createdAt}: ${txn.amount / 1_000_000} USDC`);
  console.log(`  Signature: ${txn.signature}`);
  console.log(`  Explorer: https://solscan.io/tx/${txn.signature}`);
});

Export Transaction Data

// Export as CSV
const csv = await client.vaults.exportTransactions('vault_abc123', {
  format: 'csv',
  startDate: '2026-01-01',
  endDate: '2026-01-31',
  includeMetadata: true
});

// Export as JSON
const json = await client.vaults.exportTransactions('vault_abc123', {
  format: 'json',
  includeOnChainData: true
});

Smart Contract Interactions

Direct On-Chain Calls

import { Connection, PublicKey, Transaction } from '@solana/web3.js';

const connection = new Connection('https://api.mainnet-beta.solana.com');
const vaultProgramId = new PublicKey(vault.programId);

// Read vault state directly from chain
const vaultAccount = await connection.getAccountInfo(
  new PublicKey(vault.depositAddress)
);

console.log('On-chain balance:', vaultAccount.lamports);

Custom Program Instructions

// Build custom transaction with vault interaction
const transaction = new Transaction().add(
  createCustomInstruction({
    programId: vaultProgramId,
    keys: [
      { pubkey: vaultAccount, isSigner: false, isWritable: true },
      { pubkey: authority, isSigner: true, isWritable: false }
    ],
    data: Buffer.from([/* instruction data */])
  })
);

Analytics & Monitoring

Vault Analytics

const analytics = await client.vaults.getAnalytics('vault_abc123', {
  period: '30d'
});

console.log(`Total spent: ${analytics.totalSpent / 1_000_000} USDC`);
console.log(`Transaction count: ${analytics.transactionCount}`);
console.log(`Average transaction: ${analytics.averageTransaction / 1_000_000} USDC`);
console.log(`Top merchants:`, analytics.topMerchants);
console.log(`Spending by category:`, analytics.categoryBreakdown);

Budget Tracking

await client.vaults.setBudget('vault_abc123', {
  monthly: 50000_000_000, // 50,000 USDC
  quarterly: 140000_000_000,
  annual: 500000_000_000,
  alertThreshold: 80 // Alert at 80% utilization
});

const budgetStatus = await client.vaults.getBudgetStatus('vault_abc123');
console.log(`Monthly: ${budgetStatus.monthly.percentUsed}% used`);
console.log(`Remaining: ${budgetStatus.monthly.remaining / 1_000_000} USDC`);

Best Practices

1. Multi-Signature for High-Value Vaults

// Production treasury with multi-sig
const vault = await client.vaults.create({
  name: 'Company Treasury',
  currency: 'USDC',
  network: 'solana',
  initialDeposit: 1000000_000_000, // 1M USDC
  signers: [cfo, cto, ceo],
  threshold: 2
});

2. Separate Vaults by Purpose

// Operational vaults
const vaults = await Promise.all([
  client.vaults.create({ name: 'Operating Expenses', currency: 'USDC' }),
  client.vaults.create({ name: 'Payroll', currency: 'USDC' }),
  client.vaults.create({ name: 'Emergency Reserve', currency: 'USDC' }),
  client.vaults.create({ name: 'Growth Capital', currency: 'USDC' })
]);

3. Monitor On-Chain State

// Regular vault health checks
async function monitorVault(vaultId: string) {
  const vault = await client.vaults.retrieve(vaultId);
  const balance = await client.vaults.getBalance(vaultId);
  
  if (vault.status !== 'active') {
    console.warn(`Vault ${vaultId} status: ${vault.status}`);
  }
  
  if (balance.available < 1000_000_000) {
    console.warn(`Low balance: ${balance.available / 1_000_000} USDC`);
  }
}

4. Audit Trail

const auditLogs = await client.vaults.getAuditLogs('vault_abc123', {
  limit: 100,
  includeOnChainEvents: true
});

auditLogs.forEach(log => {
  console.log(`${log.timestamp}: ${log.action} by ${log.actor}`);
  console.log(`  Transaction: ${log.signature}`);
});

Troubleshooting

Vault Frozen

const vault = await client.vaults.retrieve('vault_abc123');

if (vault.status === 'frozen') {
  console.log('Vault is frozen');
  // Check freeze reason
  const freezeDetails = await client.vaults.getFreezeDetails('vault_abc123');
  console.log(`Reason: ${freezeDetails.reason}`);
  console.log(`Frozen at: ${freezeDetails.frozenAt}`);
}

Insufficient Balance

try {
  await client.transfers.create({
    sourceVaultId: 'vault_abc123',
    destinationVaultId: 'vault_xyz789',
    amount: 10000_000_000
  });
} catch (error) {
  if (error.code === 'insufficient_balance') {
    const balance = await client.vaults.getBalance('vault_abc123');
    console.log(`Available: ${balance.available / 1_000_000} USDC`);
    console.log(`Required: 10,000 USDC`);
  }
}

Next Steps

• Programmable Spending Policies - Card-based authorization

• Authorization Engine - Policy documentation

• Real-Time Events - Vault event streams

• API Reference - Complete vault endpoints