> For the complete documentation index, see [llms.txt](https://docs.ashswap.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ashswap.io/developers/smart-contracts/liquidity-staking-farming.md).

# Liquidity Staking (Farming)

## Contract Interface

### 1. Notations & Structs

#### 1.1. Payment

`EnterFarmResultType` = `EsdtTokenPayment`

FARM token: a Meta-ESDT token representing the farming position.

#### 1.2. FarmTokenAttributes 

```rust
#[derive(TopEncode, TopDecode, NestedEncode, NestedDecode, PartialEq, TypeAbi, Clone, ManagedVecItem, Debug)]
pub struct FarmTokenAttributes<M: ManagedTypeApi> {
    pub reward_per_share: BigUint<M>,
    pub slope_used: BigUint<M>,
    pub booster: ManagedAddress<M>,
    pub initial_farm_amount: BigUint<M>,
    pub initial_farming_amount: BigUint<M>,
    pub reward_tokens: ManagedVec<M, RewardTokens<M>>,
}

fn get_farm_token_attributes<T: TopDecode>(&self, token_id: &TokenIdentifier, token_nonce: u64) -> T {
    let token_info = self.blockchain().get_esdt_token_data(&self.blockchain().get_sc_address(), token_id, token_nonce);
    token_info.decode_attributes()
}
```

Get attributes of Farm MetaESDT token.

#### 1.3. InteractFarmEvent

```rust
#[derive(TypeAbi, TopEncode)]
pub struct InteractFarmEvent<M: ManagedTypeApi> {
    farm_supply: BigUint<M>,
    reward_reserve: BigUint<M>,
    slope_boosted: ManagedVec<M, KeyValue<M>>,
}
```

### 2. Write functions

#### 2.1. enterFarm

Start farming.

Attached tokens:

* LP tokens from Ashswap’s pools
* old FARM tokens: if you attach multiple FARM tokens, they will be automatically merged with the new FARM token (like mergeFarmTokens).

Return: ManagedVec\<EsdtTokenPayment>

* A new Farm token
* Reward tokens from `old FARM tokens` above.

```rust
#[payable("*")]
#[endpoint(enterFarm)]
fn enter_farm(&self, self_boost: &bool) -> ManagedVec<EsdtTokenPayment<Self::Api>>
```

#### 2.2. exitFarm

Claim reward + withdraw LP token. You can only exit one farm using one FARM token per transaction.

Attached token: FARM token received from `enterFarm` function.

Return: ManagedVec\<EsdtTokenPayment>

* 1st `EsdtTokenPayment`: LP token
* 2nd `EsdtTokenPayment`: Reward token

```rust
#[payable("*")]
#[endpoint(exitFarm)]
fn exit_farm(&self) -> ManagedVec<EsdtTokenPayment<Self::Api>>
```

#### 2.3. claimRewards

Claim rewards (ASH token) without withdrawal. You can only claim rewards from one FARM token in one transaction.

Return: ManagedVec\<EsdtTokenPayment>

* 1st `EsdtTokenPayment`: LP token
* 2nd `EsdtTokenPayment`: Reward token

```rust
#[payable("*")]
#[endpoint(claimRewards)]
fn claim_rewards(&self, self_boost: &bool) -> ManagedVec<EsdtTokenPayment<Self::Api>>
```

### 3. Read functions

#### 3.1. getState

Get the current state of a farm.&#x20;

```rust
#[derive(TopEncode, TopDecode, PartialEq, TypeAbi, Clone, Copy)]
pub enum State { Inactive, Active }

#[view(getState)]
fn state(&self) -> State;
```

#### 3.2. getRewardPerShare

Return:

* `BigUint` - the number of ASH tokens received each block per FARM token.

```rust
#[view(getRewardPerShare)]
fn reward_per_share(&self) -> SingleValueMapper<BigUint>;
```

#### 3.3. getFarmTokenSupply

Return:

* `BigUint` - the total supply of the FARM token.

```rust
#[view(getFarmTokenSupply)]
fn farm_token_supply(&self) -> BigUint;
```

#### 3.4 calculateRewardsForGivenPosition

Get your current reward from a farm.

Params:

* `amount: BigUint` - your FARM token’s balance
* `attributes: FarmTokenAttributes`

  Note: The struct is decoded from FARM token’s attributes.

```rust
#[derive(TopEncode, TopDecode, NestedEncode, NestedDecode, PartialEq, TypeAbi, Clone, ManagedVecItem, Debug)]
pub struct FarmTokenAttributes<M: ManagedTypeApi> {
    pub reward_per_share: BigUint<M>,
    pub slope_used: BigUint<M>, // slope that user used to boost in this farm token.
    pub booster: ManagedAddress<M>,
    pub initial_farm_amount: BigUint<M>,
    pub initial_farming_amount: BigUint<M>,
    pub reward_tokens: ManagedVec<M, RewardTokens<M>>,
}

#[view(calculateRewardsForGivenPosition)]
fn calculate_rewards_for_given_position(&self, amount: BigUint, attributes: FarmTokenAttributes<Self::Api>) -> BigUint
```

### 4. Events

#### 4.1. Interact farm event

Event for `enterFarm`, `exitFarm`, `claimRewards`

```rust
#[event("interact_farm_event")]
fn interact_farm_event(
    &self,
    #[indexed] caller: &ManagedAddress,
    #[indexed] timestamp: u64,
    interact_farm_event: InteractFarmEvent<Self::Api>,
);
```