Architecting Policy-Enforced Smart Contracts for Autonomous AI Agents on Stellar Soroban

// contracts/vault/src/types.rs
use soroban_sdk::{contracttype, Address, String};

#[contracttype]
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct AgentPolicy {
    pub agent: Address,
    pub token: Address,
    pub max_per_tx: i128,
    pub epoch_limit: i128,
    pub epoch_window_ledgers: u32,
    pub active: bool,
}

#[contracttype]
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct EpochState {
    pub window_start_ledger: u32,
    pub spent_in_window: i128,
}

#[contracttype]
pub enum DataKey {
    Admin,
    Paused,
    Policy(Address),    // Maps Agent Address -> AgentPolicy
    Epoch(Address),     // Maps Agent Address -> EpochState
}

// contracts/vault/src/lib.rs
#![no_std]
use soroban_sdk::{contract, contractimpl, token, Address, Env, IntoVal};

mod types;
use types::{AgentPolicy, DataKey, EpochState};

#[contract]
pub struct AgentVaultContract;

#[contractimpl]
impl AgentVaultContract {
    /// Initialize the vault with an administrative owner
    pub fn initialize(env: Env, admin: Address) {
        if env.storage().instance().has(&DataKey::Admin) {
            panic!("Vault already initialized");
        }
        env.storage().instance().set(&DataKey::Admin, &admin);
        env.storage().instance().set(&DataKey::Paused, &false);
    }

    /// Owner defines or updates an on-chain policy for an autonomous agent
    pub fn set_agent_policy(env: Env, policy: AgentPolicy) {
        let admin: Address = env.storage().instance().get(&DataKey::Admin).expect("Uninitialized");
        admin.require_auth(); // Cryptographically verifies signature of Vault Owner

        env.storage().persistent().set(&DataKey::Policy(policy.agent.clone()), &policy);
    }

    /// Autonomous Agent executes a payment within its policy envelope
    pub fn spend(env: Env, agent: Address, recipient: Address, amount: i128) {
        // 1. Verify agent authorization
        agent.require_auth();

        // 2. Verify vault is not paused
        let is_paused: bool = env.storage().instance().get(&DataKey::Paused).unwrap_or(false);
        if is_paused {
            panic!("Vault operations are paused");
        }

        // 3. Load agent policy from Persistent storage
        let policy: AgentPolicy = env
            .storage()
            .persistent()
            .get(&DataKey::Policy(agent.clone()))
            .expect("No policy configured for this agent");

        if !policy.active {
            panic!("Agent policy is inactive");
        }

        // 4. Invariant Check: Per-Transaction Ceiling
        if amount > policy.max_per_tx {
            panic!("Amount exceeds single-transaction cap");
        }

        // 5. Invariant Check: Sliding Window Epoch Cap
        let current_ledger = env.ledger().sequence();
        let mut epoch: EpochState = env
            .storage()
            .temporary()
            .get(&DataKey::Epoch(agent.clone()))
            .unwrap_or(EpochState {
                window_start_ledger: current_ledger,
                spent_in_window: 0,
            });

        // Reset epoch if window expired
        if current_ledger - epoch.window_start_ledger >= policy.epoch_window_ledgers {
            epoch.window_start_ledger = current_ledger;
            epoch.spent_in_window = 0;
        }

        if epoch.spent_in_window + amount > policy.epoch_limit {
            panic!("Amount exceeds epoch spending limit");
        }

        // Update state
        epoch.spent_in_window += amount;
        env.storage().temporary().set(&DataKey::Epoch(agent.clone()), &epoch);

        // 6. Execute token transfer via Soroban Token Client
        let token_client = token::Client::new(&env, &policy.token);
        token_client.transfer(&env.current_contract_address(), &recipient, &amount);
    }
}

// contracts/vault/src/test.rs
#[cfg(test)]
mod test {
    use super::*;
    use soroban_sdk::{testutils::Address as _, Env};

    #[test]
    fn test_agent_spending_enforcement() {
        let env = Env::default();
        env.mock_all_auths(); // Mocks cryptographic signatures for simulation

        let admin = Address::generate(&env);
        let agent = Address::generate(&env);
        let recipient = Address::generate(&env);
        let token_contract = env.register_stellar_asset_contract_v2(admin.clone());

        let vault_id = env.register(AgentVaultContract, ());
        let client = AgentVaultContractClient::new(&env, &vault_id);

        client.initialize(&admin);

        // Configure policy: Max 50 per TX, Max 100 per 100 ledgers
        let policy = AgentPolicy {
            agent: agent.clone(),
            token: token_contract.address(),
            max_per_tx: 50,
            epoch_limit: 100,
            epoch_window_ledgers: 100,
            active: true,
        };
        client.set_agent_policy(&policy);

        // Step 1: Valid spend should succeed
        client.spend(&agent, &recipient, &40);

        // Step 2: Single TX exceeding cap should panic
        // client.spend(&agent, &recipient, &60) -> Panics: "Amount exceeds single-transaction cap"
    }
}