Add tokenlimit interface

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:
 
 <https://git.grassecon.net/cicnet/erc20-demurrage-token.git>
 
+### 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
+
+- <git://holbrook.no/erc20-limiter.git>
+
 ### 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
+Token swap interface that can fit token escrow purposes aswell as token
-contracts.
+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
+        // Emitted when a new deposit has been made.
-        // Requires token approval for the balance.
+        event Deposit(address indexed _token, uint256 _value);
-        function deposit(address _inToken) external returns (uint256);
+
+        // 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
 
-- <git://holbrook.no/erc20-vend.git>
+- <git://holbrook.no/erc20-pool.git>
+
+#### 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
 

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.
 

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

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

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.

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:
 
 <https://git.grassecon.net/cicnet/erc20-demurrage-token.git>
 
+### 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
+
+- <git://holbrook.no/erc20-limiter.git>
+
 ### 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
+Token swap interface that can fit token escrow purposes aswell as token
-contracts.
+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
+        // Emitted when a new deposit has been made.
-        // Requires token approval for the balance.
+        event Deposit(address indexed _token, uint256 _value);
-        function deposit(address _inToken) external returns (uint256);
+
+        // 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
 
-- <git://holbrook.no/erc20-vend.git>
+- <git://holbrook.no/erc20-pool.git>
+
+#### 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
 

solidity/TokenLimit.sol

@@ -0,0 +1,9 @@
+pragma solidity >=0.6.12;
+
+// Author:	Louis Holbrook <dev@holbrook.no> 0826EDA1702D1E87C6E2875121D2E7BB88C2A746
+// SPDX-License-Identifier:	AGPL-3.0-or-later
+// File-version: 1
+
+interface ITokenLimit {
+	function limitOf(address _token, address _holder) external view returns(uint256);
+}

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
+	// Emitted when a new deposit has been made.
-	// Requires token approval for the balance.
+	event Deposit(address indexed _token, uint256 _value);
-	function deposit(address _inToken) external returns (uint256);
+
+	// 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);
 }