API reference

Every instruction of the par program, its arguments, its accounts and what it checks. Market and PriceFeeds are the shared account groups described in Integration.

Instructions

Instruction	Arguments	Signer	Priced with
`initialize`	none	anyone (payer)	none
`create_branch`	none	anyone (payer)	none
`open_trove`	`bucket_index: u16, collateral: u64, debt: u64`	owner	Borrow
`add_collateral`	`amount: u64`	owner	none
`withdraw_collateral`	`amount: u64`	owner	Borrow
`borrow`	`amount: u64`	owner	Borrow
`repay`	`amount: u64`	owner	none
`set_rate`	`new_index: u16`	owner	Borrow, only when an upfront fee is charged
`close_trove`	none	owner	none
`redeem`	`amount: u64, max_fee_bps: u16`	redeemer	Exit
`liquidate`	none	anyone	Exit
`provide_to_pool`	`amount: u64`	owner	none
`withdraw_from_pool`	`amount: u64` (`u64::MAX` = all, `0` = claim only)	owner	none
`close_deposit`	none	owner	none

Borrow pricing needs Pyth and Switchboard fresh and within 2% and uses the lower price. Exit pricing uses the higher fresh price, or the only fresh one.

initialize

Starts the protocol and creates PAR. Callable once, by anyone, and only after the program's upgrade authority is gone.

Account	Notes
`payer`	signer, writable
`protocol`	init, `["protocol"]`
`par_mint`	init, `["par_mint"]`, owned by Token-2022
`program`	this program; its program data must match `program_data`
`program_data`	must have `upgrade_authority_address == None`, else `ProgramUpgradeable`
`par_token_program`, `system_program`

Effects: Protocol.launch_ts = now; PAR mint created with 6 decimals, mint authority = protocol, freeze authority = none.

create_branch

Opens a branch for a listed collateral. Permissionless.

Account	Notes
`payer`	signer
`protocol`
`collateral_mint`	must be jitoSOL or mSOL (`CollateralNotListed`)
`branch`	init, `["branch", collateral_mint]`
`collateral_vault`	init, `["collateral_vault", branch]`, SPL Token
`pool_vault`	init, `["pool_vault", branch]`, Token-2022
`par_mint`	pinned to `protocol.par_mint`
`rate_source`	must be the listed rate source (`WrongRateSource`)

open_trove

Deposits collateral and borrows debt PAR at bucket bucket_index's rate. The trove's debt is debt plus the upfront fee (seven days of interest at that rate).

Account	Notes
`owner`	signer
`market`, `feeds`
`bucket`	init if needed, `["bucket", branch, bucket_index]`
`trove`	init, `["trove", branch, owner]`
`owner_collateral`	owner's LST token account
`owner_par`	owner's PAR account (Token-2022)

Checks: bucket_index < 246 (InvalidBucket), total debt at least 200 PAR (DebtBelowMinimum), ratio at least 120% (BelowMinimumCollateralRatio), branch under the ceiling (DebtCeilingExceeded), oracles usable for Borrow.

add_collateral, withdraw_collateral, borrow, repay

The four single-direction adjustments of an active trove, sharing the AdjustTrove accounts: owner, market, feeds, bucket, trove, owner_collateral, owner_par. Each first accrues the branch and brings the trove current.

withdraw_collateral and borrow re-check the 120% floor at the Borrow price; borrow charges the upfront fee on the new amount and checks the ceiling.
repay cannot take the debt under 200 PAR (RepayTooLarge); paying everything is close_trove.

set_rate

Moves the trove to bucket new_index. Free once every seven days; sooner, it charges the upfront fee at the new rate.

Account	Notes
`owner`	signer; the trove PDA is `["trove", branch, owner]`
`market`, `feeds`
`trove`	active (`TroveNotActive`)
`current_bucket`	`["bucket", branch, trove.bucket]`
`new_bucket`	init if needed, `["bucket", branch, new_index]`; `new_index < 246`, different from current (`SameRate`)

close_trove

Active trove: burns all its debt and returns all collateral. Redeemed or liquidated trove: returns whatever collateral was left for the owner. The account closes and its rent returns to the owner.

redeem

Swaps up to amount PAR for $1 of collateral each, minus the redemption fee, taking debt from the lowest-rate troves first. Remaining accounts: [bucket, trove, trove, .., bucket, trove, ..].

Account	Notes
`redeemer`	signer
`market`, `feeds`
`redeemer_par`	burned with the redeemer's signature (`InsufficientPar` if short)
`redeemer_collateral`	receives the collateral

Checks: fee rate at most max_fee_bps (RedemptionFeeTooHigh); each bucket is the lowest non-empty one when reached (WrongRedemptionOrder); each trove belongs to the bucket before it (TroveNotInBucket); something was redeemed (NothingRedeemed).

liquidate

Closes out a trove under 120%. Accounts: liquidator (signer), market, feeds, trove, bucket, liquidator_collateral. See How it works for the split between pool, redistribution and the owner's surplus.

provide_to_pool, withdraw_from_pool, close_deposit

provide_to_pool(amount): creates or tops up ["deposit", branch, owner], pays out earned collateral and PAR, then adds amount.
withdraw_from_pool(amount): pays out all gains and withdraws up to amount of the compounded deposit.
close_deposit: closes an empty deposit account (DepositNotEmpty otherwise) and returns its rent.

Account layouts

Trove

Field	Type	Meaning
`branch`, `owner`	`Pubkey`
`status`	`TroveStatus`	Active, or closed by redemption or liquidation
`bucket`	`u16`	Rate bucket index
`shares`	`u128`	Share of the bucket's debt
`collateral`	`u64`	LST base units (9 decimals)
`stake`, `l_collateral_snapshot`, `l_debt_snapshot`	`u128`	Redistribution bookkeeping
`last_rate_change_ts`	`i64`	Start of the seven-day free window

Bucket

Field	Type	Meaning
`index`	`u16`	0 to 245
`debt`, `shares`	`u128`	Debt of every trove in the bucket and the shares it is split into
`troves`	`u32`	Active troves
`last_accrual_ts`	`i64`

Deposit

Field	Type	Meaning
`amount`	`u128`	Initial deposit value at the last snapshot
`p_snapshot`, `scale_snapshot`	`u128`, `u64`	Product snapshot
`collateral_sum_snapshot`, `yield_sum_snapshot`	`u128`	Gains snapshots