Updated generated docs

1inch · Jan 17, 2024 · 18e9c86 · 18e9c86
1 parent e26c23a
commit 18e9c86
Show file tree

Hide file tree

Showing 4 changed files with 258 additions and 17 deletions.
diff --git a/documentation/src/contracts/Escrow.sol/contract.Escrow.md b/documentation/src/contracts/Escrow.sol/contract.Escrow.md
@@ -1,65 +1,115 @@
 # Escrow
-[Git Source](https://github.com/byshape/cross-chain-swap/blob/c49176f8473d9a06db920990a07a4d8464dd4dd4/contracts/Escrow.sol)
+[Git Source](https://github.com/byshape/cross-chain-swap/blob/e26c23ac0516aa14fa1ee0839087565b952fb4f1/contracts/Escrow.sol)
 
 **Inherits:**
 Clone, [IEscrow](/contracts/interfaces/IEscrow.sol/interface.IEscrow.md)
 
+Contract to initially lock funds on both chains and then unlock with verification of the secret presented.
+
+*Funds are locked in at the time of contract deployment. On both chains this is done by calling `EscrowFactory`
+functions. On the source chain Limit Order Protocol calls the `postInteraction` function and on the destination
+chain taker calls the `createEscrow` function.
+Withdrawal and cancellation functions for the source and destination chains are implemented separately.*
+
 
 ## Functions
 ### withdrawSrc
 
+See [IEscrow-withdrawSrc](/contracts/interfaces/IEscrow.sol/interface.IEscrow.md#withdrawsrc).
+
 
 ```solidity
 function withdrawSrc(bytes32 secret) external;
 ```
 
 ### cancelSrc
 
+See [IEscrow-cancelSrc](/contracts/interfaces/IEscrow.sol/interface.IEscrow.md#cancelsrc).
+
 
 ```solidity
 function cancelSrc() external;
 ```
 
 ### withdrawDst
 
+See [IEscrow-withdrawDst](/contracts/interfaces/IEscrow.sol/interface.IEscrow.md#withdrawdst).
+
 
 ```solidity
 function withdrawDst(bytes32 secret) external;
 ```
 
 ### cancelDst
 
+See [IEscrow-cancelDst](/contracts/interfaces/IEscrow.sol/interface.IEscrow.md#canceldst).
+
 
 ```solidity
 function cancelDst() external;
 ```
 
 ### srcEscrowImmutables
 
+See [IEscrow-srcEscrowImmutables](/contracts/interfaces/IEscrow.sol/interface.IEscrow.md#srcescrowimmutables).
+
 
 ```solidity
 function srcEscrowImmutables() public pure returns (SrcEscrowImmutables calldata);
 ```
 
 ### dstEscrowImmutables
 
+See [IEscrow-dstEscrowImmutables](/contracts/interfaces/IEscrow.sol/interface.IEscrow.md#dstescrowimmutables).
+
 
 ```solidity
 function dstEscrowImmutables() public pure returns (DstEscrowImmutables calldata);
 ```
 
 ### _isValidSecret
 
+Verifies the provided secret.
+
+*The secret is valid if its hash matches the hashlock.*
+
 
 ```solidity
-function _isValidSecret(bytes32 secret, uint256 hashlock) internal pure returns (bool);
+function _isValidSecret(bytes32 secret, bytes32 hashlock) internal pure returns (bool);
 ```
+**Parameters**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`secret`|`bytes32`|Provided secret to verify.|
+|`hashlock`|`bytes32`|Hashlock to compare with.|
+
+**Returns**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`<none>`|`bool`|True if the secret is valid, false otherwise.|
+
 
 ### _checkSecretAndTransfer
 
+Checks the secret and transfers tokens to the recipient.
+
+*The secret is valid if its hash matches the hashlock.*
+
 
 ```solidity
-function _checkSecretAndTransfer(bytes32 secret, uint256 hashlock, address recipient, address token, uint256 amount)
+function _checkSecretAndTransfer(bytes32 secret, bytes32 hashlock, address recipient, address token, uint256 amount)
     internal;
 ```
+**Parameters**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`secret`|`bytes32`|Provided secret to verify.|
+|`hashlock`|`bytes32`|Hashlock to compare with.|
+|`recipient`|`address`|Address to transfer tokens to.|
+|`token`|`address`|Address of the token to transfer.|
+|`amount`|`uint256`|Amount of tokens to transfer.|
+
 
diff --git a/documentation/src/contracts/EscrowFactory.sol/contract.EscrowFactory.md b/documentation/src/contracts/EscrowFactory.sol/contract.EscrowFactory.md
@@ -1,8 +1,10 @@
 # EscrowFactory
-[Git Source](https://github.com/byshape/cross-chain-swap/blob/c49176f8473d9a06db920990a07a4d8464dd4dd4/contracts/EscrowFactory.sol)
+[Git Source](https://github.com/byshape/cross-chain-swap/blob/e26c23ac0516aa14fa1ee0839087565b952fb4f1/contracts/EscrowFactory.sol)
 
 **Inherits:**
-[IEscrowFactory](/contracts/interfaces/IEscrowFactory.sol/interface.IEscrowFactory.md), ExtensionBase
+[IEscrowFactory](/contracts/interfaces/IEscrowFactory.sol/interface.IEscrowFactory.md), SimpleSettlementExtension
+
+Contract to create escrow contracts for cross-chain atomic swap.
 
 
 ## State Variables
@@ -18,12 +20,18 @@ address public immutable IMPLEMENTATION;
 
 
 ```solidity
-constructor(address implementation, address limitOrderProtocol) ExtensionBase(limitOrderProtocol);
+constructor(address implementation, address limitOrderProtocol, IERC20 token)
+    SimpleSettlementExtension(limitOrderProtocol, token);
 ```
 
 ### _postInteraction
 
-*Creates a new escrow contract for maker.*
+Creates a new escrow contract for maker on the source chain.
+
+*The caller must be whitelisted and pre-send the safety deposit in a native token
+to a pre-computed deterministic address of the created escrow.
+The external postInteraction function call will be made from the Limit Order Protocol
+after all funds have been transferred. See [IPostInteraction-postInteraction](/lib/limit-order-protocol/contracts/mocks/InteractionMock.sol/contract.InteractionMock.md#postinteraction).*
 
 
 ```solidity
@@ -41,24 +49,44 @@ function _postInteraction(
 
 ### createEscrow
 
-*Creates a new escrow contract for taker.*
+See [IEscrowFactory-createEscrow](/contracts/interfaces/IEscrowFactory.sol/interface.IEscrowFactory.md#createescrow).
 
 
 ```solidity
-function createEscrow(DstEscrowImmutablesCreation calldata dstEscrowImmutables) external;
+function createEscrow(DstEscrowImmutablesCreation calldata dstEscrowImmutables) external payable;
 ```
 
 ### addressOfEscrow
 
+See [IEscrowFactory-addressOfEscrow](/contracts/interfaces/IEscrowFactory.sol/interface.IEscrowFactory.md#addressofescrow).
+
 
 ```solidity
-function addressOfEscrow(bytes32 salt) external view returns (address);
+function addressOfEscrow(bytes32 salt) public view returns (address);
 ```
 
 ### _createEscrow
 
+Creates a new escrow contract with immutable arguments.
+
+*The escrow contract is a proxy clone created using the create3 pattern.*
+
 
 ```solidity
-function _createEscrow(bytes memory data, bytes32 salt) private returns (address clone);
+function _createEscrow(bytes memory data, bytes32 salt, uint256 value) private returns (address clone);
 ```
+**Parameters**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`data`|`bytes`|Encoded immutable args.|
+|`salt`|`bytes32`|The salt that influences the contract address in deterministic deployment.|
+|`value`|`uint256`||
+
+**Returns**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`clone`|`address`|The address of the created escrow contract.|
+
 
diff --git a/documentation/src/contracts/interfaces/IEscrow.sol/interface.IEscrow.md b/documentation/src/contracts/interfaces/IEscrow.sol/interface.IEscrow.md
@@ -1,5 +1,105 @@
 # IEscrow
-[Git Source](https://github.com/byshape/cross-chain-swap/blob/c49176f8473d9a06db920990a07a4d8464dd4dd4/contracts/interfaces/IEscrow.sol)
+[Git Source](https://github.com/byshape/cross-chain-swap/blob/e26c23ac0516aa14fa1ee0839087565b952fb4f1/contracts/interfaces/IEscrow.sol)
+
+
+## Functions
+### withdrawSrc
+
+Withdraws funds to the taker on the source chain.
+
+*Withdrawal can only be made during the public unlock period and with secret
+with hash matches the hashlock.
+The safety deposit is sent to the caller.*
+
+
+```solidity
+function withdrawSrc(bytes32 secret) external;
+```
+**Parameters**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`secret`|`bytes32`|The secret that unlocks the escrow.|
+
+
+### cancelSrc
+
+Cancels the escrow on the source chain and returns tokens to the maker.
+
+*The escrow can only be cancelled by taker during the private cancel period or
+by anyone during the public cancel period.
+The safety deposit is sent to the caller.*
+
+
+```solidity
+function cancelSrc() external;
+```
+
+### withdrawDst
+
+Withdraws funds to the maker on the destination chain.
+
+*Withdrawal can only be made by taker during the private unlock period or by anyone
+during the public unlock period. In both cases, a secret with hash matching the hashlock must be provided.
+The safety deposit is sent to the caller.*
+
+
+```solidity
+function withdrawDst(bytes32 secret) external;
+```
+**Parameters**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`secret`|`bytes32`|The secret that unlocks the escrow.|
+
+
+### cancelDst
+
+Cancels the escrow on the destination chain and returns tokens to the taker.
+
+*The escrow can only be cancelled during the cancel period.
+The safety deposit is sent to the caller.*
+
+
+```solidity
+function cancelDst() external;
+```
+
+### srcEscrowImmutables
+
+Returns the immutable parameters of the escrow contract on the source chain.
+
+*The immutables are stored at the end of the proxy clone contract bytecode and
+are added to the calldata each time the proxy clone function is called.*
+
+
+```solidity
+function srcEscrowImmutables() external pure returns (SrcEscrowImmutables calldata);
+```
+**Returns**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`<none>`|`SrcEscrowImmutables`|The immutables of the escrow contract.|
+
+
+### dstEscrowImmutables
+
+Returns the immutable parameters of the escrow contract on the destination chain.
+
+*The immutables are stored at the end of the proxy clone contract bytecode and
+are added to the calldata each time the proxy clone function is called.*
+
+
+```solidity
+function dstEscrowImmutables() external pure returns (DstEscrowImmutables calldata);
+```
+**Returns**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`<none>`|`DstEscrowImmutables`|The immutables of the escrow contract.|
 
 
 ## Errors
@@ -27,17 +127,34 @@ error InvalidSecret();
 error InvalidWithdrawalTime();
 ```
 
+### NativeTokenSendingFailure
+
+```solidity
+error NativeTokenSendingFailure();
+```
+
 ## Structs
 ### SrcTimelocks
+Timelocks for the source chain.
+finality: The duration of the chain finality period.
+publicUnlock: The duration of the period when anyone with a secret can withdraw tokens for the taker.
+cancel: The duration of the period when escrow can only be cancelled by the taker.
+
 
 ```solidity
 struct SrcTimelocks {
     uint256 finality;
     uint256 publicUnlock;
+    uint256 cancel;
 }
 ```
 
 ### DstTimelocks
+Timelocks for the destination chain.
+finality: The duration of the chain finality period.
+unlock: The duration of the period when only the taker with a secret can withdraw tokens for the maker.
+publicUnlock publicUnlock: The duration of the period when anyone with a secret can withdraw tokens for the maker.
+
 
 ```solidity
 struct DstTimelocks {
@@ -64,10 +181,11 @@ struct InteractionParams {
 
 ```solidity
 struct ExtraDataParams {
-    uint256 hashlock;
+    bytes32 hashlock;
     uint256 dstChainId;
     address dstToken;
-    uint256 safetyDeposit;
+    uint256 srcSafetyDeposit;
+    uint256 dstSafetyDeposit;
     SrcTimelocks srcTimelocks;
     DstTimelocks dstTimelocks;
 }
@@ -84,11 +202,14 @@ struct SrcEscrowImmutables {
 ```
 
 ### DstEscrowImmutables
+Data for the destination chain order immutables.
+chainId, token, amount and safetyDeposit relate to the destination chain.
+
 
 ```solidity
 struct DstEscrowImmutables {
     uint256 deployedAt;
-    uint256 hashlock;
+    bytes32 hashlock;
     address maker;
     address taker;
     uint256 chainId;