Add tokenlimit interface

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
-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
 
-- <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