diff --git a/docs/limit-order-protocol/smart-contract/LimitOrderProtocol.md b/docs/limit-order-protocol/smart-contract/LimitOrderProtocol.md index 63e347758..47852da2c 100644 --- a/docs/limit-order-protocol/smart-contract/LimitOrderProtocol.md +++ b/docs/limit-order-protocol/smart-contract/LimitOrderProtocol.md @@ -1,27 +1,68 @@ -# LimitOrderProtocol +## LimitOrderProtocol -1inch Limit Order Protocol v2 +The key features of the protocol are **extreme flexibility** and **high gas efficiency**, which are achieved with the following features +**Basic features** +- Select an asset receiver for an order. +- Choose whether to allow or disallow partial and multiple fills. +- Define conditions that must be met before execution can proceed (e.g. stop-loss, take-profit orders). +- Specify interactions (arbitrary maker's code) to execute before and after order filling. +- Choose an approval scheme for token spend (approve, permit, permit2). +- Request that WETH be unwrapped to ETH either before (to sell ETH) or after the swap (to receive ETH). +- Make an order private by specifying the only allowed taker's address. +- Set the order's expiration date. +- Assign a nonce or epoch to the order for easy cancellation later. -## Derives -- [OrderRFQMixin](OrderRFQMixin.md) -- [OrderMixin](OrderMixin.md) -- [Permitable](libraries/Permitable.md) -- [PredicateHelper](helpers/PredicateHelper.md) -- [NonceManager](helpers/NonceManager.md) -- [ChainlinkCalculator](helpers/ChainlinkCalculator.md) -- [AmountCalculator](helpers/AmountCalculator.md) -- [EIP712](https://docs.openzeppelin.com/contracts/3.x/api/utils/cryptography#draft-EIP712) +**Advanced features** + +- Define a proxy to handle transfers of assets that are not compliant with `IERC20`, allowing the swapping of non-ERC20 tokens, such as ERC721 or ERC1155. +- Define functions to calculate, on-chain, the exchange rate for maker and taker assets. These functions can be used to implement dutch auctions (where the rate decreases over time) or range orders (where the rate depends on the volume already filled), among others. + +### RFQ orders + +Separate RFQ order are deprecated in v4. To create the most gas efficient order use a basic order without extensions. + +### Supported tokens + +- ERC 20 +- ERC 721 +- ERC 1155 +- Other token standards could be supported via external extension + +### Functions list +- [constructor(_weth) public](#constructor) +- [DOMAIN_SEPARATOR() external](#domain_separator) +- [pause() external](#pause) +- [unpause() external](#unpause) + +### Functions +### constructor + +```solidity +constructor(contract IWETH _weth) public +``` -## Functions ### DOMAIN_SEPARATOR + ```solidity -function DOMAIN_SEPARATOR( -) external returns (bytes32) +function DOMAIN_SEPARATOR() external view returns (bytes32) ``` +_Returns the domain separator for the current chain (EIP-712)_ + +### pause + +```solidity +function pause() external +``` +Pauses all the trading functionality in the contract. +### unpause +```solidity +function unpause() external +``` +Unpauses all the trading functionality in the contract. diff --git a/docs/limit-order-protocol/smart-contract/LimitOrderProtocolPro.md b/docs/limit-order-protocol/smart-contract/LimitOrderProtocolPro.md deleted file mode 100644 index d014831f8..000000000 --- a/docs/limit-order-protocol/smart-contract/LimitOrderProtocolPro.md +++ /dev/null @@ -1,26 +0,0 @@ -# LimitOrderProtocolPro - - -1inch Pro Limit Order Protocol - - - -## Derives -- [OrderMixin](OrderMixin.md) -- [Permitable](libraries/Permitable.md) -- [PredicateHelper](helpers/PredicateHelper.md) -- [NonceManager](helpers/NonceManager.md) -- [ChainlinkCalculator](helpers/ChainlinkCalculator.md) -- [AmountCalculator](helpers/AmountCalculator.md) -- [EIP712](https://docs.openzeppelin.com/contracts/3.x/api/utils/cryptography#draft-EIP712) - -## Functions -### DOMAIN_SEPARATOR -```solidity -function DOMAIN_SEPARATOR( -) external returns (bytes32) -``` - - - - diff --git a/docs/limit-order-protocol/smart-contract/OrderLib.md b/docs/limit-order-protocol/smart-contract/OrderLib.md index d7180dca7..105edad0c 100644 --- a/docs/limit-order-protocol/smart-contract/OrderLib.md +++ b/docs/limit-order-protocol/smart-contract/OrderLib.md @@ -1,135 +1,159 @@ -# OrderLib - +## OrderLib +_The library provides common functionality for processing and manipulating limit orders. +It provides functionality to calculate and verify order hashes, calculate trade amounts, and validate +extension data associated with orders. The library also contains helper methods to get the receiver of +an order and call getter functions._ +### Functions list +- [hash(order, domainSeparator) internal](#hash) +- [getReceiver(order) internal](#getreceiver) +- [calculateMakingAmount(order, extension, requestedTakingAmount, remainingMakingAmount, orderHash) internal](#calculatemakingamount) +- [calculateTakingAmount(order, extension, requestedMakingAmount, remainingMakingAmount, orderHash) internal](#calculatetakingamount) +- [isValidExtension(order, extension) internal](#isvalidextension) +### Errors list +- [MissingOrderExtension() ](#missingorderextension) +- [UnexpectedOrderExtension() ](#unexpectedorderextension) +- [InvalidExtensionHash() ](#invalidextensionhash) +### Functions +### hash -## Functions -### makerAssetData ```solidity -function makerAssetData( - struct OrderLib.Order order -) internal returns (bytes) +function hash(struct IOrderMixin.Order order, bytes32 domainSeparator) internal pure returns (bytes32 result) ``` +Calculates the hash of an order. + +#### Parameters +| Name | Type | Description | +| ---- | ---- | ----------- | +| order | struct IOrderMixin.Order | The order to be hashed. | +| domainSeparator | bytes32 | The domain separator to be used for the EIP-712 hashing. | -#### Parameters: -| Name | Type | Description | -| :--- | :--- | :------------------------------------------------------------------- | -|`order` | struct OrderLib.Order | +#### Return Values +| Name | Type | Description | +| ---- | ---- | ----------- | +result | bytes32 | The keccak256 hash of the order data. | + +### getReceiver -### takerAssetData ```solidity -function takerAssetData( - struct OrderLib.Order order -) internal returns (bytes) +function getReceiver(struct IOrderMixin.Order order) internal pure returns (address) ``` +Returns the receiver address for an order. + +#### Parameters +| Name | Type | Description | +| ---- | ---- | ----------- | +| order | struct IOrderMixin.Order | The order. | -#### Parameters: -| Name | Type | Description | -| :--- | :--- | :------------------------------------------------------------------- | -|`order` | struct OrderLib.Order | +#### Return Values +| Name | Type | Description | +| ---- | ---- | ----------- | +[0] | address | receiver The address of the receiver, either explicitly defined in the order or the maker's address if not specified. | + +### calculateMakingAmount -### getMakingAmount ```solidity -function getMakingAmount( - struct OrderLib.Order order -) internal returns (bytes) +function calculateMakingAmount(struct IOrderMixin.Order order, bytes extension, uint256 requestedTakingAmount, uint256 remainingMakingAmount, bytes32 orderHash) internal view returns (uint256) ``` +Calculates the making amount based on the requested taking amount. +_If getter is specified in the extension data, the getter is called to calculate the making amount, +otherwise the making amount is calculated linearly._ -#### Parameters: -| Name | Type | Description | -| :--- | :--- | :------------------------------------------------------------------- | -|`order` | struct OrderLib.Order | +#### Parameters +| Name | Type | Description | +| ---- | ---- | ----------- | +| order | struct IOrderMixin.Order | The order. | +| extension | bytes | The extension data associated with the order. | +| requestedTakingAmount | uint256 | The amount the taker wants to take. | +| remainingMakingAmount | uint256 | The remaining amount of the asset left to fill. | +| orderHash | bytes32 | The hash of the order. | -### getTakingAmount -```solidity -function getTakingAmount( - struct OrderLib.Order order -) internal returns (bytes) -``` +#### Return Values +| Name | Type | Description | +| ---- | ---- | ----------- | +[0] | uint256 | makingAmount The amount of the asset the maker receives. | -#### Parameters: -| Name | Type | Description | -| :--- | :--- | :------------------------------------------------------------------- | -|`order` | struct OrderLib.Order | +### calculateTakingAmount - -### predicate ```solidity -function predicate( - struct OrderLib.Order order -) internal returns (bytes) +function calculateTakingAmount(struct IOrderMixin.Order order, bytes extension, uint256 requestedMakingAmount, uint256 remainingMakingAmount, bytes32 orderHash) internal view returns (uint256) ``` +Calculates the taking amount based on the requested making amount. +_If getter is specified in the extension data, the getter is called to calculate the taking amount, +otherwise the taking amount is calculated linearly._ -#### Parameters: -| Name | Type | Description | -| :--- | :--- | :------------------------------------------------------------------- | -|`order` | struct OrderLib.Order | - +#### Parameters -### permit -```solidity -function permit( - struct OrderLib.Order order -) internal returns (bytes) -``` +| Name | Type | Description | +| ---- | ---- | ----------- | +| order | struct IOrderMixin.Order | The order. | +| extension | bytes | The extension data associated with the order. | +| requestedMakingAmount | uint256 | The amount the maker wants to receive. | +| remainingMakingAmount | uint256 | The remaining amount of the asset left to be filled. | +| orderHash | bytes32 | The hash of the order. | +#### Return Values -#### Parameters: -| Name | Type | Description | -| :--- | :--- | :------------------------------------------------------------------- | -|`order` | struct OrderLib.Order | +| Name | Type | Description | +| ---- | ---- | ----------- | +[0] | uint256 | takingAmount The amount of the asset the taker takes. | +### isValidExtension -### preInteraction ```solidity -function preInteraction( - struct OrderLib.Order order -) internal returns (bytes) +function isValidExtension(struct IOrderMixin.Order order, bytes extension) internal pure returns (bool, bytes4) ``` +_Validates the extension associated with an order._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| order | struct IOrderMixin.Order | The order to validate against. | +| extension | bytes | The extension associated with the order. | + +#### Return Values -#### Parameters: -| Name | Type | Description | -| :--- | :--- | :------------------------------------------------------------------- | -|`order` | struct OrderLib.Order | +| Name | Type | Description | +| ---- | ---- | ----------- | +[0] | bool | valid True if the extension is valid, false otherwise. | +[1] | bytes4 | errorSelector The error selector if the extension is invalid, 0x00000000 otherwise. | +### Errors +### MissingOrderExtension -### postInteraction ```solidity -function postInteraction( - struct OrderLib.Order order -) internal returns (bytes) +error MissingOrderExtension() ``` +_Error to be thrown when the extension data of an order is missing._ -#### Parameters: -| Name | Type | Description | -| :--- | :--- | :------------------------------------------------------------------- | -|`order` | struct OrderLib.Order | +### UnexpectedOrderExtension - -### hash ```solidity -function hash( - struct OrderLib.Order order -) internal returns (bytes32 result) +error UnexpectedOrderExtension() ``` +_Error to be thrown when the order has an unexpected extension._ + +### InvalidExtensionHash -#### Parameters: -| Name | Type | Description | -| :--- | :--- | :------------------------------------------------------------------- | -|`order` | struct OrderLib.Order | +```solidity +error InvalidExtensionHash() +``` +_Error to be thrown when the order extension hash is invalid._ diff --git a/docs/limit-order-protocol/smart-contract/OrderMixin.md b/docs/limit-order-protocol/smart-contract/OrderMixin.md index 354b7d82a..0546476e4 100644 --- a/docs/limit-order-protocol/smart-contract/OrderMixin.md +++ b/docs/limit-order-protocol/smart-contract/OrderMixin.md @@ -1,241 +1,117 @@ -# OrderMixin +## OrderMixin + +### Functions list +- [constructor(weth) internal](#constructor) +- [bitInvalidatorForOrder(maker, slot) external](#bitinvalidatorfororder) +- [remainingInvalidatorForOrder(maker, orderHash) external](#remaininginvalidatorfororder) +- [rawRemainingInvalidatorForOrder(maker, orderHash) external](#rawremaininginvalidatorfororder) +- [simulate(target, data) external](#simulate) +- [cancelOrder(makerTraits, orderHash) public](#cancelorder) +- [cancelOrders(makerTraits, orderHashes) external](#cancelorders) +- [bitsInvalidateForOrder(makerTraits, additionalMask) external](#bitsinvalidatefororder) +- [hashOrder(order) external](#hashorder) +- [checkPredicate(predicate) public](#checkpredicate) +- [fillOrder(order, r, vs, amount, takerTraits) external](#fillorder) +- [fillOrderArgs(order, r, vs, amount, takerTraits, args) external](#fillorderargs) +- [fillContractOrder(order, signature, amount, takerTraits) external](#fillcontractorder) +- [fillContractOrderArgs(order, signature, amount, takerTraits, args) external](#fillcontractorderargs) + +### Functions +### constructor -Regular Limit Order mixin - - - -## Derives -- [Permitable](libraries/Permitable.md) -- [PredicateHelper](helpers/PredicateHelper.md) -- [NonceManager](helpers/NonceManager.md) -- [ChainlinkCalculator](helpers/ChainlinkCalculator.md) -- [AmountCalculator](helpers/AmountCalculator.md) -- [EIP712](https://docs.openzeppelin.com/contracts/3.x/api/utils/cryptography#draft-EIP712) - -## Functions -### remaining ```solidity -function remaining( - bytes32 orderHash -) external returns (uint256) +constructor(contract IWETH weth) internal ``` -Returns unfilled amount for order. Throws if order does not exist -#### Parameters: -| Name | Type | Description | -| :--- | :--- | :------------------------------------------------------------------- | -|`orderHash` | bytes32 | +### bitInvalidatorForOrder - -### remainingRaw ```solidity -function remainingRaw( - bytes32 orderHash -) external returns (uint256) +function bitInvalidatorForOrder(address maker, uint256 slot) external view returns (uint256) ``` -Returns unfilled amount for order - - -#### Parameters: -| Name | Type | Description | -| :--- | :--- | :------------------------------------------------------------------- | -|`orderHash` | bytes32 | +See {IOrderMixin-bitInvalidatorForOrder}. -#### Return Values: -| Name | Type | Description | -| :----------------------------- | :------------ | :--------------------------------------------------------------------------- | -|`Result`| uint256 | Unfilled amount of order plus one if order exists. Otherwise 0 +### remainingInvalidatorForOrder -### remainingsRaw ```solidity -function remainingsRaw( - bytes32[] orderHashes -) external returns (uint256[]) +function remainingInvalidatorForOrder(address maker, bytes32 orderHash) external view returns (uint256) ``` -Same as `remainingRaw` but for multiple orders +See {IOrderMixin-remainingInvalidatorForOrder}. -#### Parameters: -| Name | Type | Description | -| :--- | :--- | :------------------------------------------------------------------- | -|`orderHashes` | bytes32[] | +### rawRemainingInvalidatorForOrder - -### simulateCalls ```solidity -function simulateCalls( - address[] targets, - bytes[] data -) external +function rawRemainingInvalidatorForOrder(address maker, bytes32 orderHash) external view returns (uint256) ``` -Calls every target with corresponding data. Then reverts with CALL_RESULTS_0101011 where zeroes and ones -denote failure or success of the corresponding call - +See {IOrderMixin-rawRemainingInvalidatorForOrder}. -#### Parameters: -| Name | Type | Description | -| :--- | :--- | :------------------------------------------------------------------- | -|`targets` | address[] | Array of addresses that will be called -|`data` | bytes[] | Array of data that will be passed to each call +### simulate - -### cancelOrder ```solidity -function cancelOrder( - struct OrderLib.Order order -) external +function simulate(address target, bytes data) external ``` -Cancels order by setting remaining amount to zero - -#### Parameters: -| Name | Type | Description | -| :--- | :--- | :------------------------------------------------------------------- | -|`order` | struct OrderLib.Order | +See {IOrderMixin-simulate}. +### cancelOrder -### fillOrder ```solidity -function fillOrder( - struct OrderLib.Order order, - bytes signature, - bytes interaction, - uint256 makingAmount, - uint256 takingAmount, - uint256 thresholdAmount -) external returns (uint256, uint256) +function cancelOrder(MakerTraits makerTraits, bytes32 orderHash) public ``` -Fills an order. If one doesn't exist (first fill) it will be created using order.makerAssetData +See {IOrderMixin-cancelOrder}. +### cancelOrders -#### Parameters: -| Name | Type | Description | -| :--- | :--- | :------------------------------------------------------------------- | -|`order` | struct OrderLib.Order | Order quote to fill -|`signature` | bytes | Signature to confirm quote ownership -|`interaction` | bytes | Making amount -|`makingAmount` | uint256 | Taking amount -|`takingAmount` | uint256 | Specifies maximum allowed takingAmount when takingAmount is zero, otherwise specifies minimum allowed makingAmount -|`thresholdAmount` | uint256 | - - -### fillOrderToWithPermit ```solidity -function fillOrderToWithPermit( - struct OrderLib.Order order, - bytes signature, - bytes interaction, - uint256 makingAmount, - uint256 takingAmount, - uint256 thresholdAmount, - address target, - bytes permit -) external returns (uint256, uint256) +function cancelOrders(MakerTraits[] makerTraits, bytes32[] orderHashes) external ``` -Same as `fillOrder` but calls permit first, -allowing to approve token spending and make a swap in one transaction. -Also allows to specify funds destination instead of `msg.sender` - -See tests for examples -#### Parameters: -| Name | Type | Description | -| :--- | :--- | :------------------------------------------------------------------- | -|`order` | struct OrderLib.Order | Order quote to fill -|`signature` | bytes | Signature to confirm quote ownership -|`interaction` | bytes | Making amount -|`makingAmount` | uint256 | Taking amount -|`takingAmount` | uint256 | Specifies maximum allowed takingAmount when takingAmount is zero, otherwise specifies minimum allowed makingAmount -|`thresholdAmount` | uint256 | Address that will receive swap funds -|`target` | address | Should consist of abiencoded token address and encoded `IERC20Permit.permit` call. -|`permit` | bytes | - - -### fillOrderTo +See {IOrderMixin-cancelOrders}. + +### bitsInvalidateForOrder + ```solidity -function fillOrderTo( - struct OrderLib.Order order_, - bytes signature, - bytes interaction, - uint256 makingAmount, - uint256 takingAmount, - uint256 thresholdAmount, - address target -) public returns (uint256, uint256) +function bitsInvalidateForOrder(MakerTraits makerTraits, uint256 additionalMask) external ``` -Same as `fillOrder` but allows to specify funds destination instead of `msg.sender` +See {IOrderMixin-bitsInvalidateForOrder}. +### hashOrder -#### Parameters: -| Name | Type | Description | -| :--- | :--- | :------------------------------------------------------------------- | -|`order_` | struct OrderLib.Order | Order quote to fill -|`signature` | bytes | Signature to confirm quote ownership -|`interaction` | bytes | Making amount -|`makingAmount` | uint256 | Taking amount -|`takingAmount` | uint256 | Specifies maximum allowed takingAmount when takingAmount is zero, otherwise specifies minimum allowed makingAmount -|`thresholdAmount` | uint256 | Address that will receive swap funds -|`target` | address | - +```solidity +function hashOrder(struct IOrderMixin.Order order) external view returns (bytes32) +``` +See {IOrderMixin-hashOrder}. ### checkPredicate + ```solidity -function checkPredicate( - struct OrderLib.Order order -) public returns (bool) +function checkPredicate(bytes predicate) public view returns (bool) ``` -Checks order predicate - -#### Parameters: -| Name | Type | Description | -| :--- | :--- | :------------------------------------------------------------------- | -|`order` | struct OrderLib.Order | +See {IOrderMixin-checkPredicate}. +### fillOrder -### hashOrder ```solidity -function hashOrder( - struct OrderLib.Order order -) public returns (bytes32) +function fillOrder(struct IOrderMixin.Order order, bytes32 r, bytes32 vs, uint256 amount, TakerTraits takerTraits) external payable returns (uint256, uint256, bytes32) ``` +See {IOrderMixin-fillOrder}. +### fillOrderArgs -#### Parameters: -| Name | Type | Description | -| :--- | :--- | :------------------------------------------------------------------- | -|`order` | struct OrderLib.Order | +```solidity +function fillOrderArgs(struct IOrderMixin.Order order, bytes32 r, bytes32 vs, uint256 amount, TakerTraits takerTraits, bytes args) external payable returns (uint256, uint256, bytes32) +``` +See {IOrderMixin-fillOrderArgs}. +### fillContractOrder -## Events -### OrderFilled ```solidity -event OrderFilled( - address maker, - bytes32 orderHash, - uint256 remaining -) +function fillContractOrder(struct IOrderMixin.Order order, bytes signature, uint256 amount, TakerTraits takerTraits) external returns (uint256, uint256, bytes32) ``` -Emitted every time order gets filled, including partial fills +See {IOrderMixin-fillContractOrder}. -#### Parameters: -| Name | Type | Description | -| :--- | :--- | :------------------------------------------------------------------- | -|`maker` | address | -|`orderHash` | bytes32 | -|`remaining` | uint256 | +### fillContractOrderArgs -### OrderCanceled ```solidity -event OrderCanceled( - address maker, - bytes32 orderHash, - uint256 remainingRaw -) +function fillContractOrderArgs(struct IOrderMixin.Order order, bytes signature, uint256 amount, TakerTraits takerTraits, bytes args) external returns (uint256, uint256, bytes32) ``` -Emitted when order gets cancelled - -#### Parameters: -| Name | Type | Description | -| :--- | :--- | :------------------------------------------------------------------- | -|`maker` | address | -|`orderHash` | bytes32 | -|`remainingRaw` | uint256 | +See {IOrderMixin-fillContractOrderArgs}. diff --git a/docs/limit-order-protocol/smart-contract/OrderRFQMixin.md b/docs/limit-order-protocol/smart-contract/OrderRFQMixin.md deleted file mode 100644 index c7d5128b7..000000000 --- a/docs/limit-order-protocol/smart-contract/OrderRFQMixin.md +++ /dev/null @@ -1,135 +0,0 @@ -# OrderRFQMixin - - -RFQ Limit Order mixin - - - -## Derives -- [Permitable](libraries/Permitable.md) -- [AmountCalculator](helpers/AmountCalculator.md) -- [EIP712](https://docs.openzeppelin.com/contracts/3.x/api/utils/cryptography#draft-EIP712) - -## Functions -### invalidatorForOrderRFQ -```solidity -function invalidatorForOrderRFQ( - address maker, - uint256 slot -) external returns (uint256) -``` -Returns bitmask for double-spend invalidators based on lowest byte of order.info and filled quotes - - -#### Parameters: -| Name | Type | Description | -| :--- | :--- | :------------------------------------------------------------------- | -|`maker` | address | -|`slot` | uint256 | - -#### Return Values: -| Name | Type | Description | -| :----------------------------- | :------------ | :--------------------------------------------------------------------------- | -|`Result`| uint256 | Each bit represents whether corresponding was already invalidated - -### cancelOrderRFQ -```solidity -function cancelOrderRFQ( - uint256 orderInfo -) external -``` -Cancels order's quote - -#### Parameters: -| Name | Type | Description | -| :--- | :--- | :------------------------------------------------------------------- | -|`orderInfo` | uint256 | - - -### fillOrderRFQ -```solidity -function fillOrderRFQ( - struct OrderRFQMixin.Order order, - bytes signature, - uint256 makingAmount, - uint256 takingAmount -) external returns (uint256, uint256) -``` -Fills order's quote, fully or partially (whichever is possible) - - -#### Parameters: -| Name | Type | Description | -| :--- | :--- | :------------------------------------------------------------------- | -|`order` | struct OrderRFQMixin.Order | Order quote to fill -|`signature` | bytes | Signature to confirm quote ownership -|`makingAmount` | uint256 | Making amount -|`takingAmount` | uint256 | Taking amount - - -### fillOrderRFQToWithPermit -```solidity -function fillOrderRFQToWithPermit( - struct OrderRFQMixin.Order order, - bytes signature, - uint256 makingAmount, - uint256 takingAmount, - address target, - bytes permit -) external returns (uint256, uint256) -``` -Fills Same as `fillOrderRFQ` but calls permit first, -allowing to approve token spending and make a swap in one transaction. -Also allows to specify funds destination instead of `msg.sender` - -See tests for examples -#### Parameters: -| Name | Type | Description | -| :--- | :--- | :------------------------------------------------------------------- | -|`order` | struct OrderRFQMixin.Order | Order quote to fill -|`signature` | bytes | Signature to confirm quote ownership -|`makingAmount` | uint256 | Making amount -|`takingAmount` | uint256 | Taking amount -|`target` | address | Address that will receive swap funds -|`permit` | bytes | Should consist of abiencoded token address and encoded `IERC20Permit.permit` call. - - -### fillOrderRFQTo -```solidity -function fillOrderRFQTo( - struct OrderRFQMixin.Order order, - bytes signature, - uint256 makingAmount, - uint256 takingAmount, - address target -) public returns (uint256, uint256) -``` -Same as `fillOrderRFQ` but allows to specify funds destination instead of `msg.sender` - - -#### Parameters: -| Name | Type | Description | -| :--- | :--- | :------------------------------------------------------------------- | -|`order` | struct OrderRFQMixin.Order | Order quote to fill -|`signature` | bytes | Signature to confirm quote ownership -|`makingAmount` | uint256 | Making amount -|`takingAmount` | uint256 | Taking amount -|`target` | address | Address that will receive swap funds - - -## Events -### OrderFilledRFQ -```solidity -event OrderFilledRFQ( - bytes32 orderHash, - uint256 makingAmount -) -``` -Emitted when RFQ gets filled - -#### Parameters: -| Name | Type | Description | -| :--- | :--- | :------------------------------------------------------------------- | -|`orderHash` | bytes32 | -|`makingAmount` | uint256 | - diff --git a/docs/limit-order-protocol/smart-contract/README.md b/docs/limit-order-protocol/smart-contract/README.md index e7b3744c3..fe004a2fd 100644 --- a/docs/limit-order-protocol/smart-contract/README.md +++ b/docs/limit-order-protocol/smart-contract/README.md @@ -1,3 +1,2 @@ -# 1inch limit order protocol - -https://github.com/1inch/limit-order-protocol +# Smart Contracts +https://github.com/1inch/limit-order-protocol \ No newline at end of file diff --git a/docs/limit-order-protocol/smart-contract/SUMMARY.md b/docs/limit-order-protocol/smart-contract/SUMMARY.md index 55bee6aa4..b652be7a0 100644 --- a/docs/limit-order-protocol/smart-contract/SUMMARY.md +++ b/docs/limit-order-protocol/smart-contract/SUMMARY.md @@ -1,35 +1,41 @@ # Table of contents * [Main Readme](README.md) +* [extensions](extensions/README.md) + * [ApprovalPreInteraction](extensions/ApprovalPreInteraction.md) + * [ChainlinkCalculator](extensions/ChainlinkCalculator.md) + * [DutchAuctionCalculator](extensions/DutchAuctionCalculator.md) + * [ERC1155Proxy](extensions/ERC1155Proxy.md) + * [ERC721Proxy](extensions/ERC721Proxy.md) + * [ERC721ProxySafe](extensions/ERC721ProxySafe.md) + * [ETHOrders](extensions/ETHOrders.md) + * [FeeTaker](extensions/FeeTaker.md) + * [ImmutableOwner](extensions/ImmutableOwner.md) + * [OrderIdInvalidator](extensions/OrderIdInvalidator.md) + * [Permit2WitnessProxy](extensions/Permit2WitnessProxy.md) + * [PrioirityFeeLimiter](extensions/PrioirityFeeLimiter.md) + * [RangeAmountCalculator](extensions/RangeAmountCalculator.md) * [helpers](helpers/README.md) - * [AmountCalculator](helpers/AmountCalculator.md) - * [ChainlinkCalculator](helpers/ChainlinkCalculator.md) - * [ERC1155Proxy](helpers/ERC1155Proxy.md) - * [ERC721Proxy](helpers/ERC721Proxy.md) - * [ERC721ProxySafe](helpers/ERC721ProxySafe.md) - * [ImmutableOwner](helpers/ImmutableOwner.md) - * [NonceManager](helpers/NonceManager.md) * [PredicateHelper](helpers/PredicateHelper.md) + * [SeriesEpochManager](helpers/SeriesEpochManager.md) * [SeriesNonceManager](helpers/SeriesNonceManager.md) - * [WethUnwrapper](helpers/WethUnwrapper.md) * [interfaces](interfaces/README.md) - * [IDaiLikePermit](interfaces/IDaiLikePermit.md) - * [IWithdrawable](interfaces/IWithdrawable.md) - * [Interaction](interfaces/Interaction.md) - * [PostInteraction](interfaces/PostInteraction.md) - * [PreInteraction](interfaces/PreInteraction.md) + * [IAmountGetter](interfaces/IAmountGetter.md) + * [ICreate3Deployer](interfaces/ICreate3Deployer.md) + * [IOrderMixin](interfaces/IOrderMixin.md) + * [IPermit2WitnessTransferFrom](interfaces/IPermit2WitnessTransferFrom.md) + * [IPostInteraction](interfaces/IPostInteraction.md) + * [IPreInteraction](interfaces/IPreInteraction.md) + * [ITakerInteraction](interfaces/ITakerInteraction.md) * [libraries](libraries/README.md) - * [ArgumentsDecoder](libraries/ArgumentsDecoder.md) - * [Permitable](libraries/Permitable.md) - * [RevertReasonParser](libraries/RevertReasonParser.md) -* [mocks](mocks/README.md) - * [AggregatorMock](mocks/AggregatorMock.md) - * [TokenMock](mocks/TokenMock.md) - * [WrappedTokenMock](mocks/WrappedTokenMock.md) -* [tests](tests/README.md) - * [ArgumentsDecoderTest](tests/ArgumentsDecoderTest.md) + * [AmountCalculatorLib](libraries/AmountCalculatorLib.md) + * [BitInvalidatorLib](libraries/BitInvalidatorLib.md) + * [Errors](libraries/Errors.md) + * [ExtensionLib](libraries/ExtensionLib.md) + * [MakerTraitsLib](libraries/MakerTraitsLib.md) + * [OffsetsLib](libraries/OffsetsLib.md) + * [RemainingInvalidatorLib](libraries/RemainingInvalidatorLib.md) + * [TakerTraitsLib](libraries/TakerTraitsLib.md) * [LimitOrderProtocol](LimitOrderProtocol.md) -* [LimitOrderProtocolPro](LimitOrderProtocolPro.md) * [OrderLib](OrderLib.md) -* [OrderMixin](OrderMixin.md) -* [OrderRFQMixin](OrderRFQMixin.md) +* [OrderMixin](OrderMixin.md) \ No newline at end of file diff --git a/docs/limit-order-protocol/smart-contract/extensions/ApprovalPreInteraction.md b/docs/limit-order-protocol/smart-contract/extensions/ApprovalPreInteraction.md new file mode 100644 index 000000000..1702ec013 --- /dev/null +++ b/docs/limit-order-protocol/smart-contract/extensions/ApprovalPreInteraction.md @@ -0,0 +1,39 @@ + +## ApprovalPreInteraction + +### Functions list +- [constructor(_immutableOwner, _maker) public](#constructor) +- [preInteraction(order, , , , makingAmount, , , ) external](#preinteraction) +- [isValidSignature(orderHash, signature) external](#isvalidsignature) + +### Errors list +- [UnathorizedMaker() ](#unathorizedmaker) + +### Functions +### constructor + +```solidity +constructor(address _immutableOwner, address _maker) public +``` + +### preInteraction + +```solidity +function preInteraction(struct IOrderMixin.Order order, bytes, bytes32, address, uint256 makingAmount, uint256, uint256, bytes) external +``` +See {IPreInteraction-preInteraction}. + +### isValidSignature + +```solidity +function isValidSignature(bytes32 orderHash, bytes signature) external view returns (bytes4) +``` +Checks if orderHash signature was signed with real order maker. + +### Errors +### UnathorizedMaker + +```solidity +error UnathorizedMaker() +``` + diff --git a/docs/limit-order-protocol/smart-contract/extensions/ChainlinkCalculator.md b/docs/limit-order-protocol/smart-contract/extensions/ChainlinkCalculator.md new file mode 100644 index 000000000..ad037d5ca --- /dev/null +++ b/docs/limit-order-protocol/smart-contract/extensions/ChainlinkCalculator.md @@ -0,0 +1,77 @@ + +## ChainlinkCalculator + +### Functions list +- [doublePrice(oracle1, oracle2, decimalsScale, amount) external](#doubleprice) +- [getMakingAmount(, , , , takingAmount, , extraData) external](#getmakingamount) +- [getTakingAmount(, , , , makingAmount, , extraData) external](#gettakingamount) +- [_getSpreadedAmount(amount, blob) internal](#_getspreadedamount) +- [_doublePrice(oracle1, oracle2, decimalsScale, amount) internal](#_doubleprice) + +### Errors list +- [DifferentOracleDecimals() ](#differentoracledecimals) +- [StaleOraclePrice() ](#staleoracleprice) + +### Functions +### doublePrice + +```solidity +function doublePrice(contract AggregatorV3Interface oracle1, contract AggregatorV3Interface oracle2, int256 decimalsScale, uint256 amount) external view returns (uint256 result) +``` +Calculates price of token A relative to token B. Note that order is important + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +result | uint256 | Token A relative price times amount | + +### getMakingAmount + +```solidity +function getMakingAmount(struct IOrderMixin.Order, bytes, bytes32, address, uint256 takingAmount, uint256, bytes extraData) external view returns (uint256) +``` + +### getTakingAmount + +```solidity +function getTakingAmount(struct IOrderMixin.Order, bytes, bytes32, address, uint256 makingAmount, uint256, bytes extraData) external view returns (uint256) +``` + +### _getSpreadedAmount + +```solidity +function _getSpreadedAmount(uint256 amount, bytes blob) internal view returns (uint256) +``` +Calculates price of token relative to oracle unit (ETH or USD) +The first byte of the blob contain inverse and useDoublePrice flags, +The inverse flag is set when oracle price should be inverted, +e.g. for DAI-ETH oracle, inverse=false means that we request DAI price in ETH +and inverse=true means that we request ETH price in DAI +The useDoublePrice flag is set when needs price for two custom tokens (other than ETH or USD) + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +[0] | uint256 | Amount * spread * oracle price | + +### _doublePrice + +```solidity +function _doublePrice(contract AggregatorV3Interface oracle1, contract AggregatorV3Interface oracle2, int256 decimalsScale, uint256 amount) internal view returns (uint256 result) +``` + +### Errors +### DifferentOracleDecimals + +```solidity +error DifferentOracleDecimals() +``` + +### StaleOraclePrice + +```solidity +error StaleOraclePrice() +``` + diff --git a/docs/limit-order-protocol/smart-contract/extensions/DutchAuctionCalculator.md b/docs/limit-order-protocol/smart-contract/extensions/DutchAuctionCalculator.md new file mode 100644 index 000000000..5adac4213 --- /dev/null +++ b/docs/limit-order-protocol/smart-contract/extensions/DutchAuctionCalculator.md @@ -0,0 +1,22 @@ + +## DutchAuctionCalculator + +The contract implements Dutch auction price calculation for 1inch limit orders, it is used by 1inch Fusion + +### Functions list +- [getMakingAmount(order, , , , takingAmount, , extraData) external](#getmakingamount) +- [getTakingAmount(order, , , , makingAmount, , extraData) external](#gettakingamount) + +### Functions +### getMakingAmount + +```solidity +function getMakingAmount(struct IOrderMixin.Order order, bytes, bytes32, address, uint256 takingAmount, uint256, bytes extraData) external view returns (uint256) +``` + +### getTakingAmount + +```solidity +function getTakingAmount(struct IOrderMixin.Order order, bytes, bytes32, address, uint256 makingAmount, uint256, bytes extraData) external view returns (uint256) +``` + diff --git a/docs/limit-order-protocol/smart-contract/extensions/ERC1155Proxy.md b/docs/limit-order-protocol/smart-contract/extensions/ERC1155Proxy.md new file mode 100644 index 000000000..8295c526e --- /dev/null +++ b/docs/limit-order-protocol/smart-contract/extensions/ERC1155Proxy.md @@ -0,0 +1,31 @@ + +## ERC1155Proxy + +### Functions list +- [constructor(_immutableOwner) public](#constructor) +- [func_301JL5R(from, to, amount, token, tokenId, data) external](#func_301jl5r) + +### Errors list +- [ERC1155ProxyBadSelector() ](#erc1155proxybadselector) + +### Functions +### constructor + +```solidity +constructor(address _immutableOwner) public +``` + +### func_301JL5R + +```solidity +function func_301JL5R(address from, address to, uint256 amount, contract IERC1155 token, uint256 tokenId, bytes data) external +``` +Proxy transfer method for `IERC1155.safeTransferFrom`. Selector must match `IERC20.transferFrom` + +### Errors +### ERC1155ProxyBadSelector + +```solidity +error ERC1155ProxyBadSelector() +``` + diff --git a/docs/limit-order-protocol/smart-contract/extensions/ERC721Proxy.md b/docs/limit-order-protocol/smart-contract/extensions/ERC721Proxy.md new file mode 100644 index 000000000..01620bdbc --- /dev/null +++ b/docs/limit-order-protocol/smart-contract/extensions/ERC721Proxy.md @@ -0,0 +1,32 @@ + +## ERC721Proxy + +### Functions list +- [constructor(_immutableOwner) public](#constructor) +- [func_60iHVgK(from, to, , tokenId, token) external](#func_60ihvgk) + +### Errors list +- [ERC721ProxyBadSelector() ](#erc721proxybadselector) + +### Functions +### constructor + +```solidity +constructor(address _immutableOwner) public +``` + +### func_60iHVgK + +```solidity +function func_60iHVgK(address from, address to, uint256, uint256 tokenId, contract IERC721 token) external +``` +Proxy transfer method for `IERC721.transferFrom`. Selector must match `IERC20.transferFrom`. +Note that `amount` is unused for security reasons to prevent unintended ERC-721 token sale via partial fill + +### Errors +### ERC721ProxyBadSelector + +```solidity +error ERC721ProxyBadSelector() +``` + diff --git a/docs/limit-order-protocol/smart-contract/extensions/ERC721ProxySafe.md b/docs/limit-order-protocol/smart-contract/extensions/ERC721ProxySafe.md new file mode 100644 index 000000000..859c38eb1 --- /dev/null +++ b/docs/limit-order-protocol/smart-contract/extensions/ERC721ProxySafe.md @@ -0,0 +1,32 @@ + +## ERC721ProxySafe + +### Functions list +- [constructor(_immutableOwner) public](#constructor) +- [func_60iHVgK(from, to, , tokenId, token) external](#func_60ihvgk) + +### Errors list +- [ERC721ProxySafeBadSelector() ](#erc721proxysafebadselector) + +### Functions +### constructor + +```solidity +constructor(address _immutableOwner) public +``` + +### func_60iHVgK + +```solidity +function func_60iHVgK(address from, address to, uint256, uint256 tokenId, contract IERC721 token) external +``` +Proxy transfer method for `IERC721.transferFrom`. Selector must match `IERC20.transferFrom`. +Note that `amount` is unused for security reasons to prevent unintended ERC-721 token sale via partial fill + +### Errors +### ERC721ProxySafeBadSelector + +```solidity +error ERC721ProxySafeBadSelector() +``` + diff --git a/docs/limit-order-protocol/smart-contract/extensions/ETHOrders.md b/docs/limit-order-protocol/smart-contract/extensions/ETHOrders.md new file mode 100644 index 000000000..66f08235a --- /dev/null +++ b/docs/limit-order-protocol/smart-contract/extensions/ETHOrders.md @@ -0,0 +1,128 @@ + +## ETHOrders + +### Types list +- [ETHOrder](#ethorder) + +### Functions list +- [constructor(weth, limitOrderProtocol) public](#constructor) +- [ethOrdersBatch(orderHashes) external](#ethordersbatch) +- [ethOrderDeposit(order, extension) external](#ethorderdeposit) +- [cancelOrder(makerTraits, orderHash) external](#cancelorder) +- [isValidSignature(orderHash, signature) external](#isvalidsignature) +- [postInteraction(, , orderHash, , makingAmount, , , ) external](#postinteraction) + +### Events list +- [ETHDeposited(orderHash, amount) ](#ethdeposited) +- [ETHOrderCancelled(orderHash, amount) ](#ethordercancelled) + +### Errors list +- [AccessDenied() ](#accessdenied) +- [InvalidOrder() ](#invalidorder) +- [NotEnoughBalance() ](#notenoughbalance) +- [ExistingOrder() ](#existingorder) + +### Types +### ETHOrder + +ETH order struct. + +```solidity +struct ETHOrder { + address maker; + uint96 balance; +} +``` + +### Functions +### constructor + +```solidity +constructor(contract IWETH weth, address limitOrderProtocol) public +``` + +### ethOrdersBatch + +```solidity +function ethOrdersBatch(bytes32[] orderHashes) external view returns (struct ETHOrders.ETHOrder[] ethOrders) +``` + +### ethOrderDeposit + +```solidity +function ethOrderDeposit(struct IOrderMixin.Order order, bytes extension) external payable returns (bytes32 orderHash) +``` + +### cancelOrder + +```solidity +function cancelOrder(MakerTraits makerTraits, bytes32 orderHash) external +``` +Sets ordersMakersBalances to 0, refunds ETH and does standard order cancellation on Limit Order Protocol. + +### isValidSignature + +```solidity +function isValidSignature(bytes32 orderHash, bytes signature) external view returns (bytes4) +``` +Checks if orderHash signature was signed with real order maker. + +### postInteraction + +```solidity +function postInteraction(struct IOrderMixin.Order, bytes, bytes32 orderHash, address, uint256 makingAmount, uint256, uint256, bytes) external +``` +Callback method that gets called after all funds transfers. +Updates _ordersMakersBalances by makingAmount for order with orderHash. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| | struct IOrderMixin.Order | | +| | bytes | | +| orderHash | bytes32 | Hash of the order being processed | +| | address | | +| makingAmount | uint256 | Actual making amount | +| | uint256 | | +| | uint256 | | +| | bytes | | + +### Events +### ETHDeposited + +```solidity +event ETHDeposited(bytes32 orderHash, uint256 amount) +``` + +### ETHOrderCancelled + +```solidity +event ETHOrderCancelled(bytes32 orderHash, uint256 amount) +``` + +### Errors +### AccessDenied + +```solidity +error AccessDenied() +``` + +### InvalidOrder + +```solidity +error InvalidOrder() +``` + +### NotEnoughBalance + +```solidity +error NotEnoughBalance() +``` + +### ExistingOrder + +```solidity +error ExistingOrder() +``` + diff --git a/docs/limit-order-protocol/smart-contract/extensions/FeeTaker.md b/docs/limit-order-protocol/smart-contract/extensions/FeeTaker.md new file mode 100644 index 000000000..fdf1adc73 --- /dev/null +++ b/docs/limit-order-protocol/smart-contract/extensions/FeeTaker.md @@ -0,0 +1,80 @@ + +## FeeTaker + +### Functions list +- [constructor(limitOrderProtocol, weth, owner) public](#constructor) +- [receive() external](#receive) +- [postInteraction(order, , , , , takingAmount, , extraData) external](#postinteraction) +- [rescueFunds(token, amount) external](#rescuefunds) + +### Errors list +- [OnlyLimitOrderProtocol() ](#onlylimitorderprotocol) +- [EthTransferFailed() ](#ethtransferfailed) + +### Functions +### constructor + +```solidity +constructor(address limitOrderProtocol, address weth, address owner) public +``` +Initializes the contract. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| limitOrderProtocol | address | The limit order protocol contract. | +| weth | address | | +| owner | address | | + +### receive + +```solidity +receive() external payable +``` +Fallback function to receive ETH. + +### postInteraction + +```solidity +function postInteraction(struct IOrderMixin.Order order, bytes, bytes32, address, uint256, uint256 takingAmount, uint256, bytes extraData) external +``` +See {IPostInteraction-postInteraction}. + +_Takes the fee in taking tokens and transfers the rest to the maker. +`extraData` consists of: +2 bytes — fee percentage (in 1e5) +20 bytes — fee recipient +20 bytes — receiver of taking tokens (optional, if not set, maker is used)_ + +### rescueFunds + +```solidity +function rescueFunds(contract IERC20 token, uint256 amount) external +``` +Retrieves funds accidently sent directly to the contract address + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| token | contract IERC20 | ERC20 token to retrieve | +| amount | uint256 | amount to retrieve | + +### Errors +### OnlyLimitOrderProtocol + +```solidity +error OnlyLimitOrderProtocol() +``` + +_The caller is not the limit order protocol contract._ + +### EthTransferFailed + +```solidity +error EthTransferFailed() +``` + +_Eth transfer failed. The target fallback may have reverted._ + diff --git a/docs/limit-order-protocol/smart-contract/extensions/ImmutableOwner.md b/docs/limit-order-protocol/smart-contract/extensions/ImmutableOwner.md new file mode 100644 index 000000000..ce04a9c6b --- /dev/null +++ b/docs/limit-order-protocol/smart-contract/extensions/ImmutableOwner.md @@ -0,0 +1,23 @@ + +## ImmutableOwner + +### Functions list +- [constructor(_immutableOwner) public](#constructor) + +### Errors list +- [IOAccessDenied() ](#ioaccessdenied) + +### Functions +### constructor + +```solidity +constructor(address _immutableOwner) public +``` + +### Errors +### IOAccessDenied + +```solidity +error IOAccessDenied() +``` + diff --git a/docs/limit-order-protocol/smart-contract/extensions/OrderIdInvalidator.md b/docs/limit-order-protocol/smart-contract/extensions/OrderIdInvalidator.md new file mode 100644 index 000000000..9094b46da --- /dev/null +++ b/docs/limit-order-protocol/smart-contract/extensions/OrderIdInvalidator.md @@ -0,0 +1,40 @@ + +## OrderIdInvalidator + +OrderIdInvalidator stores pairs (orderId, orderHash) +that allows to execute only one order with the same orderId + +### Functions list +- [constructor(limitOrderProtocol_) public](#constructor) +- [preInteraction(order, , orderHash, , , , , extraData) external](#preinteraction) + +### Errors list +- [AccessDenied() ](#accessdenied) +- [InvalidOrderHash() ](#invalidorderhash) + +### Functions +### constructor + +```solidity +constructor(address limitOrderProtocol_) public +``` + +### preInteraction + +```solidity +function preInteraction(struct IOrderMixin.Order order, bytes, bytes32 orderHash, address, uint256, uint256, uint256, bytes extraData) external +``` + +### Errors +### AccessDenied + +```solidity +error AccessDenied() +``` + +### InvalidOrderHash + +```solidity +error InvalidOrderHash() +``` + diff --git a/docs/limit-order-protocol/smart-contract/extensions/Permit2WitnessProxy.md b/docs/limit-order-protocol/smart-contract/extensions/Permit2WitnessProxy.md new file mode 100644 index 000000000..6dba1bf8e --- /dev/null +++ b/docs/limit-order-protocol/smart-contract/extensions/Permit2WitnessProxy.md @@ -0,0 +1,43 @@ + +## Permit2WitnessProxy + +### Types list +- [Witness](#witness) + +### Functions list +- [constructor(_immutableOwner) public](#constructor) +- [func_801zDya(from, to, amount, permit, witness, sig) external](#func_801zdya) + +### Errors list +- [Permit2WitnessProxyBadSelector() ](#permit2witnessproxybadselector) + +### Types +### Witness + +```solidity +struct Witness { + bytes32 salt; +} +``` + +### Functions +### constructor + +```solidity +constructor(address _immutableOwner) public +``` + +### func_801zDya + +```solidity +function func_801zDya(address from, address to, uint256 amount, struct IPermit2WitnessTransferFrom.PermitTransferFrom permit, bytes32 witness, bytes sig) external +``` +Proxy transfer method for `Permit2.permitWitnessTransferFrom`. Selector must match `IERC20.transferFrom` + +### Errors +### Permit2WitnessProxyBadSelector + +```solidity +error Permit2WitnessProxyBadSelector() +``` + diff --git a/docs/limit-order-protocol/smart-contract/extensions/PrioirityFeeLimiter.md b/docs/limit-order-protocol/smart-contract/extensions/PrioirityFeeLimiter.md new file mode 100644 index 000000000..f63c68001 --- /dev/null +++ b/docs/limit-order-protocol/smart-contract/extensions/PrioirityFeeLimiter.md @@ -0,0 +1,18 @@ + +## PriorityFeeLimiter + +### Functions list +- [isPriorityFeeValid() public](#ispriorityfeevalid) + +### Functions +### isPriorityFeeValid + +```solidity +function isPriorityFeeValid() public view returns (bool) +``` +Validates priority fee according to the spec +https://snapshot.org/#/1inch.eth/proposal/0xa040c60050147a0f67042ae024673e92e813b5d2c0f748abf70ddfa1ed107cbe +For blocks with baseFee <10.6 gwei – the priorityFee is capped at 70% of the baseFee. +For blocks with baseFee between 10.6 gwei and 104.1 gwei – the priorityFee is capped at 50% of the baseFee. +For blocks with baseFee >104.1 gwei – priorityFee is capped at 65% of the block’s baseFee. + diff --git a/docs/limit-order-protocol/smart-contract/extensions/README.md b/docs/limit-order-protocol/smart-contract/extensions/README.md new file mode 100644 index 000000000..bccd6f819 --- /dev/null +++ b/docs/limit-order-protocol/smart-contract/extensions/README.md @@ -0,0 +1 @@ +# extensions diff --git a/docs/limit-order-protocol/smart-contract/extensions/RangeAmountCalculator.md b/docs/limit-order-protocol/smart-contract/extensions/RangeAmountCalculator.md new file mode 100644 index 000000000..c6127eb93 --- /dev/null +++ b/docs/limit-order-protocol/smart-contract/extensions/RangeAmountCalculator.md @@ -0,0 +1,59 @@ + +## RangeAmountCalculator + +A range limit order is a strategy used to sell an asset within a specified price range. +For instance, suppose you anticipate the value of ETH to increase in the next week from its +current worth of 3000 DAI to a minimum of 4000 DAI. +In that case, you can create an ETH -> DAI limit order within the price range of 3000 -> 4000. +For example, you could create an order to sell 10 ETH within that price range. + +When someone places a bid for the entire limit order, they may purchase it all at once at +an average price of 3500 DAI. Alternatively, the limit order may be executed in portions. +For instance, the buyer might purchase 1 ETH for 3050 DAI, then another 1 ETH for 3150 DAI, and so on. + +Function of the changing price of makerAsset tokens in takerAsset tokens by the filling amount of makerAsset tokens in order: + priceEnd - priceStart +y = ----------------------- * x + priceStart + totalAmount + +### Functions list +- [getTakingAmount(order, , , , makingAmount, remainingMakingAmount, extraData) external](#gettakingamount) +- [getMakingAmount(order, , , , takingAmount, remainingMakingAmount, extraData) external](#getmakingamount) +- [getRangeTakerAmount(priceStart, priceEnd, orderMakingAmount, makingAmount, remainingMakingAmount) public](#getrangetakeramount) +- [getRangeMakerAmount(priceStart, priceEnd, orderMakingAmount, takingAmount, remainingMakingAmount) public](#getrangemakeramount) + +### Errors list +- [IncorrectRange() ](#incorrectrange) + +### Functions +### getTakingAmount + +```solidity +function getTakingAmount(struct IOrderMixin.Order order, bytes, bytes32, address, uint256 makingAmount, uint256 remainingMakingAmount, bytes extraData) external pure returns (uint256) +``` + +### getMakingAmount + +```solidity +function getMakingAmount(struct IOrderMixin.Order order, bytes, bytes32, address, uint256 takingAmount, uint256 remainingMakingAmount, bytes extraData) external pure returns (uint256) +``` + +### getRangeTakerAmount + +```solidity +function getRangeTakerAmount(uint256 priceStart, uint256 priceEnd, uint256 orderMakingAmount, uint256 makingAmount, uint256 remainingMakingAmount) public pure returns (uint256) +``` + +### getRangeMakerAmount + +```solidity +function getRangeMakerAmount(uint256 priceStart, uint256 priceEnd, uint256 orderMakingAmount, uint256 takingAmount, uint256 remainingMakingAmount) public pure returns (uint256) +``` + +### Errors +### IncorrectRange + +```solidity +error IncorrectRange() +``` + diff --git a/docs/limit-order-protocol/smart-contract/helpers/AmountCalculator.md b/docs/limit-order-protocol/smart-contract/helpers/AmountCalculator.md deleted file mode 100644 index 8fb1fd14a..000000000 --- a/docs/limit-order-protocol/smart-contract/helpers/AmountCalculator.md +++ /dev/null @@ -1,76 +0,0 @@ -# AmountCalculator - - -A helper contract for calculations related to order amounts - - - - -## Functions -### getMakingAmount -```solidity -function getMakingAmount( - uint256 orderMakerAmount, - uint256 orderTakerAmount, - uint256 swapTakerAmount -) public returns (uint256) -``` -Calculates maker amount - - -#### Parameters: -| Name | Type | Description | -| :--- | :--- | :------------------------------------------------------------------- | -|`orderMakerAmount` | uint256 | -|`orderTakerAmount` | uint256 | -|`swapTakerAmount` | uint256 | - -#### Return Values: -| Name | Type | Description | -| :----------------------------- | :------------ | :--------------------------------------------------------------------------- | -|`Result`| uint256 | Floored maker amount - -### getTakingAmount -```solidity -function getTakingAmount( - uint256 orderMakerAmount, - uint256 orderTakerAmount, - uint256 swapMakerAmount -) public returns (uint256) -``` -Calculates taker amount - - -#### Parameters: -| Name | Type | Description | -| :--- | :--- | :------------------------------------------------------------------- | -|`orderMakerAmount` | uint256 | -|`orderTakerAmount` | uint256 | -|`swapMakerAmount` | uint256 | - -#### Return Values: -| Name | Type | Description | -| :----------------------------- | :------------ | :--------------------------------------------------------------------------- | -|`Result`| uint256 | Ceiled taker amount - -### arbitraryStaticCall -```solidity -function arbitraryStaticCall( - address target, - bytes data -) external returns (uint256) -``` -Performs an arbitrary call to target with data - - -#### Parameters: -| Name | Type | Description | -| :--- | :--- | :------------------------------------------------------------------- | -|`target` | address | -|`data` | bytes | - -#### Return Values: -| Name | Type | Description | -| :----------------------------- | :------------ | :--------------------------------------------------------------------------- | -|`Result`| uint256 | Bytes transmuted to uint256 - diff --git a/docs/limit-order-protocol/smart-contract/helpers/ChainlinkCalculator.md b/docs/limit-order-protocol/smart-contract/helpers/ChainlinkCalculator.md deleted file mode 100644 index 62d68e50d..000000000 --- a/docs/limit-order-protocol/smart-contract/helpers/ChainlinkCalculator.md +++ /dev/null @@ -1,59 +0,0 @@ -# ChainlinkCalculator - - -A helper contract for interactions with https://docs.chain.link - - - - -## Functions -### singlePrice -```solidity -function singlePrice( - contract AggregatorV3Interface oracle, - uint256 inverseAndSpread, - uint256 amount -) external returns (uint256) -``` -Calculates price of token relative to oracle unit (ETH or USD) - - -#### Parameters: -| Name | Type | Description | -| :--- | :--- | :------------------------------------------------------------------- | -|`oracle` | contract AggregatorV3Interface | concatenated inverse flag and spread. Lowest 254 bits specify spread amount. Spread is scaled by 1e9, i.e. 101% = 1.01e9, 99% = 0.99e9. Highest bit is set when oracle price should be inverted, e.g. for DAI-ETH oracle, inverse=false means that we request DAI price in ETH and inverse=true means that we request ETH price in DAI -|`inverseAndSpread` | uint256 | -|`amount` | uint256 | - -#### Return Values: -| Name | Type | Description | -| :----------------------------- | :------------ | :--------------------------------------------------------------------------- | -|`Amount`| uint256 | * spread * oracle price - -### doublePrice -```solidity -function doublePrice( - contract AggregatorV3Interface oracle1, - contract AggregatorV3Interface oracle2, - uint256 spread, - int256 decimalsScale, - uint256 amount -) external returns (uint256) -``` -Calculates price of token A relative to token B. Note that order is important - - -#### Parameters: -| Name | Type | Description | -| :--- | :--- | :------------------------------------------------------------------- | -|`oracle1` | contract AggregatorV3Interface | -|`oracle2` | contract AggregatorV3Interface | -|`spread` | uint256 | -|`decimalsScale` | int256 | -|`amount` | uint256 | - -#### Return Values: -| Name | Type | Description | -| :----------------------------- | :------------ | :--------------------------------------------------------------------------- | -|`Result`| uint256 | Token A relative price times amount - diff --git a/docs/limit-order-protocol/smart-contract/helpers/ERC1155Proxy.md b/docs/limit-order-protocol/smart-contract/helpers/ERC1155Proxy.md deleted file mode 100644 index dfd900326..000000000 --- a/docs/limit-order-protocol/smart-contract/helpers/ERC1155Proxy.md +++ /dev/null @@ -1,49 +0,0 @@ -# ERC1155Proxy - - - - - - -## Derives -- [ImmutableOwner](helpers/ImmutableOwner.md) - -## Functions -### constructor -```solidity -function constructor( - address _immutableOwner -) public -``` - - -#### Parameters: -| Name | Type | Description | -| :--- | :--- | :------------------------------------------------------------------- | -|`_immutableOwner` | address | - - -### func_301JL5R -```solidity -function func_301JL5R( - address from, - address to, - uint256 amount, - contract IERC1155 token, - uint256 tokenId, - bytes data -) external -``` -Proxy transfer method for `IERC1155.safeTransferFrom`. Selector must match `IERC20.transferFrom` - -#### Parameters: -| Name | Type | Description | -| :--- | :--- | :------------------------------------------------------------------- | -|`from` | address | -|`to` | address | -|`amount` | uint256 | -|`token` | contract IERC1155 | -|`tokenId` | uint256 | -|`data` | bytes | - - diff --git a/docs/limit-order-protocol/smart-contract/helpers/ERC721Proxy.md b/docs/limit-order-protocol/smart-contract/helpers/ERC721Proxy.md deleted file mode 100644 index 515f8de26..000000000 --- a/docs/limit-order-protocol/smart-contract/helpers/ERC721Proxy.md +++ /dev/null @@ -1,48 +0,0 @@ -# ERC721Proxy - - - - - - -## Derives -- [ImmutableOwner](helpers/ImmutableOwner.md) - -## Functions -### constructor -```solidity -function constructor( - address _immutableOwner -) public -``` - - -#### Parameters: -| Name | Type | Description | -| :--- | :--- | :------------------------------------------------------------------- | -|`_immutableOwner` | address | - - -### func_60iHVgK -```solidity -function func_60iHVgK( - address from, - address to, - uint256 , - uint256 tokenId, - contract IERC721 token -) external -``` -Proxy transfer method for `IERC721.transferFrom`. Selector must match `IERC20.transferFrom`. -Note that `amount` is unused for security reasons to prevent unintended ERC-721 token sale via partial fill - -#### Parameters: -| Name | Type | Description | -| :--- | :--- | :------------------------------------------------------------------- | -|`from` | address | -|`to` | address | -|`` | uint256 | -|`tokenId` | uint256 | -|`token` | contract IERC721 | - - diff --git a/docs/limit-order-protocol/smart-contract/helpers/ERC721ProxySafe.md b/docs/limit-order-protocol/smart-contract/helpers/ERC721ProxySafe.md deleted file mode 100644 index a5695414c..000000000 --- a/docs/limit-order-protocol/smart-contract/helpers/ERC721ProxySafe.md +++ /dev/null @@ -1,48 +0,0 @@ -# ERC721ProxySafe - - - - - - -## Derives -- [ImmutableOwner](helpers/ImmutableOwner.md) - -## Functions -### constructor -```solidity -function constructor( - address _immutableOwner -) public -``` - - -#### Parameters: -| Name | Type | Description | -| :--- | :--- | :------------------------------------------------------------------- | -|`_immutableOwner` | address | - - -### func_60iHVgK -```solidity -function func_60iHVgK( - address from, - address to, - uint256 , - uint256 tokenId, - contract IERC721 token -) external -``` -Proxy transfer method for `IERC721.transferFrom`. Selector must match `IERC20.transferFrom`. -Note that `amount` is unused for security reasons to prevent unintended ERC-721 token sale via partial fill - -#### Parameters: -| Name | Type | Description | -| :--- | :--- | :------------------------------------------------------------------- | -|`from` | address | -|`to` | address | -|`` | uint256 | -|`tokenId` | uint256 | -|`token` | contract IERC721 | - - diff --git a/docs/limit-order-protocol/smart-contract/helpers/ImmutableOwner.md b/docs/limit-order-protocol/smart-contract/helpers/ImmutableOwner.md deleted file mode 100644 index a9cfd2bb7..000000000 --- a/docs/limit-order-protocol/smart-contract/helpers/ImmutableOwner.md +++ /dev/null @@ -1,23 +0,0 @@ -# ImmutableOwner - - -A helper contract with helper modifiers to allow access to original contract creator only - - - - -## Functions -### constructor -```solidity -function constructor( - address _immutableOwner -) public -``` - - -#### Parameters: -| Name | Type | Description | -| :--- | :--- | :------------------------------------------------------------------- | -|`_immutableOwner` | address | - - diff --git a/docs/limit-order-protocol/smart-contract/helpers/NonceManager.md b/docs/limit-order-protocol/smart-contract/helpers/NonceManager.md deleted file mode 100644 index 42e271dc5..000000000 --- a/docs/limit-order-protocol/smart-contract/helpers/NonceManager.md +++ /dev/null @@ -1,69 +0,0 @@ -# NonceManager - - -A helper contract for managing nonce of tx sender - - - - -## Functions -### increaseNonce -```solidity -function increaseNonce( -) external -``` -Advances nonce by one - - - -### advanceNonce -```solidity -function advanceNonce( - uint8 amount -) public -``` -Advances nonce by specified amount - -#### Parameters: -| Name | Type | Description | -| :--- | :--- | :------------------------------------------------------------------- | -|`amount` | uint8 | - - -### nonceEquals -```solidity -function nonceEquals( - address makerAddress, - uint256 makerNonce -) external returns (bool) -``` -Checks if `makerAddress` has specified `makerNonce` - - -#### Parameters: -| Name | Type | Description | -| :--- | :--- | :------------------------------------------------------------------- | -|`makerAddress` | address | -|`makerNonce` | uint256 | - -#### Return Values: -| Name | Type | Description | -| :----------------------------- | :------------ | :--------------------------------------------------------------------------- | -|`Result`| bool | True if `makerAddress` has specified nonce. Otherwise, false - -## Events -### NonceIncreased -```solidity -event NonceIncreased( - address maker, - uint256 newNonce -) -``` - - -#### Parameters: -| Name | Type | Description | -| :--- | :--- | :------------------------------------------------------------------- | -|`maker` | address | -|`newNonce` | uint256 | - diff --git a/docs/limit-order-protocol/smart-contract/helpers/PredicateHelper.md b/docs/limit-order-protocol/smart-contract/helpers/PredicateHelper.md index 907a8fadb..097898b73 100644 --- a/docs/limit-order-protocol/smart-contract/helpers/PredicateHelper.md +++ b/docs/limit-order-protocol/smart-contract/helpers/PredicateHelper.md @@ -1,139 +1,142 @@ -# PredicateHelper +## PredicateHelper -A helper contract for executing boolean functions on arbitrary target call results +### Functions list +- [or(offsets, data) public](#or) +- [and(offsets, data) public](#and) +- [not(data) public](#not) +- [eq(value, data) public](#eq) +- [lt(value, data) public](#lt) +- [gt(value, data) public](#gt) +- [arbitraryStaticCall(target, data) public](#arbitrarystaticcall) +- [_staticcallForUint(target, data) internal](#_staticcallforuint) +### Errors list +- [ArbitraryStaticCallFailed() ](#arbitrarystaticcallfailed) - - -## Functions +### Functions ### or + ```solidity -function or( - address[] targets, - bytes[] data -) external returns (bool) +function or(uint256 offsets, bytes data) public view returns (bool) ``` Calls every target with corresponding data +#### Return Values -#### Parameters: -| Name | Type | Description | -| :--- | :--- | :------------------------------------------------------------------- | -|`targets` | address[] | -|`data` | bytes[] | - -#### Return Values: -| Name | Type | Description | -| :----------------------------- | :------------ | :--------------------------------------------------------------------------- | -|`Result`| bool | True if call to any target returned True. Otherwise, false +| Name | Type | Description | +| ---- | ---- | ----------- | +[0] | bool | Result True if call to any target returned True. Otherwise, false | ### and + ```solidity -function and( - address[] targets, - bytes[] data -) external returns (bool) +function and(uint256 offsets, bytes data) public view returns (bool) ``` Calls every target with corresponding data +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +[0] | bool | Result True if calls to all targets returned True. Otherwise, false | -#### Parameters: -| Name | Type | Description | -| :--- | :--- | :------------------------------------------------------------------- | -|`targets` | address[] | -|`data` | bytes[] | +### not -#### Return Values: -| Name | Type | Description | -| :----------------------------- | :------------ | :--------------------------------------------------------------------------- | -|`Result`| bool | True if calls to all targets returned True. Otherwise, false +```solidity +function not(bytes data) public view returns (bool) +``` +Calls target with specified data and tests if it's equal to 0 + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +[0] | bool | Result True if call to target returns 0. Otherwise, false | ### eq + ```solidity -function eq( - uint256 value, - address target, - bytes data -) external returns (bool) +function eq(uint256 value, bytes data) public view returns (bool) ``` Calls target with specified data and tests if it's equal to the value +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| value | uint256 | Value to test | +| data | bytes | | -#### Parameters: -| Name | Type | Description | -| :--- | :--- | :------------------------------------------------------------------- | -|`value` | uint256 | Value to test -|`target` | address | -|`data` | bytes | +#### Return Values -#### Return Values: -| Name | Type | Description | -| :----------------------------- | :------------ | :--------------------------------------------------------------------------- | -|`Result`| bool | True if call to target returns the same value as `value`. Otherwise, false +| Name | Type | Description | +| ---- | ---- | ----------- | +[0] | bool | Result True if call to target returns the same value as `value`. Otherwise, false | ### lt + ```solidity -function lt( - uint256 value, - address target, - bytes data -) external returns (bool) +function lt(uint256 value, bytes data) public view returns (bool) ``` Calls target with specified data and tests if it's lower than value +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| value | uint256 | Value to test | +| data | bytes | | -#### Parameters: -| Name | Type | Description | -| :--- | :--- | :------------------------------------------------------------------- | -|`value` | uint256 | Value to test -|`target` | address | -|`data` | bytes | +#### Return Values -#### Return Values: -| Name | Type | Description | -| :----------------------------- | :------------ | :--------------------------------------------------------------------------- | -|`Result`| bool | True if call to target returns value which is lower than `value`. Otherwise, false +| Name | Type | Description | +| ---- | ---- | ----------- | +[0] | bool | Result True if call to target returns value which is lower than `value`. Otherwise, false | ### gt + ```solidity -function gt( - uint256 value, - address target, - bytes data -) external returns (bool) +function gt(uint256 value, bytes data) public view returns (bool) ``` Calls target with specified data and tests if it's bigger than value +#### Parameters -#### Parameters: -| Name | Type | Description | -| :--- | :--- | :------------------------------------------------------------------- | -|`value` | uint256 | Value to test -|`target` | address | -|`data` | bytes | +| Name | Type | Description | +| ---- | ---- | ----------- | +| value | uint256 | Value to test | +| data | bytes | | -#### Return Values: -| Name | Type | Description | -| :----------------------------- | :------------ | :--------------------------------------------------------------------------- | -|`Result`| bool | True if call to target returns value which is bigger than `value`. Otherwise, false +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +[0] | bool | Result True if call to target returns value which is bigger than `value`. Otherwise, false | + +### arbitraryStaticCall -### timestampBelow ```solidity -function timestampBelow( - uint256 time -) external returns (bool) +function arbitraryStaticCall(address target, bytes data) public view returns (uint256) ``` -Checks passed time against block timestamp +Performs an arbitrary call to target with data + +#### Return Values +| Name | Type | Description | +| ---- | ---- | ----------- | +[0] | uint256 | Result Bytes transmuted to uint256 | -#### Parameters: -| Name | Type | Description | -| :--- | :--- | :------------------------------------------------------------------- | -|`time` | uint256 | +### _staticcallForUint -#### Return Values: -| Name | Type | Description | -| :----------------------------- | :------------ | :--------------------------------------------------------------------------- | -|`Result`| bool | True if current block timestamp is lower than `time`. Otherwise, false +```solidity +function _staticcallForUint(address target, bytes data) internal view returns (bool success, uint256 res) +``` + +### Errors +### ArbitraryStaticCallFailed + +```solidity +error ArbitraryStaticCallFailed() +``` diff --git a/docs/limit-order-protocol/smart-contract/helpers/SeriesEpochManager.md b/docs/limit-order-protocol/smart-contract/helpers/SeriesEpochManager.md new file mode 100644 index 000000000..6e5faf878 --- /dev/null +++ b/docs/limit-order-protocol/smart-contract/helpers/SeriesEpochManager.md @@ -0,0 +1,64 @@ + +## SeriesEpochManager + +### Functions list +- [epoch(maker, series) public](#epoch) +- [increaseEpoch(series) external](#increaseepoch) +- [advanceEpoch(series, amount) public](#advanceepoch) +- [epochEquals(maker, series, makerEpoch) public](#epochequals) + +### Events list +- [EpochIncreased(maker, series, newEpoch) ](#epochincreased) + +### Errors list +- [AdvanceEpochFailed() ](#advanceepochfailed) + +### Functions +### epoch + +```solidity +function epoch(address maker, uint96 series) public view returns (uint256) +``` +Returns nonce for `maker` and `series` + +### increaseEpoch + +```solidity +function increaseEpoch(uint96 series) external +``` +Advances nonce by one + +### advanceEpoch + +```solidity +function advanceEpoch(uint96 series, uint256 amount) public +``` +Advances nonce by specified amount + +### epochEquals + +```solidity +function epochEquals(address maker, uint256 series, uint256 makerEpoch) public view returns (bool) +``` +Checks if `maker` has specified `makerEpoch` for `series` + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +[0] | bool | Result True if `maker` has specified epoch. Otherwise, false | + +### Events +### EpochIncreased + +```solidity +event EpochIncreased(address maker, uint256 series, uint256 newEpoch) +``` + +### Errors +### AdvanceEpochFailed + +```solidity +error AdvanceEpochFailed() +``` + diff --git a/docs/limit-order-protocol/smart-contract/helpers/SeriesNonceManager.md b/docs/limit-order-protocol/smart-contract/helpers/SeriesNonceManager.md index fb4ee73af..81e1333cb 100644 --- a/docs/limit-order-protocol/smart-contract/helpers/SeriesNonceManager.md +++ b/docs/limit-order-protocol/smart-contract/helpers/SeriesNonceManager.md @@ -1,80 +1,77 @@ -# SeriesNonceManager +## SeriesNonceManager -A helper contract to manage nonce with the series +### Functions list +- [increaseNonce(series) external](#increasenonce) +- [advanceNonce(series, amount) public](#advancenonce) +- [nonceEquals(series, makerAddress, makerNonce) public](#nonceequals) +- [timestampBelow(time) public](#timestampbelow) +- [timestampBelowAndNonceEquals(timeNonceSeriesAccount) public](#timestampbelowandnonceequals) +### Events list +- [NonceIncreased(maker, series, newNonce) ](#nonceincreased) +### Errors list +- [AdvanceNonceFailed() ](#advancenoncefailed) - -## Functions +### Functions ### increaseNonce + ```solidity -function increaseNonce( - uint8 series -) external +function increaseNonce(uint8 series) external ``` Advances nonce by one -#### Parameters: -| Name | Type | Description | -| :--- | :--- | :------------------------------------------------------------------- | -|`series` | uint8 | - - ### advanceNonce + ```solidity -function advanceNonce( - uint8 series, - uint8 amount -) public +function advanceNonce(uint256 series, uint256 amount) public ``` Advances nonce by specified amount -#### Parameters: -| Name | Type | Description | -| :--- | :--- | :------------------------------------------------------------------- | -|`series` | uint8 | -|`amount` | uint8 | - - ### nonceEquals + ```solidity -function nonceEquals( - uint8 series, - address makerAddress, - uint256 makerNonce -) external returns (bool) +function nonceEquals(uint256 series, address makerAddress, uint256 makerNonce) public view returns (bool) ``` Checks if `makerAddress` has specified `makerNonce` for `series` +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +[0] | bool | Result True if `makerAddress` has specified nonce. Otherwise, false | + +### timestampBelow -#### Parameters: -| Name | Type | Description | -| :--- | :--- | :------------------------------------------------------------------- | -|`series` | uint8 | -|`makerAddress` | address | -|`makerNonce` | uint256 | +```solidity +function timestampBelow(uint256 time) public view returns (bool) +``` +Checks passed time against block timestamp + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +[0] | bool | Result True if current block timestamp is lower than `time`. Otherwise, false | + +### timestampBelowAndNonceEquals -#### Return Values: -| Name | Type | Description | -| :----------------------------- | :------------ | :--------------------------------------------------------------------------- | -|`Result`| bool | True if `makerAddress` has specified nonce. Otherwise, false +```solidity +function timestampBelowAndNonceEquals(uint256 timeNonceSeriesAccount) public view returns (bool) +``` -## Events +### Events ### NonceIncreased + ```solidity -event NonceIncreased( - address maker, - uint8 series, - uint256 newNonce -) +event NonceIncreased(address maker, uint256 series, uint256 newNonce) ``` +### Errors +### AdvanceNonceFailed -#### Parameters: -| Name | Type | Description | -| :--- | :--- | :------------------------------------------------------------------- | -|`maker` | address | -|`series` | uint8 | -|`newNonce` | uint256 | +```solidity +error AdvanceNonceFailed() +``` diff --git a/docs/limit-order-protocol/smart-contract/helpers/WethUnwrapper.md b/docs/limit-order-protocol/smart-contract/helpers/WethUnwrapper.md deleted file mode 100644 index 1472bec5c..000000000 --- a/docs/limit-order-protocol/smart-contract/helpers/WethUnwrapper.md +++ /dev/null @@ -1,44 +0,0 @@ -# WethUnwrapper - - - - - - -## Derives -- PostInteraction - -## Functions -### receive -```solidity -function receive( -) external -``` - - - - -### postInteraction -```solidity -function postInteraction( - address , - address , - address takerAsset, - uint256 , - uint256 takingAmount, - bytes interactiveData -) external -``` - - -#### Parameters: -| Name | Type | Description | -| :--- | :--- | :------------------------------------------------------------------- | -|`` | address | -|`` | address | -|`takerAsset` | address | -|`` | uint256 | -|`takingAmount` | uint256 | -|`interactiveData` | bytes | - - diff --git a/docs/limit-order-protocol/smart-contract/interfaces/IAmountGetter.md b/docs/limit-order-protocol/smart-contract/interfaces/IAmountGetter.md new file mode 100644 index 000000000..c1b92a5d7 --- /dev/null +++ b/docs/limit-order-protocol/smart-contract/interfaces/IAmountGetter.md @@ -0,0 +1,46 @@ + +## IAmountGetter + +### Functions list +- [getMakingAmount(order, extension, orderHash, taker, takingAmount, remainingMakingAmount, extraData) external](#getmakingamount) +- [getTakingAmount(order, extension, orderHash, taker, makingAmount, remainingMakingAmount, extraData) external](#gettakingamount) + +### Functions +### getMakingAmount + +```solidity +function getMakingAmount(struct IOrderMixin.Order order, bytes extension, bytes32 orderHash, address taker, uint256 takingAmount, uint256 remainingMakingAmount, bytes extraData) external view returns (uint256) +``` +View method that gets called to determine the actual making amount + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| order | struct IOrderMixin.Order | Order being processed | +| extension | bytes | Order extension data | +| orderHash | bytes32 | Hash of the order being processed | +| taker | address | Taker address | +| takingAmount | uint256 | Actual taking amount | +| remainingMakingAmount | uint256 | Order remaining making amount | +| extraData | bytes | Extra data | + +### getTakingAmount + +```solidity +function getTakingAmount(struct IOrderMixin.Order order, bytes extension, bytes32 orderHash, address taker, uint256 makingAmount, uint256 remainingMakingAmount, bytes extraData) external view returns (uint256) +``` +View method that gets called to determine the actual making amount + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| order | struct IOrderMixin.Order | Order being processed | +| extension | bytes | Order extension data | +| orderHash | bytes32 | Hash of the order being processed | +| taker | address | Taker address | +| makingAmount | uint256 | Actual taking amount | +| remainingMakingAmount | uint256 | Order remaining making amount | +| extraData | bytes | Extra data | + diff --git a/docs/limit-order-protocol/smart-contract/interfaces/ICreate3Deployer.md b/docs/limit-order-protocol/smart-contract/interfaces/ICreate3Deployer.md new file mode 100644 index 000000000..0b075cb15 --- /dev/null +++ b/docs/limit-order-protocol/smart-contract/interfaces/ICreate3Deployer.md @@ -0,0 +1,20 @@ + +## ICreate3Deployer + +### Functions list +- [deploy(salt, code) external](#deploy) +- [addressOf(salt) external](#addressof) + +### Functions +### deploy + +```solidity +function deploy(bytes32 salt, bytes code) external returns (address) +``` + +### addressOf + +```solidity +function addressOf(bytes32 salt) external view returns (address) +``` + diff --git a/docs/limit-order-protocol/smart-contract/interfaces/IDaiLikePermit.md b/docs/limit-order-protocol/smart-contract/interfaces/IDaiLikePermit.md deleted file mode 100644 index ba5432e42..000000000 --- a/docs/limit-order-protocol/smart-contract/interfaces/IDaiLikePermit.md +++ /dev/null @@ -1,37 +0,0 @@ -# IDaiLikePermit - - -Interface for DAI-style permits - - - - -## Functions -### permit -```solidity -function permit( - address holder, - address spender, - uint256 nonce, - uint256 expiry, - bool allowed, - uint8 v, - bytes32 r, - bytes32 s -) external -``` - - -#### Parameters: -| Name | Type | Description | -| :--- | :--- | :------------------------------------------------------------------- | -|`holder` | address | -|`spender` | address | -|`nonce` | uint256 | -|`expiry` | uint256 | -|`allowed` | bool | -|`v` | uint8 | -|`r` | bytes32 | -|`s` | bytes32 | - - diff --git a/docs/limit-order-protocol/smart-contract/interfaces/IOrderMixin.md b/docs/limit-order-protocol/smart-contract/interfaces/IOrderMixin.md new file mode 100644 index 000000000..6f9b03a35 --- /dev/null +++ b/docs/limit-order-protocol/smart-contract/interfaces/IOrderMixin.md @@ -0,0 +1,462 @@ + +## IOrderMixin + +### Types list +- [Order](#order) + +### Functions list +- [bitInvalidatorForOrder(maker, slot) external](#bitinvalidatorfororder) +- [remainingInvalidatorForOrder(maker, orderHash) external](#remaininginvalidatorfororder) +- [rawRemainingInvalidatorForOrder(maker, orderHash) external](#rawremaininginvalidatorfororder) +- [cancelOrder(makerTraits, orderHash) external](#cancelorder) +- [cancelOrders(makerTraits, orderHashes) external](#cancelorders) +- [bitsInvalidateForOrder(makerTraits, additionalMask) external](#bitsinvalidatefororder) +- [hashOrder(order) external](#hashorder) +- [simulate(target, data) external](#simulate) +- [fillOrder(order, r, vs, amount, takerTraits) external](#fillorder) +- [fillOrderArgs(order, r, vs, amount, takerTraits, args) external](#fillorderargs) +- [fillContractOrder(order, signature, amount, takerTraits) external](#fillcontractorder) +- [fillContractOrderArgs(order, signature, amount, takerTraits, args) external](#fillcontractorderargs) + +### Events list +- [OrderFilled(orderHash, remainingAmount) ](#orderfilled) +- [OrderCancelled(orderHash) ](#ordercancelled) +- [BitInvalidatorUpdated(maker, slotIndex, slotValue) ](#bitinvalidatorupdated) + +### Errors list +- [InvalidatedOrder() ](#invalidatedorder) +- [TakingAmountExceeded() ](#takingamountexceeded) +- [PrivateOrder() ](#privateorder) +- [BadSignature() ](#badsignature) +- [OrderExpired() ](#orderexpired) +- [WrongSeriesNonce() ](#wrongseriesnonce) +- [SwapWithZeroAmount() ](#swapwithzeroamount) +- [PartialFillNotAllowed() ](#partialfillnotallowed) +- [OrderIsNotSuitableForMassInvalidation() ](#orderisnotsuitableformassinvalidation) +- [EpochManagerAndBitInvalidatorsAreIncompatible() ](#epochmanagerandbitinvalidatorsareincompatible) +- [ReentrancyDetected() ](#reentrancydetected) +- [PredicateIsNotTrue() ](#predicateisnottrue) +- [TakingAmountTooHigh() ](#takingamounttoohigh) +- [MakingAmountTooLow() ](#makingamounttoolow) +- [TransferFromMakerToTakerFailed() ](#transferfrommakertotakerfailed) +- [TransferFromTakerToMakerFailed() ](#transferfromtakertomakerfailed) +- [MismatchArraysLengths() ](#mismatcharrayslengths) +- [InvalidPermit2Transfer() ](#invalidpermit2transfer) +- [SimulationResults(success, res) ](#simulationresults) + +### Types +### Order + +```solidity +struct Order { + uint256 salt; + Address maker; + Address receiver; + Address makerAsset; + Address takerAsset; + uint256 makingAmount; + uint256 takingAmount; + MakerTraits makerTraits; +} +``` + +### Functions +### bitInvalidatorForOrder + +```solidity +function bitInvalidatorForOrder(address maker, uint256 slot) external view returns (uint256 result) +``` +Returns bitmask for double-spend invalidators based on lowest byte of order.info and filled quotes + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| maker | address | Maker address | +| slot | uint256 | Slot number to return bitmask for | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +result | uint256 | Each bit represents whether corresponding was already invalidated | + +### remainingInvalidatorForOrder + +```solidity +function remainingInvalidatorForOrder(address maker, bytes32 orderHash) external view returns (uint256 remaining) +``` +Returns bitmask for double-spend invalidators based on lowest byte of order.info and filled quotes + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| maker | address | | +| orderHash | bytes32 | Hash of the order | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +remaining | uint256 | Remaining amount of the order | + +### rawRemainingInvalidatorForOrder + +```solidity +function rawRemainingInvalidatorForOrder(address maker, bytes32 orderHash) external view returns (uint256 remainingRaw) +``` +Returns bitmask for double-spend invalidators based on lowest byte of order.info and filled quotes + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| maker | address | | +| orderHash | bytes32 | Hash of the order | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +remainingRaw | uint256 | Inverse of the remaining amount of the order if order was filled at least once, otherwise 0 | + +### cancelOrder + +```solidity +function cancelOrder(MakerTraits makerTraits, bytes32 orderHash) external +``` +Cancels order's quote + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| makerTraits | MakerTraits | Order makerTraits | +| orderHash | bytes32 | Hash of the order to cancel | + +### cancelOrders + +```solidity +function cancelOrders(MakerTraits[] makerTraits, bytes32[] orderHashes) external +``` +Cancels orders' quotes + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| makerTraits | MakerTraits[] | Orders makerTraits | +| orderHashes | bytes32[] | Hashes of the orders to cancel | + +### bitsInvalidateForOrder + +```solidity +function bitsInvalidateForOrder(MakerTraits makerTraits, uint256 additionalMask) external +``` +Cancels all quotes of the maker (works for bit-invalidating orders only) + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| makerTraits | MakerTraits | Order makerTraits | +| additionalMask | uint256 | Additional bitmask to invalidate orders | + +### hashOrder + +```solidity +function hashOrder(struct IOrderMixin.Order order) external view returns (bytes32 orderHash) +``` +Returns order hash, hashed with limit order protocol contract EIP712 + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| order | struct IOrderMixin.Order | Order | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +orderHash | bytes32 | Hash of the order | + +### simulate + +```solidity +function simulate(address target, bytes data) external +``` +Delegates execution to custom implementation. Could be used to validate if `transferFrom` works properly + +_The function always reverts and returns the simulation results in revert data._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| target | address | Addresses that will be delegated | +| data | bytes | Data that will be passed to delegatee | + +### fillOrder + +```solidity +function fillOrder(struct IOrderMixin.Order order, bytes32 r, bytes32 vs, uint256 amount, TakerTraits takerTraits) external payable returns (uint256 makingAmount, uint256 takingAmount, bytes32 orderHash) +``` +Fills order's quote, fully or partially (whichever is possible). + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| order | struct IOrderMixin.Order | Order quote to fill | +| r | bytes32 | R component of signature | +| vs | bytes32 | VS component of signature | +| amount | uint256 | Taker amount to fill | +| takerTraits | TakerTraits | Specifies threshold as maximum allowed takingAmount when takingAmount is zero, otherwise specifies minimum allowed makingAmount. The 2nd (0 based index) highest bit specifies whether taker wants to skip maker's permit. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +makingAmount | uint256 | Actual amount transferred from maker to taker | +takingAmount | uint256 | Actual amount transferred from taker to maker | +orderHash | bytes32 | Hash of the filled order | + +### fillOrderArgs + +```solidity +function fillOrderArgs(struct IOrderMixin.Order order, bytes32 r, bytes32 vs, uint256 amount, TakerTraits takerTraits, bytes args) external payable returns (uint256 makingAmount, uint256 takingAmount, bytes32 orderHash) +``` +Same as `fillOrder` but allows to specify arguments that are used by the taker. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| order | struct IOrderMixin.Order | Order quote to fill | +| r | bytes32 | R component of signature | +| vs | bytes32 | VS component of signature | +| amount | uint256 | Taker amount to fill | +| takerTraits | TakerTraits | Specifies threshold as maximum allowed takingAmount when takingAmount is zero, otherwise specifies minimum allowed makingAmount. The 2nd (0 based index) highest bit specifies whether taker wants to skip maker's permit. | +| args | bytes | Arguments that are used by the taker (target, extension, interaction, permit) | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +makingAmount | uint256 | Actual amount transferred from maker to taker | +takingAmount | uint256 | Actual amount transferred from taker to maker | +orderHash | bytes32 | Hash of the filled order | + +### fillContractOrder + +```solidity +function fillContractOrder(struct IOrderMixin.Order order, bytes signature, uint256 amount, TakerTraits takerTraits) external returns (uint256 makingAmount, uint256 takingAmount, bytes32 orderHash) +``` +Same as `fillOrder` but uses contract-based signatures. + +_See tests for examples_ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| order | struct IOrderMixin.Order | Order quote to fill | +| signature | bytes | Signature to confirm quote ownership | +| amount | uint256 | Taker amount to fill | +| takerTraits | TakerTraits | Specifies threshold as maximum allowed takingAmount when takingAmount is zero, otherwise specifies minimum allowed makingAmount. The 2nd (0 based index) highest bit specifies whether taker wants to skip maker's permit. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +makingAmount | uint256 | Actual amount transferred from maker to taker | +takingAmount | uint256 | Actual amount transferred from taker to maker | +orderHash | bytes32 | Hash of the filled order | + +### fillContractOrderArgs + +```solidity +function fillContractOrderArgs(struct IOrderMixin.Order order, bytes signature, uint256 amount, TakerTraits takerTraits, bytes args) external returns (uint256 makingAmount, uint256 takingAmount, bytes32 orderHash) +``` +Same as `fillContractOrder` but allows to specify arguments that are used by the taker. + +_See tests for examples_ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| order | struct IOrderMixin.Order | Order quote to fill | +| signature | bytes | Signature to confirm quote ownership | +| amount | uint256 | Taker amount to fill | +| takerTraits | TakerTraits | Specifies threshold as maximum allowed takingAmount when takingAmount is zero, otherwise specifies minimum allowed makingAmount. The 2nd (0 based index) highest bit specifies whether taker wants to skip maker's permit. | +| args | bytes | Arguments that are used by the taker (target, extension, interaction, permit) | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +makingAmount | uint256 | Actual amount transferred from maker to taker | +takingAmount | uint256 | Actual amount transferred from taker to maker | +orderHash | bytes32 | Hash of the filled order | + +### Events +### OrderFilled + +```solidity +event OrderFilled(bytes32 orderHash, uint256 remainingAmount) +``` +Emitted when order gets filled + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| orderHash | bytes32 | Hash of the order | +| remainingAmount | uint256 | Amount of the maker asset that remains to be filled | + +### OrderCancelled + +```solidity +event OrderCancelled(bytes32 orderHash) +``` +Emitted when order without `useBitInvalidator` gets cancelled + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| orderHash | bytes32 | Hash of the order | + +### BitInvalidatorUpdated + +```solidity +event BitInvalidatorUpdated(address maker, uint256 slotIndex, uint256 slotValue) +``` +Emitted when order with `useBitInvalidator` gets cancelled + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| maker | address | Maker address | +| slotIndex | uint256 | Slot index that was updated | +| slotValue | uint256 | New slot value | + +### Errors +### InvalidatedOrder + +```solidity +error InvalidatedOrder() +``` + +### TakingAmountExceeded + +```solidity +error TakingAmountExceeded() +``` + +### PrivateOrder + +```solidity +error PrivateOrder() +``` + +### BadSignature + +```solidity +error BadSignature() +``` + +### OrderExpired + +```solidity +error OrderExpired() +``` + +### WrongSeriesNonce + +```solidity +error WrongSeriesNonce() +``` + +### SwapWithZeroAmount + +```solidity +error SwapWithZeroAmount() +``` + +### PartialFillNotAllowed + +```solidity +error PartialFillNotAllowed() +``` + +### OrderIsNotSuitableForMassInvalidation + +```solidity +error OrderIsNotSuitableForMassInvalidation() +``` + +### EpochManagerAndBitInvalidatorsAreIncompatible + +```solidity +error EpochManagerAndBitInvalidatorsAreIncompatible() +``` + +### ReentrancyDetected + +```solidity +error ReentrancyDetected() +``` + +### PredicateIsNotTrue + +```solidity +error PredicateIsNotTrue() +``` + +### TakingAmountTooHigh + +```solidity +error TakingAmountTooHigh() +``` + +### MakingAmountTooLow + +```solidity +error MakingAmountTooLow() +``` + +### TransferFromMakerToTakerFailed + +```solidity +error TransferFromMakerToTakerFailed() +``` + +### TransferFromTakerToMakerFailed + +```solidity +error TransferFromTakerToMakerFailed() +``` + +### MismatchArraysLengths + +```solidity +error MismatchArraysLengths() +``` + +### InvalidPermit2Transfer + +```solidity +error InvalidPermit2Transfer() +``` + +### SimulationResults + +```solidity +error SimulationResults(bool success, bytes res) +``` + diff --git a/docs/limit-order-protocol/smart-contract/interfaces/IPermit2WitnessTransferFrom.md b/docs/limit-order-protocol/smart-contract/interfaces/IPermit2WitnessTransferFrom.md new file mode 100644 index 000000000..e00b5bef1 --- /dev/null +++ b/docs/limit-order-protocol/smart-contract/interfaces/IPermit2WitnessTransferFrom.md @@ -0,0 +1,45 @@ + +## IPermit2WitnessTransferFrom + +### Types list +- [TokenPermissions](#tokenpermissions) +- [PermitTransferFrom](#permittransferfrom) +- [SignatureTransferDetails](#signaturetransferdetails) + +### Functions list +- [permitWitnessTransferFrom(permit, transferDetails, owner, witness, witnessTypeString, signature) external](#permitwitnesstransferfrom) + +### Types +### TokenPermissions + +```solidity +struct TokenPermissions { + address token; + uint256 amount; +} +``` +### PermitTransferFrom + +```solidity +struct PermitTransferFrom { + struct IPermit2WitnessTransferFrom.TokenPermissions permitted; + uint256 nonce; + uint256 deadline; +} +``` +### SignatureTransferDetails + +```solidity +struct SignatureTransferDetails { + address to; + uint256 requestedAmount; +} +``` + +### Functions +### permitWitnessTransferFrom + +```solidity +function permitWitnessTransferFrom(struct IPermit2WitnessTransferFrom.PermitTransferFrom permit, struct IPermit2WitnessTransferFrom.SignatureTransferDetails transferDetails, address owner, bytes32 witness, string witnessTypeString, bytes signature) external +``` + diff --git a/docs/limit-order-protocol/smart-contract/interfaces/IPostInteraction.md b/docs/limit-order-protocol/smart-contract/interfaces/IPostInteraction.md new file mode 100644 index 000000000..2d5974ad2 --- /dev/null +++ b/docs/limit-order-protocol/smart-contract/interfaces/IPostInteraction.md @@ -0,0 +1,27 @@ + +## IPostInteraction + +### Functions list +- [postInteraction(order, extension, orderHash, taker, makingAmount, takingAmount, remainingMakingAmount, extraData) external](#postinteraction) + +### Functions +### postInteraction + +```solidity +function postInteraction(struct IOrderMixin.Order order, bytes extension, bytes32 orderHash, address taker, uint256 makingAmount, uint256 takingAmount, uint256 remainingMakingAmount, bytes extraData) external +``` +Callback method that gets called after all fund transfers + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| order | struct IOrderMixin.Order | Order being processed | +| extension | bytes | Order extension data | +| orderHash | bytes32 | Hash of the order being processed | +| taker | address | Taker address | +| makingAmount | uint256 | Actual making amount | +| takingAmount | uint256 | Actual taking amount | +| remainingMakingAmount | uint256 | Order remaining making amount | +| extraData | bytes | Extra data | + diff --git a/docs/limit-order-protocol/smart-contract/interfaces/IPreInteraction.md b/docs/limit-order-protocol/smart-contract/interfaces/IPreInteraction.md new file mode 100644 index 000000000..0cbfb3351 --- /dev/null +++ b/docs/limit-order-protocol/smart-contract/interfaces/IPreInteraction.md @@ -0,0 +1,27 @@ + +## IPreInteraction + +### Functions list +- [preInteraction(order, extension, orderHash, taker, makingAmount, takingAmount, remainingMakingAmount, extraData) external](#preinteraction) + +### Functions +### preInteraction + +```solidity +function preInteraction(struct IOrderMixin.Order order, bytes extension, bytes32 orderHash, address taker, uint256 makingAmount, uint256 takingAmount, uint256 remainingMakingAmount, bytes extraData) external +``` +Callback method that gets called before any funds transfers + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| order | struct IOrderMixin.Order | Order being processed | +| extension | bytes | Order extension data | +| orderHash | bytes32 | Hash of the order being processed | +| taker | address | Taker address | +| makingAmount | uint256 | Actual making amount | +| takingAmount | uint256 | Actual taking amount | +| remainingMakingAmount | uint256 | Order remaining making amount | +| extraData | bytes | Extra data | + diff --git a/docs/limit-order-protocol/smart-contract/interfaces/ITakerInteraction.md b/docs/limit-order-protocol/smart-contract/interfaces/ITakerInteraction.md new file mode 100644 index 000000000..baa73e084 --- /dev/null +++ b/docs/limit-order-protocol/smart-contract/interfaces/ITakerInteraction.md @@ -0,0 +1,31 @@ + +## ITakerInteraction + +The order filling steps are `preInteraction` =>` Transfer "maker -> taker"` => **`Interaction`** => `Transfer "taker -> maker"` => `postInteraction` + +### Functions list +- [takerInteraction(order, extension, orderHash, taker, makingAmount, takingAmount, remainingMakingAmount, extraData) external](#takerinteraction) + +### Functions +### takerInteraction + +```solidity +function takerInteraction(struct IOrderMixin.Order order, bytes extension, bytes32 orderHash, address taker, uint256 makingAmount, uint256 takingAmount, uint256 remainingMakingAmount, bytes extraData) external +``` +Callback method that gets called after maker fund transfer but before taker fund transfer + +_This callback allows to interactively handle maker aseets to produce takers assets, doesn't supports ETH as taker assets_ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| order | struct IOrderMixin.Order | Order being processed | +| extension | bytes | Order extension data | +| orderHash | bytes32 | Hash of the order being processed | +| taker | address | Taker address | +| makingAmount | uint256 | Actual making amount | +| takingAmount | uint256 | Actual taking amount | +| remainingMakingAmount | uint256 | Order remaining making amount | +| extraData | bytes | Extra data | + diff --git a/docs/limit-order-protocol/smart-contract/interfaces/IWithdrawable.md b/docs/limit-order-protocol/smart-contract/interfaces/IWithdrawable.md deleted file mode 100644 index ef8d27275..000000000 --- a/docs/limit-order-protocol/smart-contract/interfaces/IWithdrawable.md +++ /dev/null @@ -1,23 +0,0 @@ -# IWithdrawable - - - - - - - -## Functions -### withdraw -```solidity -function withdraw( - uint256 wad -) external -``` - - -#### Parameters: -| Name | Type | Description | -| :--- | :--- | :------------------------------------------------------------------- | -|`wad` | uint256 | - - diff --git a/docs/limit-order-protocol/smart-contract/interfaces/InteractionNotificationReceiver.md b/docs/limit-order-protocol/smart-contract/interfaces/InteractionNotificationReceiver.md deleted file mode 100644 index 4740a3565..000000000 --- a/docs/limit-order-protocol/smart-contract/interfaces/InteractionNotificationReceiver.md +++ /dev/null @@ -1,33 +0,0 @@ -# Interaction - - - - - - - -## Functions -### fillOrderInteraction -```solidity -function fillOrderInteraction( - address taker, - address makerAsset, - address takerAsset, - uint256 makingAmount, - uint256 takingAmount, - bytes interactiveData -) external -``` - - -#### Parameters: -| Name | Type | Description | -| :--- | :--- | :------------------------------------------------------------------- | -|`taker` | address | -|`makerAsset` | address | -|`takerAsset` | address | -|`makingAmount` | uint256 | -|`takingAmount` | uint256 | -|`interactiveData` | bytes | - - diff --git a/docs/limit-order-protocol/smart-contract/interfaces/PostInteractionNotificationReceiver.md b/docs/limit-order-protocol/smart-contract/interfaces/PostInteractionNotificationReceiver.md deleted file mode 100644 index a851d0913..000000000 --- a/docs/limit-order-protocol/smart-contract/interfaces/PostInteractionNotificationReceiver.md +++ /dev/null @@ -1,34 +0,0 @@ -# PostInteraction - - - - - - - -## Functions -### postInteraction -```solidity -function postInteraction( - address taker, - address makerAsset, - address takerAsset, - uint256 makingAmount, - uint256 takingAmount, - bytes interactiveData -) external -``` -Callback method that gets called after taker transferred funds to maker but before -the opposite transfer happened - -#### Parameters: -| Name | Type | Description | -| :--- | :--- | :------------------------------------------------------------------- | -|`taker` | address | -|`makerAsset` | address | -|`takerAsset` | address | -|`makingAmount` | uint256 | -|`takingAmount` | uint256 | -|`interactiveData` | bytes | - - diff --git a/docs/limit-order-protocol/smart-contract/interfaces/PreInteractionNotificationReceiver.md b/docs/limit-order-protocol/smart-contract/interfaces/PreInteractionNotificationReceiver.md deleted file mode 100644 index a80e36908..000000000 --- a/docs/limit-order-protocol/smart-contract/interfaces/PreInteractionNotificationReceiver.md +++ /dev/null @@ -1,33 +0,0 @@ -# PreInteraction - - -Interface for interactor which acts between `maker => taker` and `taker => maker` transfers. - - - - -## Functions -### preInteraction -```solidity -function preInteraction( - address taker, - address makerAsset, - address takerAsset, - uint256 makingAmount, - uint256 takingAmount, - bytes interactiveData -) external -``` - - -#### Parameters: -| Name | Type | Description | -| :--- | :--- | :------------------------------------------------------------------- | -|`taker` | address | -|`makerAsset` | address | -|`takerAsset` | address | -|`makingAmount` | uint256 | -|`takingAmount` | uint256 | -|`interactiveData` | bytes | - - diff --git a/docs/limit-order-protocol/smart-contract/libraries/AmountCalculatorLib.md b/docs/limit-order-protocol/smart-contract/libraries/AmountCalculatorLib.md new file mode 100644 index 000000000..7157b242d --- /dev/null +++ b/docs/limit-order-protocol/smart-contract/libraries/AmountCalculatorLib.md @@ -0,0 +1,34 @@ + +## AmountCalculatorLib + +### Functions list +- [getMakingAmount(orderMakerAmount, orderTakerAmount, swapTakerAmount) internal](#getmakingamount) +- [getTakingAmount(orderMakerAmount, orderTakerAmount, swapMakerAmount) internal](#gettakingamount) + +### Functions +### getMakingAmount + +```solidity +function getMakingAmount(uint256 orderMakerAmount, uint256 orderTakerAmount, uint256 swapTakerAmount) internal pure returns (uint256) +``` +Calculates maker amount + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +[0] | uint256 | Result Floored maker amount | + +### getTakingAmount + +```solidity +function getTakingAmount(uint256 orderMakerAmount, uint256 orderTakerAmount, uint256 swapMakerAmount) internal pure returns (uint256) +``` +Calculates taker amount + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +[0] | uint256 | Result Ceiled taker amount | + diff --git a/docs/limit-order-protocol/smart-contract/libraries/ArgumentsDecoder.md b/docs/limit-order-protocol/smart-contract/libraries/ArgumentsDecoder.md deleted file mode 100644 index 59b8fe690..000000000 --- a/docs/limit-order-protocol/smart-contract/libraries/ArgumentsDecoder.md +++ /dev/null @@ -1,79 +0,0 @@ -# ArgumentsDecoder - - -Library with gas efficient alternatives to `abi.decode` - - - - -## Functions -### decodeUint256Memory -```solidity -function decodeUint256Memory( - bytes data -) internal returns (uint256 value) -``` - - -#### Parameters: -| Name | Type | Description | -| :--- | :--- | :------------------------------------------------------------------- | -|`data` | bytes | - - -### decodeUint256 -```solidity -function decodeUint256( - bytes data -) internal returns (uint256 value) -``` - - -#### Parameters: -| Name | Type | Description | -| :--- | :--- | :------------------------------------------------------------------- | -|`data` | bytes | - - -### decodeBoolMemory -```solidity -function decodeBoolMemory( - bytes data -) internal returns (bool value) -``` - - -#### Parameters: -| Name | Type | Description | -| :--- | :--- | :------------------------------------------------------------------- | -|`data` | bytes | - - -### decodeBool -```solidity -function decodeBool( - bytes data -) internal returns (bool value) -``` - - -#### Parameters: -| Name | Type | Description | -| :--- | :--- | :------------------------------------------------------------------- | -|`data` | bytes | - - -### decodeTargetAndCalldata -```solidity -function decodeTargetAndCalldata( - bytes data -) internal returns (address target, bytes args) -``` - - -#### Parameters: -| Name | Type | Description | -| :--- | :--- | :------------------------------------------------------------------- | -|`data` | bytes | - - diff --git a/docs/limit-order-protocol/smart-contract/libraries/BitInvalidatorLib.md b/docs/limit-order-protocol/smart-contract/libraries/BitInvalidatorLib.md new file mode 100644 index 000000000..29db2139e --- /dev/null +++ b/docs/limit-order-protocol/smart-contract/libraries/BitInvalidatorLib.md @@ -0,0 +1,101 @@ + +## BitInvalidatorLib + +_The library provides a mechanism to invalidate objects based on a bit invalidator. +The bit invalidator holds a mapping where each key represents a slot number and each value contains an integer. +Each bit of the integer represents whether the object with corresponding index is valid or has been invalidated (0 - valid, 1 - invalidated). +The nonce given to access or invalidate an entity's state follows this structure: +- bits [0..7] represent the object state index in the slot. +- bits [8..255] represent the slot number (mapping key)._ + +### Types list +- [Data](#data) + +### Functions list +- [checkSlot(self, nonce) internal](#checkslot) +- [checkAndInvalidate(self, nonce) internal](#checkandinvalidate) +- [massInvalidate(self, nonce, additionalMask) internal](#massinvalidate) + +### Errors list +- [BitInvalidatedOrder() ](#bitinvalidatedorder) + +### Types +### Data + +```solidity +struct Data { + mapping(uint256 => uint256) _raw; +} +``` + +### Functions +### checkSlot + +```solidity +function checkSlot(struct BitInvalidatorLib.Data self, uint256 nonce) internal view returns (uint256) +``` +Retrieves the validity status of entities in a specific slot. + +_Each bit in the returned value corresponds to the validity of an entity. 0 for valid, 1 for invalidated._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BitInvalidatorLib.Data | The data structure. | +| nonce | uint256 | The nonce identifying the slot. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +[0] | uint256 | result The validity status of entities in the slot as a uint256. | + +### checkAndInvalidate + +```solidity +function checkAndInvalidate(struct BitInvalidatorLib.Data self, uint256 nonce) internal +``` +Checks the validity of a specific entity and invalidates it if valid. + +_Throws an error if the entity has already been invalidated._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BitInvalidatorLib.Data | The data structure. | +| nonce | uint256 | The nonce identifying the slot and the entity. | + +### massInvalidate + +```solidity +function massInvalidate(struct BitInvalidatorLib.Data self, uint256 nonce, uint256 additionalMask) internal returns (uint256 result) +``` +Invalidates multiple entities in a single slot. + +_The entities to be invalidated are identified by setting their corresponding bits to 1 in a mask._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BitInvalidatorLib.Data | The data structure. | +| nonce | uint256 | The nonce identifying the slot. | +| additionalMask | uint256 | A mask of bits to be invalidated. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +result | uint256 | Resulting validity status of entities in the slot as a uint256. | + +### Errors +### BitInvalidatedOrder + +```solidity +error BitInvalidatedOrder() +``` + +_The error is thrown when an attempt is made to invalidate an already invalidated entity._ + diff --git a/docs/limit-order-protocol/smart-contract/libraries/Errors.md b/docs/limit-order-protocol/smart-contract/libraries/Errors.md new file mode 100644 index 000000000..364ea6d96 --- /dev/null +++ b/docs/limit-order-protocol/smart-contract/libraries/Errors.md @@ -0,0 +1,20 @@ + +## Errors + +### Errors list +- [InvalidMsgValue() ](#invalidmsgvalue) +- [ETHTransferFailed() ](#ethtransferfailed) + +### Errors +### InvalidMsgValue + +```solidity +error InvalidMsgValue() +``` + +### ETHTransferFailed + +```solidity +error ETHTransferFailed() +``` + diff --git a/docs/limit-order-protocol/smart-contract/libraries/ExtensionLib.md b/docs/limit-order-protocol/smart-contract/libraries/ExtensionLib.md new file mode 100644 index 000000000..19d6722e7 --- /dev/null +++ b/docs/limit-order-protocol/smart-contract/libraries/ExtensionLib.md @@ -0,0 +1,208 @@ + +## ExtensionLib + +Library for retrieving extensions information for the IOrderMixin Interface. + +### Types list +- [DynamicField](#dynamicfield) + +### Functions list +- [makerAssetSuffix(extension) internal](#makerassetsuffix) +- [takerAssetSuffix(extension) internal](#takerassetsuffix) +- [makingAmountData(extension) internal](#makingamountdata) +- [takingAmountData(extension) internal](#takingamountdata) +- [predicate(extension) internal](#predicate) +- [makerPermit(extension) internal](#makerpermit) +- [preInteractionTargetAndData(extension) internal](#preinteractiontargetanddata) +- [postInteractionTargetAndData(extension) internal](#postinteractiontargetanddata) +- [customData(extension) internal](#customdata) + +### Types +### DynamicField + +```solidity +enum DynamicField { + MakerAssetSuffix, + TakerAssetSuffix, + MakingAmountData, + TakingAmountData, + Predicate, + MakerPermit, + PreInteractionData, + PostInteractionData, + CustomData +} +``` + +### Functions +### makerAssetSuffix + +```solidity +function makerAssetSuffix(bytes extension) internal pure returns (bytes) +``` +Returns the MakerAssetSuffix from the provided extension calldata. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| extension | bytes | The calldata from which the MakerAssetSuffix is to be retrieved. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +[0] | bytes | calldata Bytes representing the MakerAssetSuffix. | + +### takerAssetSuffix + +```solidity +function takerAssetSuffix(bytes extension) internal pure returns (bytes) +``` +Returns the TakerAssetSuffix from the provided extension calldata. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| extension | bytes | The calldata from which the TakerAssetSuffix is to be retrieved. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +[0] | bytes | calldata Bytes representing the TakerAssetSuffix. | + +### makingAmountData + +```solidity +function makingAmountData(bytes extension) internal pure returns (bytes) +``` +Returns the MakingAmountData from the provided extension calldata. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| extension | bytes | The calldata from which the MakingAmountData is to be retrieved. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +[0] | bytes | calldata Bytes representing the MakingAmountData. | + +### takingAmountData + +```solidity +function takingAmountData(bytes extension) internal pure returns (bytes) +``` +Returns the TakingAmountData from the provided extension calldata. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| extension | bytes | The calldata from which the TakingAmountData is to be retrieved. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +[0] | bytes | calldata Bytes representing the TakingAmountData. | + +### predicate + +```solidity +function predicate(bytes extension) internal pure returns (bytes) +``` +Returns the order's predicate from the provided extension calldata. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| extension | bytes | The calldata from which the predicate is to be retrieved. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +[0] | bytes | calldata Bytes representing the predicate. | + +### makerPermit + +```solidity +function makerPermit(bytes extension) internal pure returns (bytes) +``` +Returns the maker's permit from the provided extension calldata. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| extension | bytes | The calldata from which the maker's permit is to be retrieved. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +[0] | bytes | calldata Bytes representing the maker's permit. | + +### preInteractionTargetAndData + +```solidity +function preInteractionTargetAndData(bytes extension) internal pure returns (bytes) +``` +Returns the pre-interaction from the provided extension calldata. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| extension | bytes | The calldata from which the pre-interaction is to be retrieved. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +[0] | bytes | calldata Bytes representing the pre-interaction. | + +### postInteractionTargetAndData + +```solidity +function postInteractionTargetAndData(bytes extension) internal pure returns (bytes) +``` +Returns the post-interaction from the provided extension calldata. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| extension | bytes | The calldata from which the post-interaction is to be retrieved. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +[0] | bytes | calldata Bytes representing the post-interaction. | + +### customData + +```solidity +function customData(bytes extension) internal pure returns (bytes) +``` +Returns extra suffix data from the provided extension calldata. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| extension | bytes | The calldata from which the extra suffix data is to be retrieved. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +[0] | bytes | calldata Bytes representing the extra suffix data. | + diff --git a/docs/limit-order-protocol/smart-contract/libraries/MakerTraitsLib.md b/docs/limit-order-protocol/smart-contract/libraries/MakerTraitsLib.md new file mode 100644 index 000000000..7312ed137 --- /dev/null +++ b/docs/limit-order-protocol/smart-contract/libraries/MakerTraitsLib.md @@ -0,0 +1,297 @@ + +## MakerTraits + +## MakerTraitsLib + +A library to manage and check MakerTraits, which are used to encode the maker's preferences for an order in a single uint256. +@dev +The MakerTraits type is a uint256 and different parts of the number are used to encode different traits. +High bits are used for flags +255 bit `NO_PARTIAL_FILLS_FLAG` - if set, the order does not allow partial fills +254 bit `ALLOW_MULTIPLE_FILLS_FLAG` - if set, the order permits multiple fills +253 bit - unused +252 bit `PRE_INTERACTION_CALL_FLAG` - if set, the order requires pre-interaction call +251 bit `POST_INTERACTION_CALL_FLAG` - if set, the order requires post-interaction call +250 bit `NEED_CHECK_EPOCH_MANAGER_FLAG` - if set, the order requires to check the epoch manager +249 bit `HAS_EXTENSION_FLAG` - if set, the order has extension(s) +248 bit `USE_PERMIT2_FLAG` - if set, the order uses permit2 +247 bit `UNWRAP_WETH_FLAG` - if set, the order requires to unwrap WETH + +Low 200 bits are used for allowed sender, expiration, nonceOrEpoch, and series +uint80 last 10 bytes of allowed sender address (0 if any) +uint40 expiration timestamp (0 if none) +uint40 nonce or epoch +uint40 series + +### Functions list +- [hasExtension(makerTraits) internal](#hasextension) +- [isAllowedSender(makerTraits, sender) internal](#isallowedsender) +- [isExpired(makerTraits) internal](#isexpired) +- [nonceOrEpoch(makerTraits) internal](#nonceorepoch) +- [series(makerTraits) internal](#series) +- [allowPartialFills(makerTraits) internal](#allowpartialfills) +- [needPreInteractionCall(makerTraits) internal](#needpreinteractioncall) +- [needPostInteractionCall(makerTraits) internal](#needpostinteractioncall) +- [allowMultipleFills(makerTraits) internal](#allowmultiplefills) +- [useBitInvalidator(makerTraits) internal](#usebitinvalidator) +- [needCheckEpochManager(makerTraits) internal](#needcheckepochmanager) +- [usePermit2(makerTraits) internal](#usepermit2) +- [unwrapWeth(makerTraits) internal](#unwrapweth) + +### Functions +### hasExtension + +```solidity +function hasExtension(MakerTraits makerTraits) internal pure returns (bool) +``` +Checks if the order has the extension flag set. + +_If the `HAS_EXTENSION_FLAG` is set in the makerTraits, then the protocol expects that the order has extension(s)._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| makerTraits | MakerTraits | The traits of the maker. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +[0] | bool | result A boolean indicating whether the flag is set. | + +### isAllowedSender + +```solidity +function isAllowedSender(MakerTraits makerTraits, address sender) internal pure returns (bool) +``` +Checks if the maker allows a specific taker to fill the order. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| makerTraits | MakerTraits | The traits of the maker. | +| sender | address | The address of the taker to be checked. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +[0] | bool | result A boolean indicating whether the taker is allowed. | + +### isExpired + +```solidity +function isExpired(MakerTraits makerTraits) internal view returns (bool) +``` +Checks if the order has expired. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| makerTraits | MakerTraits | The traits of the maker. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +[0] | bool | result A boolean indicating whether the order has expired. | + +### nonceOrEpoch + +```solidity +function nonceOrEpoch(MakerTraits makerTraits) internal pure returns (uint256) +``` +Returns the nonce or epoch of the order. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| makerTraits | MakerTraits | The traits of the maker. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +[0] | uint256 | result The nonce or epoch of the order. | + +### series + +```solidity +function series(MakerTraits makerTraits) internal pure returns (uint256) +``` +Returns the series of the order. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| makerTraits | MakerTraits | The traits of the maker. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +[0] | uint256 | result The series of the order. | + +### allowPartialFills + +```solidity +function allowPartialFills(MakerTraits makerTraits) internal pure returns (bool) +``` +Determines if the order allows partial fills. + +_If the _NO_PARTIAL_FILLS_FLAG is not set in the makerTraits, then the order allows partial fills._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| makerTraits | MakerTraits | The traits of the maker, determining their preferences for the order. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +[0] | bool | result A boolean indicating whether the maker allows partial fills. | + +### needPreInteractionCall + +```solidity +function needPreInteractionCall(MakerTraits makerTraits) internal pure returns (bool) +``` +Checks if the maker needs pre-interaction call. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| makerTraits | MakerTraits | The traits of the maker. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +[0] | bool | result A boolean indicating whether the maker needs a pre-interaction call. | + +### needPostInteractionCall + +```solidity +function needPostInteractionCall(MakerTraits makerTraits) internal pure returns (bool) +``` +Checks if the maker needs post-interaction call. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| makerTraits | MakerTraits | The traits of the maker. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +[0] | bool | result A boolean indicating whether the maker needs a post-interaction call. | + +### allowMultipleFills + +```solidity +function allowMultipleFills(MakerTraits makerTraits) internal pure returns (bool) +``` +Determines if the order allows multiple fills. + +_If the _ALLOW_MULTIPLE_FILLS_FLAG is set in the makerTraits, then the maker allows multiple fills._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| makerTraits | MakerTraits | The traits of the maker, determining their preferences for the order. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +[0] | bool | result A boolean indicating whether the maker allows multiple fills. | + +### useBitInvalidator + +```solidity +function useBitInvalidator(MakerTraits makerTraits) internal pure returns (bool) +``` +Determines if an order should use the bit invalidator or remaining amount validator. + +_The bit invalidator can be used if the order does not allow partial or multiple fills._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| makerTraits | MakerTraits | The traits of the maker, determining their preferences for the order. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +[0] | bool | result A boolean indicating whether the bit invalidator should be used. True if the order requires the use of the bit invalidator. | + +### needCheckEpochManager + +```solidity +function needCheckEpochManager(MakerTraits makerTraits) internal pure returns (bool) +``` +Checks if the maker needs to check the epoch. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| makerTraits | MakerTraits | The traits of the maker. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +[0] | bool | result A boolean indicating whether the maker needs to check the epoch manager. | + +### usePermit2 + +```solidity +function usePermit2(MakerTraits makerTraits) internal pure returns (bool) +``` +Checks if the maker uses permit2. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| makerTraits | MakerTraits | The traits of the maker. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +[0] | bool | result A boolean indicating whether the maker uses permit2. | + +### unwrapWeth + +```solidity +function unwrapWeth(MakerTraits makerTraits) internal pure returns (bool) +``` +Checks if the maker needs to unwraps WETH. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| makerTraits | MakerTraits | The traits of the maker. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +[0] | bool | result A boolean indicating whether the maker needs to unwrap WETH. | + diff --git a/docs/limit-order-protocol/smart-contract/libraries/OffsetsLib.md b/docs/limit-order-protocol/smart-contract/libraries/OffsetsLib.md new file mode 100644 index 000000000..c00a466f8 --- /dev/null +++ b/docs/limit-order-protocol/smart-contract/libraries/OffsetsLib.md @@ -0,0 +1,49 @@ + +## Offsets + +## OffsetsLib + +_A library for retrieving values by offsets from a concatenated calldata._ + +### Functions list +- [get(offsets, concat, index) internal](#get) + +### Errors list +- [OffsetOutOfBounds() ](#offsetoutofbounds) + +### Functions +### get + +```solidity +function get(Offsets offsets, bytes concat, uint256 index) internal pure returns (bytes result) +``` +Retrieves the field value calldata corresponding to the provided field index from the concatenated calldata. + +_The function performs the following steps: +1. Retrieve the start and end of the segment corresponding to the provided index from the offsets array. +2. Get the value from segment using offset and length calculated based on the start and end of the segment. +3. Throw `OffsetOutOfBounds` error if the length of the segment is greater than the length of the concatenated data._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| offsets | Offsets | The offsets encoding the start and end of each segment within the concatenated calldata. | +| concat | bytes | The concatenated calldata. | +| index | uint256 | The index of the segment to retrieve. The field index 0 corresponds to the lowest bytes of the offsets array. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +result | bytes | The calldata from a segment of the concatenated calldata corresponding to the provided index. | + +### Errors +### OffsetOutOfBounds + +```solidity +error OffsetOutOfBounds() +``` + +_Error to be thrown when the offset is out of bounds._ + diff --git a/docs/limit-order-protocol/smart-contract/libraries/Permitable.md b/docs/limit-order-protocol/smart-contract/libraries/Permitable.md deleted file mode 100644 index 63aa4e5e6..000000000 --- a/docs/limit-order-protocol/smart-contract/libraries/Permitable.md +++ /dev/null @@ -1,25 +0,0 @@ -# Permitable - - -Base contract with common permit handling logics - - - - -## Functions -### _permit -```solidity -function _permit( - address token, - bytes permit -) internal -``` - - -#### Parameters: -| Name | Type | Description | -| :--- | :--- | :------------------------------------------------------------------- | -|`token` | address | -|`permit` | bytes | - - diff --git a/docs/limit-order-protocol/smart-contract/libraries/RemainingInvalidatorLib.md b/docs/limit-order-protocol/smart-contract/libraries/RemainingInvalidatorLib.md new file mode 100644 index 000000000..c73e40aef --- /dev/null +++ b/docs/limit-order-protocol/smart-contract/libraries/RemainingInvalidatorLib.md @@ -0,0 +1,126 @@ + +## RemainingInvalidator + +## RemainingInvalidatorLib + +The library provides a mechanism to invalidate order based on the remaining amount of the order. + +_The remaining amount is used as a nonce to invalidate the order. +When order is created, the remaining invalidator is 0. +When order is filled, the remaining invalidator is the inverse of the remaining amount._ + +### Functions list +- [isNewOrder(invalidator) internal](#isneworder) +- [remaining(invalidator) internal](#remaining) +- [remaining(invalidator, orderMakerAmount) internal](#remaining) +- [remains(remainingMakingAmount, makingAmount) internal](#remains) +- [fullyFilled() internal](#fullyfilled) + +### Errors list +- [RemainingInvalidatedOrder() ](#remaininginvalidatedorder) + +### Functions +### isNewOrder + +```solidity +function isNewOrder(RemainingInvalidator invalidator) internal pure returns (bool) +``` +Checks if an order is new based on the invalidator value. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| invalidator | RemainingInvalidator | The remaining invalidator of the order. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +[0] | bool | result Whether the order is new or not. | + +### remaining + +```solidity +function remaining(RemainingInvalidator invalidator) internal pure returns (uint256) +``` +Retrieves the remaining amount for an order. + +_If the order is unknown, a RemainingInvalidatedOrder error is thrown._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| invalidator | RemainingInvalidator | The remaining invalidator for the order. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +[0] | uint256 | result The remaining amount for the order. | + +### remaining + +```solidity +function remaining(RemainingInvalidator invalidator, uint256 orderMakerAmount) internal pure returns (uint256) +``` +Calculates the remaining amount for an order. + +_If the order is unknown, the order maker amount is returned._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| invalidator | RemainingInvalidator | The remaining invalidator for the order. | +| orderMakerAmount | uint256 | The amount to return if the order is new. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +[0] | uint256 | result The remaining amount for the order. | + +### remains + +```solidity +function remains(uint256 remainingMakingAmount, uint256 makingAmount) internal pure returns (RemainingInvalidator) +``` +Calculates the remaining invalidator of the order. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| remainingMakingAmount | uint256 | The remaining making amount of the order. | +| makingAmount | uint256 | The making amount of the order. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +[0] | RemainingInvalidator | result The remaining invalidator for the order. | + +### fullyFilled + +```solidity +function fullyFilled() internal pure returns (RemainingInvalidator) +``` +Provides the remaining invalidator for a fully filled order. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +[0] | RemainingInvalidator | result The remaining invalidator for a fully filled order. | + +### Errors +### RemainingInvalidatedOrder + +```solidity +error RemainingInvalidatedOrder() +``` + +_The error is thrown when an attempt is made to invalidate an already invalidated entity._ + diff --git a/docs/limit-order-protocol/smart-contract/libraries/RevertReasonParser.md b/docs/limit-order-protocol/smart-contract/libraries/RevertReasonParser.md deleted file mode 100644 index aef80a55b..000000000 --- a/docs/limit-order-protocol/smart-contract/libraries/RevertReasonParser.md +++ /dev/null @@ -1,30 +0,0 @@ -# RevertReasonParser - - -Library that allows to parse unsuccessful arbitrary calls revert reasons. -See https://solidity.readthedocs.io/en/latest/control-structures.html#revert for details. -Note that we assume revert reason being abi-encoded as Error(string) so it may fail to parse reason -if structured reverts appear in the future. - -All unsuccessful parsings get encoded as Unknown(data) string - - - - -## Functions -### parse -```solidity -function parse( - bytes data, - string prefix -) internal returns (string) -``` - - -#### Parameters: -| Name | Type | Description | -| :--- | :--- | :------------------------------------------------------------------- | -|`data` | bytes | -|`prefix` | string | - - diff --git a/docs/limit-order-protocol/smart-contract/libraries/TakerTraitsLib.md b/docs/limit-order-protocol/smart-contract/libraries/TakerTraitsLib.md new file mode 100644 index 000000000..c1412ac5b --- /dev/null +++ b/docs/limit-order-protocol/smart-contract/libraries/TakerTraitsLib.md @@ -0,0 +1,182 @@ + +## TakerTraits + +## TakerTraitsLib + +This library to manage and check TakerTraits, which are used to encode the taker's preferences for an order in a single uint256. + +_The TakerTraits are structured as follows: +High bits are used for flags +255 bit `_MAKER_AMOUNT_FLAG` - If set, the taking amount is calculated based on making amount, otherwise making amount is calculated based on taking amount. +254 bit `_UNWRAP_WETH_FLAG` - If set, the WETH will be unwrapped into ETH before sending to taker. +253 bit `_SKIP_ORDER_PERMIT_FLAG` - If set, the order skips maker's permit execution. +252 bit `_USE_PERMIT2_FLAG` - If set, the order uses the permit2 function for authorization. +251 bit `_ARGS_HAS_TARGET` - If set, then first 20 bytes of args are treated as target address for maker’s funds transfer. +224-247 bits `ARGS_EXTENSION_LENGTH` - The length of the extension calldata in the args. +200-223 bits `ARGS_INTERACTION_LENGTH` - The length of the interaction calldata in the args. +0-184 bits - The threshold amount (the maximum amount a taker agrees to give in exchange for a making amount)._ + +### Functions list +- [argsHasTarget(takerTraits) internal](#argshastarget) +- [argsExtensionLength(takerTraits) internal](#argsextensionlength) +- [argsInteractionLength(takerTraits) internal](#argsinteractionlength) +- [isMakingAmount(takerTraits) internal](#ismakingamount) +- [unwrapWeth(takerTraits) internal](#unwrapweth) +- [skipMakerPermit(takerTraits) internal](#skipmakerpermit) +- [usePermit2(takerTraits) internal](#usepermit2) +- [threshold(takerTraits) internal](#threshold) + +### Functions +### argsHasTarget + +```solidity +function argsHasTarget(TakerTraits takerTraits) internal pure returns (bool) +``` +Checks if the args should contain target address. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| takerTraits | TakerTraits | The traits of the taker. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +[0] | bool | result A boolean indicating whether the args should contain target address. | + +### argsExtensionLength + +```solidity +function argsExtensionLength(TakerTraits takerTraits) internal pure returns (uint256) +``` +Retrieves the length of the extension calldata from the takerTraits. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| takerTraits | TakerTraits | The traits of the taker. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +[0] | uint256 | result The length of the extension calldata encoded in the takerTraits. | + +### argsInteractionLength + +```solidity +function argsInteractionLength(TakerTraits takerTraits) internal pure returns (uint256) +``` +Retrieves the length of the interaction calldata from the takerTraits. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| takerTraits | TakerTraits | The traits of the taker. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +[0] | uint256 | result The length of the interaction calldata encoded in the takerTraits. | + +### isMakingAmount + +```solidity +function isMakingAmount(TakerTraits takerTraits) internal pure returns (bool) +``` +Checks if the taking amount should be calculated based on making amount. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| takerTraits | TakerTraits | The traits of the taker. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +[0] | bool | result A boolean indicating whether the taking amount should be calculated based on making amount. | + +### unwrapWeth + +```solidity +function unwrapWeth(TakerTraits takerTraits) internal pure returns (bool) +``` +Checks if the order should unwrap WETH and send ETH to taker. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| takerTraits | TakerTraits | The traits of the taker. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +[0] | bool | result A boolean indicating whether the order should unwrap WETH. | + +### skipMakerPermit + +```solidity +function skipMakerPermit(TakerTraits takerTraits) internal pure returns (bool) +``` +Checks if the order should skip maker's permit execution. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| takerTraits | TakerTraits | The traits of the taker. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +[0] | bool | result A boolean indicating whether the order don't apply permit. | + +### usePermit2 + +```solidity +function usePermit2(TakerTraits takerTraits) internal pure returns (bool) +``` +Checks if the order uses the permit2 instead of permit. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| takerTraits | TakerTraits | The traits of the taker. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +[0] | bool | result A boolean indicating whether the order uses the permit2. | + +### threshold + +```solidity +function threshold(TakerTraits takerTraits) internal pure returns (uint256) +``` +Retrieves the threshold amount from the takerTraits. +The maximum amount a taker agrees to give in exchange for a making amount. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| takerTraits | TakerTraits | The traits of the taker. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +[0] | uint256 | result The threshold amount encoded in the takerTraits. | +