Add documentation (#15)

* Add doc for API

* Add docs for structs

README.md

@@ -67,6 +67,7 @@ The contract furthermore caters for edge cases in user behaviour which current p
 The following users provide some context as to how users will interact with the contract from the Sweat Wallet application. 
 
 ### Server side
+
 -------------------------------------
 
 1. As a server I want to impose a 48 hour count down time (offchain) which prevents the "Claim" button from being active. After the 48 hours have matured, the Claim button should be shown as active such that a user may interact with it.
@@ -76,6 +77,7 @@ The following users provide some context as to how users will interact with the
 5. As a server I want to limit contract interaction by requiring an active Sweat Wallet UUID that matches a valid keypair to prevent access to the contracts function from independent users (users not using an active Sweat Wallet session)
 
 ### Client side
+
 -------------------------------------
 
 1. As a user I want to view my accrued $SWEAT in-app
@@ -86,3 +88,9 @@ The following users provide some context as to how users will interact with the
 6. As a user I want to see the gas fee displayed before interacting in any way with the claim contract.
 7. As a user I want to receive logical error messages when a contract interaction fails e.g. insufficient NEAR or $SWEAT to cover gas fees, etc. or any reason that causes the contract to panic.
 8. As a user I want to receive notifications before an method is called in the claim contract by the server that affects my unclaimed balance in the smart contract (offchain functionality) 
+
+# Implementation
+
+## Interaction within the system
+
+![contracts_interaction.png](doc/contracts_interaction.png)

contract/src/claim/api.rs

@@ -59,6 +59,7 @@ impl ClaimApi for Contract {
         );
 
         let account_data = self.accounts.get_mut(&account_id).expect("Account data is not found");
+        account_data.is_locked = true;
 
         let now = now_seconds();
         let mut total_accrual = 0;
@@ -89,6 +90,7 @@ impl ClaimApi for Contract {
         if total_accrual > 0 {
             self.transfer_external(now, account_id, total_accrual, details)
         } else {
+            account_data.is_locked = false;
             PromiseOrValue::Value(ClaimResultView::new(0))
         }
     }
@@ -104,6 +106,7 @@ impl Contract {
         is_success: bool,
     ) -> ClaimResultView {
         let account = self.accounts.get_mut(&account_id).expect("Account not found");
+        account.is_locked = false;
 
         if is_success {
             account.last_claim_at = now.into();

contract/src/lib.rs

@@ -17,18 +17,53 @@ mod record;
 const INITIAL_CLAIM_PERIOD_MS: u32 = 24 * 60 * 60;
 const INITIAL_BURN_PERIOD_MS: u32 = 30 * 24 * 60 * 60;
 
+/// The main structure representing a smart contract for managing fungible tokens.
 #[near_bindgen]
 #[derive(BorshDeserialize, BorshSerialize, PanicOnDefault)]
 pub struct Contract {
+    /// The account ID of the fungible token contract serviced by this smart contract.
+    ///
+    /// This field specifies the associated fungible token contract with which this smart
+    /// contract interacts.
     token_account_id: AccountId,
 
+    /// A set of account IDs authorized to perform sensitive operations within the contract.
+    ///
+    /// `oracles` represents the entities that have the authority to execute critical
+    /// functions such as burning tokens. These accounts are trusted and have elevated privileges.
     oracles: UnorderedSet<AccountId>,
-    claim_period: Duration, // Period in seconds during which tokens are locked after claim
-    burn_period: Duration,  // Time in seconds after that unclaimed tokens are burnt
 
+    /// The period in seconds during which tokens are locked after being claimed.
+    ///
+    /// `claim_period` defines the duration for which the tokens remain locked and
+    /// untransferable after a user claims them. This lock period helps in managing the
+    /// token lifecycle and user claims.
+    claim_period: Duration,
+
+    /// The period in seconds after which unclaimed tokens are eligible to be burnt.
+    ///
+    /// `burn_period` specifies the timeframe after which tokens that haven't been claimed
+    /// are considered for burning, helping in regulating the token supply.
+    burn_period: Duration,
+
+    /// A ledger storing the timestamps of recordings and the corresponding user accruals.
+    ///
+    /// `accruals` does not contain account IDs directly but correlates with `AccountRecord`
+    /// entries in the `accounts` field. It is essential for tracking token accruals over time.
     accruals: UnorderedMap<UnixTimestamp, (Vector<TokensAmount>, TokensAmount)>,
+
+    /// A map containing accrual and service details for each user account.
+    ///
+    /// `accounts` holds individual records for users, detailing their accrued tokens and
+    /// related service information. It works in conjunction with `accruals` to provide a
+    /// comprehensive view of each user's token status.
     accounts: LookupMap<AccountId, AccountRecord>,
 
+    /// Indicates whether a service call is currently in progress.
+    ///
+    /// `is_service_call_running` is used to prevent double spending by indicating if the
+    /// contract is currently executing a service call. This flag ensures the integrity of
+    /// token transactions and operations within the contract.
     is_service_call_running: bool,
 }
 

contract/src/record/tests.rs

@@ -35,7 +35,7 @@ fn record_by_oracle() {
 }
 
 #[test]
-#[should_panic(expected = "Record for this timestamp: 0 already existed. It was owerwritten.")]
+#[should_panic(expected = "Record for this timestamp: 0 already existed. It was overwritten.")]
 fn test_record() {
     let (mut context, mut contract, accounts) = Context::init_with_oracle();
 

model/src/account_record.rs

@@ -5,11 +5,38 @@ use near_sdk::{
 
 use crate::{AccrualIndex, UnixTimestamp};
 
+/// Represents the state of a registered account in the smart contract.
+///
+/// `AccountRecord` maintains the status and history of an individual user's account within
+/// the smart contract. It tracks various aspects of the account, such as accrual references,
+/// claim history, and operational states.
 #[derive(BorshDeserialize, BorshSerialize)]
 pub struct AccountRecord {
+    /// A list of references to accrual entries in `Contract.accruals`.
+    ///
+    /// `accruals` contains pairs of timestamps and indices that link to specific accrual
+    /// records in the contract's accruals ledger. These references are used to calculate
+    /// and verify the user's accrued token amount.
     pub accruals: Vec<(UnixTimestamp, AccrualIndex)>,
+
+    /// Indicates whether the user is authorized to use the contract's features.
+    ///
+    /// Currently, `is_enabled` is not actively used but is prepared for future releases.
+    /// It can be used to enable or disable access to contract functionalities for this
+    /// particular account.
     pub is_enabled: bool,
+
+    /// The timestamp of the last claim operation performed by the account.
+    ///
+    /// `last_claim_at` holds an `Option<UnixTimestamp>` that records the time when the user
+    /// last claimed their tokens. It is used to determine eligibility for future claims.
     pub last_claim_at: Option<UnixTimestamp>,
+
+    /// Indicates whether there is an active operation on the user's balance.
+    ///
+    /// `is_locked` is used to signal if the account is currently engaged in an operation
+    /// that affects its balance, such as a claim process. This is important for ensuring
+    /// the integrity of account operations and preventing concurrent modifications.
     pub is_locked: bool,
 }