Pool

The Pool contract is the central component of the CPMM V2 protocol.

It implements the Constant Product Market Maker ($x \times y = k$) logic for a specific pair of assets.

The contract is responsible for:

• Executing Swaps: Facilitating automated asset exchange with slippage protection and multi-hop routing support.
• Liquidity Management: Orchestrating the minting and burning of liquidity shares through interaction with Deposit and Position contracts.
• Fee Collection & Distribution: Accumulating trading fees and distributing them proportionally among liquidity providers, the pool creator, and the protocol.
• Incentive Programs: Managing active reward distributions to encourage liquidity provisioning.

Each pool is uniquely identified by its configuration parameters (PoolConfig).

Getters

Method get_pool_data

Returns the current state of the pool, including configuration, reserves, fees, resolved wallets, and reward settings.

Arguments

This getter does not accept any arguments.

Returns

Method get_position_address

Calculates the account address of a Position contract for a given owner.

Arguments

Returns

Events

Events are emitted after successful state-changing operations and describe both the operation parameters and the resulting next pool state.

Each event includes:

• operation-specific fields,
• the initiator and recipient addresses,
• a nextState snapshot representing the pool state after the operation.

Event Deposit

Emitted after a liquidity deposit into the pool.

The event records the deposited amounts of both assets, the amount of liquidity minted, and the resulting pool state.

struct (0x35df2e12) Deposit {
    amountXIn: coins
    amountYIn: coins
    liquidity: coins
    initiatorAddress: address
    recipientAddress: address
    nextState: Cell<PoolUpdatedState>
}

Event Withdrawal

Emitted after a liquidity withdrawal from the pool.

The event records the amount of liquidity burned, the withdrawn asset amounts, and the resulting pool state.

struct (0xc0d77b54) Withdrawal {
    liquidity: coins
    amountXOut: coins
    amountYOut: coins
    initiatorAddress: address
    recipientAddress: address
    nextState: Cell<PoolUpdatedState>
}

Event Swap

Emitted after a successful asset swap.

The event records the swap direction, input and output amounts, fees applied, and the resulting pool state.

struct (0x78e79ba4) Swap {
    xToY: bool
    amountIn: coins
    amountOut: coins
    initiatorAddress: address
    recipientAddress: address
    nextState: Cell<PoolUpdatedState>
    fees: Cell<SwapFees>
}

Payments

Payments are value-carrying messages that instruct the pool to perform a specific operation. Each payment includes a payment payload describing the operation parameters and MUST be accompanied by the appropriate asset transfer (native TON or jetton).

Payment Swap

Requests execution of an asset swap subject to slippage and time constraints.

For a step-by-step walkthrough of this process, see Swap.

struct (0xc442500f) Swap {
    minimalAmountOut: coins
    deadline: uint40
    next: Cell<SwapStep>?
    partnerConfig: PartnerConfig?
    referrerConfig: ReferrerConfig?
}

Semantics

• The swap MUST fail if amountOut < minimalAmountOut.
• The swap MUST fail if the current time is greater than deadline.
• If next is present, the swap is treated as part of a multi-hop route.

Payment Deposit

Requests a liquidity deposit into the pool.

The deposit is fulfilled via two separate asset payments:

• amountX specifies the expected amount of asset X
• amountY specifies the expected amount of asset Y

Liquidity is added to the pool only after both payments are received. If either payment is missing or does not match the declared amounts, the deposit must not be finalized.

For a step-by-step walkthrough of this process, see Liquidity Provisioning.

struct (0xc9a015da) Deposit {
    amountX: coins
    amountY: coins
    minimalLiquidity: coins
    lockedLiquidityShare: uint16
}

Semantics

• A Deposit payment initiates a multi-step process. The Pool deploys a temporary Deposit contract to accumulate the required assets.
• The operation MUST fail if the actual minted liquidity is less than minimalLiquidity (slippage protection).
• lockedLiquidityShare determines the portion of the minted liquidity that will be marked as "permanently locked" in the user's Position, preventing withdrawal.
• The Pool calculates the required amount of the second asset based on the first payment's amount and the current reserves to maintain the constant product invariant.

Payment FundReward

Funds an active reward program of the pool. This payment increases the remaining budget of the specified reward program and potentially extends its duration.

struct (0x2eb87df9) FundReward {
    till: uint40
}

Semantics

• The payment MUST be accompanied by the asset defined in the pool's RewardConfig.
• The new duration (till - now) MUST NOT exceed the maxDuration specified in the reward configuration.
• If the reward is already active, the funding MUST NOT dilute the current reward rate.

Incoming Messages

Message InitPool

Starts the pool initialization process. This call triggers the resolution of jetton wallet addresses for the pool's assets and any allowed reward jettons. Once all addresses are resolved, the pool state transitions to initialized.

struct (0xde8402ce) InitPool {
    queryId: uint64
    customPayload: cell?
}

Message PayNative

Used for payments in native TON.

struct (0xa5a7cbf8) PayNative {
    queryId: uint64
    amount: coins
    paymentPayload: cell
    payoutConfig: Cell<ExtendedPayoutConfig>
}

Message TransferNotification

A standard TEP-74 notification message received by the pool when jettons are transferred to it. The pool parses the forwardPayload to determine which operation (swap, deposit, or reward funding) to perform.

struct (0x7362d09c) TransferNotificationMessage {
    queryId: uint64
    amount: coins
    sender: address
    forwardPayload: RemainingBitsAndRefs | cell
}

Message JoinLiquidity

Sent by a Deposit contract to the Pool to finalize a liquidity provision. This message is sent only after the Deposit contract has successfully collected both required assets. The pool then mints liquidity tokens and updates its reserves.

struct (0x25251ee0) JoinLiquidity {
    queryId: uint64
    config: Cell<DepositConfig>
    amountX: coins
    amountY: coins
    initiatorAddress: address
}

Message RefundDeposit

Sent by a Deposit contract to the Pool to finalize a liquidity provision. This message is sent only after the Deposit contract has successfully collected both required assets. The pool then mints liquidity tokens and updates its reserves.

struct (0x0d299e12) RefundDeposit {
    queryId: uint64
    config: Cell<DepositConfig>
    amountX: coins
    amountY: coins
    initiatorAddress: address
}

Message TakeWalletAddress

A callback message used during pool initialization. It is sent by a Jetton Minter (or a custom resolver) to provide the address of the Jetton Wallet that the pool should use.

struct (0xd1735400) TakeWalletAddress {
    queryId: uint64
    walletAddress: address
    ownerAddress: Cell<address>?
}

Message ClaimPositionFees

Initiates the collection of accrued trading fees for a specific liquidity position. The pool synchronizes the fee states and forwards a request to the user's Position contract to calculate and claim the available fees.

struct (0x5652f1df) ClaimPositionFees {
    queryId: uint64
    excessesTo: address
}

Message PayoutPositionFees

Sent by a Position contract to the Pool to trigger the actual transfer of collected fees to the position owner.

struct (0x29ff1bcf) PayoutPositionFees {
    queryId: uint64
    xFees: coins
    yFees: coins
    ownerAddress: address
    excessesTo: address
}

Message ClaimProtocolFees

Allows the protocol controller to withdraw accumulated protocol fees from the pool. The message triggers the transfer of the specified assets to the destination address, provided the sender is authorized.

struct (0x419a17b3) ClaimProtocolFees {
    queryId: uint64
    to: address
    excessesTo: address
}

Message ClaimCreatorFees

Allows the pool creator to withdraw their share of accumulated trading fees. The pool verifies that the sender matches the creatorAddress defined in the pool's configuration and transfers the available fees.

struct (0xbe3e3179) ClaimCreatorFees {
    queryId: uint64
    to: address
    excessesTo: address
}

Message Withdraw

Initiates the withdrawal of liquidity from the pool. This message is sent to the pool, which then forwards the request to the user's Position contract to burn the liquidity tokens and calculate the proportional share of reserves to be returned.

struct (0x20b5ef89) Withdraw {
    queryId: uint64
    liquidity: coins
    minimalXOut: coins
    minimalYOut: coins
    autoClaimFees: bool
    payoutConfig: Cell<BasicPayoutConfig>
}

Message ExitLiquidity

Sent by a Position contract to the Pool to finalize the withdrawal process. The pool burns the liquidity tokens, updates its reserves, and sends the corresponding assets to the user.

struct (0xf6f6a3aa) ExitLiquidity {
    queryId: uint64
    liquidity: coins
    xFees: coins
    yFees: coins
    ownerAddress: address
    minimalAmountX: coins
    minimalAmountY: coins
    payoutConfig: Cell<BasicPayoutConfig>
}

Message ProvidePoolState

Requests a snapshot of the current pool state. The pool responds with a TakePoolState message. Detailed information such as configuration, fees, or reward settings can be requested via optional flags.

TODO: state that the response (TakePoolState) will contain null or Maybe values for the requested fields if the flags are false.

struct (0x00d8d379) ProvidePoolState {
    queryId: uint64
    includeConfig: bool
    includeFees: bool
    includeCodeHash: bool
    includeRewards: bool
}

Parameters

Caller: Any address.

Message ClaimReward

Initiates the process of claiming earned rewards for a specific reward program. The pool synchronizes reward states and forwards the claim request to the user's Position contract.

struct (0x909fdb65) ClaimReward {
    queryId: uint64
    rewardIndex: uint2
    excessesTo: address
}

Parameters

Message PayoutReward

Sent by a Position contract to the Pool to request the actual distribution of earned rewards to the position owner.

struct (0x9e17fbbe) PayoutReward {
    queryId: uint64
    amount: coins
    rewardIndex: uint2
    ownerAddress: address
    excessesTo: address
}

Parameters

Outgoing Messages

Message InitPoolResult

Sent to the initiator after an attempt to initialize the pool. It indicates whether the setup was successful or failed with a specific error.

struct (0xce185bd7) InitPoolResult {
  queryId: uint64
  exitCode: int32
  customPayload: cell?
}

Message TakePoolState

TakePoolState is sent in response to a ProvidePoolState request. It returns a snapshot of the current pool state. Optional fields are included only if explicitly requested via the corresponding include* flags in ProvidePoolState.

struct (0x870a9579) TakePoolState {
    queryId: uint64
    status: PoolStatus
    depositActive: bool
    swapActive: bool
    liquidity: coins
    reserveX: coins
    reserveY: coins
    config: Cell<PoolConfig>?
    fees: Cell<PoolFees>?
    rewards: PoolRewards?
    codeHash: uint256?
}

Other Payloads

Payload PayJetton

Used for jetton payments. This payload is expected to be received as the forward_payload of a TransferNotification.

This structure contains the business logic payload (e.g., a swap or deposit request) and the configuration for handling the operation's result.

struct (0xcbc33949) PayJetton {
    paymentPayload: cell
    payoutConfig: Cell<ExtendedPayoutConfig>
}

Other Types

Type PoolStatus

Represents the current lifecycle stage of the pool.

struct (0b00) PoolStatusUninitialized {
}

struct (0b01) PoolStatusInitializing {
    initiatorAddress: address
}

struct (0b10) PoolStatusInitialized {
}

type PoolStatus =
    | PoolStatusUninitialized
    | PoolStatusInitializing
    | PoolStatusInitialized

Initializing Parameters

Type PoolConfig

Defines the immutable configuration parameters of the pool, established during its initialization.

struct PoolConfig {
    assetX: Asset
    assetY: Asset
    creatorAddress: address
    baseFeeBPS: uint16
    creatorFeeBPS: uint16
    depositActivation: Cell<Activation>?
    swapActivation: Cell<Activation>?
    feeIn: FeeIn
    customResolvers: map<uint256, address>
    allowedRewards: map<uint2, RewardConfig>
}

Type Asset

Represents an asset identifier used by the pool (e.g. a jetton or native token).

type Asset = address_any

Type FeeIn

Defines the strategy for swap fee collection. The pool can collect fees in both assets of the pair or restrict it to one specific asset.

enum FeeIn : uint2 {
    Both = 0b00
    AssetX = 0b01
    AssetY = 0b10
}

Type Activation

Defines when swaps or deposits can be used, or who triggers their activation.

struct (0x01) ActivationTime {
    activeSince: uint40
}

struct (0x02) ActivationInitiator {
    initiatorAddress: address
}

type Activation =
    | ActivationTime
    | ActivationInitiator

Time-based activation

Initiator-based activation

Type RewardConfig

Defines configuration parameters for a reward program.

struct RewardConfig {
    asset: Asset;
    maxDuration: uint40;
}

Type PoolRewards

Represents all active reward programs of the pool.

It is encoded as a map indexed by a local index of reward.

type PoolRewards = map<uint2, PoolReward>

Type PoolReward

Represents the current state of a single reward program.

struct PoolReward {
    remainingTime: uint40
    remainingBudget: coins
    rewardsPerToken: Q120X120
    lastUpdate: uint40
}

Type SwapFees

Represents the fee breakdown applied to a single swap.

struct SwapFees {
    isX: bool;
    lpFee: coins;
    creatorFee: coins;
    protocolFee: coins;
    partnerFee: coins;
    referrerFee: coins;
}

Type Q120X120

A Q120.120 fixed-point number representation.

This format uses:

• 120 bits for the integer part
• 120 bits for the fractional part

It is used for high-precision fractional values, such as accumulated fees per unit of liquidity.

See: https://en.wikipedia.org/wiki/Q_(number_format)

type Q120X120 = varuint32

Type PoolFees

Represents accumulated fees and fee distribution state of the pool.

• protocolFee* — fees owed to the protocol
• creatorFee* — fees owed to the pool creator
• *FeePerToken — accumulated fee per unit of liquidity, used for proportional distribution

struct PoolFees {
    protocolFeeX: coins
    protocolFeeY: coins
    creatorFeeX: coins
    creatorFeeY: coins
    xFeePerToken: Q120X120
    yFeePerToken: Q120X120
}

Type PoolUpdatedState

A compact state snapshot emitted after pool-state-changing operations.

This structure contains only the minimal set of fields required to describe an updated pool state and is typically used in events, notifications, or intermediate computations.

struct PoolUpdatedState {
    reserveX: coins
    reserveY: coins
    liquidity: coins
    fees: Cell<PoolFees>
}

Type SwapStep

Defines a single step in a multi-hop swap. Multiple SwapStep instances may be chained via next to describe routed swaps across several pools.

struct SwapStep {
    pool: address
    minimalAmountOut: coins
    deadline: uint40
    next: Cell<SwapStep>?
}

Type PartnerConfig

Specifies partner attribution and fee sharing for a swap operation.

struct PartnerConfig {
    partnerId: uint256
    partnerFeeBPS: uint16
}

Type ReferrerConfig

Specifies referrer attribution and fee sharing for a swap operation.

struct ReferrerConfig {
    referrerId: uint256
    referrerFeeBPS: uint16
}

Type ExtendedPayoutConfig

Configuration for handling both successful and rejected payment operations.

struct ExtendedPayoutConfig {
    fulfill: PayoutOptions
    reject: PayoutOptions
    excessesTo: address
}

Type BasicPayoutConfig

Simplified configuration used for operations where only one outcome path is required, such as withdrawals.

struct BasicPayoutConfig {
    options: PayoutOptions
    excessesTo: address
}

Type PayoutOptions

Detailed parameters for asset delivery and notification.

struct PayoutOptions {
    destination: address
    extraGas: coins
    payload: cell?
    wrapPayload: bool
}

Payload PayoutPayload

A wrapper used in outgoing messages to provide the result of an operation. It is automatically generated if wrapPayload is set to true in PayoutOptions.

struct (0xe8db4696) PayoutPayload {
    exitCode: int32
    payload: cell?
}