Documentation update (#626)

* update documentation for 721 and 1155 safes

* minor docs addition

* fix multiple typos

* refactor typo depositer to depositor

* describe difference generic vs erc handlers on fail

* rename depositer to depositor

* change fee percent desc

* add erc1155 data description

* Update data definition for erc1155

Co-authored-by: Oleksii Matiiasevych <lastperson@gmail.com>

* Update data definition for erc1155

Co-authored-by: Oleksii Matiiasevych <lastperson@gmail.com>

Co-authored-by: Oleksii Matiiasevych <lastperson@gmail.com>

Author: MakMuftic

contracts/Bridge.sol

@@ -146,18 +146,21 @@ contract Bridge is Pausable, Context {
         @param handlerAddress Address of handler resource will be set for.
         @param resourceID ResourceID to be used when making deposits.
         @param contractAddress Address of contract to be called when a deposit is made and a deposited is executed.
+        @param depositFunctionSig Function signature of method to be called in {contractAddress} when a deposit is made.
+        @param depositFunctionDepositorOffset Depositor address position offset in the metadata, in bytes.
+        @param executeFunctionSig Function signature of method to be called in {contractAddress} when a deposit is executed.
      */
     function adminSetGenericResource(
         address handlerAddress,
         bytes32 resourceID,
         address contractAddress,
         bytes4 depositFunctionSig,
-        uint256 depositFunctionDepositerOffset,
+        uint256 depositFunctionDepositorOffset,
         bytes4 executeFunctionSig
     ) external onlyAllowed {
         _resourceIDToHandlerAddress[resourceID] = handlerAddress;
         IGenericHandler handler = IGenericHandler(handlerAddress);
-        handler.setResource(resourceID, contractAddress, depositFunctionSig, depositFunctionDepositerOffset, executeFunctionSig);
+        handler.setResource(resourceID, contractAddress, depositFunctionSig, depositFunctionDepositorOffset, executeFunctionSig);
     }
 
     /**
@@ -274,6 +277,9 @@ contract Bridge is Pausable, Context {
         @param data Data originally provided when deposit was made.
         @param signature bytes memory signature composed of MPC key shares
         @notice Emits {ProposalExecution} event.
+        @notice Behaviour of this function is different for {GenericHandler} and other specific ERC handlers.
+        In the case of ERC handler, when execution fails, the handler will terminate the function with revert.
+        In the case of {GenericHandler}, when execution fails, the handler will emit a failure event and terminate the function normally.
      */
     function executeProposal(uint8 originDomainID, uint64 depositNonce, bytes calldata data, bytes32 resourceID, bytes calldata signature) public whenNotPaused {
         require(isProposalExecuted(originDomainID, depositNonce) != true, "Deposit with provided nonce already executed");
@@ -303,6 +309,9 @@ contract Bridge is Pausable, Context {
         - data Data originally provided when deposit was made.
         @param signature bytes memory signature for the whole array composed of MPC key shares
         @notice Emits {ProposalExecution} event for each proposal in the batch.
+        @notice Behaviour of this function is different for {GenericHandler} and other specific ERC handlers.
+        In the case of ERC handler, when execution fails, the handler will terminate the function with revert.
+        In the case of {GenericHandler}, when execution fails, the handler will emit a failure event and terminate the function normally.
      */
     function executeProposals(Proposal[] memory proposals, bytes memory signature) public whenNotPaused {
         require(proposals.length > 0, "Proposals can't be an empty array");
@@ -373,6 +382,7 @@ contract Bridge is Pausable, Context {
     /**
         @notice This method is used to trigger the process for retrying failed deposits on the MPC side.
         @param txHash Transaction hash which contains deposit that should be retried
+        @notice This is not applicable for failed executions on {GenericHandler}
      */
     function retry(string memory txHash) external {
         emit Retry(txHash);

contracts/ERC1155Safe.sol

@@ -56,6 +56,7 @@ contract ERC1155Safe {
     /**
         @notice Used to burn ERC1155s with batching.
         @param tokenAddress Address of ERC1155 to burn.
+        @param owner Owner of tokens to burn.
         @param tokenIDs IDs of tokens to burn.
         @param amounts Amounts of tokens to burn.
      */

contracts/ERC721Safe.sol

@@ -12,7 +12,7 @@ import "./ERC721MinterBurnerPauser.sol";
 contract ERC721Safe {
 
     /**
-        @notice Used to gain custoday of deposited token.
+        @notice Used to gain custody of deposited token.
         @param tokenAddress Address of ERC721 to transfer.
         @param owner Address of current token owner.
         @param recipient Address to transfer token to.
@@ -51,6 +51,7 @@ contract ERC721Safe {
     /**
         @notice Used to burn ERC721s.
         @param tokenAddress Address of ERC721 to burn.
+        @param owner Owner of token to burn.
         @param tokenID ID of token to burn.
      */
     function burnERC721(address tokenAddress, address owner, uint256 tokenID) internal {

contracts/TestContracts.sol

@@ -35,11 +35,11 @@ contract ThreeArguments {
     }
 }
 
-contract WithDepositer {
-    event WithDepositerCalled(address argumentOne, uint256 argumentTwo);
+contract WithDepositor {
+    event WithDepositorCalled(address argumentOne, uint256 argumentTwo);
 
-    function withDepositer(address argumentOne, uint256 argumentTwo) external {
-        emit WithDepositerCalled(argumentOne, argumentTwo);
+    function withDepositor(address argumentOne, uint256 argumentTwo) external {
+        emit WithDepositorCalled(argumentOne, argumentTwo);
     }
 }
 

contracts/handlers/ERC1155Handler.sol

@@ -23,12 +23,17 @@ contract ERC1155Handler is IDepositExecute, HandlerHelpers, ERC1155Safe, ERC1155
     }
 
     /**
-        @notice A deposit is initiatied by making a deposit in the Bridge contract.
+        @notice A deposit is initiated by making a deposit in the Bridge contract.
         @param resourceID ResourceID used to find address of token to be used for deposit.
-        @param depositer Address of account making the deposit in the Bridge contract.
+        @param depositor Address of account making the deposit in the Bridge contract.
         @param data Consists of ABI-encoded arrays of tokenIDs and amounts.
+        @notice Data passed into the function should be constructed as ABI encoding of:
+        tokenIDs                                    uint256[]  bytes
+        amounts                                     uint256[]  bytes
+        destinationRecipientAddress                   bytes    bytes
+        transferData                                  bytes    bytes
      */
-    function deposit(bytes32 resourceID, address depositer, bytes calldata data) external override onlyBridge returns (bytes memory metaData) {
+    function deposit(bytes32 resourceID, address depositor, bytes calldata data) external override onlyBridge returns (bytes memory metaData) {
         uint[] memory tokenIDs;
         uint[] memory amounts;
 
@@ -38,17 +43,23 @@ contract ERC1155Handler is IDepositExecute, HandlerHelpers, ERC1155Safe, ERC1155
         require(tokenAddress != address(0), "provided resourceID does not exist");
 
         if (_burnList[tokenAddress]) {
-            burnBatchERC1155(tokenAddress, depositer, tokenIDs, amounts);
+            burnBatchERC1155(tokenAddress, depositor, tokenIDs, amounts);
         } else {
-            lockBatchERC1155(tokenAddress, depositer, address(this), tokenIDs, amounts, EMPTY_BYTES);
+            lockBatchERC1155(tokenAddress, depositor, address(this), tokenIDs, amounts, EMPTY_BYTES);
         }
     }
 
     /**
         @notice Proposal execution should be initiated when a proposal is finalized in the Bridge contract.
         by a relayer on the deposit's destination chain.
+        @param resourceID ResourceID to be used when making deposits.
         @param data Consists of ABI-encoded {tokenIDs}, {amounts}, {recipient},
         and {transferData} of types uint[], uint[], bytes, bytes.
+        @notice Data passed into the function should be constructed as ABI encoding of:
+        tokenIDs                                    uint256[]  bytes
+        amounts                                     uint256[]  bytes
+        destinationRecipientAddress                   bytes    bytes
+        transferData                                  bytes    bytes
      */
     function executeProposal(bytes32 resourceID, bytes calldata data) external override onlyBridge {
         uint[] memory tokenIDs;

contracts/handlers/ERC20Handler.sol

@@ -20,19 +20,21 @@ contract ERC20Handler is IDepositExecute, HandlerHelpers, ERC20Safe {
     }
 
     /**
-        @notice A deposit is initiatied by making a deposit in the Bridge contract.
+        @notice A deposit is initiated by making a deposit in the Bridge contract.
         @param resourceID ResourceID used to find address of token to be used for deposit.
-        @param depositer Address of account making the deposit in the Bridge contract.
+        @param depositor Address of account making the deposit in the Bridge contract.
         @param data Consists of {amount} padded to 32 bytes.
         @notice Data passed into the function should be constructed as follows:
-        amount                      uint256     bytes   0 - 32
+        amount                                      uint256     bytes   0 - 32
+        destinationRecipientAddress     length      uint256     bytes  32 - 64
+        destinationRecipientAddress                 bytes       bytes  64 - END
         @dev Depending if the corresponding {tokenAddress} for the parsed {resourceID} is
         marked true in {_burnList}, deposited tokens will be burned, if not, they will be locked.
         @return an empty data.
      */
     function deposit(
         bytes32 resourceID,
-        address depositer,
+        address depositor,
         bytes   calldata data
     ) external override onlyBridge returns (bytes memory) {
         uint256        amount;
@@ -42,15 +44,16 @@ contract ERC20Handler is IDepositExecute, HandlerHelpers, ERC20Safe {
         require(_contractWhitelist[tokenAddress], "provided tokenAddress is not whitelisted");
 
         if (_burnList[tokenAddress]) {
-            burnERC20(tokenAddress, depositer, amount);
+            burnERC20(tokenAddress, depositor, amount);
         } else {
-            lockERC20(tokenAddress, depositer, address(this), amount);
+            lockERC20(tokenAddress, depositor, address(this), amount);
         }
     }
 
     /**
         @notice Proposal execution should be initiated when a proposal is finalized in the Bridge contract.
         by a relayer on the deposit's destination chain.
+        @param resourceID ResourceID to be used when making deposits.
         @param data Consists of {resourceID}, {amount}, {lenDestinationRecipientAddress},
         and {destinationRecipientAddress} all padded to 32 bytes.
         @notice Data passed into the function should be constructed as follows:

contracts/handlers/ERC721Handler.sol

@@ -27,20 +27,24 @@ contract ERC721Handler is IDepositExecute, HandlerHelpers, ERC721Safe {
     }
 
     /**
-        @notice A deposit is initiatied by making a deposit in the Bridge contract.
+        @notice A deposit is initiated by making a deposit in the Bridge contract.
         @param resourceID ResourceID used to find address of token to be used for deposit.
-        @param depositer Address of account making the deposit in the Bridge contract.
+        @param depositor Address of account making the deposit in the Bridge contract.
         @param data Consists of {tokenID} padded to 32 bytes.
         @notice Data passed into the function should be constructed as follows:
         tokenID                                     uint256    bytes    0  - 32
+        destinationRecipientAddress     length      uint256    bytes    32 - 64
+        destinationRecipientAddress                   bytes    bytes    64 - (64 + len(destinationRecipientAddress))
+        metadata                        length      uint256    bytes    (64 + len(destinationRecipientAddress)) - (64 + len(destinationRecipientAddress) + 32)
+        metadata                                      bytes    bytes    (64 + len(destinationRecipientAddress) + 32) - END
         @notice If the corresponding {tokenAddress} for the parsed {resourceID} supports {_INTERFACE_ERC721_METADATA},
         then {metaData} will be set according to the {tokenURI} method in the token contract.
         @dev Depending if the corresponding {tokenAddress} for the parsed {resourceID} is
         marked true in {_burnList}, deposited tokens will be burned, if not, they will be locked.
         @return metaData : the deposited token metadata acquired by calling a {tokenURI} method in the token contract.
      */
     function deposit(bytes32    resourceID,
-                    address     depositer,
+                    address     depositor,
                     bytes       calldata data
                     ) external override onlyBridge returns (bytes memory metaData) {
         uint         tokenID;
@@ -57,15 +61,16 @@ contract ERC721Handler is IDepositExecute, HandlerHelpers, ERC721Safe {
         }
 
         if (_burnList[tokenAddress]) {
-            burnERC721(tokenAddress, depositer, tokenID);
+            burnERC721(tokenAddress, depositor, tokenID);
         } else {
-            lockERC721(tokenAddress, depositer, address(this), tokenID);
+            lockERC721(tokenAddress, depositor, address(this), tokenID);
         }
     }
 
     /**
         @notice Proposal execution should be initiated when a proposal is finalized in the Bridge contract.
         by a relayer on the deposit's destination chain.
+        @param resourceID ResourceID to be used when making deposits.
         @param data Consists of {tokenID}, {resourceID}, {lenDestinationRecipientAddress},
         {destinationRecipientAddress}, {lenMeta}, and {metaData} all padded to 32 bytes.
         @notice Data passed into the function should be constructed as follows:

contracts/handlers/FeeHandlerRouter.sol

@@ -59,6 +59,7 @@ contract FeeHandlerRouter is IFeeHandler, AccessControl {
     /**
         @notice Initiates collecting fee with corresponding fee handler contract using IFeeHandler interface.
         @param sender Sender of the deposit.
+        @param fromDomainID ID of the source chain.
         @param destinationDomainID ID of chain deposit will be bridged to.
         @param resourceID ResourceID to be used when making deposits.
         @param depositData Additional data to be passed to specified handler.
@@ -72,6 +73,7 @@ contract FeeHandlerRouter is IFeeHandler, AccessControl {
      /**
         @notice Initiates calculating fee with corresponding fee handler contract using IFeeHandler interface.
         @param sender Sender of the deposit.
+        @param fromDomainID ID of the source chain.
         @param destinationDomainID ID of chain deposit will be bridged to.
         @param resourceID ResourceID to be used when making deposits.
         @param depositData Additional data to be passed to specified handler.