universalsettle-api 0.2.0

X402-inspired settlement program for any token on Solana
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122

# 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.

[![Crates.io](https://img.shields.io/crates/v/universalsettle-api.svg)](https://crates.io/crates/universalsettle-api)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)

---

## 🏗️ 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

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

### 2. Create a Vault

```rust
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

```rust
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

| Instruction | Access | Description |
|---|---|---|
| `Sweep` (0) | Public | Settle funds from a vault — splits payout and fee |
| `CreateVault` (1) | Public | Create a SplitVault PDA for a seller |
| `Initialize` (100) | Admin | One-time program initialization |
| `UpdateAuthority` (101) | Admin | Propose config authority transfer (two-step) |
| `UpdateFeeRate` (102) | Admin | Update standard fee basis points |
| `UpdateFeeDestination` (103) | Admin | Update fee destination wallet |
| `UpdateMinFeeAmount` (104) | Admin | Update SPL minimum fee floor |
| `UpdateMinFeeAmountSol` (105) | Admin | Update SOL minimum fee floor |
| `UpdateProvisioningFee` (106) | Admin | Update provisioning recovery targets |
| `UpdateDiscountedFeeRate` (107) | Admin | Update sovereign fee basis points |
| `AcceptAuthority` (108) | Admin | Proposed new authority accepts a pending transfer |
| `CancelAuthorityProposal` (109) | Admin | Current authority cancels a pending transfer |
| `InitShard` (110) | Admin | Create fee-shard PDA + shard SOL storage for an index |
| `CollectFromShard` (111) | Admin | Move shard fees (SOL or SPL) to treasury |
| `UpdateShardConfig` (112) | Admin | Enable/disable sharding; set shard count |

## 📜 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.