universalsettle-api

The High-Velocity Settlement Standard for the Solana Agentic Economy.

universalsettle-api is the official Rust SDK for interacting with the UniversalSettle program on Solana. Designed for the machine-to-machine (M2M) economy, it enables autonomous agents to perform instant, trustless settlement for any SPL token or Native SOL.

🏗️ Architecture

UniversalSettle implements a Commission-First settlement model with two-tier fee structure:

1. SplitVault PDAs: Every seller gets a unique vault (derived from their wallet address) that partitions revenue from protocol fees.
2. Dual-Floor Minimum Fees: Independent minimum fee floors for SPL tokens (6-decimal standard) and Native SOL (9-decimal standard), preventing economic value drift across assets.
3. Sovereign Path: Sellers who self-provision their vault pay a discounted fee rate (discounted_fee_bps). Facilitator-provisioned vaults pay the standard rate (fee_bps) until provisioning costs are recovered.
4. Provisioning Recovery: When a facilitator creates a vault on behalf of a seller, the protocol automatically diverts a portion of initial sweep payouts to the fee destination until the one-time provisioning cost is recovered.

🚀 Quick Start

1. Add Dependency

[dependencies]
universalsettle-api = "0.1.7"
solana-sdk = "^2.1"

2. Create a Vault

use universalsettle_api::sdk;

// Create a vault for a seller (payer covers rent)
let ix = sdk::create_vault(payer_pubkey, seller_pubkey);

3. Sweep Funds

use universalsettle_api::sdk;

let (vault_pda, _) = universalsettle_api::state::split_vault_pda(&seller_pubkey);

// SOL sweep — settle all available SOL from the vault.
// `fee_destination` must be the *writable lamport recipient* the program expects:
// typically `config.fee_destination` when sharding is off, or the shard SOL storage
// PDA when fee sharding is on (see `fee_shard_sol_storage_pda`).
let ix = sdk::sweep(
    payer_pubkey,       // facilitator or crank signer
    vault_pda,          // the seller's SplitVault PDA
    seller_pubkey,      // seller's wallet (receives payout)
    fee_lamport_receiver,
    Pubkey::default(),  // token_mint: default = Native SOL
    0,                  // amount: 0 = sweep all available
    true,               // is_sol: true for Native SOL
    None,               // vault_tokens (not needed for SOL)
    None,               // seller_tokens (not needed for SOL)
    None,               // fee_dest_tokens (not needed for SOL)
    None,               // token_program (not needed for SOL)
);

// SPL sweep — settle USDC from the vault.
// `fee_dest_tokens` is the ATA that receives the fee portion (treasury-owned ATA, or
// shard-owned fee ATA when sharding is enabled). The `fee_destination` argument is
// ignored when `is_sol == false` (the SPL account list uses only the ATAs below).
let ix = sdk::sweep(
    payer_pubkey,
    vault_pda,
    seller_pubkey,
    Pubkey::default(),  // ignored for SPL sweeps
    usdc_mint,          // SPL token mint address
    0,                  // 0 = sweep all
    false,              // is_sol: false for SPL
    Some(vault_ata),    // vault's associated token account
    Some(seller_ata),   // seller's associated token account
    Some(fee_dest_ata), // fee recipient ATA
    None,               // token_program: None defaults to legacy SPL Token
);

🛠️ Key Features

• SplitVault PDAs: Deterministic per-seller vaults with independent SOL storage accounts.
• Dual-Floor Architecture: Independent minimum fee floors for SPL (min_fee_amount) and Native SOL (min_fee_amount_sol).
• Sovereign Fee Tier: Self-provisioned sellers automatically receive the discounted fee rate.
• Provisioning Recovery: Facilitator-fronted vault creation costs are transparently recovered from initial sweeps.
• All Asset Support: Native SOL, legacy SPL Token mints, and plain Token-2022 mints.
  • Token-2022 mints with extra mint extensions are rejected until their transfer semantics are modeled explicitly.
  • Recommendation: We strongly recommend using USDC or USDT (stablecoins) for SPL transactions. While custom tokens are supported, the min_fee_amount floor is economically optimized for 6-decimal stable assets.
• Fee sharding (optional): init_shard, collect_from_shard, update_shard_config, plus Config.use_fee_shard / shard_count in initialize.
• Comprehensive SDK: Helpers for all instructions — including shard ops above and create_vault, sweep, initialize, authority two-step (update_authority, accept_authority, cancel_authority_proposal), fee tuning, and provisioning fee updates.

📋 Instructions

📜 Standard Alignment

This crate is the reference implementation for the x402 Protocol. It works with the pr402 Facilitator and the spl-token-balance-serverless reference project.

⚖️ License

Licensed under the Apache License, Version 2.0.