# Farm

A contract to distribute reward tokens to stakers.

{% hint style="warning" %}
All times are in seconds.
{% endhint %}

## Structs

### <mark style="color:blue;">**Account**</mark>

```rust
  struct Account<phantom StakeCoin, phantom RewardCoin> has key, store {
    id: UID,
    farm_id: ID, 
    amount: u64,
    reward_debt: u256
  }
```

* **farm\_id** - The \`sui::object::ID\` of the farm to which this account belongs to.&#x20;
* **amount** - The amount of StakeCoin the user has in the Farm.
* **reward\_debt -** Amount of rewards the Farm has already paid the user.

### <mark style="color:blue;">**Farm**</mark>

```rust
struct Farm<phantom StakeCoin, phantom RewardCoin> has key, store {
    id: UID,  
    rewards_per_second: u64,
    start_timestamp: u64,
    last_reward_timestamp: u64, 
    accrued_rewards_per_share: u256,
    balance_stake_coin: Balance<StakeCoin>,
    balance_reward_coin: Balance<RewardCoin>,
    stake_coin_decimal_factor: u64,
    owned_by: ID
 }
```

* **rewards\_per\_second** - Amount of RewardCoin to give to stakers per second.
* **start\_timestamp** - The timestamp in seconds that this farm will start distributing rewards.
* &#x20;**last\_reward\_timestamp -** Last timestamp that the farm was updated.&#x20;
* **accrued\_rewards\_per\_share -** Total amount of rewards per share distributed by this farm.  &#x20;
* **balance\_stake\_coin -** StakeCoin deposited in this farm.&#x20;
* &#x20;**balance\_reward\_coin -** RewardCoin deposited in this farm.
* **stake\_coin\_decimal\_factor -** The decimal scalar of the StakeCoin.&#x20;
* **owned\_by -** The \`sui::object::ID\` of the OwnerCap that "owns" this farm.

## Interface

### <mark style="color:blue;">new\_cap</mark>

**It creates an OwnerCap. It is used to provide admin capabilities to the holder.**

```rust
public fun new_cap(ctx: &mut TxContext): OwnerCap<FarmWitness>
```

* **@return** OwnerCap.

### <mark style="color:blue;">new\_farm</mark>

**It creates an Farm\<StakeCoin, RewardCoin>. The `start_timestamp` is in seconds.**

```rust
public fun new_farm<StakeCoin, RewardCoin>(
    cap: &mut OwnerCap<FarmWitness>,
    stake_coin_metadata: &CoinMetadata<StakeCoin>,
    c: &Clock,
    rewards_per_second: u64,
    start_timestamp: u64,
    ctx: &mut TxContext
 ): Farm<StakeCoin, RewardCoin>
```

* **@param cap:** An OwnerCap that will be assigned the admin rights of the newly created Farm.
* **@param stake\_coin\_metadata:** The `sui::coin::CoinMetadata` of the `StakeCoin`.
* **@param c:** The `sui::clock::Clock` shared object.
* **@param rewards\_per\_second:**  The amount of `RewardCoin` the farm can distribute to stakers.
* **@param start\_timestamp:** The timestamp in seconds that the farm is allowed to start distributing rewards.
* **@return** Farm\<StakeCoin, RewardCoin>.

### <mark style="color:blue;">new\_account</mark>

**It creates an Account\<StakeCoin, RewardCoin>. It is used to keep track of the holder's deposit and rewards.**

```rust
public fun new_account<StakeCoin, RewardCoin>(self: &Farm<StakeCoin, RewardCoin>, ctx: &mut TxContext): Account<StakeCoin, RewardCoin>
```

* **@param cap:** self The Farm\<StakeCoin, RewardCoin>.&#x20;
* **@return** Account\<StakeCoin, RewardCoin>.

### <mark style="color:blue;">rewards\_per\_second</mark>

**Returns the `self` rewards per second.**&#x20;

```rust
public fun rewards_per_second<StakeCoin, RewardCoin>(self: &Farm<StakeCoin, RewardCoin>): u64
```

* **@param cap:** self The Farm\<StakeCoin, RewardCoin>.&#x20;
* **@return** u64.

### <mark style="color:blue;">start\_timestamp</mark>

**Returns the `self` start timestamp.**

```rust
public fun start_timestamp<StakeCoin, RewardCoin>(self: &Farm<StakeCoin, RewardCoin>): u64
```

* **@param cap:** self The Farm\<StakeCoin, RewardCoin>.&#x20;
* **@return** u64.

### <mark style="color:blue;">last\_reward\_timestamp</mark>

**Returns the `self` last reward timestamp.**

```rust
public fun last_reward_timestamp<StakeCoin, RewardCoin>(self: &Farm<StakeCoin, RewardCoin>): u64
```

* **@param cap:** self The Farm\<StakeCoin, RewardCoin>.&#x20;
* **@return** u64.

### <mark style="color:blue;">accrued\_rewards\_per\_share</mark>

**Returns the `self` accrued rewards per share.**

```rust
public fun accrued_rewards_per_share<StakeCoin, RewardCoin>(self: &Farm<StakeCoin, RewardCoin>): u256
```

* **@param cap:** self The Farm\<StakeCoin, RewardCoin>.&#x20;
* **@return** u256.

### <mark style="color:blue;">balance\_stake\_coin</mark>

**Returns the `self` stake coin balance.**

```rust
public fun balance_stake_coin<StakeCoin, RewardCoin>(self: &Farm<StakeCoin, RewardCoin>): u64
```

* **@param cap:** self The Farm\<StakeCoin, RewardCoin>.&#x20;
* **@return** u64.

### <mark style="color:blue;">balance\_reward\_coin</mark>

**Returns the `self` reward coin balance.**

```rust
public fun balance_reward_coin<StakeCoin, RewardCoin>(self: &Farm<StakeCoin, RewardCoin>): u64
```

* **@param cap:** self The Farm\<StakeCoin, RewardCoin>.&#x20;
* **@return** u64.

### <mark style="color:blue;">stake\_coin\_decimal\_factor</mark>

**Returns the `self` reward coin decimal scalar.**

```rust
public fun stake_coin_decimal_factor<StakeCoin, RewardCoin>(self: &Farm<StakeCoin, RewardCoin>): u64
```

* **@param cap:** self The Farm\<StakeCoin, RewardCoin>.&#x20;
* **@return** u64.

### <mark style="color:blue;">owned\_by</mark>

**Returns the `self` reward coin decimal scalar.**

```rust
public fun owned_by<StakeCoin, RewardCoin>(self: &Farm<StakeCoin, RewardCoin>): ID
```

* **@param cap:** self The Farm\<StakeCoin, RewardCoin>.&#x20;
* **@return** ID.

### <mark style="color:blue;">amount</mark>

**Returns the `account` staked amount.**

```rust
public fun amount<StakeCoin, RewardCoin>(account: &Account<StakeCoin, RewardCoin>): u64
```

* **@param cap:** self The Farm\<StakeCoin, RewardCoin>.&#x20;
* **@return** u64.

### <mark style="color:blue;">reward\_debt</mark>

**Returns the `account` reward debt.**

```rust
public fun reward_debt<StakeCoin, RewardCoin>(account: &Account<StakeCoin, RewardCoin>): u256
```

* **@param cap:** self The Farm\<StakeCoin, RewardCoin>.&#x20;
* **@return** u256.

### <mark style="color:blue;">pending\_rewards</mark>

**Returns the `account`'s pending rewards.** **It does not update the state.**

```rust
public fun pending_rewards<StakeCoin, RewardCoin>(
    farm: &Farm<StakeCoin, RewardCoin>, 
    account: &Account<StakeCoin, RewardCoin>,
    c: &Clock, 
 ): u64
```

* **@param** **farm:** The Farm\<StakeCoin, RewardCoin>.
* **@param** **account:** The Account associated with the `farm`.
* **@param** **c:** The `sui::clock::Clock` shared object.
* **@return** u64.

### <mark style="color:blue;">add\_rewards</mark>

**It allows anyone to add rewards to the `farm`.**

```rust
public fun add_rewards<StakeCoin, RewardCoin>(self: &mut Farm<StakeCoin, RewardCoin>, c: &Clock, reward: Coin<RewardCoin>)
```

* **@param** **self:** The Farm\<StakeCoin, RewardCoin>.
* **@param** **c:** The `sui::clock::Clock` shared object.
* **@param** **reward:** The RewardCoin to be added to the `self`.&#x20;

### <mark style="color:blue;">stake</mark>

**Allows a user to stake `stake_coin` in the `farm`. On the first deposits the returned Coin will have a value of zero. So make sure to destroy it.**

```rust
public fun stake<StakeCoin, RewardCoin>(
    farm: &mut Farm<StakeCoin, RewardCoin>, 
    account: &mut Account<StakeCoin, RewardCoin>,
    stake_coin: Coin<StakeCoin>, 
    c: &Clock,
    ctx: &mut TxContext
): Coin<RewardCoin>
```

* **@param** **farm:** The Farm\<StakeCoin, RewardCoin>.
* **@param** **account:** The Account associated with the `farm`.
* **@param** **stake\_coin:** The StakeCoin to stake in the `farm`.
* **@param c:** The `sui::clock::Clock` shared object.
* **@return Coin.** It gives any pending rewards to the user.

**Aborts**

* If the `account` does not belong to the `farm`.

### <mark style="color:blue;">unstake</mark>

**Allows a user to unstake his `stake_coin` in the `farm`.**

```rust
public fun unstake<StakeCoin, RewardCoin>(
    farm: &mut Farm<StakeCoin, RewardCoin>, 
    account: &mut Account<StakeCoin, RewardCoin>,
    amount: u64,
    c: &Clock,
    ctx: &mut TxContext
 ): (Coin<StakeCoin>, Coin<RewardCoin>)
```

* **@param** **farm:** The Farm\<StakeCoin, RewardCoin>.
* **@param** **account:** The Account associated with the `farm`.
* **@param amount**: The amount of StakeCoin to remove from the `farm`.
* **@param c:** The `sui::clock::Clock` shared object.
* **@return** Coin. The staked Coin.&#x20;
* **@return Coin.** It gives any pending rewards to the user.

**Aborts**

* `amount` is larger than the `account.amount`. If the user tries to unstake more than he has staked.

### <mark style="color:blue;">destroy\_zero\_account</mark>

**Destroys the `account`.**

```rust
public fun destroy_zero_account<StakeCoin, RewardCoin>(account: Account<StakeCoin, RewardCoin>)
```

* **@param** **account:** The Account associated with the `farm`.

**Aborts**

* `account` has an amount greater than zero.

### <mark style="color:blue;">update\_rewards\_per\_second</mark>

**Updates the rewards per second of the `farm`.**

```rust
public fun update_rewards_per_second<StakeCoin, RewardCoin>(
    farm: &mut Farm<StakeCoin, RewardCoin>,     
    cap: &OwnerCap<FarmWitness>, 
    new_rewards_per_second: u64,
    c: &Clock
)
```

* **@param** **farm:** The Farm\<StakeCoin, RewardCoin>.
* **@param** **cap:** The OwnerCap that "owns" the `farm`.
* **@param new\_rewards\_per\_second**: The new amount of RewardCoin the `farm` will give.
* **@param c:** The `sui::clock::Clock` shared object.

**Aborts**

* `cap` does not own the `farm`.

### <mark style="color:blue;">destroy\_zero\_farm</mark>

**Destroys the `farm`.**

```rust
public fun destroy_zero_farm<StakeCoin, RewardCoin>(farm: Farm<StakeCoin, RewardCoin>, cap: &OwnerCap<FarmWitness>)
```

* **@param** **farm:** The Farm\<StakeCoin, RewardCoin>.
* **@param** **cap:** The OwnerCap that "owns" the `farm`.

**Aborts**

* `cap` does not own the `farm`.
* `farm` still has staked coins.
* `farm` still has reward coins.

### <mark style="color:blue;">borrow\_mut\_uid</mark>

**Returns a mutable reference of the `farm`'s `sui::object::UI to allow the cap` owner to extend its functionalities.**

```rust
public fun borrow_mut_uid<StakeCoin, RewardCoin>(farm: &mut Farm<StakeCoin, RewardCoin>, cap: &OwnerCap<FarmWitness>): &mut UID
```

* **@param** **farm:** The Farm\<StakeCoin, RewardCoin>.
* **@param** **cap:** The OwnerCap that "owns" the `farm`.
* **@return** \&mut UID.

**Aborts**

* `cap` does not own the `farm`.


---

# 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.interestprotocol.com/overview/deprecated/sui-tears/defi/farm.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.