Pools | SplitPay Docs

A Pool is the fundamental organizational primitive in SplitPay. It represents a persistent set of rules for routing and dividing incoming payments.

Pools are Rule Engines, Not Bank Accounts

A SplitPay pool is not a custodial bank account or vault. It does not hold pooled balances. Instead, it is an on-chain configuration contract that routes incoming funds immediately to recipient wallets upon settlement.

What is a Pool?

Each pool has a unique numerical identifier (pool_id: u64), a designated owner address, an accepted Stellar asset address (such as native XLM SAC or USDC SAC), an operational status, and a list of registered members.

On-Chain Pool Data Structure

In the Soroban smart contract, pools are defined as:

rustcontracts/splitpay/src/types.rs

#[contracttype]
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct Pool {
    pub id: u64,
    pub owner: Address,
    pub asset: Address,
    pub status: PoolStatus,
    pub created_at: u64,
}

Pool Lifecycle & Statuses

A pool exists in one of two operational states governed by the PoolStatus enum:

Active (1): The pool can configure members, accept pending payment registrations, and execute atomic settlements.
Inactive (2): The pool is paused by the owner. It cannot accept new payments or settle pending ones until reactivated.

Pool Ownership & Administration

Only the designated owner address can add members, remove members, update shares, or change the pool's status. Any unauthorized attempt to mutate pool configuration results in Error::Unauthorized.