# Liquidity Staking Guide

This guide covers the TMS LiqLocker contract — provide liquidity to a Uniswap V2 (or Aerodrome) pair and lock LP tokens to earn rewards.

Use the "Read as Proxy" and "Write as Proxy" tabs on the block explorer.

### Prerequisites

* Your LiqLocker contract address.
* A block explorer for your chain (e.g., Etherscan, BscScan).
* A wallet (e.g., MetaMask) connected to the correct network.
* Both tokens of the liquidity pair.

### How It Works

The LiqLocker combines two steps into one transaction:

1. Adds liquidity to a Uniswap V2 (or Aerodrome) pair using your two tokens.
2. Locks the resulting LP tokens in the contract to earn rewards.

When you unlock, the contract removes liquidity from the pair and returns both tokens to you.

***

### Part 1: Investor Guide

#### 1.1 — View Available Pools

Navigate to "Read as Proxy".

Call `getPools` or `pools` with a pool index.

Key fields:

* `rewardRate`: Annual reward rate in basis points (e.g., 1000 = 10% APY). Divided by 1000 internally, so 1000 = 100% APY equivalent.
* `lockPeriodInDays`: Lock period.
* `endDate`: When rewards stop.
* `input`: LP pair address.
* `reward`: Reward token address (must be one of the two tokens in the LP pair).
* `isWithdrawLocked`: If `true`, cannot unlock until lock period ends.

#### 1.2 — Check Your Position

Call `users` with pool ID and your address.

You will see:

* `totalInvested`: Total LP tokens locked (in wei).
* `totalWithdrawn`: Total LP tokens unlocked (in wei).
* `totalClaimed`: Total rewards claimed (in wei).
* `depositTime`: Timestamp of your last deposit.
* `lastPayout`: Timestamp of your last reward claim.

#### 1.3 — Check Staked Token Amount

Call `stakedTokens` with pool ID and your address.

Returns the amount of the reward token side you originally provided when adding liquidity.

#### 1.4 — Check Pending Rewards

Call `payout` with pool ID and your address.

Returns the amount of reward tokens you can claim (in wei). Rewards stop accruing after your lock period ends.

#### 1.5 — Check If You Can Claim / Unlock

Call `canClaim` with pool ID and your address.

Returns `true` if your lock period has passed.

#### 1.6 — Check NFT Multiplier

* Call `multis` with pool ID. If `active` is `true`, a boost exists.
* Call `calcMultiplier` with pool ID and your address — `100` = 1x (no boost), `200` = 2x, `150` = 1.5x.
* Call `ownsCorrectMulti` with pool ID and your address to verify eligibility.

#### 1.7 — Check Fees

There may be two types of fees.

**Deposit Fee (Percentage)**

Call `fee`.

* `depositFee`: Fee percentage out of 10,000 (e.g., 100 = 1%).
* `feeReceiver`: Address that receives the fee.

This fee is charged in the reward token when you lock LP tokens.

**Native Token Fee (USD-denominated)**

Call `minFeeUSD`. If greater than `0`, you must pay a fee in the chain's native token (ETH, BNB, etc.) when locking.

The fee amount in wei is determined by the `feeConverter` contract at lock time. You need to include this fee in the transaction value.

For pools that use native tokens (ETH/BNB): send the fee amount **plus** your native token liquidity amount as the transaction value. The fee is deducted first, and the remainder goes to liquidity.

For pools that do not use native tokens: send only the fee amount as the transaction value.

#### 1.8 — Check If Pair Uses Native Token

Call `isWrappedNative` with the pair address.

* `0` = token0 is the wrapped native token (WETH/WBNB).
* `1` = token1 is the wrapped native token.
* `2` = neither token is the wrapped native token.

#### 1.9 — Approve Tokens (Before First Lock)

Approve both tokens of the pair on their respective contracts:

* Token 0: Call `approve` with LiqLocker address and amount.
* Token 1: Call `approve` with LiqLocker address and amount.

If one token is the native token (ETH, BNB), you do not need to approve it — send it as the transaction value instead.

#### 1.10 — Add Liquidity and Lock

1. Navigate to "Write as Proxy".
2. Find `addLiquidityAndLock`.
3. Enter:
   * `_pid`: Pool ID.
   * `_token0Amt`: Amount of token 0 in wei. Set to `0` if token 0 is the native token.
   * `_token1Amt`: Amount of token 1 in wei. Set to `0` if token 1 is the native token.
   * `_token0Min`: Minimum token 0 accepted (slippage protection, \~95% of amount).
   * `_token1Min`: Minimum token 1 accepted (slippage protection, \~95% of amount).
4. If using native token (ETH/BNB): Set the value (`payableAmount`) field to the native token amount for liquidity.
5. If `minFeeUSD > 0`: Add the USD fee amount (in native token wei) to the value field. To find the correct fee amount:
   * Call `feeConverter` on the LiqLocker to get the converter address.
   * On the converter contract, call `convertUSDFeeToWei` with the `minFeeUSD` value.
   * Add the returned value to whatever native amount you are sending for liquidity.
6. Click Write and confirm the transaction.

Any excess tokens not used by the DEX are returned to your wallet automatically.

You cannot lock if the current time is within `lockPeriodInDays` of the pool's `endDate`.

#### 1.11 — Claim Rewards

Call `claim` with `_pid`. Or `claimAll`.

Lock period must have passed. Rewards are also auto-claimed when you add liquidity or unlock.

#### 1.12 — Unlock and Remove Liquidity

1. Navigate to "Write as Proxy".
2. Find `unlockAndRemoveLP`.
3. Enter:
   * `_pid`: Pool ID.
   * `_amount`: LP token amount to unlock in wei. Use `totalInvested` from `users` for full unlock.
   * `_token0Min`: Minimum token 0 to receive (slippage protection).
   * `_token1Min`: Minimum token 1 to receive (slippage protection).
4. Click Write and confirm the transaction.

Both tokens are returned to your wallet. If one token is the native token, you receive it as ETH/BNB directly.

Lock period must have passed if `isWithdrawLocked` is `true`.

***

### Part 2: Admin / Founder Guide

Requires `MANAGER_ROLE`.

#### Roles

| Role                 | Description               |
| -------------------- | ------------------------- |
| DEFAULT\_ADMIN\_ROLE | Grant/revoke manager role |
| MANAGER\_ROLE        | Manage pools and settings |

#### Grant / Revoke Manager

Requires `DEFAULT_ADMIN_ROLE`.

Call `setManagerRole` with `_user` and `_status` (true/false).

#### Add a Pool

Call `add` with:

* `_isWithdrawLocked`: true to lock unstaking during lock period.
* `_rewardRate`: Annual reward rate in basis points (e.g., 1000 = 10% APY).
* `_lockPeriodInDays`: Lock period in days (must be > 0).
* `_endDate`: Unix timestamp when pool ends.
* `_hardCap`: Unused — pass `0`.
* `_inputToken`: LP pair address.
* `_rewardToken`: Reward token address (must be token0 or token1 of the LP pair).

#### Update a Pool

Call `set` with:

* `_pid`: Pool ID.
* `_isWithdrawLocked`: Updated lock setting.
* `_rewardRate`: Updated reward rate.
* `_lockPeriodInDays`: Updated lock period (must be > 0).
* `_endDate`: Updated end date.
* Remaining params (hardCap, input, reward): Unused — pass `0` and zero address.

Input and reward tokens cannot be changed after pool creation.

#### Set NFT Multiplier

Call `setMultiplier` with:

* `_pid`: Pool ID.
* `_name`: Name of the NFT collection.
* `_contractAdd`: NFT contract address. Must not be zero address if enabling.
* `_isUsed`: true to enable, false to disable.
* `_multi`: Multiplier value (100 = 1x, 200 = 2x, max 10000 = 100x).
* `_start`: Start index of eligible NFT IDs.
* `_end`: End index of eligible NFT IDs.

#### Set Deposit Fee

Only callable by the current `feeReceiver`.

Call `setDepositFee` with `_feeReceiver` and `_depositFee` (out of 10,000, max 4999).

#### Set User Fee (Native Token / USD)

Only callable by the current `feeReceiver`.

Call `setUsersFee` with:

* `_feeConverter`: Fee converter contract address.
* `_minFeeUSD`: Minimum fee in USD (8 decimals, where 1e8 = $1).

Set `_minFeeUSD` to `0` to disable the native token fee.

#### Expire a Pool

Call `set` and set `_endDate` to a past timestamp.

#### Transfer User Stake

Call `transferUserStakeInfo` with:

* `from`: Original staker address.
* `to`: Destination address (must not already have a stake in the pool).
* `pid`: Pool ID.
* `deadline`: Signature expiry timestamp.
* `signature`: Valid EIP-712 signature from the original staker.

#### Transfer Stuck Tokens

Call `transferStuckToken` with `_token`, `_to`, and `_amount`.

Only allows transferring tokens that are not part of user-deposited LP tokens (checks deposited balance).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://tms-finance.gitbook.io/tms.finance/tms-contracts/liquidity-staking-guide.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.