Safeguard Delegation Program

A Solana smart contract enabling multi-agent delegation for SPL tokens. Users authorize multiple AI agent wallets with independent spending limits while maintaining a single SPL token delegation.

Table of Contents

• Problem
• Solution: Proxy Delegate Pattern
• Program IDs
• TypeScript Client
  • Installation
  • Usage
  • API Reference
  • AgentBalance
• Account Structures
  • DelegationVault
  • AgentDelegation
  • PDA Derivation
• Data Model
• Instructions
  • revoke_agent vs remove_agent
• Sequence Diagrams
  • 1. Vault Initialization
  • 2. MCP Tool Execution (Transfer)
  • 3. Agent Revoke and Restore
  • 4. Emergency Revoke
  • 5. Agent Removal
• Security & Trust Model
  • Authorization Requirements
  • PDA Isolation
  • What is Trustless
  • What Requires Trusting Safeguard
  • Worst Case: Backend Compromise
  • User Self-Protection
• Integration with Safeguard
• Development
  • Build
  • Test
  • Deploy
• Reference
  • Error Codes

Problem

Solana's SPL Token program only allows one delegate per token account. Safeguard needs multiple agent connections per external wallet, each with independent spending limits.

Solution: Proxy Delegate Pattern

The program acts as an intermediary between the user's token account and multiple agent wallets.

┌──────────────────┐     SPL Approve      ┌─────────────────────┐
│  User's Token    │─────────────────────>│  Safeguard Program  │
│  Account (ATA)   │   (one-time setup)   │  Authority PDA      │
└──────────────────┘                      └─────────────────────┘
                                                   │
                                                   │ Internal routing
                                                   ▼
                              ┌────────────────────┬────────────────────┬
                              │                    │                    │
                              ▼                    ▼                    ▼
                    ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐
                    │ Agent Connection │ │ Agent Connection │ │ Agent Connection │
                    │    Wallet #1     │ │    Wallet #2     │ │    Wallet #3     │
                    │ (max spend: 100) │ │ (max spend: 500) │ │(max spend: 1000) │
                    └──────────────────┘ └──────────────────┘ └──────────────────┘

Program IDs

| Network | Program ID | | ------- | ---------------------------------------------- | | Devnet | 2NFrZTi8A51yYe5GMXQap2up1HLsGuB95oAaNexw2sHM | | Mainnet | 2NFrZTi8A51yYe5GMXQap2up1HLsGuB95oAaNexw2sHM |

TypeScript Packages

This repository ships two packages:

| Package | Description | | ------------------------------------ | -------------------------------------------------------- | | @exodus/safeguard-solana | TypeScript client for building and querying transactions | | @exodus/safeguard-solana-interface | IDL and TypeScript types for the on-chain program |

Installation

pnpm add @exodus/safeguard-solana
# Optional: only needed if you need the IDL or raw types directly
pnpm add @exodus/safeguard-solana-interface

Usage

import { SafeguardDelegationClient } from "@exodus/safeguard-solana";
import { safeguardDelegation } from "@exodus/safeguard-solana-interface";
import type { SafeguardDelegation } from "@exodus/safeguard-solana-interface";

const client = new SafeguardDelegationClient("https://api.devnet.solana.com");

// Derive PDA addresses
const vaultPda = client.deriveVaultPda({
  owner: ownerPublicKey,
  userTokenAccount,
});
const delegationPda = client.deriveDelegationPda({
  vault: vaultPda,
  agentWallet: agentWalletPublicKey,
});

// Build a transaction (returns base64-encoded serialized tx for the user to sign)
// payer can differ from owner to sponsor transaction fees on the owner's behalf
// mint is required so the client can create the owner's ATA if it doesn't exist yet
const tx = await client.buildInitializeVaultTx({
  owner: ownerPublicKey,
  payer: payerPublicKey, // covers rent and tx fee; pass ownerPublicKey if owner pays
  mint: usdcMintPublicKey,
  userTokenAccount,
  agent: {
    agentWallet: agentWalletPublicKey,
    limits: { label: "My AI Agent", maxSpendAmount },
  },
});

API Reference

| Method | Returns | Description | | -------------------------------- | -------------------------- | -------------------------------------------------------------------------------------------------------- | | deriveVaultPda(params) | PublicKey | Derive vault PDA address | | deriveDelegationPda(params) | PublicKey | Derive delegation PDA address | | buildInitializeVaultTx(params) | Promise<string> | Serialized tx: create owner ATA (if needed) + vault; optionally bundles first agent if agent provided | | buildAddAgentTx(params) | Promise<string> | Serialized tx: add agent to existing vault | | buildRevokeAgentTx(params) | Promise<string> | Serialized tx: deactivate agent (account kept) | | buildRestoreAgentTx(params) | Promise<string> | Serialized tx: reactivate a revoked agent | | buildRemoveAgentTx(params) | Promise<string> | Serialized tx: permanently close agent account; automatically closes vault if it's the last active agent | | buildUpdateLimitsTx(params) | Promise<string> | Serialized tx: modify agent spending limits | | buildEmergencyRevokeTx(params) | Promise<string> | Serialized tx: pause vault + zero out SPL delegation (delegate field preserved, amount set to 0) | | buildUnpauseVaultTx(params) | Promise<string> | Serialized tx: unpause vault + SPL approve for newDelegatedAmount (required param) | | buildExecuteTransferTx(params) | Promise<string> | Serialized tx: agent executes a token transfer | | buildCloseVaultTx(params) | Promise<string> | Serialized tx: remove all agent accounts, SPL revoke, then close vault (funder reclaims rent) | | getAgentBalance(params) | Promise<AgentBalance> | Query current spend capacity for an agent | | getVaults(owner) | Promise<VaultInfo[]> | Fetch all vaults owned by a wallet | | getTokenVault(params) | Promise<VaultInfo\|null> | Fetch vault for a specific token mint |

All methods (except getVaults) accept a named param object. See the exported Build*Params, Derive*Params, and Get*Params interfaces in @exodus/safeguard-solana for the exact shape of each.

AgentBalance

getAgentBalance returns the current spending state for an agent:

interface AgentBalance {
  maxSpendAmount: NumberUnit; // Configured lifetime cap
  totalSpent: NumberUnit; // Amount used so far
  tokenAccountBalance: NumberUnit; // Actual balance in token account
  expendableBalance: NumberUnit; // min(remaining allowance, token balance)
}

expendableBalance is the amount the agent can actually spend right now — capped by both the remaining delegation allowance and the real token account balance.

AgentLimits

Used by buildAddAgentTx to configure an agent's spending parameters:

interface AgentLimits {
  label: string; // Human-readable name (max 64 chars)
  maxSpendAmount: NumberUnit; // Lifetime spending cap
  expiresAt?: number; // Optional Solana slot number for expiry
}

VaultInfo

Returned by getVaults and getTokenVault:

interface VaultInfo {
  vaultPda: PublicKey; // On-chain vault PDA address
  userTokenAccount: PublicKey; // Token account delegated to this vault
  mint: PublicKey; // SPL token mint address
  isPaused: boolean; // Whether the vault is emergency-paused
  activeDelegationsCount: number; // Number of active agents
}

Account Structures

DelegationVault

Created per user token account. Tracks total delegation and manages agent connections.

| Field | Type | Description | | -------------------------- | ------ | -------------------------------------------------------- | | owner | Pubkey | User's wallet address | | funder | Pubkey | Account that paid vault rent (receives it back on close) | | user_token_account | Pubkey | Token account that delegated to this vault | | mint | Pubkey | SPL token mint address | | total_delegated_amount | u64 | Amount approved via SPL Token | | active_delegations_count | u32 | Number of currently active agents | | total_delegations_count | u32 | Total agents ever added (including revoked/removed) | | is_paused | bool | Emergency freeze flag | | bump | u8 | PDA bump seed | | version | u8 | Account schema version |

AgentDelegation

Created per agent per vault. Tracks lifetime spending limit and usage.

| Field | Type | Description | | ------------------ | ----------- | ----------------------------------------------------- | | vault | Pubkey | Parent vault reference | | funder | Pubkey | Account that paid delegation rent (reclaims on close) | | agent_wallet | Pubkey | Authorized signer (server wallet) | | label | String | Human-readable name (max 64 chars) | | max_spend_amount | u64 | Lifetime spending cap | | total_spent | u64 | Cumulative amount spent | | is_active | bool | Whether delegation is active | | expires_at | Option | Optional expiry slot number | | bump | u8 | PDA bump seed | | version | u8 | Account schema version |

PDA Derivation

Vault PDA      = hash("vault",      owner,            userTokenAccount)
Delegation PDA = hash("delegation", vault,            agentWallet)

Each delegation is cryptographically bound to a specific vault — an agent authorized for Vault A cannot spend from Vault B.

Data Model

On-Chain Entities (Solana - Trustless)

erDiagram
    Mint ||--o{ TokenAccount : "mints"
    TokenAccount ||--o| DelegationVault : "delegates to"
    DelegationVault ||--o{ AgentDelegation : "authorizes"
    AgentDelegation }o--|| ServerWallet : "signed by"

    Mint {
        pubkey address PK
        u8 decimals
        string symbol
    }

    TokenAccount {
        pubkey address PK
        pubkey owner
        pubkey mint FK
        u64 amount
        pubkey delegate
        u64 delegated_amount
    }

    DelegationVault {
        pubkey owner PK
        pubkey funder
        pubkey user_token_account FK
        pubkey mint FK
        u64 total_delegated_amount
        u32 active_delegations_count
        u32 total_delegations_count
        bool is_paused
        u8 bump
        u8 version
    }

    AgentDelegation {
        pubkey vault FK
        pubkey funder
        pubkey agent_wallet FK
        string label
        u64 max_spend_amount
        u64 total_spent
        bool is_active
        u64 expires_at
        u8 bump
        u8 version
    }

    ServerWallet {
        pubkey address PK
    }

Instructions

| Instruction | Signer | Description | | ------------------ | ------ | ----------------------------------------------------------------------------------------- | | initialize_vault | Owner | Create vault PDA; the TypeScript client optionally bundles add_agent in the same tx | | add_agent | Owner | Authorize an additional agent with a spending limit; re-approves SPL delegation | | revoke_agent | Owner | Deactivate agent (account kept, can be restored); re-approves SPL with reduced total | | restore_agent | Owner | Reactivate a previously revoked agent; re-approves SPL with restored total | | remove_agent | Owner | Permanently close agent account, return rent; re-approves SPL with remaining amount | | execute_transfer | Agent | Transfer within lifetime spend limit | | update_limits | Owner | Modify agent max_spend_amount and/or expiry; re-approves SPL delegation when amount grows | | emergency_revoke | Owner | Pause vault + zero out SPL delegation amount (delegate field preserved; amount set to 0) | | unpause_vault | Owner | Unpause vault and re-approve SPL delegation |

revoke_agent vs remove_agent

Both deactivate an agent, but differ in reversibility and account lifecycle:

| Aspect | revoke_agent | remove_agent | | --------------- | --------------------------------- | ------------------------------ | | Agent status | Deactivated (is_active = false) | Deleted | | Account | Kept on-chain | Closed, rent returned to owner | | Reversible? | Yes — via restore_agent | No | | SPL re-approval | Yes — reduces total allocated | Yes — reduces total allocated | | Use case | Temporary suspension | Permanent removal |

restore_agent will fail if the vault is paused, the delegation has expired, or the vault has reached the maximum agent count.

Sequence Diagrams

1. Vault Initialization

initialize_vault atomically creates the vault PDA, the first agent delegation, and calls the SPL Token approve CPI — all in a single transaction. The user signs only once.

sequenceDiagram
    participant User as User Wallet
    participant Frontend as Safeguard Frontend
    participant Backend as Auth Server
    participant Solana as Solana Network
    participant Program as Safeguard Program

    User->>Frontend: Connect wallet
    Frontend->>User: Request wallet signature
    User->>Frontend: Sign authentication

    Frontend->>Backend: Create vault + first agent request
    Backend->>Backend: Generate vault PDA + delegation PDA
    Backend->>Frontend: Return initialize_vault transaction

    Frontend->>User: Request user signature (initialize_vault tx)
    User->>Solana: Sign & send initialize_vault tx
    Program->>Program: Create DelegationVault account
    Program->>Program: Create AgentDelegation account
    Program->>Solana: CPI: SPL Token Approve (vault PDA as delegate)
    Program->>Solana: Emit VaultInitialized event
    Solana-->>Backend: Transaction confirmed

    Backend->>Frontend: Vault + agent created successfully
    Frontend->>User: Display vault status

2. MCP Tool Execution (Transfer)

sequenceDiagram
    participant Agent as AI Agent (ChatGPT/etc)
    participant MCP as MCP Server
    participant Backend as Auth Server
    participant Policy as Policy Evaluator
    participant Solana as Solana Network
    participant Program as Safeguard Program

    Agent->>MCP: tools/call transaction_send
    MCP->>Backend: POST /api/mcp (with API key)

    Backend->>Backend: Validate API key
    Backend->>Backend: Load agent connection

    Backend->>Policy: Evaluate transfer request
    Policy->>Policy: Check off-chain rules
    Policy-->>Backend: Allowed (or denied)

    alt Policy Denied
        Backend-->>MCP: Error: Policy violation
        MCP-->>Agent: Transfer denied by policy
    end

    Backend->>Solana: Call execute_transfer
    Program->>Program: Check vault not paused
    Program->>Program: Check delegation active
    Program->>Program: Check not expired
    Program->>Program: Check cumulative spend <= max_spend_amount

    alt Limit Exceeded
        Program-->>Backend: Error: SpendLimitExceeded
        Backend-->>MCP: Error: On-chain limit exceeded
        MCP-->>Agent: Transfer denied by limits
    end

    Program->>Solana: CPI: SPL Token Transfer
    Program->>Program: Update total_spent
    Program->>Solana: Emit TransferExecuted event
    Solana-->>Backend: Transaction confirmed

    Backend-->>MCP: Success response
    MCP-->>Agent: Transfer completed

3. Agent Revoke and Restore

revoke_agent deactivates an agent without closing its account — useful for temporary suspensions. restore_agent reactivates it.

sequenceDiagram
    participant User as User Wallet
    participant Frontend as Safeguard Frontend
    participant Backend as Auth Server
    participant Solana as Solana Network
    participant Program as Safeguard Program

    User->>Frontend: Pause agent connection
    Frontend->>Backend: POST /agent-connections/:id/revoke
    Backend->>Solana: Call revoke_agent

    Program->>Program: Set delegation.is_active = false
    Program->>Program: Decrement vault.active_delegations_count
    Program->>Program: Reduce vault.total_allocated by max_spend_amount
    Program->>Solana: CPI: SPL Token Approve (updated total)
    Program->>Solana: Emit AgentRevoked event
    Program->>Solana: Emit VaultStateChanged event
    Solana-->>Backend: Transaction confirmed

    Backend->>Backend: Update agent status in DB
    Backend-->>Frontend: Agent paused
    Frontend->>User: Display paused status

    Note over User,Program: Agent can no longer execute transfers

    User->>Frontend: Restore agent connection
    Frontend->>Backend: POST /agent-connections/:id/restore
    Backend->>Solana: Call restore_agent

    Program->>Program: Check vault not paused
    Program->>Program: Check max agents not reached
    Program->>Program: Check delegation not expired
    Program->>Program: Set delegation.is_active = true
    Program->>Program: Increment vault.active_delegations_count
    Program->>Program: Restore vault.total_allocated by max_spend_amount
    Program->>Solana: CPI: SPL Token Approve (updated total)
    Program->>Solana: Emit AgentRestored event
    Program->>Solana: Emit VaultStateChanged event
    Solana-->>Backend: Transaction confirmed

    Backend->>Backend: Update agent status in DB
    Backend-->>Frontend: Agent restored
    Frontend->>User: Display active status

4. Emergency Revoke

sequenceDiagram
    participant User as User Wallet
    participant Frontend as Safeguard Frontend
    participant Backend as Auth Server
    participant Solana as Solana Network
    participant Program as Safeguard Program

    User->>Frontend: Click Emergency Revoke
    Frontend->>User: Confirm action
    User->>Frontend: Confirm

    Frontend->>Backend: POST /vaults/:id/emergency-revoke
    Backend->>Solana: Call emergency_revoke

    Program->>Program: Set vault.is_paused = true
    Program->>Program: Set total_delegated_amount = 0
    Program->>Solana: CPI: SPL Token Approve(0)
    Program->>Solana: Emit VaultPaused event
    Program->>Solana: Emit EmergencyRevokeTriggered event
    Solana-->>Backend: Transaction confirmed

    Backend->>Backend: Mark all agents as revoked
    Backend-->>Frontend: Revoke successful
    Frontend->>User: Display revoked status

    Note over User,Program: All agent transfers now blocked

5. Agent Removal

When removing an agent the TypeScript client checks active_delegations_count on-chain. If the agent being removed is the last active one, the client automatically batches remove_agent + SPL revoke + close_vault into a single transaction, closing all remaining delegation PDAs (including any revoked ones) and the vault itself. The vault funder (not the owner) signs the close_vault instruction and reclaims the vault rent.

sequenceDiagram
    participant User as User Wallet
    participant Frontend as Safeguard Frontend
    participant Backend as Auth Server
    participant Client as TS Client
    participant Solana as Solana Network
    participant Program as Safeguard Program

    User->>Frontend: Remove agent connection
    Frontend->>User: Confirm removal
    User->>Frontend: Confirm

    Frontend->>Backend: DELETE /agent-connections/:id
    Backend->>Client: buildRemoveAgentTx(params)
    Client->>Solana: Fetch vault (active_delegations_count)

    alt Last active agent (count == 1)
        Client->>Client: Build close_vault tx (removes all PDAs + SPL revoke + vault)
        Backend->>Solana: Submit close_vault tx (signed by funder)
        Program->>Program: Close all delegation accounts
        Client->>Solana: SPL Token Revoke (clears delegate on token account)
        Program->>Program: Close vault account (checks delegate cleared)
        Program->>Program: Return vault rent to funder
        Program->>Solana: Emit AgentRemoved + VaultClosed events
        Solana-->>Backend: Transaction confirmed
        Backend->>Backend: Delete vault + delegation records from DB
    else More agents remain
        Client->>Client: Build remove_agent tx
        Backend->>Solana: Submit remove_agent tx (signed by user)
        Program->>Program: Decrement vault.active_delegations_count
        Program->>Program: Reduce vault.total_allocated
        Program->>Program: Close delegation account
        Program->>Program: Return rent to owner
        Program->>Solana: CPI: SPL Token Approve (updated total)
        Program->>Solana: Emit AgentRemoved event
        Solana-->>Backend: Transaction confirmed
        Backend->>Backend: Remove agent delegation record from DB
    end

    Backend-->>Frontend: Agent removed
    Frontend->>User: Display updated agent list

Security & Trust Model

User Controls

• Create vault with first agent (single transaction)
• Add/remove/revoke/restore additional agents
• Update spending limits
• Emergency freeze all
• Revoke SPL delegation directly (bypass program)

Agent Controls (within limits)

• Execute transfers up to max_spend_amount lifetime cap
• Cannot exceed the lifetime spend limit
• Cannot transfer after expiry
• Cannot reactivate revoked delegation

Authorization Requirements

Before any agent can spend from a user's wallet, a user-signed transaction is required:

| initialize_vault (first agent) | add_agent (additional) | | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | | User signs one transaction that atomically creates the vault, first AgentDelegation, and approves SPL token delegation | User (vault owner) signs to authorize each new agent_wallet pubkey with its spending limit |

Without a user signature, nothing can be created on-chain.

The Safeguard backend cannot unilaterally add itself as an agent — only the vault owner's signature can authorize an agent.

PDA Isolation (Cross-Vault Protection)

Each agent delegation is cryptographically bound to a specific vault:

Delegation PDA = hash("delegation", vault_pda, agent_wallet)
                                    ─────────
                                        │
                                        └── Agent authorized for Vault A
                                            CANNOT spend from Vault B

What is Trustless (On-Chain Guarantees)

These guarantees are enforced by the Solana program and cannot be bypassed by anyone, including Safeguard:

| Guarantee | Enforcement | | ------------------------------------ | ----------------------------------------------- | | Lifetime spend limit cannot exceed | On-chain cumulative check before every transfer | | Only authorized agents can transfer | PDA derivation + signature verification | | Users can always emergency revoke | Owner signature required, always succeeds | | Agents cannot reactivate themselves | Only owner can call add_agent/restore_agent | | Limits cannot be increased by agents | Only owner can call update_limits | | Expired delegations cannot transfer | On-chain timestamp check |

What Requires Trusting Safeguard (Off-Chain)

| Aspect | Trust Requirement | | -------------------------- | --------------------------------------- | | Server wallet private keys | Safeguard stores these securely | | API key → wallet mapping | Database integrity | | Policy enforcement | Off-chain rules applied before on-chain | | Transfer initiation | Only on legitimate AI agent requests |

Worst Case: Backend Compromise

If an attacker fully compromises the Safeguard backend:

| Attacker CAN | Attacker CANNOT | | --------------------------------------------------- | -------------------------------------------- | | Access server wallet keys | Exceed on-chain limits | | Initiate transfers for any agent they have keys for | Spend from vaults that never added the agent | | Bypass off-chain policy rules | Prevent user emergency revoke | | | Modify on-chain limits | | | Reactivate revoked agents |

Maximum damage = sum of (max_spend_amount - total_spent) across all active agents.

The on-chain limits act as a "blast radius cap" — even total backend compromise cannot exceed the spending limits users configured.

User Self-Protection

| Action | Effect | | ----------------------- | ----------------------------- | | Set conservative limits | Reduces maximum possible loss | | Set expiry dates | Automatic agent deactivation | | Monitor on-chain events | Detect unauthorized transfers | | Emergency revoke | Instantly stops all agents | | Direct SPL revoke | Bypass Safeguard entirely |

Trust Model Summary

| Layer | Trust Model | Failure Impact | | ------------------ | --------------- | -------------------------- | | On-chain program | Trustless | Cannot fail (code is law) | | On-chain limits | Trustless | Cannot be exceeded | | User authorization | Trustless | Cannot be bypassed | | Backend security | Trust Safeguard | Limited by on-chain limits | | Policy enforcement | Trust Safeguard | Limited by on-chain limits |

Design Philosophy: The on-chain program assumes the backend might be compromised and enforces hard limits regardless. Users should set max_spend_amount to the maximum they're comfortable losing in a worst-case scenario.

Integration with Safeguard

Architecture Overview

┌─────────────────────────────────────────────────────────────────────────────────┐
│                              SAFEGUARD SYSTEM                                   │
│                                                                                 │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐       │
│  │   Frontend  │───>│ Auth Server │───>│   Policy    │───>│  On-Chain   │       │
│  │   (Next.js) │    │  (Fastify)  │    │  Evaluator  │    │  (Solana)   │       │
│  └─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘       │
│        │                  │                  │                  │               │
│        │                  │                  │                  │               │
│        ▼                  ▼                  ▼                  ▼               │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐       │
│  │    User     │    │   Agent     │    │   Wallet    │    │ Safeguard   │       │
│  │   Wallet    │    │ Connection  │    │   Policy    │    │ Delegation  │       │
│  │  (Browser)  │    │   (DB)      │    │   Rules     │    │  Program    │       │
│  └─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘       │
│                                                                                 │
└─────────────────────────────────────────────────────────────────────────────────┘

Limit Enforcement Model

The system uses a complementary limit model:

• Off-chain (Policy Evaluator): Nuanced rules (time-of-day, recipient whitelist, AI-based risk)
• On-chain (Solana Program): Hard safety net (lifetime spend cap via max_spend_amount)

This provides defense-in-depth: even if the off-chain system is compromised, the on-chain limit prevents catastrophic losses.

API Key vs On-Chain Relationship

┌─────────────────────────────────────────────────────────────────────────┐
│                                                                         │
│                         OFF-CHAIN (Backend)                             │
│  ┌─────────────┐      ┌─────────────────────┐      ┌────────────────┐  │
│  │   API Key   │─────>│   Agent Connection  │─────>│ Server Wallet  │  │
│  │  (secret)   │      │      (database)     │      │   (keypair)    │  │
│  └─────────────┘      └─────────────────────┘      └────────────────┘  │
│                                                            │           │
│        Used for MCP            Stores mapping              │           │
│        authentication          and metadata                │           │
│                                                            │           │
└────────────────────────────────────────────────────────────┼───────────┘
                                                             │
                                          Signs transactions │
                                          with private key   │
                                                             ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                                                                         │
│                          ON-CHAIN (Solana)                              │
│                                                                         │
│  ┌─────────────────────┐           ┌─────────────────────┐             │
│  │   DelegationVault   │           │   AgentDelegation   │             │
│  │   (user's vault)    │◄─────────►│   agent_wallet =    │             │
│  │                     │           │   server wallet     │             │
│  └─────────────────────┘           │   PUBKEY only       │             │
│                                    └─────────────────────┘             │
│                                                                         │
│        The API key NEVER touches the blockchain.                        │
│        Only the server wallet's PUBLIC KEY is stored on-chain.          │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

Development

Prerequisites

• Rust 1.89+ (for edition 2024 support)
• Solana CLI 3.0+
• Anchor CLI 0.32+
• Node.js 18+

Build

From the repo root:

pnpm contracts:solana:build

Or from the package directory:

# Build TypeScript client + copy IDL to dist/
pnpm build

# Rebuild IDL only (after Rust program changes)
pnpm idl:build

Test

From the repo root:

pnpm contracts:solana:test

Or from the package directory:

pnpm test

anchor test handles starting the local validator, deploying the program, and running the full test suite automatically.

Deploy

1. Set up your deploy wallet

Copy the env example and set the absolute path to your deploy keypair:

cp .env.example .env

Edit .env:

DEPLOY_WALLET_PATH=/absolute/path/to/deploy-wallet.json

• DEPLOY_WALLET_PATH — the upgrade authority wallet used to sign and fund the upgrade transaction. This wallet must be the current upgrade authority for program 2NFrZTi8A51yYe5GMXQap2up1HLsGuB95oAaNexw2sHM.

Note: use an absolute path — ~ is not expanded in .env files.

2. Fund the deploy wallet

The deploy wallet needs enough SOL to cover the program data account rent (~2.4 SOL for the current binary size). Use the Solana faucet UI to airdrop devnet SOL:

https://faucet.solana.com/

Paste the deploy wallet address and request SOL. You can check the balance with:

solana balance <DEPLOY_WALLET_ADDRESS> --url devnet

3. Transfer upgrade authority (first time only)

If upgrading an existing program, transfer the upgrade authority to your deploy wallet:

solana program set-upgrade-authority <PROGRAM_ID> \
  --new-upgrade-authority <DEPLOY_WALLET_ADDRESS> \
  --skip-new-upgrade-authority-signer-check \
  --url devnet

4. Deploy

From the repo root:

# Devnet
pnpm contracts:solana:deploy:devnet

# Mainnet
pnpm contracts:solana:deploy:mainnet

Reference

Error Codes

| Code | Name | Description | | ---- | ----------------------------- | -------------------------------------------------------------- | | 6000 | VaultPaused | Vault is paused - no operations allowed | | 6001 | DelegationInactive | Delegation is not active | | 6002 | DelegationExpired | Delegation has expired | | 6003 | SpendLimitExceeded | Transfer exceeds lifetime spend limit | | 6004 | InvalidTokenAccountOwner | Token account not owned by signer | | 6005 | MintMismatch | Token mint doesn't match vault | | 6006 | InsufficientDelegation | SPL delegation insufficient | | 6007 | ArithmeticOverflow | Math overflow | | 6008 | LabelTooLong | Agent label exceeds 64 chars | | 6009 | Unauthorized | Only owner can perform action | | 6010 | InvalidExpiry | Expiry must be in the future | | 6011 | MaxAgentsReached | Vault has reached the maximum agent count | | 6012 | DelegationAlreadyActive | Delegation is already active | | 6013 | InvalidAgentWallet | Agent wallet must differ from vault owner | | 6014 | InvalidAmount | Amount must be greater than zero | | 6015 | AgentVaultMismatch | Agent account does not belong to this vault | | 6016 | VaultStillDelegated | Token account still delegating to vault; revoke before closing | | 6017 | VaultNotPaused | Vault is not paused | | 6018 | InvalidDelegationAccountCount | Remaining accounts count must match total delegation count |