REAPP — Agentic Payment Protocol for Stellar

The Key Custody Problem

The strongest security argument in the REAPP proposal — "no user key custody; agent signs only scoped invocations" — is directly supported by Soroban's host-managed authorization model and the account abstraction pattern.

When a contract calls require_auth() on a contract account, the Soroban host calls __check_auth with a signature payload plus the list of invocations being authorized — enabling flexible custom authorization policies. The __check_auth function is reserved and only callable through host-managed auth, making certain policy designs inherently safer.

Authorization Flow

Soroban Host-Managed Authorization Model

The agent signs only the specific contract invocation with exact parameters. The user's private key is never involved in payment execution — only in the one-time mandate registration.

MandateRegistry Contract Interface

#[contract]
pub struct MandateRegistry;

#[contractimpl]
impl MandateRegistry {
  // Register a new mandate (called by user or their smart wallet)
  pub fn register_mandate(env: Env, mandate: MandateConfig) -> MandateId;

  // Called by REAPP validator before payment execution
  pub fn validate_and_consume(
    env: Env,
    mandate_id: MandateId,
    amount: i128,
    token: Address,
    merchant: Address
  ) -> Result<(), Error>;

  // Agent-triggered payment within mandate bounds
  pub fn execute_payment(
    env: Env,
    mandate_id: MandateId,
    to: Address,
    amount: i128,
    token: Address
  ) -> Result<TxHash, Error>;

  // Revoke a mandate (user only)
  pub fn revoke_mandate(env: Env, mandate_id: MandateId);
}

MandateConfig Structure

#[contracttype]
pub struct MandateConfig {
  pub user: Address,              // mandate owner
  pub agent: Address,             // authorized agent key
  pub token: Address,             // USDC, XLM, or any SEP-41 token
  pub per_tx_limit: i128,         // max per transaction
  pub period_limit: i128,         // max per time period
  pub period_ledgers: u32,        // period length in ledgers
  pub allowed_merchants: Vec<Address>, // empty = any
  pub expiry_ledger: u32,         // mandate TTL
  pub intent_hash: BytesN<32>,    // AP2 IntentMandate hash (audit link)
}

Mandate Lifecycle State Machine

MandateRegistry State Machine

Soroban enforces all five checks atomically. Any failure reverts the entire transaction — there is no partial payment state.

Storage Architecture

Soroban Contract Storage Model

Period spend counters use Temporary storage — they auto-expire without manual intervention, reducing contract complexity and attack surface.

OpenZeppelin Smart Account Integration

REAPP builds on OpenZeppelin's Stellar smart account framework, which supports delegated signers and policy/rule composition. OpenZeppelin has published audits for its Stellar contracts library — meaning REAPP inherits audited building blocks even before its own mandate registry undergoes review.

Delegated signers scoped to specific contract functions and amounts
Policy signer registered for execute_payment only — not general wallet access
Time-window constraints enforced at the Smart Account layer
Revocation propagates immediately — no pending transaction window