STON.fi DEX Core V2

https://github.com/ston-fi/dex-core-v2
Admin
STON.fi DEX Core V2 is a decentralized exchange protocol built on the TON blockchain, providing core...
Tokens:53,216
Snippets:286
Trust Score:7.5
License:GPL-3.0
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Basic swap through the router

Source: https://github.com/ston-fi/dex-core-v2/blob/main/_autodocs/api-reference/wrappers-Router.md

Performs a basic swap through the router using `sendSwap`. Requires a `NetworkProvider`, router address, and user address. The example sets a 1 TON budget, specifies a jetton amount, destination pair side, slippage protection via `minOut`, a deadline 300 seconds in the future, an optional referral address, and an excesses address.

```ts
import { Address, beginCell, toNano, OpenedContract } from '@ton/core';
import { NetworkProvider } from '@ton/blueprint';
import { Router } from './wrappers/Router';

async function dexSwap(provider: NetworkProvider, routerAddr: Address, user: Address) {
    const router = provider.open(Router.createFromAddress(routerAddr));
    // 1 token = 1e9 nanounits; give 1 TON budget for the route
    await router.sendSwap(provider.sender(), {
        jettonAmount: 1_500_000_000n,          // amount in
        fromAddress: user,
        otherWalletAddress: USDT_WALLET,       // destination pair side
        minOut: 1_300_000_000n,                // slippage protection
        deadline: Math.floor(Date.now() / 1000) + 300,
        refAddress: REFERRAL_ADDRESS,          // optional referral
        excessesAddress: user,
    }, toNano('1'));
}
```

--------------------------------

### get_wallet_data get method

Source: https://github.com/ston-fi/dex-core-v2/blob/main/_autodocs/api-reference/lp-wallet-contract.md

Get method that returns the wallet data tuple (balance, owner_address, jetton_master_address, jetton_wallet_code) via storage::load().

```func
(int, slice, slice, cell) get_wallet_data() method_id
```

--------------------------------

### Pool Interface Implementation

Source: https://github.com/ston-fi/dex-core-v2/blob/main/contracts/pool/pools/README.md

Defines the mandatory functions a pool contract must expose: state initialization, swap and LP calculations, storage save/load, and offchain get method. Use this as a template when implementing a new pool.

```func
;; state_init
(cell) pool_idata(slice _router_address, slice _first_jetton_address, slice _second_jetton_address, cell _jetton_lp_wallet_code, cell _lp_account_code);

;; pool
(int, int, int) pool::get_swap_out(int _side, int _ref_value, int _amount_in, int _reserve_in, int _reserve_out);
(int, int, int) pool::get_lp_provide_out(int _left_amount, int _right_amount);
(int)           pool::get_lp_provide_init_out(int _left_amount, int _right_amount);
(int, int)      pool::get_lp_burn_out(int _lp_amount);

;; storage functions
() storage::save();
() storage::load();

;; offchain get methods
_ get_pool_data();
```

--------------------------------

### LP Account get_lp_account_data get method

Source: https://github.com/ston-fi/dex-core-v2/blob/main/_autodocs/api-reference/lp-account-contract.md

Off-chain get method that returns the stored user address, pool address, amount0, and amount1. Used to query the account's current state.

```func
_ get_lp_account_data() method_id
```

--------------------------------

### State-init data builder declarations (vault_idata, lp_account_idata, lp_wallet_idata)

Source: https://github.com/ston-fi/dex-core-v2/blob/main/_autodocs/api-reference/message-builders.md

Declarations for the three state-init data builders. Each stores its fields in the order listed in the table: vault_idata stores user_address, token_address, router_address, then 0:Coins; lp_account_idata stores user_address, pool_address, then two 0:Coins; lp_wallet_idata stores 0:Coins, owner_address, jetton_master_address, and a reference to jetton_wallet_code.

```func
(cell) vault_idata(slice _user_address, slice _token_address, slice _router_address) inline;
(cell) lp_account_idata(slice _pool_address, slice _user_address) inline;
(cell) lp_wallet_idata(slice _owner_address, slice _jetton_master_address, cell _jetton_wallet_code) inline;
```

--------------------------------

### provideLpPayload(opts)

Source: https://github.com/ston-fi/dex-core-v2/blob/main/_autodocs/api-reference/wrappers-Router.md

Builds the `dex_payload` for `op::provide_lp`.

```APIDOC
## provideLpPayload(opts)

### Description
Builds the `dex_payload` for `op::provide_lp`.

### Signature
```ts
export function provideLpPayload(opts: {
    otherTokenAddress: Address, minLpOut?: bigint | number, customPayload?: Cell,
    fwdAmount?: bigint, toAddress: Address, refundAddress: Address,
    excessesAddress?: Address, bothPositive?: boolean, deadline: number
}): Builder
```

### Parameters
- **otherTokenAddress** (Address) - Required - The address of the other token.
- **minLpOut** (bigint | number) - Optional - Minimum LP tokens expected. Defaults to `1n`.
- **customPayload** (Cell) - Optional - Custom payload to include.
- **fwdAmount** (bigint) - Optional - Forward amount. Defaults to `0n`.
- **toAddress** (Address) - Required - The address to send LP tokens to.
- **refundAddress** (Address) - Required - The address to refund excess funds to.
- **excessesAddress** (Address) - Optional - The address to send excesses to. Defaults to `refundAddress`.
- **bothPositive** (boolean) - Optional - Flag indicating both tokens are positive. Defaults to `0` (false).
- **deadline** (number) - Required - The deadline for the operation.

### Returns
- **Builder** - The built payload builder.

### Payload Structure
`(opcode, otherTokenAddress, refundAddress, excessesAddress|refundAddress, deadline:64, ref[minLpOut ?? 1n, toAddress, bothPositive?1:0, fwdAmount ?? 0n, customPayload])`
```

--------------------------------

### get_vault_data get method signature

Source: https://github.com/ston-fi/dex-core-v2/blob/main/_autodocs/api-reference/vault-contract.md

Get method that returns the vault's owner address, token address, router address, and deposited amount. The client equivalent Vault.getVaultData(provider) parses the stack in the same order.

```func
_ get_vault_data() method_id
```

--------------------------------

### Router.createFromConfig

Source: https://github.com/ston-fi/dex-core-v2/blob/main/_autodocs/api-reference/wrappers-Router.md

Static factory method to create a Router instance from configuration and code.

```APIDOC
## [Class] Router

### Description
Creates a new Router instance from a configuration and code cell. This is a static factory method that serializes the configuration, computes the contract address, and returns a new Router instance.

### Method
`static createFromConfig(config: RouterConfig, code: Cell, workchain = 0): Router`

### Parameters
- **config** (RouterConfig) - Required - The router configuration.
- **code** (Cell) - Required - The contract code cell.
- **workchain** (number) - Optional - The workchain ID, defaults to 0.

### Returns
- **Router** - A new Router instance.

### Example
```ts
const router = Router.createFromConfig(config, code, 0);
```
```

--------------------------------

### swapPayload(opts)

Source: https://github.com/ston-fi/dex-core-v2/blob/main/_autodocs/api-reference/wrappers-Router.md

Builds the `dex_payload` for `op::swap`.

```APIDOC
## swapPayload(opts)

### Description
Builds the `dex_payload` for `op::swap`.

### Signature
```ts
export function swapPayload(opts: {
    otherTokenWallet: Address, receiver: Address, minOut?: bigint, fwdGas?: bigint,
    refundFwdGas?: bigint, refAddress?: Address, refundAddress: Address,
    excessesAddress?: Address, deadline: number, customPayload?: Cell,
    refundPayload?: Cell, refFee?: bigint
}): Builder
```

### Parameters
- **otherTokenWallet** (Address) - Required - The address of the other token wallet.
- **receiver** (Address) - Required - The address that receives the swapped tokens.
- **minOut** (bigint) - Optional - Minimum output amount. Defaults to `1n`.
- **fwdGas** (bigint) - Optional - Forward gas amount. Defaults to `0n`.
- **refundFwdGas** (bigint) - Optional - Refund forward gas amount. Defaults to `0n`.
- **refAddress** (Address) - Optional - Referral address. Defaults to `null`.
- **refundAddress** (Address) - Required - The address to refund excess funds to.
- **excessesAddress** (Address) - Optional - The address to send excesses to.
- **deadline** (number) - Required - The deadline for the operation.
- **customPayload** (Cell) - Optional - Custom payload to include.
- **refundPayload** (Cell) - Optional - Refund payload.
- **refFee** (bigint) - Optional - Referral fee. Defaults to `10` (0.1%).

### Returns
- **Builder** - The built payload builder.
```

--------------------------------

### crossSwapPayload(opts)

Source: https://github.com/ston-fi/dex-core-v2/blob/main/_autodocs/api-reference/wrappers-Router.md

Builds the `dex_payload` for `op::crossSwap`.

```APIDOC
## crossSwapPayload(opts)

### Description
Builds the `dex_payload` for `op::crossSwap`. Same shape as `swapPayload` but with `op::crossSwap`. Pass its output as `customPayload` of an outer `swapPayload` to chain swaps on one router (`swapPayload`'s `customPayload` may also carry it).

### Signature
```ts
export function crossSwapPayload(opts: {
    otherTokenWallet: Address, receiver: Address, minOut?: bigint, fwdGas?: bigint,
    refundFwdGas?: bigint, refAddress?: Address, refundAddress: Address,
    excessesAddress?: Address, deadline: number, customPayload?: Cell,
    refundPayload?: Cell, refFee?: bigint
}): Builder
```

### Parameters
- **otherTokenWallet** (Address) - Required - The address of the other token wallet.
- **receiver** (Address) - Required - The address that receives the swapped tokens.
- **minOut** (bigint) - Optional - Minimum output amount. Defaults to `1n`.
- **fwdGas** (bigint) - Optional - Forward gas amount. Defaults to `0n`.
- **refundFwdGas** (bigint) - Optional - Refund forward gas amount. Defaults to `0n`.
- **refAddress** (Address) - Optional - Referral address. Defaults to `null`.
- **refundAddress** (Address) - Required - The address to refund excess funds to.
- **excessesAddress** (Address) - Optional - The address to send excesses to.
- **deadline** (number) - Required - The deadline for the operation.
- **customPayload** (Cell) - Optional - Custom payload to include.
- **refundPayload** (Cell) - Optional - Refund payload.
- **refFee** (bigint) - Optional - Referral fee. Defaults to `10` (0.1%).

### Returns
- **Builder** - The built payload builder.
```

--------------------------------

### LPWallet class constructor and static method

Source: https://github.com/ston-fi/dex-core-v2/blob/main/_autodocs/api-reference/wrappers-LPWallet.md

Constructor and static factory method for LPWallet. createFromConfig takes a config, code, and optional workchain (default 0).

```typescript
constructor(readonly address: Address, readonly init?: { code: Cell; data: Cell; })
static createFromConfig(config: LPWalletConfig, code: Cell, workchain = 0): LPWallet
```

--------------------------------

### LPAccount static createFromConfig method

Source: https://github.com/ston-fi/dex-core-v2/blob/main/_autodocs/api-reference/wrappers-LPAccount.md

Creates an LPAccount instance from a config, code, and optional workchain. Inherits other methods from CommonContractBase.

```TypeScript
static createFromConfig(config: LPAccountConfig, code: Cell, workchain = 0): LPAccount
```

--------------------------------

### Liquidity message builder declarations (pool::cb_refund_me, pool::cb_add_liquidity, lp_account::add_liquidity)

Source: https://github.com/ston-fi/dex-core-v2/blob/main/_autodocs/api-reference/message-builders.md

Declarations for the liquidity message builders. pool::cb_refund_me is the LP Account → Pool refund callback; pool::cb_add_liquidity is the LP Account → Pool post-deposit callback; lp_account::add_liquidity is the Pool → LP Account instruction. Each stores its documented fields in order.

```func
(cell) pool::cb_refund_me(int _left_amount, int _right_amount, cell _left_maybe_payload, cell _right_maybe_payload) inline;
(cell) pool::cb_add_liquidity(
    slice _user_address, int _left_amount, int _right_amount, slice _to_user,
    int _min_lp_out, int _fwd_amount, cell _custom_payload_cs,
    slice _refund_address, slice _excess_address) inline;
(cell) lp_account::add_liquidity(
    int _left_amount, int _right_amount, int _min_lp_out, int _fwd_amount,
    int _both_positive?, slice _to_user, cell _custom_payload_cs,
    slice _refund_address, slice _excess_address) inline;
```

--------------------------------

### Deposit both legs and mint using LPAccount

Source: https://github.com/ston-fi/dex-core-v2/blob/main/_autodocs/api-reference/wrappers-LPAccount.md

Sends a direct add liquidity operation with specified token amounts, using zero amounts to indicate using stored balance. Defaults for minOut, fwdAmount, and addresses are applied if not provided.

```TypeScript
import { LPAccount } from './wrappers/LPAccount';

const lpAcc = provider.open(LPAccount.createFromAddress(lpAccAddress));
// zero amounts mean "use the amount already stored inside the account"
const res = await lpAcc.sendDirectAddLiquidity(provider.sender(), {
    amount1: toNano('50'),      // token0 amount
    amount2: toNano('1000'),    // token1 amount
    minOut: 1n,
    toAddress: MY_ADDR,
    excessesAddress: MY_ADDR,
});
```

--------------------------------

### Payload-builder option types for Router methods

Source: https://github.com/ston-fi/dex-core-v2/blob/main/_autodocs/types.md

Lists the option types for provideLpPayload, swapPayload, and crossSwapPayload methods. These options configure token addresses, amounts, deadlines, and other parameters for building payloads.

```typescript
provideLpPayload(opts: { otherTokenAddress: Address; minLpOut?: bigint | number; customPayload?: Cell; fwdAmount?: bigint; toAddress: Address; refundAddress: Address; excessesAddress?: Address; bothPositive?: boolean; deadline: number })
```

```typescript
swapPayload(opts: { otherTokenWallet: Address; receiver: Address; minOut?: bigint; fwdGas?: bigint; refundFwdGas?: bigint; refAddress?: Address; refundAddress: Address; excessesAddress?: Address; deadline: number; customPayload?: Cell; refundPayload?: Cell; refFee?: bigint })
```

```typescript
crossSwapPayload(opts: { otherTokenWallet: Address; receiver: Address; fwdGas?: bigint; minOut?: bigint; refAddress?: Address; refundAddress: Address; excessesAddress?: Address; customPayload?: Cell; refundFwdGas?: bigint; deadline: number; refFee?: bigint; refundPayload?: Cell })
```

--------------------------------

### RouterBase Methods

Source: https://github.com/ston-fi/dex-core-v2/blob/main/_autodocs/api-reference/wrappers-Router.md

All send* methods follow the same signature shape: async send<Op>(provider, via, opts, value?). The value defaults to DefaultValues.DEFAULT_MSG_VALUE (1 TON) and send mode is SendMode.PAY_GAS_SEPARATELY.

```APIDOC
## sendResetGas

### Description
Sends a `reset_gas` message from the admin to reset the gas of the router.

### Method
send

### Parameters
#### Request Body
- `provider` (ContractProvider) - Required - The contract provider.
- `via` (Sender) - Required - The sender of the transaction.
- `opts` (object) - Required - Empty object.
- `value` (bigint) - Optional - Amount of TON to send. Defaults to `DefaultValues.DEFAULT_MSG_VALUE` (1 TON).

### Response
Returns a Promise that resolves when the transaction is sent.
```

```APIDOC
## sendResetPoolGas

### Description
Sends a `reset_pool_gas` message to reset the gas of a specific pool.

### Method
send

### Parameters
#### Request Body
- `provider` (ContractProvider) - Required - The contract provider.
- `via` (Sender) - Required - The sender of the transaction.
- `opts` (object) - Required - Contains the following fields:
  - `firstWalletAddress` (Address) - Required - Address of the first wallet.
  - `secondWalletAddress` (Address) - Required - Address of the second wallet.
  - `excessesAddress` (Address) - Optional - Address to send excesses to.
- `value` (bigint) - Optional - Amount of TON to send. Defaults to `DefaultValues.DEFAULT_MSG_VALUE` (1 TON).

### Response
Returns a Promise that resolves when the transaction is sent.
```

```APIDOC
## sendUpdatePoolStatus

### Description
Sends an `update_pool_status` message to update the status of a pool.

### Method
send

### Parameters
#### Request Body
- `provider` (ContractProvider) - Required - The contract provider.
- `via` (Sender) - Required - The sender of the transaction.
- `opts` (object) - Required - Contains the following fields:
  - `firstWalletAddress` (Address) - Required - Address of the first wallet.
  - `secondWalletAddress` (Address) - Required - Address of the second wallet.
  - `excessesAddress` (Address) - Optional - Address to send excesses to.
- `value` (bigint) - Optional - Amount of TON to send. Defaults to `DefaultValues.DEFAULT_MSG_VALUE` (1 TON).

### Response
Returns a Promise that resolves when the transaction is sent.
```

```APIDOC
## sendSetFees

### Description
Sends a `set_fees` message to set the fees for a pool.

### Method
send

### Parameters
#### Request Body
- `provider` (ContractProvider) - Required - The contract provider.
- `via` (Sender) - Required - The sender of the transaction.
- `opts` (object) - Required - Contains the following fields:
  - `newLPFee` (uint16) - Required - New LP fee in basis points.
  - `newProtocolFee` (uint16) - Required - New protocol fee in basis points.
  - `newProtocolFeeAddress` (Address) - Required - Address to receive protocol fees.
  - `leftWalletAddress` (Address) - Required - Address of the left wallet.
  - `rightWalletAddress` (Address) - Required - Address of the right wallet.
  - `excessesAddress` (Address) - Optional - Address to send excesses to.
- `value` (bigint) - Optional - Amount of TON to send. Defaults to `DefaultValues.DEFAULT_MSG_VALUE` (1 TON).

### Response
Returns a Promise that resolves when the transaction is sent.
```

```APIDOC
## sendUpdateStatus

### Description
Sends an `update_status` message from the admin to update the router status.

### Method
send

### Parameters
#### Request Body
- `provider` (ContractProvider) - Required - The contract provider.
- `via` (Sender) - Required - The sender of the transaction.
- `opts` (object) - Required - Empty object.
- `value` (bigint) - Optional - Amount of TON to send. Defaults to `DefaultValues.DEFAULT_MSG_VALUE` (1 TON).

### Response
Returns a Promise that resolves when the transaction is sent.
```

```APIDOC
## sendInitAdminUpgrade

### Description
Sends an `init_admin_upgrade` message to initialize an admin upgrade.

### Method
send

### Parameters
#### Request Body
- `provider` (ContractProvider) - Required - The contract provider.
- `via` (Sender) - Required - The sender of the transaction.
- `opts` (object) - Required - Contains the following fields:
  - `newAdmin` (Address) - Required - Address of the new admin.
- `value` (bigint) - Optional - Amount of TON to send. Defaults to `DefaultValues.DEFAULT_MSG_VALUE` (1 TON).

### Response
Returns a Promise that resolves when the transaction is sent.
```

```APIDOC
## sendInitCodeUpgrade

### Description
Sends an `init_code_upgrade` message to initialize a code upgrade.

### Method
send

### Parameters
#### Request Body
- `provider` (ContractProvider) - Required - The contract provider.
- `via` (Sender) - Required - The sender of the transaction.
- `opts` (object) - Required - Contains the following fields:
  - `newCode` (Cell) - Required - New code cell.
- `value` (bigint) - Optional - Amount of TON to send. Defaults to `DefaultValues.DEFAULT_MSG_VALUE` (1 TON).

### Response
Returns a Promise that resolves when the transaction is sent.
```

```APIDOC
## sendCancelCodeUpgrade

### Description
Sends a `cancel_code_upgrade` message to cancel a pending code upgrade.

### Method
send

### Parameters
#### Request Body
- `provider` (ContractProvider) - Required - The contract provider.
- `via` (Sender) - Required - The sender of the transaction.
- `opts` (object) - Required - Empty object.
- `value` (bigint) - Optional - Amount of TON to send. Defaults to `DefaultValues.DEFAULT_MSG_VALUE` (1 TON).

### Response
Returns a Promise that resolves when the transaction is sent.
```

```APIDOC
## sendInitPoolCodeUpgrade

### Description
Sends an `init_pool_code_upgrade` message to initialize a pool code upgrade.

### Method
send

### Parameters
#### Request Body
- `provider` (ContractProvider) - Required - The contract provider.
- `via` (Sender) - Required - The sender of the transaction.
- `opts` (object) - Required - Contains the following fields:
  - `newCode` (Cell) - Required - New code cell.
- `value` (bigint) - Optional - Amount of TON to send. Defaults to `DefaultValues.DEFAULT_MSG_VALUE` (1 TON).

### Response
Returns a Promise that resolves when the transaction is sent.
```

```APIDOC
## sendCancelPoolCodeUpgrade

### Description
Sends a `cancel_pool_code_upgrade` message to cancel a pending pool code upgrade.

### Method
send

### Parameters
#### Request Body
- `provider` (ContractProvider) - Required - The contract provider.
- `via` (Sender) - Required - The sender of the transaction.
- `opts` (object) - Required - Empty object.
- `value` (bigint) - Optional - Amount of TON to send. Defaults to `DefaultValues.DEFAULT_MSG_VALUE` (1 TON).

### Response
Returns a Promise that resolves when the transaction is sent.
```

```APIDOC
## sendCancelAdminUpgrade

### Description
Sends a `cancel_admin_upgrade` message to cancel a pending admin upgrade.

### Method
send

### Parameters
#### Request Body
- `provider` (ContractProvider) - Required - The contract provider.
- `via` (Sender) - Required - The sender of the transaction.
- `opts` (object) - Required - Empty object.
- `value` (bigint) - Optional - Amount of TON to send. Defaults to `DefaultValues.DEFAULT_MSG_VALUE` (1 TON).

### Response
Returns a Promise that resolves when the transaction is sent.
```

```APIDOC
## sendUpgradePoolCode

### Description
Sends an `update_pool_code` message to upgrade the code of a pool.

### Method
send

### Parameters
#### Request Body
- `provider` (ContractProvider) - Required - The contract provider.
- `via` (Sender) - Required - The sender of the transaction.
- `opts` (object) - Required - Contains the following fields:
  - `firstWalletAddress` (Address) - Required - Address of the first wallet.
  - `secondWalletAddress` (Address) - Required - Address of the second wallet.
- `value` (bigint) - Optional - Amount of TON to send. Defaults to `DefaultValues.DEFAULT_MSG_VALUE` (1 TON).

### Response
Returns a Promise that resolves when the transaction is sent.
```

```APIDOC
## sendFinalizeUpgrades

### Description
Sends a `finalize_upgrades` message to finalize pending upgrades.

### Method
send

### Parameters
#### Request Body
- `provider` (ContractProvider) - Required - The contract provider.
- `via` (Sender) - Required - The sender of the transaction.
- `opts` (object) - Required - Empty object.
- `value` (bigint) - Optional - Amount of TON to send. Defaults to `DefaultValues.DEFAULT_MSG_VALUE` (1 TON).

### Response
Returns a Promise that resolves when the transaction is sent.
```

```APIDOC
## sendPayTo

### Description
Sends a `pay_to` message to the router to permit raw token pushes.

### Method
send

### Parameters
#### Request Body
- `provider` (ContractProvider) - Required - The contract provider.
- `via` (Sender) - Required - The sender of the transaction.
- `opts` (object) - Required - Contains the following fields:
  - `owner` (Address) - Required - Owner address.
  - `leftAmount` (bigint) - Required - Amount of left token.
  - `leftWalletAddress` (Address) - Required - Address of the left wallet.
  - `rightAmount` (bigint) - Required - Amount of right token.
  - `rightWalletAddress` (Address) - Required - Address of the right wallet.
  - `fwdTonAmount` (bigint) - Optional - Forward TON amount.
  - `customPayload` (Cell) - Optional - Custom payload.
- `value` (bigint) - Optional - Amount of TON to send. Defaults to `DefaultValues.DEFAULT_MSG_VALUE` (1 TON).

### Response
Returns a Promise that resolves when the transaction is sent.
```

```APIDOC
## sendSwap

### Description
Sends a `transfer_notification` with a `swapPayload` to execute a swap.

### Method
send

### Parameters
#### Request Body
- `provider` (ContractProvider) - Required - The contract provider.
- `via` (Sender) - Required - The sender of the transaction.
- `opts` (object) - Required - Contains the following fields:
  - `jettonAmount` (bigint) - Required - Amount of jetton to swap.
  - `fromAddress` (Address) - Required - Address of the sender.
  - `otherWalletAddress` (Address) - Required - Address of the other wallet.
  - `toAddress` (Address) - Optional - Address to receive the output. Defaults to `fromAddress`.
  - `minOut` (bigint) - Optional - Minimum output amount. Defaults to `1n`.
  - `refAddress` (Address) - Optional - Referral address.
  - `fwdTonAmount` (bigint) - Optional - Forward TON amount.
  - `refundAddress` (Address) - Optional - Address to send refunds to. Defaults to `fromAddress`.
  - `customPayload` (Cell) - Optional - Custom payload.
  - `refValue` (bigint) - Optional - Referral fee. Defaults to `10`.
  - `refundPayload` (Cell) - Optional - Refund payload.
  - `refundFwdTonAmount` (bigint) - Optional - Forward TON amount for refund.
  - `excessesAddress` (Address) - Optional - Address to send excesses to. Defaults to `fromAddress`.
  - `deadline` (number) - Required - Deadline timestamp.
- `value` (bigint) - Optional - Amount of TON to send. Defaults to `DefaultValues.DEFAULT_MSG_VALUE` (1 TON).

### Response
Returns a Promise that resolves when the transaction is sent.
```

```APIDOC
## sendInvalidReq

### Description
Sends a `transfer_notification` with `custom=false` to test the router bounce.

### Method
send

### Parameters
#### Request Body
- `provider` (ContractProvider) - Required - The contract provider.
- `via` (Sender) - Required - The sender of the transaction.
- `opts` (object) - Required - Contains the following fields:
  - `jettonAmount` (bigint) - Required - Amount of jetton.
  - `fromAddress` (Address) - Required - Address of the sender.
- `value` (bigint) - Optional - Amount of TON to send. Defaults to `DefaultValues.DEFAULT_MSG_VALUE` (1 TON).

### Response
Returns a Promise that resolves when the transaction is sent.
```

```APIDOC
## sendProvideLiquidity

### Description
Sends a `transfer_notification` with a `provideLpPayload` to provide liquidity.

### Method
send

### Parameters
#### Request Body
- `provider` (ContractProvider) - Required - The contract provider.
- `via` (Sender) - Required - The sender of the transaction.
- `opts` (object) - Required - Contains the following fields:
  - `jettonAmount` (bigint) - Required - Amount of jetton to provide.
  - `fromAddress` (Address) - Required - Address of the sender.
  - `otherWalletAddress` (Address) - Required - Address of the other wallet.
  - `minLPOut` (bigint) - Optional - Minimum LP tokens to receive.
  - `fwdAmount` (bigint) - Optional - Forward TON amount.
  - `customPayload` (Cell) - Optional - Custom payload.
  - `bothPositive` (boolean) - Optional - Whether both amounts must be positive.
  - `toAddress` (Address) - Optional - Address to receive LP tokens. Defaults to `via.address`.
  - `deadline` (number) - Required - Deadline timestamp.
- `value` (bigint) - Optional - Amount of TON to send. Defaults to `DefaultValues.DEFAULT_MSG_VALUE` (1 TON).

### Response
Returns a Promise that resolves when the transaction is sent.
```

```APIDOC
## sendGetterPoolAddress

### Description
Sends an async `getter_pool_address` message (admin/test) to get the pool address.

### Method
send

### Parameters
#### Request Body
- `provider` (ContractProvider) - Required - The contract provider.
- `via` (Sender) - Required - The sender of the transaction.
- `opts` (object) - Required - Contains the following fields:
  - `leftWalletAddress` (Address) - Required - Address of the left wallet.
  - `rightWalletAddress` (Address) - Required - Address of the right wallet.
- `value` (bigint) - Optional - Amount of TON to send. Defaults to `DefaultValues.DEFAULT_MSG_VALUE` (1 TON).

### Response
Returns a Promise that resolves when the transaction is sent.
```

```APIDOC
## getRouterData

### Description
Calls `get_router_data` and unwraps the `temp_upgrade` cell into `endCode/endAdmin/endPool/pendingNewAdmin/pendingCode/pendingPoolCode`.

### Method
get

### Parameters
#### Request Body
- `provider` (ContractProvider) - Required - The contract provider.

### Response
Returns a Promise that resolves to an object with the following fields:
- `id` (number) - Router ID.
- `type` (number) - Router type.
- `isLocked` (boolean) - Whether the router is locked.
- `adminAddress` (Address) - Admin address.
- `tmpUpgradeCache` (Cell) - Temporary upgrade cache.
- `poolCode` (Cell) - Pool code.
- `jettonLPWalletCode` (Cell) - Jetton LP wallet code.
- `LPAccountCode` (Cell) - LP account code.
- `endCode` (Cell) - End code.
- `endAdmin` (Address) - End admin.
- `endPool` (Address) - End pool.
- `pendingNewAdmin` (Address) - Pending new admin.
- `pendingCode` (Cell) - Pending code.
- `pendingPoolCode` (Cell) - Pending pool code.
```

```APIDOC
## getPoolAddress

### Description
Calls `get_pool_address` to get the address of a pool.

### Method
get

### Parameters
#### Request Body
- `provider` (ContractProvider) - Required - The contract provider.
- `opts` (object) - Required - Contains the following fields:
  - `firstWalletAddress` (Address) - Required - Address of the first wallet.
  - `secondWalletAddress` (Address) - Required - Address of the second wallet.

### Response
Returns a Promise that resolves to an `Address`.
```

```APIDOC
## getVaultAddress

### Description
Calls `get_vault_address` to get the vault address for a user and token wallet.

### Method
get

### Parameters
#### Request Body
- `provider` (ContractProvider) - Required - The contract provider.
- `opts` (object) - Required - Contains the following fields:
  - `userAddress` (Address) - Required - Address of the user.
  - `tokenWalletAddress` (Address) - Required - Address of the token wallet.

### Response
Returns a Promise that resolves to an `Address`.
```

```APIDOC
## getUpgradedPoolCode

### Description
Calls `get_upgraded_pool_code` to get the upgraded pool code.

### Method
get

### Parameters
#### Request Body
- `provider` (ContractProvider) - Required - The contract provider.

### Response
Returns a Promise that resolves to a `Cell`.
```

```APIDOC
## getRouterVersion

### Description
Calls `get_router_version` to get the router version.

### Method
get

### Parameters
#### Request Body
- `provider` (ContractProvider) - Required - The contract provider.

### Response
Returns a Promise that resolves to an object with the following fields:
- `major` (number) - Major version.
- `minor` (number) - Minor version.
- `dev` (string) - Development version string.
```

--------------------------------

### Getter Messages for Pool and LP Account Data (Func)

Source: https://github.com/ston-fi/dex-core-v2/blob/main/_autodocs/api-reference/message-builders.md

Defines four getter message builders that pack pool and LP account data into cells. `getter_pool_data` packs fees and router address into a referenced cell with the specified layout. Anyone can invoke these asynchronously.

```func
(cell) anyone::getter_lp_account_data(slice _user_address, slice _pool_address, int _left_amount, int _right_amount) inline;
(cell) anyone::getter_pool_data(
    int _is_locked, slice _router_address, int _total_supply_lp, int _left_reserve, int _right_reserve,
    slice _left_token_address, slice _right_token_address, int _lp_fee, int _protocol_fee,
    slice _protocol_fee_address, int _collected_left_token_protocol_fees, int _collected_right_token_protocol_fees) inline;
(cell) anyone::getter_lp_account_address(slice _addr) inline;
(cell) anyone::getter_pool_address(slice _addr) inline;
```

--------------------------------

### Read pool state and derive LP account with PoolCPI

Source: https://github.com/ston-fi/dex-core-v2/blob/main/_autodocs/api-reference/wrappers-Pool.md

Opens a pool using PoolCPI and reads its data, type, and LP account address. The getPoolData() call returns a 12-field snapshot, and getPoolType() returns a string like "constant_product". Requires a NetworkProvider and a pool address.

```typescript
import { NetworkProvider } from '@ton/blueprint';
import { PoolCPI } from './wrappers/Pool';

async function inspect(provider: NetworkProvider, poolAddr: Address) {
    const pool = provider.open(PoolCPI.createFromAddress(poolAddr));
    const data = await pool.getPoolData();          // 12-field snapshot
    console.log(data.leftReserve, data.rightReserve, data.lpFee);
    const type = await pool.getPoolType();          // "constant_product" | ...
    const lpAcc = await pool.getLPAccountAddress({ userAddress: MY_ADDR });
}
```

--------------------------------

### Vault.createFromConfig method signature

Source: https://github.com/ston-fi/dex-core-v2/blob/main/_autodocs/api-reference/wrappers-Vault.md

Static factory method to create a Vault instance from a config, code cell, and optional workchain (default 0).

```ts
static createFromConfig(config: VaultConfig, code: Cell, workchain = 0): Vault
```

--------------------------------

### State-init data builder: pool_idata signature

Source: https://github.com/ston-fi/dex-core-v2/blob/main/_autodocs/api-reference/common-contracts.md

This defines the pool_idata builder that constructs the pool state-init cell. It takes the router address, jetton addresses, and code cells for the LP wallet and LP account. The function orders token addresses by ascending slice_hash to canonicalize the token order, ensuring all pools for a pair share one address.

```func
(cell) pool_idata(slice _router_address, slice _first_jetton_address, slice _second_jetton_address, cell _jetton_lp_wallet_code, cell _lp_account_code) inline;
```

--------------------------------

### common.fc includes

Source: https://github.com/ston-fi/dex-core-v2/blob/main/_autodocs/api-reference/common-contracts.md

The main include file for the common contracts module, included by every DEX contract. It pulls in the funcbox autoload, error, parameter, op, gas, contract, and utility definitions, plus pool-specific state_init and gas files templated by the DEX type.

```func
#include "../../node_modules/@ston-fi/funcbox/autoload.fc";
#include "errors.fc";
#include "params.fc";
#include "op.fc";
#include "gas.fc";
#include "contracts.fc";
#include "utils.fc";
#include "../pool/pools/<%= dexType %>/state_init.fc";
#include "../pool/pools/<%= dexType %>/gas.fc";
```

--------------------------------

### Internal and admin message builders: pool::$route, pool::internal_set_fees, pool::internal_update_pool_code, pool::reset_gas, pool::internal_update_status, vault::deposit_ref_fee

Source: https://github.com/ston-fi/dex-core-v2/blob/main/_autodocs/api-reference/message-builders.md

Declares internal and admin message builders. `pool::$route` forwards Router→Pool messages, storing `_transferred_op` and `from_user`, then keyed on `slice_hash()` ordering of the two jetton addresses, stores `(jetton_amount, 0)` or `(0, jetton_amount)` into `left_amount`/`right_amount`, then ref `_dex_payload`. `vault::deposit_ref_fee` creates a Router→Vault referral deposit with `jetton_amount:Coins` and `response_address`.

```func
(cell) pool::$route(int _transferred_op, slice _from_user, int _jetton_amount, slice _sender_jetton_address, slice _other_jetton_address, cell _dex_payload) inline;
(cell) pool::internal_set_fees(int _new_lp_fee, int _new_protocol_fee, slice _new_protocol_fee_address, slice _excesses_recipient) inline;
(cell) pool::internal_update_pool_code(cell _new_pool_code) inline;
(cell) pool::reset_gas(slice _excesses_recipient) inline;
(cell) pool::internal_update_status(slice _excesses_recipient) inline;
(cell) vault::deposit_ref_fee(int _amount, slice _response_address) inline;
```

--------------------------------

### LPWalletConfig type definition

Source: https://github.com/ston-fi/dex-core-v2/blob/main/_autodocs/api-reference/wrappers-LPWallet.md

Defines the configuration object for creating an LP wallet. Fields include balance (optional, default 0n), ownerAddress, minterAddress, and walletCode. Used with createFromConfig.

```typescript
export type LPWalletConfig = {
    balance?: bigint;
    ownerAddress: Address | null;
    minterAddress: Address;
    walletCode: Cell;
};
```

--------------------------------

### Config parameters and CLI config

Source: https://github.com/ston-fi/dex-core-v2/blob/main/_autodocs/api-reference/helpers.md

Defines the CLI configuration parameters and the CliConfig instance. The configParams object maps each parameter to a resolver, and cliConfig marks dexType, defaultLPFee, defaultProtocolFee, and defaultIsLocked as required.

```ts
export const configParams = {
    routerAddress: resolvers.address,
    firstJettonMinter: resolvers.address,
    secondJettonMinter: resolvers.address,
    adminAddress: resolvers.address,
    tokenAmount: resolvers.bigint,
    libLpAccountAddress: resolvers.address,
    libLpWalletAddress: resolvers.address,
    libPoolAddress: resolvers.address,
    libRouterAddress: resolvers.address,
    libVaultAddress: resolvers.address,
    libLpAccountHex: resolvers.string,
    libLpWalletHex: resolvers.string,
    libPoolHex: resolvers.string,
    libRouterHex: resolvers.string,
    libVaultHex: resolvers.string,
    dexType: resolvePool,
    routerId: resolvers.number,
    defaultIsLocked: resolvers.number,
    defaultLPFee: resolveFeeBps,
    defaultProtocolFee: resolveFeeBps
};
export const cliConfig = new CliConfig(configParams, {
    dexType: true, defaultLPFee: true, defaultProtocolFee: true, defaultIsLocked: true,
});
```

--------------------------------

### Configure weighted_stableswap pool with PoolCWSI sendInternalSetParams

Source: https://github.com/ston-fi/dex-core-v2/blob/main/_autodocs/api-reference/wrappers-Pool.md

Shows how an admin configures a freshly deployed weighted_stableswap pool using PoolCWSI. The sendInternalSetParams call sets parameters like newAmp, newRate, and newW, and can throw a wrapped VM error (e.g., error::invalid_amount) if constraints are violated. A commented-out line shows the PoolStable flavor with a simpler parameter set.

```typescript
import { PoolCWSI } from './wrappers/Pool';

const pool = provider.open(PoolCWSI.createFromAddress(poolAddr));
try {
    await pool.sendInternalSetParams(provider.sender(), {
        newAmp: 1000n,
        newRate: 0n,                      // 0 keeps current rate
        newW: 500_000_000_000_000_000n,   // 0.5 in 1e18 fp
        sideWalletAddress: TOKEN0_WALLET,
        responseAddress: admin,
        rateSetterAddress: RATE_SETTER,
    });
} catch (e) {
    // wrapped VM error, e.g. error::invalid_amount (92) if constraints violated
    console.error('set params failed', e);
}
// PoolStable flavor: await pool.sendInternalSetParams(provider.sender(), { newAmp: 2000n, responseAddress: admin });
```

--------------------------------

### Implement handle_ext_admin_messages

Source: https://github.com/ston-fi/dex-core-v2/blob/main/contracts/router/pools/README.md

Required interface for adding new pool-specific logic. Must implement this function to handle external admin messages and return a boolean.

```clarity
;; returns `bool`
(int) handle_ext_admin_messages();
```

--------------------------------

### Utility function declarations: get_excesses_address and check_wc_nofail

Source: https://github.com/ston-fi/dex-core-v2/blob/main/_autodocs/api-reference/common-contracts.md

These lines declare the utility functions used across contracts. get_excesses_address returns the address for excesses, falling back to the sender address when the input address is none, and throws error::wrong_workchain (85) if the workchain check fails. check_wc_nofail returns 1 if the workchain matches or if the address is none, and never throws; it is used for the optional rate_setter_address in handle_ext_admin_messages.

```func
slice get_excesses_address(slice _addr) impure inline;
(int) check_wc_nofail(slice _addr, int _wc) inline;
```

--------------------------------

### Error handling & admin flow

Source: https://github.com/ston-fi/dex-core-v2/blob/main/_autodocs/api-reference/wrappers-Router.md

Shows error handling for a failed swap (with a comment about `exit_code op::swap_refund_tx_expired`) and an admin flow for a two-phase fee update using `sendSetFees`. The fee update requires `set_fees` on the router and sets new LP and protocol fees, a new protocol fee address, and wallet addresses.

```ts
// A failed swap bounces jettons back; the exit code lands in the transfer payload.
// Await the tx, inspect the router/pool exit code, then retry:
try {
    await router.sendSwap(provider.sender(), { /* ... */ deadline: pastDeadline });
} catch (e) {
    // TON tx failure or on-chain refund (exit_code op::swap_refund_tx_expired)
    console.error('swap failed', e);
}

// Admin: two-phase fee update requires set_fees on the router
await router.sendSetFees(provider.sender(), {
    newLPFee: 50n,               // 0.5%
    newProtocolFee: 10n,         // 0.1%
    newProtocolFeeAddress: admin,
    leftWalletAddress: TOKEN0_WALLET,
    rightWalletAddress: TOKEN1_WALLET,
    excessesAddress: admin,
});
```

--------------------------------

### provideLpPayload function signature

Source: https://github.com/ston-fi/dex-core-v2/blob/main/_autodocs/api-reference/wrappers-Router.md

Builds the dex_payload for op::provide_lp. The payload includes the opcode, otherTokenAddress, refundAddress, excessesAddress or refundAddress, deadline as 64 bits, and a reference containing minLpOut (default 1n), toAddress, bothPositive flag (1 or 0), fwdAmount (default 0n), and customPayload.

```typescript
export function provideLpPayload(opts: {
    otherTokenAddress: Address, minLpOut?: bigint | number, customPayload?: Cell,
    fwdAmount?: bigint, toAddress: Address, refundAddress: Address,
    excessesAddress?: Address, bothPositive?: boolean, deadline: number
}): Builder
```
Tokens:
Raw