Token-locker: comments and review

token-locker/src/lib.rs

@@ -49,14 +49,19 @@ enum StorageKey {
     WhitelistAccounts,
 }
 
+/// Contract for Bridge Token-Locker which responsible for
+/// (1) locking tokens on NEAR side
+/// (2) unlocking tokens in case corresponding tokens were burned on Ethereum side
+/// Only way to unlock locked tokens is to mint corresponded tokens on Ethereum side and after to burn them.
 #[near_bindgen]
 #[derive(BorshDeserialize, BorshSerialize, PanicOnDefault)]
 pub struct Contract {
-    /// The account of the prover that we can use to prove.
+    /// The account of the prover that we can use
+    /// to prove the authenticity of events generated on Ethereum side.
     pub prover_account: AccountId,
     /// Ethereum address of the token factory contract, in hex.
     pub eth_factory_address: EthAddress,
-    /// Hashes of the events that were already used.
+    /// Hashes of the Ethereum `Withdraw` events that were already used for unlock tokens.
     pub used_events: UnorderedSet<Vec<u8>>,
     /// Mask determining all paused functions
     paused: Mask,
@@ -68,54 +73,80 @@ pub struct Contract {
     pub is_whitelist_mode_enabled: bool,
 }
 
+/// Interface for Bridge Token-Locker Contract
 #[ext_contract(ext_self)]
 pub trait ExtContract {
+    /// The method which called on the last step of the deposit procedure (locking tokens)
     #[result_serializer(borsh)]
     fn finish_deposit(
         &self,
+        /// Token NEAR address
         #[serializer(borsh)] token: AccountId,
+        /// Amount of tokens to transfer
         #[serializer(borsh)] amount: Balance,
+        /// The Ethereum address of the tokens recipient
         #[serializer(borsh)] recipient: EthAddress,
     ) -> result_types::Lock;
 
+    /// The method which called on the last step of the `withdraw` procedure (unlocking tokens)
     #[result_serializer(borsh)]
     fn finish_withdraw(
         &self,
+        /// This method is called as a callback after `burn` event verification.
+        /// `verification_success` is a result of verification the proof of the Ethereum `burn` event
         #[callback]
         #[serializer(borsh)]
         verification_success: bool,
+        /// Account Id of the token on NEAR
         #[serializer(borsh)] token: String,
+        /// Account Id of the token recipient on NEAR
         #[serializer(borsh)] new_owner_id: String,
+        /// The amount of the burned tokens
         #[serializer(borsh)] amount: Balance,
+        /// The proof of the Ethereum `burn` event
         #[serializer(borsh)] proof: Proof,
     ) -> Promise;
 
+    /// The last step of logging token metadata (the token name, symbols etc).
+    /// This logging is necessary for transferring information about token to Ethereum
     #[result_serializer(borsh)]
     fn finish_log_metadata(
         &self,
+        /// The information about token (name, symbols etc)
         #[callback] metadata: FungibleTokenMetadata,
+        /// NEAR account id of the token
         token_id: AccountId,
     ) -> result_types::Metadata;
 
+    /// The method which called after checking the token Storage Balance of recipient
+    /// during the `withdraw` procedure
     fn storage_balance_callback(
         &self,
+        /// The result of checking token Storage Balance ot the recipient
         #[callback] storage_balance: Option<StorageBalance>,
+        /// The proof of the Ethereum `burn` event.
         #[serializer(borsh)] proof: Proof,
+        /// The NEAR account id of the token
         #[serializer(borsh)] token: String,
+        /// The NEAR account id of the token recipient
         #[serializer(borsh)] recipient: AccountId,
+        /// The amount of burned tokens
         #[serializer(borsh)] amount: Balance,
     );
 }
 
+/// Interface for the ERC20 Bridge Tokens
 #[ext_contract(ext_token)]
 pub trait ExtToken {
+    /// Transfer tokens to receiver NEAR account
     fn ft_transfer(
         &mut self,
         receiver_id: AccountId,
         amount: U128,
         memo: Option<String>,
     ) -> PromiseOrValue<U128>;
 
+    /// Transfer tokens to receiver NEAR account with specific message
     fn ft_transfer_call(
         &mut self,
         receiver_id: AccountId,
@@ -124,16 +155,22 @@ pub trait ExtToken {
         msg: String,
     ) -> PromiseOrValue<U128>;
 
+    /// Get the information about token (name, symbols etc)
     fn ft_metadata(&self) -> FungibleTokenMetadata;
 
+    /// Get the storage balance for the specific account
     fn storage_balance_of(&mut self, account_id: Option<AccountId>) -> Option<StorageBalance>;
 }
 
 #[near_bindgen]
 impl Contract {
+    /// The Bridge Token-Locker initialization.
+    ///
+    /// # Arguments
+    ///
+    /// * `prover_account`: NEAR account of the Near Prover contract which check the correctness of the Ethereum Events;
+    /// * `factory_address`: Ethereum address of the token factory contract, in hex.
     #[init]
-    /// `prover_account`: NEAR account of the Near Prover contract;
-    /// `factory_address`: Ethereum address of the token factory contract, in hex.
     pub fn new(prover_account: AccountId, factory_address: String) -> Self {
         Self {
             prover_account,