Soroban Smart Accounts

The Key Custody Problem

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

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)
}

Storage Architecture

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

The OZ Smart Account framework adds three primitives: Context Rules (what actions are permitted), Signers (who can act — passkeys, ed25519, secp256k1, BLS, RSA), and Policies (how permissions are enforced — threshold multisig, spending limits, sessions, time-based restrictions). For consumer onboarding, smart wallets support passkey authentication via WebAuthn — users authenticate with device biometrics instead of seed phrases.

Agent Spending Authorization via Smart Wallet

The key UX pattern for REAPP — how an AI agent gets limited spending authorization from a smart wallet:

1. User creates smart wallet via passkey (one biometric tap)
2. User adds AI agent as Ed25519 signer with restricted SignerLimits
3. Agent signs with its Ed25519 key; __check_auth enforces limits automatically
4. For amounts exceeding limits, the primary passkey signer must co-sign
5. Using SignerStore.Temporary means the agent's authorization auto-expires

// Add AI agent as restricted signer on smart wallet
const agentLimits = new Map([
  ['CBIELTK6YBZJU5UP2WWQEUCYKLPU6AUNZ2BQ4WWFEIE3USCIHMXQDAMA', undefined], // USDC contract only
]);
await account.addEd25519(agentPublicKey, agentLimits, SignerStore.Temporary);

Stellar Wallets Kit

Stellar Wallets Kit (by Creit Technologies) provides the unified wallet adapter. v2 migrated from npm to JSR — the package is now @creit-tech/stellar-wallets-kit on JSR. Supports Freighter, LOBSTR (via WalletConnect), xBull, Albedo, Hana, Rabet, HOT, and Bitget. Used by Stellar Lab, Blend Capital, FxDAO, and Soroban Domains.

import { StellarWalletsKit } from "@creit-tech/stellar-wallets-kit/sdk";
import { defaultModules } from '@creit-tech/stellar-wallets-kit/modules/utils';

StellarWalletsKit.init({ modules: defaultModules() });
const { address } = await StellarWalletsKit.getAddress();
const { signedTxXdr } = await StellarWalletsKit.signTransaction(tx.toXDR(), {
  networkPassphrase: Networks.PUBLIC, address,
});

Fee Sponsorship — OZ Relayer Channels

LaunchTube was archived on March 9, 2026. The migration target is the OpenZeppelin Relayer with Channels Plugin. Fee bump sponsorship via the relayer means agent clients need zero XLM.

Both can coexist — smart wallets support multiple signer types. A single app can offer "Connect Wallet" (Freighter / Wallets Kit) alongside "Sign in with Passkey" for the consumer path.