Position
The Position contract represents a user's share of liquidity in a specific pool. It is deterministically deployed for each owner-pool pair. This contract is responsible for tracking:
- Total liquidity owned by the user.
- "Locked" liquidity (e.g., from initial provisioning rules).
- Accrued trading fees (Asset X and Asset Y) since the last update.
- Entitlement to active reward programs.
Getters
Method get_position_data
Returns the current state of the position, including ownership, liquidity balances, and fee checkpoints.
Arguments
This getter does not accept any arguments.
Returns
| # | Name | Type | Description |
|---|---|---|---|
| 0 | poolAddress | slice (address) | Address of the associated CPMM Pool. |
| 1 | ownerAddress | slice (address) | Address of the position owner. |
| 2 | liquidity | int (coins) | Total liquidity tokens held by this position. |
| 3 | lockedLiquidity | int (coins) | Amount of liquidity tokens that are currently locked and cannot be withdrawn. |
| 4 | rewards | cell (map<uint2, PositionReward>) | Map of reward indexes to the user's specific reward state (PositionReward). |
| 5 | xPending | int (coins) | Amount of asset X fees already calculated but not yet claimed. |
| 6 | yPending | int (coins) | Amount of asset Y fees already calculated but not yet claimed. |
| 7 | xFeePerTokenCheckpoint | int (Q120X120) | Checkpoint of pool's xLPFeePerToken used to calculate newly accrued fees. |
| 8 | yFeePerTokenCheckpoint | int (Q120X120) | Checkpoint of pool's yLPFeePerToken used to calculate newly accrued fees. |
Method get_available_fees
Calculates the total fees available for claim, including both pending fees and newly accrued fees since the last checkpoint.
Arguments
| # | Name | Type | Description |
|---|---|---|---|
| 0 | xFeePerToken | int (Q120X120) | Current xLPFeePerToken from the Pool (usually fetched via get_pool_data). |
| 1 | yFeePerToken | int (Q120X120) | Current yLPFeePerToken from the Pool (usually fetched via get_pool_data). |
Returns
| # | Name | Type | Description |
|---|---|---|---|
| 0 | xFees | int (coins) | Total claimable amount of asset X fees. |
| 1 | yFees | int (coins) | Total claimable amount of asset Y fees. |
Incoming Messages
Message CreditLiquidity
Sent by the Pool to increase the user's liquidity. This occurs after a successful deposit. It also updates fee and reward checkpoints to ensure the new liquidity only earns future rewards.
struct (0x855afcbd) CreditLiquidity {
queryId: uint64
liquidity: coins
lockedLiquidityShare: uint16
notifyExtraGas: coins
notifyPayload: cell?
excessesTo: address
xFeePerToken: Q120X120
yFeePerToken: Q120X120
rewards: PoolRewards
}Caller: Must be the associated Pool address.
Message WithdrawLiquidity
Sent by the Pool when a user initiates a withdrawal. The position verifies that the user has enough unlocked liquidity, calculates the final fees/rewards, and sends an ExitLiquidity message back to the Pool.
struct (0xbc1531a9) WithdrawLiquidity {
queryId: uint64
liquidity: coins
minimalXOut: coins
minimalYOut: coins
xFeePerToken: Q120X120
yFeePerToken: Q120X120
rewards: PoolRewards
autoClaimFees: bool
payoutConfig: Cell<BasicPayoutConfig>
}Message ClaimAvailableFees
Sent by the Pool to trigger a fee claim. The position calculates all accrued fees since the last checkpoint and sends PayoutPositionFees back to the Pool.
struct (0x25f19752) ClaimAvailableFees {
queryId: uint64
excessesTo: address
xFeePerToken: Q120X120
yFeePerToken: Q120X120
}Message ClaimPositionReward
Sent by the Pool to claim earned incentives for a specific reward program.
struct (0x2e0cccba) ClaimPositionReward {
queryId: uint64
rewardIndex: uint2
reward: PoolReward
excessesTo: address
}Message ProvidePositionState
Requests a snapshot of the current position state. Responds with TakePositionState.
struct (0x9e0c2428) ProvidePositionState {
queryId: uint64
includePoolAddress: bool
includeOwnerAddress: bool
includeFees: bool
includeRewards: bool
}provide_position_state#9e0c2428 query_id:uint64
include_pool_address:Bool
include_owner_address:Bool
include_fees:Bool
include_rewards:Bool = IncomingMessage;Outgoing Messages
Message DepositNotification
Sent to the owner address after liquidity is credited to the position, providing details about the minted and locked amounts.
struct (0x63554160) DepositNotification {
queryId: uint64
liquidity: coins
lockedLiquidity: coins
payload: cell?
}Other Types
Type PositionReward
Represents the state of a specific reward distribution for this position.
struct PositionReward {
unclaimed: coins
rewardsPerTokenCheckpoint: Q120X120
}| Parameter | Type | Description |
|---|---|---|
unclaimed | coins | Amount of reward tokens earned but not yet claimed. |
rewardsPerTokenCheckpoint | Q120X120 | Last pool rewardsPerToken value synced to this position. |