# 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>,
);
```


---

# 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://docs.ashswap.io/developers/smart-contracts/liquidity-staking-farming.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.