From 9df26634fda0c35bb13a5138f34c238640761de3 Mon Sep 17 00:00:00 2001 From: lash Date: Thu, 3 Aug 2023 10:27:05 +0100 Subject: [PATCH] Add tokenlimit interface --- README.md | 76 ++++++++++++++++++++++++++++----- doc/texinfo/expire.sol.texi | 2 +- doc/texinfo/overview.texi | 2 + doc/texinfo/tokenlimit.sol.texi | 18 ++++++++ doc/texinfo/tokenswap.sol.texi | 26 ++++++++++- python/README.md | 76 ++++++++++++++++++++++++++++----- solidity/TokenLimit.sol | 9 ++++ solidity/TokenSwap.sol | 18 +++++--- 8 files changed, 196 insertions(+), 31 deletions(-) create mode 100644 doc/texinfo/tokenlimit.sol.texi create mode 100644 solidity/TokenLimit.sol diff --git a/README.md b/README.md index 6ff8053..9af02ee 100644 --- a/README.md +++ b/README.md @@ -287,7 +287,7 @@ digest *must* succeed with the default encoding. ### Expire -Defines an expiry time after which token balances or supply *cannot +Defines an expiry time after which token balances and supply *cannot change*. A contract defining an expiry *must not* allow changing the expiration @@ -632,6 +632,25 @@ Use cases of sealing include: +### TokenLimit + +Define limits of value amounts of tokens that individual addresses can +hold. + +#### ERC165 Interface identifier + +23778613 + +#### Solidity interface definition + + interface ITokenLimit { + function limitOf(address _token, address _holder) external view returns(uint256); + } + +#### Reference implementations + +- + ### TokenRateChange Enables detection of properties for CIC tokens that change value over @@ -676,38 +695,73 @@ b716af03 ### TokenSwap -Token swap interface that can fit token escrow aswell as token swap -contracts. +Token swap interface that can fit token escrow purposes aswell as token +swap contracts. + +Optionally may define a `defaultToken`, that may among other things be +used for `withdraw()` calls without an `inToken`. + +An explicit *ERC20 approval* of the balance to be transacted will +usually be required for the implementing contract. + +If the value 0 is passed as argument to `deposit` or `withdraw`, +implementers can choose one of two possible outcomes: + +- Noop. 0 *must* be returned. + +- Use *balance* or the max available *allowance*. The actual (spent) + value *must* be returned. #### ERC165 Interface identifier -9e2d0236 +4146b765 #### Solidity interface definition interface ITokenSwap { - // Add inToken liquidity of the full balance of the sender - // Requires token approval for the balance. - function deposit(address _inToken) external returns (uint256); + // Emitted when a new deposit has been made. + event Deposit(address indexed _token, uint256 _value); + + // Default token used to access the token swap. + // Returns zero-address if no default token is defined. + function defaultToken() external returns (address); // Add inToken liquidity to the tune of given value. // Requires token approval for the corresponding value. + // If value is 0, up to the full approval MAY be used for the transfer. function deposit(address _inToken, uint256 _value) external returns (uint256); - // Withdraw any pending outToken balance in the pool for the sender. - function withdraw(address _outToken) external returns (uint256); - // Withdraw pending outToken balance of given value in the pool for the sender. + // May require token approval for defaultToken if used by contract as exchange for the withdrawal. + // If value is 0, up to the full approval value MAY be used for the transfer. function withdraw(address _outToken, uint256 _value) external returns (uint256); // Exchange inToken equalling given value for outToken. // Requires token approval for the value of inToken. + // If value is 0, up to the full approval value MAY be used for the transfer. function withdraw(address _outToken, address _inToken, uint256 _value) external returns (uint256); } #### Reference implementations -- +- + +#### Handling deposits + +The implementation is free to decide whether deposits can be recovered +directly, or if they will be locked in the smart contract - temporarily +or permanently. + +For the duration deposits are locked, they are part of the smart +contract’s swap liquidity. During this time, locked deposits may only be +withdrawn in exchange for other tokens accepted by the contract. + +Deposits that are not locked should be withdrawable using the +`withdraw(address,uint256)` (`0xf3fef3a3`) method signature. + +Of course, as with most swap contracts, the tokens available for +withdrawal by the holder may not necessarily match the tokens that were +deposited by the holder. ### TokenVote diff --git a/doc/texinfo/expire.sol.texi b/doc/texinfo/expire.sol.texi index f300672..238c309 100644 --- a/doc/texinfo/expire.sol.texi +++ b/doc/texinfo/expire.sol.texi @@ -1,6 +1,6 @@ @subsection Expire -Defines an expiry time after which token balances or supply @emph{cannot change}. +Defines an expiry time after which token balances and supply @emph{cannot change}. A contract defining an expiry @emph{must not} allow changing the expiration time to a time in the past. diff --git a/doc/texinfo/overview.texi b/doc/texinfo/overview.texi index b2c0604..846375a 100644 --- a/doc/texinfo/overview.texi +++ b/doc/texinfo/overview.texi @@ -74,6 +74,8 @@ The following well-known solidity interfaces are partially implemented in CIC na @include seal.sol.texi +@include tokenlimit.sol.texi + @include tokenratechange.sol.texi @include tokenswap.sol.texi diff --git a/doc/texinfo/tokenlimit.sol.texi b/doc/texinfo/tokenlimit.sol.texi new file mode 100644 index 0000000..8aa45ba --- /dev/null +++ b/doc/texinfo/tokenlimit.sol.texi @@ -0,0 +1,18 @@ +@subsection TokenLimit + +Define limits of value amounts of tokens that individual addresses can hold. + +@subsubsection ERC165 Interface identifier + +@include ../../build/TokenLimit.interface + +@subsubsection Solidity interface definition + +@include ../../build/contract_TokenLimit.texi + +@subsubsection Reference implementations + +@itemize +@item +@uref{git://holbrook.no/erc20-limiter.git,} +@end itemize diff --git a/doc/texinfo/tokenswap.sol.texi b/doc/texinfo/tokenswap.sol.texi index 33267d5..f950e75 100644 --- a/doc/texinfo/tokenswap.sol.texi +++ b/doc/texinfo/tokenswap.sol.texi @@ -1,6 +1,17 @@ @subsection TokenSwap -Token swap interface that can fit token escrow aswell as token swap contracts. +Token swap interface that can fit token escrow purposes aswell as token swap contracts. + +Optionally may define a @code{defaultToken}, that may among other things be used for @code{withdraw()} calls without an @code{inToken}. + +An explicit @emph{ERC20 approval} of the balance to be transacted will usually be required for the implementing contract. + +If the value 0 is passed as argument to @code{deposit} or @code{withdraw}, implementers can choose one of two possible outcomes: + +@itemize +@item Noop. 0 @emph{must} be returned. +@item Use @emph{balance} or the max available @emph{allowance}. The actual (spent) value @emph{must} be returned. +@end itemize @subsubsection ERC165 Interface identifier @@ -14,5 +25,16 @@ Token swap interface that can fit token escrow aswell as token swap contracts. @itemize @item -@uref{git://holbrook.no/erc20-vend.git,} +@uref{git://holbrook.no/erc20-pool.git,} @end itemize + + +@subsubsection Handling deposits + +The implementation is free to decide whether deposits can be recovered directly, or if they will be locked in the smart contract - temporarily or permanently. + +For the duration deposits are locked, they are part of the smart contract's swap liquidity. During this time, locked deposits may only be withdrawn in exchange for other tokens accepted by the contract. + +Deposits that are not locked should be withdrawable using the @code{withdraw(address,uint256)} (@code{0xf3fef3a3}) method signature. + +Of course, as with most swap contracts, the tokens available for withdrawal by the holder may not necessarily match the tokens that were deposited by the holder. diff --git a/python/README.md b/python/README.md index 6ff8053..9af02ee 100644 --- a/python/README.md +++ b/python/README.md @@ -287,7 +287,7 @@ digest *must* succeed with the default encoding. ### Expire -Defines an expiry time after which token balances or supply *cannot +Defines an expiry time after which token balances and supply *cannot change*. A contract defining an expiry *must not* allow changing the expiration @@ -632,6 +632,25 @@ Use cases of sealing include: +### TokenLimit + +Define limits of value amounts of tokens that individual addresses can +hold. + +#### ERC165 Interface identifier + +23778613 + +#### Solidity interface definition + + interface ITokenLimit { + function limitOf(address _token, address _holder) external view returns(uint256); + } + +#### Reference implementations + +- + ### TokenRateChange Enables detection of properties for CIC tokens that change value over @@ -676,38 +695,73 @@ b716af03 ### TokenSwap -Token swap interface that can fit token escrow aswell as token swap -contracts. +Token swap interface that can fit token escrow purposes aswell as token +swap contracts. + +Optionally may define a `defaultToken`, that may among other things be +used for `withdraw()` calls without an `inToken`. + +An explicit *ERC20 approval* of the balance to be transacted will +usually be required for the implementing contract. + +If the value 0 is passed as argument to `deposit` or `withdraw`, +implementers can choose one of two possible outcomes: + +- Noop. 0 *must* be returned. + +- Use *balance* or the max available *allowance*. The actual (spent) + value *must* be returned. #### ERC165 Interface identifier -9e2d0236 +4146b765 #### Solidity interface definition interface ITokenSwap { - // Add inToken liquidity of the full balance of the sender - // Requires token approval for the balance. - function deposit(address _inToken) external returns (uint256); + // Emitted when a new deposit has been made. + event Deposit(address indexed _token, uint256 _value); + + // Default token used to access the token swap. + // Returns zero-address if no default token is defined. + function defaultToken() external returns (address); // Add inToken liquidity to the tune of given value. // Requires token approval for the corresponding value. + // If value is 0, up to the full approval MAY be used for the transfer. function deposit(address _inToken, uint256 _value) external returns (uint256); - // Withdraw any pending outToken balance in the pool for the sender. - function withdraw(address _outToken) external returns (uint256); - // Withdraw pending outToken balance of given value in the pool for the sender. + // May require token approval for defaultToken if used by contract as exchange for the withdrawal. + // If value is 0, up to the full approval value MAY be used for the transfer. function withdraw(address _outToken, uint256 _value) external returns (uint256); // Exchange inToken equalling given value for outToken. // Requires token approval for the value of inToken. + // If value is 0, up to the full approval value MAY be used for the transfer. function withdraw(address _outToken, address _inToken, uint256 _value) external returns (uint256); } #### Reference implementations -- +- + +#### Handling deposits + +The implementation is free to decide whether deposits can be recovered +directly, or if they will be locked in the smart contract - temporarily +or permanently. + +For the duration deposits are locked, they are part of the smart +contract’s swap liquidity. During this time, locked deposits may only be +withdrawn in exchange for other tokens accepted by the contract. + +Deposits that are not locked should be withdrawable using the +`withdraw(address,uint256)` (`0xf3fef3a3`) method signature. + +Of course, as with most swap contracts, the tokens available for +withdrawal by the holder may not necessarily match the tokens that were +deposited by the holder. ### TokenVote diff --git a/solidity/TokenLimit.sol b/solidity/TokenLimit.sol new file mode 100644 index 0000000..32a8083 --- /dev/null +++ b/solidity/TokenLimit.sol @@ -0,0 +1,9 @@ +pragma solidity >=0.6.12; + +// Author: Louis Holbrook 0826EDA1702D1E87C6E2875121D2E7BB88C2A746 +// SPDX-License-Identifier: AGPL-3.0-or-later +// File-version: 1 + +interface ITokenLimit { + function limitOf(address _token, address _holder) external view returns(uint256); +} diff --git a/solidity/TokenSwap.sol b/solidity/TokenSwap.sol index 52d3641..641dbd1 100644 --- a/solidity/TokenSwap.sol +++ b/solidity/TokenSwap.sol @@ -4,22 +4,28 @@ pragma solidity >=0.6.12; // SPDX-License-Identifier: AGPL-3.0-or-later // File-version: 1 +// Methods for swapping tokens for each other. + interface ITokenSwap { - // Add inToken liquidity of the full balance of the sender - // Requires token approval for the balance. - function deposit(address _inToken) external returns (uint256); + // Emitted when a new deposit has been made. + event Deposit(address indexed _token, uint256 _value); + + // Default token used to access the token swap. + // Returns zero-address if no default token is defined. + function defaultToken() external returns (address); // Add inToken liquidity to the tune of given value. // Requires token approval for the corresponding value. + // If value is 0, up to the full approval MAY be used for the transfer. function deposit(address _inToken, uint256 _value) external returns (uint256); - // Withdraw any pending outToken balance in the pool for the sender. - function withdraw(address _outToken) external returns (uint256); - // Withdraw pending outToken balance of given value in the pool for the sender. + // May require token approval for defaultToken if used by contract as exchange for the withdrawal. + // If value is 0, up to the full approval value MAY be used for the transfer. function withdraw(address _outToken, uint256 _value) external returns (uint256); // Exchange inToken equalling given value for outToken. // Requires token approval for the value of inToken. + // If value is 0, up to the full approval value MAY be used for the transfer. function withdraw(address _outToken, address _inToken, uint256 _value) external returns (uint256); }