Failure Modes
Financial infrastructure fails: providers go offline, liquidity thins, transactions expire. PairStreet detects each failure, contains it to the narrowest scope, keeps the last good state visible, and records what happened.
Containment
A Pair MarketPair MarketThe canonical pairing of an internet asset with a financial Pair: TOKEN × PAIR INSTRUMENT, plus the Pair Vault, configuration and accounting that connect them. has two halves that fail independently. The token market runs on Pump and Solana; the financial Pair runs through 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., the Pair RouterPair RouterThe execution layer that converts a Pair Vault's settlement balance into an acquisition plan for the Pair Asset and hands it to the right executor. and the provider route. A failure in the Pair half stops settlement for the affected instrument. It never stops the token from trading.
- ·The smallest unit that can stop is one instrument’s settlement route. Other instruments and other markets continue.
- ·A blocked settlement is written to the ledger with status
failedand its reasons inerror. The settlement balance stays in the vault for the next attempt. - ·Market data falls back to the last good value. A failed fetch never blanks a price.
- ·Nothing is retried with user funds on the user’s behalf. A failed transaction is reported; a retry is a new transaction the user signs.
Failure matrix
Each row gives the failure, how PairStreet detects it, what the system does, what the user sees, and how the state recovers. Mechanisms marked planned are the design for that case; everything else is in the code today.
| Failure | Detection | System response | User state | Recovery |
|---|---|---|---|---|
| Provider unavailable | Provider status probe returns provider_unavailable; quote request fails; the route carries blockers. | The plan is not executable. The settlement row is written as failed with the blockers; the balance stays in the vault. | Instrument status shown on the Pair panel. Token trading continues. | Next scheduled settlement plans again once quotes return. Brazilian Tesouro is listed as provider_unavailable today. |
| Asset transfer paused | Transfer restrictions reported by the provider (transferable: false). | Instrument status moves to paused: launches into it are rejected and claims for it wait. Planned Automated transfer monitoring. | Allocations remain claimable in the ledger. | Status returns to active; claims proceed. |
| Redemption paused | Issuer status and issuer documents. | Redemption is a relationship between holder and issuer. PairStreet notes it on the instrument and pauses the instrument if it affects acquisition or pricing. | Pair Assets already held stay in holder wallets. | Issuer resumes redemption. |
| Liquidity unavailable | Jupiter returns no route; blocker “No liquid route into …”. | Settlement recorded as failed; the balance carries to the next epoch. | Settlement history shows the attempt and its reason. | Automatic at the next cadence once a route quotes. |
| Reference price stale | Reference prices carry referencePriceAt; the SOL price fetch fails or times out. | Last good SOL price is used; Pair Value uses the last stored reference price. | Values remain on screen with their last update. | Next successful fetch or settlement refreshes the price. |
| Transaction failed | Client simulation fails before signing; or confirmation returns an error. | Nothing is recorded offchain. Launch confirmation rejects a transaction that failed onchain. | The transaction flow shows the error. A simulation failure costs nothing. | Rebuild with a fresh blockhash and sign again. |
| Settlement partial | Purchase status (planned, submitted, confirmed, failed). | Only confirmed purchases count toward acquired totals. Planned A partial fill records the confirmed output and returns the unconverted remainder to the settlement balance. | Pair Value reflects confirmed units only. | Remainder settles in the next epoch. |
| Instrument delisted | Instrument status deprecated. | New launches rejected; the Eligibility Engine returns INSTRUMENT_UNAVAILABLE; every plan carries a blocker. | Existing markets keep trading. Existing allocations stay in the ledger. | Re-pairing an existing market to another instrument: Planned |
| Asset frozen | Issuer freeze controls are recorded in the instrument’s transfer restrictions. Planned Token-account state monitoring. | Instrument moves to paused; settlement and claims for it wait. | Allocations remain recorded. | Issuer unfreezes; status returns to active. |
| Provider integration revoked | The provider adapter raises not enabled; the API answers NOT_AVAILABLE (501) with the missing pieces. | Instrument status provider_unavailable; launches into it rejected. | Instrument stays listed with its status. | Re-enable, or route the instrument through another provider: product code depends only on the provider interface. |
| Solana congestion | Confirmation passes the transaction’s last valid block height without landing. | Nothing is written offchain until a transaction confirms. | The flow reports expiry. | Retry builds a fresh transaction. |
| Pump API or indexer outage | Curve read, DexScreener or GeckoTerminal fails; indexer source writes status: error. | Pages render from the database read model; caches keep last good values; candles wait. | Market data shows its last update. | Next refresh. Pump state is read from chain, so a Pump web outage does not affect it. |
| Fee-split transaction did not land | Launch confirmation reads the sharing config: one shareholder means pending. | The Pair Market registers normally with its split marked pending. | Market shows “Split pending”; the creator sees “Lock fee split”. | Creator signs the lock (POST /api/markets/[mint]/fees, action lock); the next read records locked. |
| Treasury below rent minimum | Treasury balance checked against Solana’s rent-exempt minimum before the fee is added. | A fee too small to fund the account is skipped; the trade proceeds. | The quote shows a zero PairStreet fee. | Automatic once the treasury is funded. |
Pair Instrument status
A Pair InstrumentPair InstrumentThe financial exposure a Pair Market is paired with, such as Tokyo Residential or Swiss Government Debt. A catalog object with a provider, an eligibility policy and a status. moves through a small set of states. The model below is the full state machine; the table after it shows how each state maps to the status enum the registry enforces today.
Hover a state for its meaning.
Figure summary: ACTIVE moves to DEGRADED on a provider or market signal, or directly to EMERGENCY. DEGRADED branches to MINT_PAUSED, REDEMPTION_PAUSED, TRANSFER_RESTRICTED, PAIR_SUSPENDED, DELISTED or EMERGENCY. Every state except DELISTED returns to ACTIVE when its condition clears.
| Model state | Enum today | Status | Effect |
|---|---|---|---|
| ACTIVE | active | Live | Launches accepted; settlement routes plan and, once activated, execute. |
| DEGRADED | provider_unavailable | Live | Listed and visible; launches rejected; plans carry a blocker. |
| MINT_PAUSED | expressed as paused | Planned | Acquisition routes that mint are blocked. |
| REDEMPTION_PAUSED | informational | Planned | Noted on the instrument; acquisition may continue. |
| TRANSFER_RESTRICTED | expressed as paused | Planned | Claims wait until transfers resume. |
| PAIR_SUSPENDED | paused | Live | No new launches, no settlement for the instrument. |
| DELISTED | deprecated | Live | Retired; existing markets keep trading. |
| EMERGENCY | expressed as paused | Planned | Immediate halt with a recorded reason. |
| Before listing | coming_soon | Live | Visible in the catalog; launches open when it becomes active. |
Any status other than active is enforced in three places at once: launch preparation rejects the instrument, the Eligibility EngineEligibility EngineEvaluates a viewer's region and verification state against a Pair Instrument's rules and returns allow or restrict before any Pair interaction. returns INSTRUMENT_UNAVAILABLE, and the Pair Router adds the status as a blocker to every plan.
Pair Market status
Pair Markets carry their own status, separate from their instrument’s.
pending- Registration in progress.
active- Settlement runs on the market’s cadence (default hourly).
settlement_disabled- Shown as “Settlement pending”. Live markets register in this state until their instrument’s route and vault custody activate;
nextSettlementAtis empty. paused- Settlement paused for this market only.
closed- The market’s Pair is closed; no further settlement.
What stays up
In every Pair Market and instrument state, the token keeps trading on its Pump bonding curve or PumpSwap pool, accrued creator fees remain distributable through the permissionless distribution, and the ledger keeps every allocation already made. See Security for who can change each status, and Accounting for how failed settlements reconcile.