Price market liquidity

Liquidity lots

Each addLiquidity call creates a new liquidity lot for the receiver. The first deposit into a pool mints principal shares one-for-one with collateral. Later deposits mint shares at the current effectiveMass / activeBacking ratio. The request carries minSharesOut, an expectedCheckpointDigest, and a deadline, so a stale quote cannot execute silently.

Every new v24 lot is Funding-eligible: its funding weight equals its principal shares, and there is no opt-out at deposit time. A lot records:

• owner and principal shares
• principal deposited
• accrued Funding mass and the Funding index it last paid
• fee-sharing weight and lock expiry
• whether the lot is still active

Use addLiquidityTo to add collateral to an existing lot you own instead of creating a new one. The top-up mints shares at the current ratio and carries its own minSharesOut, expected accounting and custody digests, and deadline.

How Funding accrues and is claimed

When a market accrues funding, trader-paid Funding mass is credited to eligible LP weight through a pool-level Funding index. Each lot tracks its accrued mass and a rounding remainder.

Funding is accounted as mass, not as transferred collateral. Claiming converts mass to collateral at the current checkpoint and is subject to the pool's risk state:

• claimLpFunding realizes accrued Funding for one lot. claimLpFundingBatch claims several lots in one call.
• Each claim carries minCollateralOut, an expected accounting digest, a deadline, and a payoutMode of DIRECT or ESCROW.
• A claim is limited or rejected when the pool cannot safely realize the full accrued mass at that moment.

Fee sharing

Fee sharing is separate from Funding and is opt-in. joinFeeSharing(lotId, shareAmount) enrolls a whole lot or an exact slice, and exitFeeSharing(lotId, shareAmount) leaves after the lock expires. Fee-sharing weight lives inside the lot. There is no separate LP token.

Fee rewards accrue to an owner-level balance, denominated directly in collateral through the pool's LP fee reserve. This reserve is separate from Funding accounting and from the Safety Reserve. Claim it with claimLpFeeRewards, which carries a claim amount, minCollateralOut, an expected custody digest, a deadline, and DIRECT or ESCROW payout.

Joining fee sharing starts a lock. The default initial lock is 604800 seconds (7 days) and is pool-configurable. Topping up a fee-sharing lot through addLiquidityTo refreshes the lock. While the lock is active, exitFeeSharing and removeLiquidity for that lot are rejected.

One lot, separate rights

A deposit creates principal shares and Funding eligibility. Fee sharing is a separate opt-in. The branches represent rights, not successive token conversions.

Removing liquidity

removeLiquidity exits a whole lot or an exact shareAmount slice. The request carries:

• lotId and shareAmount
• receiver
• payoutMode: DIRECT transfers collateral immediately, ESCROW records it in settlement escrow for a later claim
• minCollateralOut, checked against principal plus realized Funding in this transaction
• expectedCheckpointDigest and deadline

A partial exit keeps the lot open. The removed slice's accrued Funding is realized when the pool can safely pay it, and any unrealized portion stays recorded on the remaining lot.

A full exit closes the lot. Funding that cannot be safely realized at exit converts into deferred Funding attached to the lot ID, which you claim later through the Funding claim flow, subject to pool state. A full exit therefore does not guarantee that principal and all accrued Funding arrive at the same time.

Contract-owned lots must use DIRECT payouts to the owning contract; they cannot choose escrow for removal. For other eligible owners, escrow payouts go to the owner. Exits can also be denied by the pool's risk engine in stressed states.

Partial and full exit outcomes

Both exits require lock, phase, oracle, risk and minimum-output checks. Settlement and retained rights are distinct results of the same operation.

Contract-owned lots must receive removal proceeds directly into the owning contract. Ordinary removal rejects non-positive total effective mass; it does not convert principal into deferred position claims.

What your liquidity is worth

LPs are the counterparty to traders. A lot's redeemable value is not fixed at the amount you deposited:

• If traders are losing in aggregate, the pool's collateral base grows and your redeemable value can be above your deposit.
• If traders are winning in aggregate, your redeemable value can be below your deposit. You can lose principal.
• Ordinary removal rejects non-positive total effective mass. Recovery and risk limits can block principal withdrawal; this LP removal path does not convert principal into a deferred position claim. Deferred Funding remains a separate mass entitlement whose future collateral value is not fixed.

Quote an exit immediately before signing, carry the quoted digests and minCollateralOut, and re-check the pool's phase and oracle state. See Technical details and Price market risks.