airstreetDocs
Pairing

Pair Vault

Each Pair Market has one Pair Vault. It receives the settlement value allocated to the market, holds it until the Pair Router converts it into the Pair Asset, and holds the Pair Asset until holders claim it.

What the Pair Vault does

The Pair VaultPair VaultThe account that receives settlement value allocated to one Pair Market, holds it until conversion, and holds the acquired Pair Asset until it is allocated to holders. is the accounting and custody boundary of a Pair Market. Value enters it from the market’s configured economic sources. Value leaves it in two ways only: as settlement asset spent on a conversion, and as Pair Asset claimed by an eligible holder.

A vault holds two balances. The settlement balance is denominated in the Settlement assetSettlement assetThe asset a Pair Vault accumulates before conversion. USDC by default. (USDC by default) and waits for the next settlement window. The Pair Asset balance is the instrument token acquired by the Pair Router. Every movement between them is a ledger row, so the vault’s state can be rebuilt from history at any time.

One per market
pair_vaults.pairMarketId is unique. The vault address is mirrored on the market as pairVaultAddress.
Inflows
pair_vault_fundings rows, each tagged with its economic source: creator_fees, launch_economics, protocol_fees or other.
Conversion
A settlement spends the full settlement balance through the Pair Router and records a pair_purchases row.
Outflows
Pair Asset leaves only through reward claims (reward_claims) to eligible holders.

Reading a Pair Vault

The readout below is the shape of a vault after thirteen settlements. TOKYO-042 and TYO.RES are example identifiers: TYO.RES stands in for the Pair Asset that Tokyo Residential’s provider route delivers. Every number in it reconciles with the invariants further down this page.

Pair VaultTOKYO-042EXAMPLE SETTLEMENT
Pair Market
$TOKYO × Tokyo Residential
Custody model
program_pda
Settlement asset
USDC
Settlement balance
$8,482
Lifetime deposited
$241,802
Lifetime converted
$233,320
Settlements
13
Pair Asset
TYO.RES
Pair Asset acquired
9,310.40
Allocated to epochs
2,018.92
Unallocated
7,291.48
Claimed
1,402.36
Held in vault
7,908.04
Readout lineSourceMeaning
Settlement balancepair_vaults.settlementBalanceUsdSettlement asset waiting for the next window. Reset to zero by each completed settlement.
Lifetime depositedpair_vaults.totalDepositedUsdSum of every funding row.
Lifetime convertedpair_vaults.totalConvertedUsdSettlement asset spent by completed settlements.
Pair Asset acquiredΣ pair_purchases.outputAmountRawUnits delivered by confirmed purchases.
Allocated to epochsΣ reward_allocations.amountRawUnits assigned to holders in finalized reward epochs.
Unallocatedpair_markets.pairAssetBalanceRawUnits held for the market and not yet released to an epoch. The quantity behind Pair Value.
ClaimedΣ reward_claims.amountRawUnits transferred to holder wallets.

Pair Vault accounting graph

The same vault drawn as a flow. Band height is proportional to value. Each grey band peeling off below is value that stopped at that stage: settlement asset waiting for the next window, the cost of conversion, Pair Asset not yet released to an epoch, and allocations not yet claimed.

Value through Pair Vault TOKYO-042EXAMPLE SETTLEMENT
SETTLEMENT BALANCE$8,482UNALLOCATED$182,287CLAIMABLE$15,414ECONOMICS$241,802Pair Vault reserveSETTLEMENT$241,802USDCPAIR VAULT$241,802lifetime depositedCONVERSION$233,32013 settlementsPAIR ASSET$232,7609,310.40 unitsREWARD POOL$50,4732,018.92 unitsCLAIMS$35,0591,402.36 units
Execution cost ($560) is too thin to draw at this scale. Pair Asset stages are valued at the $25.00 average reference price at acquisition, so units and dollars reconcile exactly. Pair Value uses the current reference price instead; see Pair Value.

Figure summary: Pair economics of $241,802 enter as USDC and are deposited into the Pair Vault. $8,482 waits as settlement balance and $233,320 is converted. $560 is execution cost, leaving $232,760 of Pair Asset (9,310.40 units at a $25.00 average reference price). $182,287 of that remains unallocated. $50,473 (2,018.92 units) was released to reward epochs, of which $35,059 (1,402.36 units) has been claimed and $15,414 (616.56 units) is claimable.

Accounting invariants

The settlement engine writes every step to ledger tables and updates the read model on pair_markets from those rows. The identities below hold by construction in that engine. Each is shown with the TOKYO-042 numbers.

Settlement asset side

A funding adds to both the settlement balance and lifetime deposited. A completed settlement spends the entire settlement balance and adds the same amount to lifetime converted.

Lifetime deposited = Lifetime converted + Settlement balance
$241,802 = $233,320 + $8,482
pair_vaults.totalDepositedUsd = totalConvertedUsd + settlementBalanceUsd

A settlement whose plan carries blockers writes a failed pair_settlements row with the router’s blockers in error and leaves the settlement balance untouched. Value is never lost between stages: a failed or blocked settlement keeps the balance in the vault for the next window, so the failed and refunded term of this identity is zero by construction.

Conversion

Each pair_purchases row records the settlement asset spent (inputUsd), the units received (outputAmountRaw) and the execution price. On an onchain swap the execution price is the effective price, input divided by output, so price impact and venue fees are carried inside it. Measured against the reference price, they appear as the conversion cost.

Lifetime converted = Pair Asset acquired × reference price + Execution cost
$233,320 = 9,310.40 × $25.00 + $560 = $232,760 + $560
Execution cost is derived: settlement asset spent minus units acquired at the reference price.

Pair Asset side

recomputeFromLedger rebuilds these quantities from ledger rows alone: acquired from confirmed purchases, allocated from reward allocations, claimed from confirmed claims.

Pair Asset acquired = Allocated + Unallocated
9,310.40 = 2,018.92 + 7,291.48
unallocatedRaw = acquiredRaw − allocatedRaw
Allocated = Claimed + Claimable
2,018.92 = 1,402.36 + 616.56
claimable = allocated − claimed
Held in vault = Pair Asset acquired − Claimed = Unallocated + Claimable
7,908.04 = 9,310.40 − 1,402.36 = 7,291.48 + 616.56
vaultPairAssetRaw = acquiredRaw − claimedRaw

Epoch exactness and the read model

Σ allocation_i = epoch pool (exactly, in raw units)
Largest-remainder allocation in integer base units. Tested for every epoch.
pair_markets read model = recomputeFromLedger(pairMarketId)
The pair_markets aggregates equal a pure rebuild from ledger rows. Tested.

The first identity means rounding never creates or destroys Pair Asset: leftover base units go to the largest fractional remainders, ties broken by wallet. The second means the numbers shown on a market page are a cache of the ledger, not a separate source of truth. Accounting and Reconciliation walks a full settlement through both.

Custody models

Every vault declares a custody model. It answers one question: which signer can move the vault’s assets, and under what rules. Live custody is the activation point for settlement into a Pair Asset.

custody_modelSignerStatus
program_pdaA PairStreet Pair Vault program owns the vault through a program-derived address. Movements follow program rules: swap into the Pair Asset, release to the claim distributor.Planned
multisigA multisig controls the vault. Each settlement transaction is proposed and approved by its signers.Planned
provider_custodyThe provider holds the Pair Asset for the market, for instruments whose asset is delivered and held at the issuer or broker.Architecture
dev_simulatedDevelopment network only. Writes dev_simulated ledger rows; production never reads them.Development network

PairStreet deploys no custom onchain program today. The Pair Vault program is planned, and an audit precedes its activation. See Security.

How live custody activates for a market

  1. Step 01custody_model
    Vault signer configured
    A program PDA or multisig signer is attached to the market’s vault and its address is written to pairVaultAddress. This clears the router blocker “Pair Vault signer not configured”.
  2. Step 02ONCHAIN_SWAP
    Settlement executor online
    The executor that signs and submits Jupiter swaps from the vault goes live for the instrument’s route. Route-ready instruments already plan against live quotes.
  3. Step 03status
    Market switches to active
    The Pair Market moves from settlement_disabled to active and receives a nextSettlementAt. The scheduler (dueSettlements) only selects active markets that are due.
  4. Step 043600 s
    Settlement runs on cadence
    Each window converts the settlement balance into the Pair Asset and funds a reward epoch. See Settlement.

The Pair Vault reserve on mainnet

On Solana mainnet today, every Pair Market launched through PairStreet routes 25% of its creator fees to a Pair Vault reservePair Vault reserveThe 25% share of a Pair Market's creator fees earmarked for its Pair Vault. Held by the PairStreet treasury until the market's settlement route activates.. The split is fixed in Pump’s fee-sharing config at launch and locked by Pump, so no party can change it afterwards.

Creator-fee split for every PairStreet launchMAINNET
Creator fees · per Pair Market
50%
25%
25%
Creator
Paid to the creator wallet.
PairStreet protocol
Protocol revenue.
Pair Vault reserve
Earmarked for the market’s Pair Asset acquisition.
On-chain shareholders: creator 5,000 bps, PairStreet treasury 5,000 bps. The treasury share is protocol 25% plus Pair Vault reserve 25%.

Figure summary: Creator fees split 50% to the creator, 25% to the PairStreet protocol and 25% to the Pair Vault reserve. On-chain this is two shareholders: the creator at 5,000 basis points and the PairStreet treasury at 5,000 basis points, which holds the protocol share and the Pair Vault reserve.

Until a market’s vault custody and settlement route activate, its reserve accrues to the PairStreet treasury at 5XAwPtXHkA2F68tEj5ZAZePJfJWH4tzGkeQiqK5ggfRg. Accrued creator fees are paid out by Pump’s permissionless distribute_creator_fees instruction, which anyone can trigger from the market page.

Live markets register with status settlement_disabled (shown as “Settlement pending”) and no vault row yet. The economic flow that funds the vault is already running; the vault converts it once the steps above complete. Status tracks activation per instrument.