Concepts

This section provides a high-level overview of the core concepts and architectural components of the CPMM V2 protocol.

Assets

In CPMM V2, an asset is an abstract representation of a value that can be traded or deposited. The protocol supports three distinct types of assets, identified by their address format:

1. Native (TON): Represented by addr_none. This is the native currency of the TON blockchain.
2. Jettons: Represented by a standard internal address (addr_std). This identifies the Jetton Minter (root) contract.
3. Extra Currencies (Not supported yet, but included in the design): Represented by an external address ( addr_extern) with a length of 32 bits, where the value corresponds to the currency_id.

Payment Abstraction

The protocol uses a unified payment abstraction to handle different asset types consistently. Whether a user provides TON or Jettons, the logic for swaps and deposits remains the same.

The business logic for any operation (like a swap or deposit) is encapsulated in a payment payload. This payload is passed via the paymentPayload field in one of the following two ways, depending on the asset:

• Native Payments: Sent via the PayNative message directly to the Pool. The paymentPayload is included as a reference in the message.
• Jetton Payments: Received via a standard Jetton TransferNotification. The forwardPayload of this notification must contain a PayJetton structure, which in turn holds the paymentPayload.

Payout Configuration

Every payment (via PayNative or PayJetton) includes a payoutConfig. This tells the contract exactly where to send fulfilling assets, where to return funds on rejection, and how much "extra gas" to attach for downstream notifications.

Fees

The protocol implements a multi-tier fee structure to incentivize participants and maintain the ecosystem.

Creator Fee

The Creator Fee is a unique feature of CPMM V2 that allows the pool's creator to earn a percentage of every swap performed in that pool.

• Configuration: The fee is set during pool initialization via creatorFeeBPS (basis points).
• Authorization: Only the address specified as creatorAddress in the PoolConfig can claim these fees.
• Claiming: Fees are accumulated in the Pool contract and can be withdrawn at any time using the ClaimCreatorFees message.

Fee Collection Strategies (Fee-In)

By default, fees are collected in the input asset of a swap. However, the protocol supports flexible strategies:

• Both: Fees are collected in the asset being sold (standard).
• Asset X Only: All fees (for both X→Y and Y→X swaps) are collected in Asset X.
• Asset Y Only: All fees are collected in Asset Y.

Affiliate Fee

The Affiliate Fee system allows integrators (partners and referrers) to earn commissions from swaps facilitated through their platforms.

• Attribution: When a swap is initiated, the paymentPayload can include optional PartnerConfig and ReferrerConfig.
• Fee Structure: Partners and referrers specify their desired fee in basis points (BPS). This fee is added on top of the pool's base trading fees.
• Distribution: Affiliate fees are deducted from the swap output and accumulated in dedicated Affiliate Account contracts, ensuring that integrators can claim their earnings independently of the pool's main reserves.

Core Contracts

The protocol's logic is distributed across three specialized contracts:

Pool

The central orchestrator. It holds the reserves for a specific asset pair (X and Y) and implements the Constant Product Market Maker formula ($x \times y = k$). It handles swap execution, fee distribution, and manages incentive programs.

Position

A non-transferable contract that represents a specific user's liquidity in a specific pool. It tracks the user's total liquidity, "locked" shares, and calculates accrued trading fees and rewards proportionally.

Deposit

A temporary "escrow" or accumulator. Since a liquidity deposit requires two assets but TON messages usually carry one, the Deposit contract collects both before sending a combined JoinLiquidity request to the Pool.

Wallet Resolution

When a pool is first created, it doesn't know the addresses of its own Jetton Wallets (where it will store the assets).

Wallet Resolution is the process that happens during the Initializing state. The pool sends requests to Jetton Minters to "discover" its wallet addresses. This ensures that the pool only accepts and sends assets through its own verified wallets, preventing various security exploits.

Rewards

Pools can be incentivized through Rewards.

• Funding: Anyone can fund a reward program by providing the required asset and specifying a duration.
• Distribution: Rewards are distributed to liquidity providers proportionally based on their share of the total liquidity.
• Incentive Checkpoints: When a user's liquidity changes (deposit or withdrawal), the Position contract syncs with the Pool's rewardsPerToken to ensure accurate claiming.