doc: update farm lock public functions & actions

README.md

@@ -249,7 +249,7 @@ This action can be triggered only by the Router contract of the dex. It allow th
 
 ### Farm Lock
 
-Farm is a contract that allows users to deposit lp tokens from a pool for a given period and receive rewards at the end of the lock period.
+This farm allows users to lock their LP tokens for a given time in order to receive rewards.
 
 #### Public functions
 
@@ -259,7 +259,7 @@ get_farm_infos()
 
 Returns the informations of the farm
 
-```json
+```jsonc
 {
   "lp_token_address": "0000ABCD...", // LP Token Address
   "reward_token": "00001234...", // Reward token address or "UCO"
@@ -269,19 +269,16 @@ Returns the informations of the farm
   "rewards_distributed": 4523.97235, // Amount of rewards already distributed
   "available_levels": { // an enumeration (string (level) ⇒ end date)
     "1": 1750829615,
-    "2": 1782365615
+    // ...
   },
   "stats": {
     "1": {
-      "deposits_count": 1344.454, // Deposits count currently on this level by all users
-      "lp_tokens_deposited": 34553,  // Amount deposited currently on this level by all users
-      "rewards_allocated": 3564332.333, // Amount of rewards remaining for this level for all users
+      "weight": 0.013, // Weight of this level
+      "deposits_count": 1344.454, // Current count of deposits on this level
+      "lp_tokens_deposited": 34553,  // Current amount deposited on this level
+      "remaining_rewards": 3564332.333, // Remaining rewards for this level (based on current distribution)
     },
-    "2": {
-      "deposits_count": 12341.454, // Deposits count currently on this level by all users
-      "lp_tokens_deposited": 43513,  // Amount deposited currently on this level by all users
-      "rewards_allocated": 3561342.13, // Amount of rewards remaining for this level for all users
-    }
+    // ...
   }
 }
 ```
@@ -290,62 +287,61 @@ Returns the informations of the farm
 get_user_infos(user_genesis_address)
 ```
 
-Returns the informations of a user who has deposited and locked lp token in the farm
+Returns the deposits' details of a given user.
 
-```json
+```jsonc
 [
   {
-  "index": 1, // Deposit index
+  "id": "1725136117", // Deposit's identifier
   "amount": 1213.456339, // Amount locked
-  "reward_amount": 33.45, // Current amount rewards
+  "reward_amount": 33.45, // Current rewards accumulated
   "start": 1750829615, // Timestamp lock begin
   "end": 1782365634, // Timestamp lock end
   "level": "3", // Current level
   },
-    {
-  "index": 2, // Deposit index
-  "amount": 213.456339, // Amount locked
-  "reward_amount": 12.45, // Current amount rewards
-  "start": 1750829615, // Timestamp lock begin
-  "end": 1782365634, // Timestamp lock end
-  "level": "6", // Current level
-  }
+  // ...
 ]
 ```
 
 #### Actions triggered by transaction
 
 ```elixir
-deposit(end_timestamp :: integer)
+deposit(level :: "1" | "2" | "3" | "4" | "5" | "6" | "7" | "max")
 ```
 
-This action allow user to deposit lp token in the farm. User must send tokens to the farm's genesis address. It's fund will be hold by the contract and could be reclaimed using `claim` action when the end_timestamp is over.
-A user can deposit multiple time in the same farm with different duration of lock (level)
+- `level`: Determine the lock duration
 
-- Lock `end_timestamp` Unix: seconds since epoch
+This action allow users to deposit LP tokens in the farm. Users must send LP tokens to the farm's genesis address. Users may deposit multiple times. Deposits may be merged together for optimisation.
+
+note: `max` can be used when there is less than 3 years remaining to ensure the lock ends with the farm's end.
 
 ```elixir
-claim(index :: int)
+claim(identifier :: string)
 ```
 
-This action allow user to claim all the reward he earned since he deposited in the farm if lock duration is exceeded.
+- `identifier`: Deposit's identifier
 
-- Lock `index` (a user can have several locks)
+This action allow users to claim a single deposit's rewards. The LP tokens remains in the deposit. The deposit must be unlocked.
 
 ```elixir
-withdraw(amount :: float, index :: int)
+withdraw(amount :: float, identifier :: string)
 ```
 
-This action allow user to retrieve, if the lock duration is exceeded, LP tokens and associated rewards.
+- `amount`: Amount of LP tokens to withdraw
+- `identifier`: Deposit's identifier
 
-- `amount` to withdraw (partial withdrawal authorized)
-- Lock `index` (a user can have several locks)
+This action allow users to withdraw partially or entirely a deposit. The deposit must be unlocked.
 
 ```elixir
-udpate_dates(new_start_date, new_end_date)
+relock(level :: "1" | "2" | "3" | "4" | "5" | "6" | "7" | "max", identifier :: string)
 ```
 
-This action can be triggered only by the Master address of the dex. The farm will update the start and end date.
+- `level`: Determine the lock duration
+- `identifier`: Deposit's identifier
+
+This action allow users to update a deposit. It can only expand the lock duration. Accumulated rewards are transferred to the user.
+
+note: `max` can be used when there is less than 3 years remaining to ensure the lock ends with the farm's end.
 
 ```elixir
 update_code()