Currency pool
Holds every pool, every underwriter balance and every protection position. Pricing: how the premium, markup and fees combine is in Premium calculation, the payout in Payout calculation and every fee in Fees. Amounts are i128 in 7-decimal USDC units; rates are u64 with 6 decimals; fee rates are u32 per million; distances and markups are u32 basis points.
Stellar (testnet) · CAEKJTUSZIWY5OMK6EVOSNPMEULI3MDO3BLP6Y5OKPHRNKM6KTH5YURM · View on explorer · View on GitHub
Protection
buy_protection
WRITEbuy_protection(hedger: Address, params: BuyParams, signature: BytesN<64>) -> u32
Who can call: hedger
Buys protection from a pool with a quote signed by the pricing key. Checks the deadline, pool, tenor, terms, quote age (at most 120 seconds) and nonce; reserves the maximum payout from current backers in proportion to their free money; credits them the premium less the liquidity fee at once; charges the hedger premium plus platform fee, never more than max_cost. Returns the position id.
Errors: PoolNotAccepting, TenorNotOffered, InvalidTerms, StrikeTooClose, CapOutOfBounds, OpenCapMismatch, QuoteExpired, QuoteReused, InsufficientCapacity, SlippageExceeded, Paused
settle_position
WRITEsettle_position(position_id: u32) -> i128
Who can call: anyone
Settles an expired position from the oracle's agreed rate for its own expiry. Rejects a rate outside 0.5× to 2× of the spot at purchase. Charges the payout to the position's funders in proportion to their reserve and releases the rest. Takes no price argument. Returns the gross payout.
Errors: NotReady, InvalidOracle, AlreadySettled, OraclePolicyTooLoose
claim_payout
WRITEclaim_payout(position_id: u32) -> i128
Who can call: position's hedger
Pays a settled position's payout less the payout fee (Payout calculation). Returns the net amount.
Errors: NotClaimable, NothingToClaim
Underwriting
deposit
WRITEdeposit(pool_id: u32, lp: Address, amount: i128) -> i128
Who can call: lp
Adds to the underwriter's free balance. It backs only sales made from now on. Minimum 10 USDC; outside underwriters need the pool to allow them; at most 50 per pool.
Errors: InvalidAmount, ExternalLpClosed, TooManyLps, Paused
set_lp_preferences
WRITEset_lp_preferences(pool_id: u32, lp: Address, backing: bool, max_tenor_days: u32)
Who can call: lp
Turns backing of new sales on or off and sets the longest tenor backed (0 = any). Existing reserves are unaffected.
Errors: TenorInvalid
request_withdrawal
WRITErequest_withdrawal(pool_id: u32, lp: Address, shares: i128) -> u32
Who can call: lp
Sets aside an amount of free money (in USDC units; the name is kept for compatibility) to withdraw. It unlocks at once. Returns the request id.
Errors: NotEnoughShares
cancel_withdrawal
WRITEcancel_withdrawal(request_id: u32)
Who can call: request's lp
Returns a pending request's amount to backing new sales.
Errors: RequestNotFound, RequestClosed
execute_withdrawal
WRITEexecute_withdrawal(request_id: u32) -> i128
Who can call: request's lp
Pays out a request. Works while the contract is paused.
Errors: RequestClosed, NoticeNotOver, CapitalReserved
Pool creators
create_pool
WRITEcreate_pool(creator: Address, pair: String, direction: u32, allow_external_lp: bool, structures: Structures, tenors: Vec<Tenor>, initial_liquidity: i128) -> u32
Who can call: creator
Opens a pool on an enabled pair, for one direction (1 up, 2 down), and seeds it. Charges the creation fee plus the initial liquidity. Sells at once.
Errors: PairNotEnabled, InvalidAmount, InvalidTerms, TenorInvalid, MarkupOutOfRange, MaxTenorsReached, Paused
set_tenor
WRITEset_tenor(pool_id: u32, tenor: Tenor)
Who can call: pool creator
Adds a tenor or changes its markup or status (how a markup turns into the price: Premium calculation). Tenor { tenor_days, active, markup_bps }; 1 to 365 days, markup 9,000 to 50,000 bps, at most 16.
Errors: TenorInvalid, MarkupOutOfRange, MaxTenorsReached
set_structures
WRITEset_structures(pool_id: u32, structures: Structures)
Who can call: pool creator
Changes the structures on sale and their limits. New sales only.
Errors: InvalidTerms
set_pool_settings
WRITEset_pool_settings(pool_id: u32, accepting_hedges: bool, allow_external_lp: bool)
Who can call: pool creator
Stops or resumes sales; allows or refuses outside underwriters.
withdraw_creator_earnings
WRITEwithdraw_creator_earnings(pool_id: u32) -> i128
Who can call: pool creator
Pays the creator's accrued share of fees.
Errors: NothingToClaim
Reads
get_pool
READget_pool(pool_id: u32) -> Pool
A pool's terms, fees and balances.
Errors: PoolNotFound
get_pool_count
READget_pool_count() -> u32
Number of pools.
get_liquidity
READget_liquidity(pool_id: u32) -> Liquidity
A pool's capital, reserved amount and capacity.
get_position
READget_position(position_id: u32) -> Position
One protection position.
Errors: PositionNotFound
list_pool_positions
READlist_pool_positions(pool_id: u32, start: u32, limit: u32) -> Vec<Position>
A pool's positions, paged.
list_user_positions
READlist_user_positions(hedger: Address, start: u32, limit: u32) -> Vec<Position>
A hedger's positions, paged.
get_lp_account
READget_lp_account(pool_id: u32, lp: Address) -> Option<LpAccount>
An underwriter's free, reserved, earned, paid, pending_withdraw, backing, max_tenor_days.
list_pool_lps
READlist_pool_lps(pool_id: u32) -> Vec<(Address, LpAccount)>
Every underwriter in a pool.
get_funders
READget_funders(position_id: u32) -> Vec<Funder>
The underwriters backing a position and each one's reserve.
get_withdrawal
READget_withdrawal(request_id: u32) -> WithdrawalRequest
One withdrawal request.
Errors: RequestNotFound
open_cap
READopen_cap(max_payout_bps: u32, strike_above: bool, spot: u64, strike: u64) -> u64
The limit (cap) an Open position must use.
quote_message
READquote_message(hedger: Address, params: BuyParams) -> BytesN<32>
The digest the pricing key signs for a quote.
is_pair_enabled
READis_pair_enabled(pair: String) -> bool
Whether new pools may use a pair.
get_configuration
READget_configuration() -> (Address, Address, Address, BytesN<32>, u32, u32, u32, u32, i128, bool)
Owner, USDC, oracle, pricing key, fee rates, creation fee and paused flag.
Admin
upgrade
ADMINupgrade(new_wasm_hash: BytesN<32>)
Who can call: owner
Replaces the contract code in place; address and storage are kept.
set_paused
ADMINset_paused(paused: bool)
Who can call: owner
Pauses pool creation, deposits and purchases. Withdrawals, settlement and claims continue.
set_fees
ADMINset_fees(hedger_fee_rate: u32, payout_fee_rate: u32, lp_profit_fee_rate: u32, creator_share: u32, creation_fee: i128)
Who can call: owner
Sets fees for new pools (what each fee is and who pays it: Fees). Each rate at most 100,000 (10%); creator share at most 500,000 (50%).
set_pricing_key
ADMINset_pricing_key(pricing_key: BytesN<32>)
Who can call: owner
Sets the ed25519 key that signs quotes.
set_pair
ADMINset_pair(pair: String, enabled: bool)
Who can call: owner
Enables or disables a pair for new pools.
withdraw_treasury_fees
ADMINwithdraw_treasury_fees(amount: i128, destination: Address)
Who can call: owner
Withdraws collected protocol fees, never pool capital.
propose_owner
ADMINpropose_owner(next_owner: Address) / accept_owner()
Who can call: owner, then new owner
Two-step ownership transfer.
Events
| Event | Topics | Data |
|---|---|---|
PoolCreated | pool_id, creator | pair, direction, initial_liquidity, shares |
TenorSet | pool_id | tenor_days, active, markup_bps, added |
StructuresSet | pool_id | open_enabled, capped_enabled, min/max_cap_distance_bps, open_max_payout_bps, min_strike_distance_bps |
PoolSettingsSet | pool_id | accepting_hedges, allow_external_lp |
LiquidityAdded | pool_id, lp | amount, shares |
WithdrawalRequested | pool_id, request_id | lp, shares, unlock_at |
WithdrawalCancelled | pool_id, request_id | lp, shares |
WithdrawalExecuted | pool_id, request_id | lp, shares, amount |
CreatorEarningsWithdrawn | pool_id, creator | amount |
ProtectionPurchased | pool_id, position_id | hedger, structure, strike_above, tenor_days, notional, spot, strike, cap, fair_rate, premium_rate, premium, fee, max_payout, expiry |
PositionSettled | pool_id, position_id | settlement_price, payout, lp_profit_fee |
PayoutClaimed | position_id, hedger | gross_amount, fee, net_amount |