# 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`.