Add tokenquote interface

Signed-off-by: lash <dev@holbrook.no>

README.md

@@ -61,10 +61,12 @@ matching `address(0x00)` should be skipped, and not counted towards
 
 May optionally record time when account was added.
 
-ERC165 Interface identifier  
+#### ERC165 Interface identifier
+
 b7bca625
 
-Solidity interface definition  
+#### Solidity interface definition
+
     interface IAccountsIndex {
         // Address added to store, index in array.
         event AddressAdded(uint256 indexed _idx, address _account);
@@ -88,7 +90,8 @@ Solidity interface definition
         function time(address) external view returns (uint256);
     }
 
-Reference implementation  
+#### Reference implementation
+
 <git://holbrook.no/eth-accounts-index.git> (v0.5.1)
 
 ### Accounts Index Mutable
@@ -99,10 +102,12 @@ address list.
 Addresses may be *added*, *removed*, aswell as *deactivated* and
 *activated*. Deactivated accounts still count towards the `entryCount`.
 
-ERC165 Interface identifier  
+#### ERC165 Interface identifier
+
 9479f0ae
 
-Solidity interface definition  
+#### Solidity interface definition
+
     interface IAccountsIndexMutable {
         // Active status of address changed, and by whom changed.
         event AddressActive(address indexed _account, bool _active);
@@ -123,7 +128,8 @@ Solidity interface definition
         function isActive(address) external view returns (bool);
     }
 
-Reference implementation  
+#### Reference implementation
+
 <git://holbrook.no/eth-accounts-index.git> (v0.5.1)
 
 ### Burner
@@ -132,10 +138,12 @@ Attached to `ERC20` and `ERC721` tokens that may be *burned*.
 
 Implements the `burn(...)` part of `ERC5679` for interoperability.
 
-ERC165 Interface identifier  
-bc4babdd
+#### ERC165 Interface identifier
+
+b1110c1b
+
+#### Solidity interface definition
 
-Solidity interface definition  
     interface IBurner {
         // Token(s) successfully burned; by who and how much.
         event Burn(address indexed _burner, uint256 _burned);
@@ -144,10 +152,11 @@ Solidity interface definition
         function burn(address _from, uint256 _amount, bytes calldata _data) external;
 
         // Burn given amount of tokens held by signer.
-        function burn(uint256 _burn) external returns (bool);
+        function burn(uint256 _amount) external returns (bool);
 
         // Burn all tokens held by signer.
-        function burn() external returns (bool);
+        // Returns the amount of tokens burned.
+        function burn() external returns (uint256);
 
         // Total amount of tokens that have been burned.
         function totalBurned() external returns (uint256);
@@ -157,7 +166,8 @@ Solidity interface definition
         function totalMinted() external returns (uint256);
     }
 
-Example implementation  
+#### Example implementation
+
 <https://git.grassecon.net/cicnet/erc20-demurrage-token.git>
 
 ### Chrono
@@ -166,17 +176,20 @@ Define a creation time for a resource.
 
 Complements `ERC5007`.
 
-ERC165 Interface identifier  
+#### ERC165 Interface identifier
+
 4db1ccd4
 
-Solidity interface definition  
+#### Solidity interface definition
+
     interface IChrono {
         // Returns the timestamp of when a resource corresponding to _idx was first created.
         // int64 chosen as return value for simpler interoperability with ERC5007.
         function createTime(uint256 _idx) external returns(int64);
     }
 
-Example implementation  
+#### Example implementation
+
 <https://git.defalsify.org/eth-erc721> (BadgeToken contract)
 
 ### Declarator
@@ -196,10 +209,12 @@ Any number of claims can be made about an address under any number of
 topics. All claims must be stored, and returned in the order which they
 were added.
 
-ERC165 Interface identifier  
+#### ERC165 Interface identifier
+
 21b7493b
 
-Solidity interface definition  
+#### Solidity interface definition
+
     interface IDeclarator {
         event DeclarationAdded(address indexed _declarator, address indexed _subject, bytes32 indexed _topic, bytes32 _proof);
         
@@ -228,7 +243,8 @@ Solidity interface definition
         function declaratorCount(address _subject) external view returns ( uint256 );
     }
 
-Reference implementation  
+#### Reference implementation
+
 <git://holbrook.no/eth-address-index.git>
 
 ### Digest
@@ -241,10 +257,12 @@ Primary use-case is the abstraction of self-describing
 A default encoding *must* always be defined, and the encoding of a valid
 digest *must* succeed with the default encoding.
 
-ERC165 Interface identifier  
+#### ERC165 Interface identifier
+
 982ab05d
 
-Solidity interface definition  
+#### Solidity interface definition
+
     interface IDigest {
         // Returns the default digest encoding used by the contract instance.
         function defaultDigestEncoding() external view returns (uint256 _encoding);
@@ -263,21 +281,24 @@ Solidity interface definition
         function encodeDigest(bytes memory _data) external view returns (bytes memory);
     }
 
-Example implementation  
+#### Example implementation
+
 <git://holbrook.no/eth-event-msg.git>
 
 ### 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
 time to a time in the past.
 
-ERC165 Interface identifier  
+#### ERC165 Interface identifier
+
 841a0e94
 
-Solidity interface definition  
+#### Solidity interface definition
+
     interface IExpire {
         // Contract has expired.
         event Expired(uint256 _timestamp);
@@ -296,7 +317,8 @@ Solidity interface definition
         function applyExpiry() external returns(uint8);
     }
 
-Example implementation  
+#### Example implementation
+
 <https://git.grassecon.net/cicnet/erc20-demurrage-token.git>
 
 ### Faucet
@@ -331,10 +353,12 @@ amount to dispense.
 The *check(address)* contract call *must* evaluate all four criteria,
 and *must* return `false` if any of the criteria are not met.
 
-ERC165 Interface identifier  
+#### ERC165 Interface identifier
+
 1a3ac634
 
-Solidity interface definition  
+#### Solidity interface definition
+
     interface IFaucet {
         // Tokens were given to an address
         event Give(address indexed _recipient, address indexed _token, uint256 _value);
@@ -369,7 +393,8 @@ Solidity interface definition
         function nextBalance(address _recipient) external returns (uint256);
     }
 
-Reference implementations  
+#### Reference implementations
+
 - <git://holbrook.no/erc20-faucet.git>
 
 - <git://holbrook.no/eth-faucet.git>
@@ -388,10 +413,12 @@ the content address.
 Furthermore, it *should* be possible to refer to a resource by a
 fully-qualified location on the web or an overlay network (e.g. tor).
 
-ERC165 Interface identifier  
+#### ERC165 Interface identifier
+
 ed75b333
 
-Solidity interface definition  
+#### Solidity interface definition
+
     interface ILocator {
         // URI that may or may not point to a specific resource location.
         function toURI(bytes memory _data) external view returns (string memory);
@@ -400,10 +427,11 @@ Solidity interface definition
         function toURL(bytes memory _data) external view returns(string memory);
     }
 
-Example implementation  
+#### Example implementation
+
 <git://holbrook.no/eth-event-msg.git>
 
-#### Expressing locators in terms of numetic token id
+#### Expressing locators in terms of numeric token id
 
 Given the numeric token id `1234567890987654321` (`0x112210f4b16c1cb1`
 hex), and a base url `https://contentgateway.grassecon.net`, the result
@@ -462,14 +490,19 @@ Attached to `ERC20` and `ERC721` tokens that may be minted.
 Implements the `mint(...)` and `safeMint(...)` parts of `ERC5679` for
 interoperability.
 
-ERC165 Interface identifier  
+#### ERC165 Interface identifier
+
 5878bcf4
 
-Solidity interface definition  
+#### Solidity interface definition
+
     interface IMinter {
         // Tokens are successfully minted; by who, to whom and how much
         event Mint(address indexed _minter, address indexed _beneficiary, uint256 value);
 
+        // The given token has been successfully minted; by who, to whom and how much
+        event Mint(address indexed _minter, address indexed _beneficiary, address indexed _token, uint256 value);
+
         // Mint the specified value of tokens to the specified recipient
         function mintTo(address _beneficiary, uint256 value) external returns (bool);
 
@@ -480,7 +513,8 @@ Solidity interface definition
         function safeMint(address _beneficiary, uint256 value, bytes calldata _data) external;
     }
 
-Example implementation  
+#### Example implementation
+
 <https://git.grassecon.net/cicnet/erc20-demurrage-token.git>
 
 ### Msg
@@ -493,10 +527,12 @@ The reference may or may not be mutable.
 The interface complements `Locator` and `MultiHash` to generate locators
 for how to resolve the reference.
 
-ERC165 Interface identifier  
+#### ERC165 Interface identifier
+
 a3002595
 
-Solidity interface definition  
+#### Solidity interface definition
+
     interface IMsg {
         // Emitted when a new message digest has been set
         // Should not be emitted if the digest set is identical to the previous
@@ -506,7 +542,8 @@ Solidity interface definition
         function getMsg() external view returns(bytes memory);
     }
 
-Example implementation  
+#### Example implementation
+
 <git://holbrook.no/eth-event-msg.git>
 
 ### Registry
@@ -520,10 +557,12 @@ It currently has two distinct uses in the CIC context:
 
 2.  Unique (ERC20) token symbol resolver.
 
-ERC165 Interface identifier  
+#### ERC165 Interface identifier
+
 effbf671
 
-Solidity interface definition  
+#### Solidity interface definition
+
     interface IRegistryClient {
         // Address added to store with the given key
         event AddressKey(bytes32 indexed _key, address _address);
@@ -538,10 +577,12 @@ Solidity interface definition
         function identifierCount() external view returns (uint256);
     }
 
-Contract registry implementation  
+#### Contract registry implementation
+
 <git://holbrook.no/eth-contract-registry.git>
 
-Token index implementation  
+#### Token index implementation
+
 <git://holbrook.no/eth-contract-registry.git>
 
 ### Seal
@@ -570,10 +611,12 @@ Use cases of sealing include:
 
 - The expiry time of a token (see `Expire`)
 
-ERC165 Interface identifier  
+#### ERC165 Interface identifier
+
 0d7491f8
 
-Solidity interface definition  
+#### Solidity interface definition
+
     interface ISeal {
         // Seal state has changed.
         event SealStateChange(bool indexed _final, uint256 _sealState);
@@ -585,40 +628,172 @@ Solidity interface definition
         function maxSealState() external view returns(uint256);
     }
 
-Example implementation  
+#### Example implementation
+
 <https://git.grassecon.net/cicnet/erc20-demurrage-token.git>
 
-### TokenVend
+### TokenLimit
 
-This interface defines the mechanism for which a specific ERC20 token
-may be exchanged for a different ERC20 token.
+Define limits of value amounts of tokens that individual addresses can
+hold.
 
-A typical use-case is generation of voting tokens based on a momentary
-voucher balance. This is especially useful if the original ERC20 token
-is subject to decay (demurrage).
+Limits are inclusive; a limit for 42 means transfer resulting in a token
+balance *higher* than 42 should be rejected.
 
-The tokens used for exchange **SHOULD** be locked for the full duration
-of holding the vended tokens.
+A return value of 0 indicates that the token is categorically not
+accepted by the holder.
 
-The withdrawal function may or may not allow partial withdrawals.
+#### ERC165 Interface identifier
 
-ERC165 Interface identifier  
-8a13249c
+23778613
 
-Solidity interface definition  
-    interface ITokenVend {
-        // A new vended token has been created.
-        event TokenCreated(uint256 indexed _tokenIdx, uint256 indexed _supply, address _token);
+#### Solidity interface definition
 
-        // Create corresponding vended tokens for the control token balance of the caller.  
-        function getFor(address _token) external returns (uint256);
-
-        // Recover control tokens that were used to retrieve the corresponding vended tokens.
-        function withdrawFor(address _token) external returns (uint256);
+    interface ITokenLimit {
+        // Returns limit of total value a holder will accept of a specific token.
+        // The value limit returned is inclusive; A limit of 42 means any operation resulting in a balance OVER 42 should be rejected.
+        // A value of 0 means that no value of the token is accepted.
+        function limitOf(address _token, address _holder) external view returns(uint256);
     }
 
-Reference implementations  
-- <git://holbrook.no/erc20-vend.git>
+#### Reference implementations
+
+- <git://holbrook.no/erc20-limiter.git>
+
+### TokenQuote
+
+Quote an output token value for a given value of input tokens.
+
+Both input and output value is denominated in the smallest available
+unit of respective tokens.
+
+#### ERC165 Interface identifier
+
+dbb21d40
+
+#### Solidity interface definition
+
+    interface ITokenQuote {
+        // Returns, within a current context, what value of outTokens the given value of inTokens translates to.
+        // The values are given in smallest unit of each respective token.
+        function valueFor(address _outToken, address _inToken, uint256 value) external view returns (uint256);
+    }
+
+#### Example implementation
+
+- <git://holbrook.no/erc20-limiter.git>
+
+### TokenRateChange
+
+Enables detection of properties for CIC tokens that change value over
+time, e.g. through demurrage.
+
+It allows defining the granularity of the rate of change, aswell as a
+frequency for which the rate of change is applied.
+
+A method for canonical value change calculations is also provided.
+
+#### ERC165 Interface identifier
+
+b716af03
+
+#### Solidity interface definition
+
+    interface ITokenChangeRate {
+        // Time unit resolution for rate of change.
+        // A value of 0 indicates no rate of change,
+        function changeTimeUnit() external view returns(uint256);
+
+        // Rate of change per changeTimeUnit(), signed integer.
+        // An effective value of 0 indicates no rate of change.
+        function changeRate() external view returns (int256);
+
+        // Number of decimals with which the changeRate is defined.
+            // changeRate() should be divided by 10 ** changeRateDecimals() to obtain effective value
+        function changeRateDecimals() external view returns(uint8);
+
+        // Timestamp from when rate of change should be applied.
+        // A value of 0 indicates no rate of change,
+        function changeStartTime() external view returns(uint256);
+
+        // Calculate value with change rate applied for given amount of time units.
+        // Will calculate compounded change over the given amount of time units
+        function applyChange(int256 _value, uint256 _changeTimeUnits) external view returns(int256);
+    }
+
+#### Reference implementations
+
+- <git://holbrook.no/erc20-demurrage-token.git>
+
+### TokenSwap
+
+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
+
+4146b765
+
+#### Solidity interface definition
+
+    interface ITokenSwap {
+        // 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 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-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
 
@@ -632,10 +807,12 @@ Voted tokens **SHOULD** be locked until the voting has finalized.
 
 Finalization of voting should be callable by anyone.
 
-ERC165 Interface identifier  
-28091366
+#### ERC165 Interface identifier
+
+f2e0bfeb
+
+#### Solidity interface definition
 
-Solidity interface definition  
     interface ITokenVote {
 
         // A new proposal has been created.
@@ -655,8 +832,8 @@ Solidity interface definition
         // * _blockWait blocks from now.
         function propose(bytes32 _description, uint256 _blockWait, uint24 _targetVotePpm) external returns (uint256);
 
-        // Same as propose(...), but provide options to vote on.
-        function proposeMulti(bytes32 _description, bytes32[] memory _options, uint256 _blockWait, uint24 _targetVotePpm) external returns (uint256);
+        // Add a voting option to a proposal
+        function addOption(uint256 _proposalIdx, bytes32 _description) external;
 
         // Get number of options available for the proposal.
         // This decides the boundary of the index that can be used with voteOptions(...)
@@ -691,7 +868,8 @@ Solidity interface definition
         function finalize() external returns (bool);
     }
 
-Reference implementations  
+#### Reference implementations
+
 - <git://holbrook.no/evm-tokenvote.git>
 
 ### Writer
@@ -716,10 +894,12 @@ Some use-case examples of super-user actions include:
 
 - Edit access control lists.
 
-ERC165 Interface identifier  
+#### ERC165 Interface identifier
+
 abe1f1f5
 
-Solidity interface definition  
+#### Solidity interface definition
+
     interface IWriter {
         // A writer has been added by _executor
         event WriterAdded(address _writer);
@@ -737,5 +917,6 @@ Solidity interface definition
         function isWriter(address _writer) external view returns (bool);
     }
 
-Example implementation  
+#### Example implementation
+
 <https://git.grassecon.net/cicnet/erc20-demurrage-token.git>

doc/texinfo/accountsindex.sol.texi

@@ -9,14 +9,17 @@ The @code{entry} method is used to iterate the account list. The order of which
 May optionally record time when account was added.
 
 
-@table @dfn
-@item ERC165 Interface identifier
+@subsubsection ERC165 Interface identifier
+
 @include ../../build/AccountsIndex.interface
-@item Solidity interface definition
+
+@subsubsection Solidity interface definition
+
 @include ../../build/contract_AccountsIndex.texi
-@item Reference implementation
+
+@subsubsection Reference implementation
+
 @uref{git://holbrook.no/eth-accounts-index.git,} (v0.5.1)
-@end table
 
 
 @subsection Accounts Index Mutable
@@ -26,11 +29,14 @@ Extends the functionality of @code{Accounts Index} to allow changes to the addre
 Addresses may be @emph{added}, @emph{removed}, aswell as @emph{deactivated} and @emph{activated}. Deactivated accounts still count towards the @code{entryCount}.
 
 
-@table @dfn
-@item ERC165 Interface identifier
+@subsubsection ERC165 Interface identifier
+
 @include ../../build/AccountsIndexMutable.interface
-@item Solidity interface definition
+
+@subsubsection Solidity interface definition
+
 @include ../../build/contract_AccountsIndexMutable.texi
-@item Reference implementation
+
+@subsubsection Reference implementation
+
 @uref{git://holbrook.no/eth-accounts-index.git,} (v0.5.1)
-@end table

doc/texinfo/burner.sol.texi

@@ -4,11 +4,14 @@ Attached to @code{ERC20} and @code{ERC721} tokens that may be @emph{burned}.
 
 Implements the @code{burn(...)} part of @code{ERC5679} for interoperability.
 
-@table @dfn
-@item ERC165 Interface identifier
+@subsubsection ERC165 Interface identifier
+
 @include ../../build/Burner.interface
-@item Solidity interface definition
+
+@subsubsection Solidity interface definition
+
 @include ../../build/contract_Burner.texi
-@item Example implementation
+
+@subsubsection Example implementation
+
 @uref{https://git.grassecon.net/cicnet/erc20-demurrage-token.git}
-@end table

doc/texinfo/chrono.sol.texi

@@ -5,11 +5,14 @@ Define a creation time for a resource.
 Complements @code{ERC5007}.
 
 
-@table @dfn
-@item ERC165 Interface identifier
+@subsubsection ERC165 Interface identifier
+
 @include ../../build/Chrono.interface
-@item Solidity interface definition
+
+@subsubsection Solidity interface definition
+
 @include ../../build/contract_Chrono.texi
-@item Example implementation
+
+@subsubsection Example implementation
+
 @uref{https://git.defalsify.org/eth-erc721} (BadgeToken contract)
-@end table

doc/texinfo/declarator.sol.texi

@@ -10,11 +10,14 @@ Claims may be made with or without topics. A missing topic is synonymous with a
 
 Any number of claims can be made about an address under any number of topics. All claims must be stored, and returned in the order which they were added.
 
-@table @dfn
-@item ERC165 Interface identifier
+@subsubsection ERC165 Interface identifier
+
 @include ../../build/Declarator.interface
-@item Solidity interface definition
+
+@subsubsection Solidity interface definition
+
 @include ../../build/contract_Declarator.texi
-@item Reference implementation
+
+@subsubsection Reference implementation
+
 @uref{git://holbrook.no/eth-address-index.git,}
-@end table

doc/texinfo/digest.sol.texi

@@ -7,11 +7,14 @@ Primary use-case is the abstraction of self-describing @uref{https://multiformat
 A default encoding @emph{must} always be defined, and the encoding of a valid digest @emph{must} succeed with the default encoding.
 
 
-@table @dfn
-@item ERC165 Interface identifier
+@subsubsection ERC165 Interface identifier
+
 @include ../../build/Digest.interface
-@item Solidity interface definition
+
+@subsubsection Solidity interface definition
+
 @include ../../build/contract_Digest.texi
-@item Example implementation
+
+@subsubsection Example implementation
+
 @uref{git://holbrook.no/eth-event-msg.git}
-@end table

doc/texinfo/expire.sol.texi

@@ -1,15 +1,18 @@
 @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.
 
 
-@table @dfn
-@item ERC165 Interface identifier
+@subsubsection ERC165 Interface identifier
+
 @include ../../build/Expire.interface
-@item Solidity interface definition
+
+@subsubsection Solidity interface definition
+
 @include ../../build/contract_Expire.texi
-@item Example implementation
+
+@subsubsection Example implementation
+
 @uref{https://git.grassecon.net/cicnet/erc20-demurrage-token.git}
-@end table

doc/texinfo/faucet.sol.texi

@@ -24,16 +24,19 @@ The contract has sufficient token funds to dispense the current defined amount t
 The @emph{check(address)} contract call @emph{must} evaluate all four criteria, and @emph{must} return @code{false} if any of the criteria are not met.
 
 
-@table @dfn
-@item ERC165 Interface identifier
+@subsubsection ERC165 Interface identifier
+
 @include ../../build/Faucet.interface
-@item Solidity interface definition
+
+@subsubsection Solidity interface definition
+
 @include ../../build/contract_Faucet.texi
-@item Reference implementations
+
+@subsubsection Reference implementations
+
 @itemize
 @item
 @uref{git://holbrook.no/erc20-faucet.git,}
 @item
 @uref{git://holbrook.no/eth-faucet.git,}
 @end itemize
-@end table

doc/texinfo/locator.sol.texi

@@ -8,17 +8,20 @@ It @emph{must} be possible to refer to all off-chain resources directly by the c
 
 Furthermore, it @emph{should} be possible to refer to a resource by a fully-qualified location on the web or an overlay network (e.g. tor).
 
-@table @dfn
-@item ERC165 Interface identifier
+@subsubsection ERC165 Interface identifier
+
 @include ../../build/Locator.interface
-@item Solidity interface definition
+
+@subsubsection Solidity interface definition
+
 @include ../../build/contract_Locator.texi
-@item Example implementation
+
+@subsubsection Example implementation
+
 @uref{git://holbrook.no/eth-event-msg.git}
-@end table
 
 
-@subsubsection Expressing locators in terms of numetic token id
+@subsubsection Expressing locators in terms of numeric token id
 
 Given the numeric token id @code{1234567890987654321} (@code{0x112210f4b16c1cb1} hex), and a base url @code{https://contentgateway.grassecon.net}, the result of the methods may be as follows:
 

doc/texinfo/minter.sol.texi

@@ -4,11 +4,14 @@ Attached to @code{ERC20} and @code{ERC721} tokens that may be minted.
 
 Implements the @code{mint(...)} and @code{safeMint(...)} parts of @code{ERC5679} for interoperability.
 
-@table @dfn
-@item ERC165 Interface identifier
+@subsubsection ERC165 Interface identifier
+
 @include ../../build/Minter.interface
-@item Solidity interface definition
+
+@subsubsection Solidity interface definition
+
 @include ../../build/contract_Minter.texi
-@item Example implementation
+
+@subsubsection Example implementation
+
 @uref{https://git.grassecon.net/cicnet/erc20-demurrage-token.git}
-@end table

doc/texinfo/msg.sol.texi

@@ -7,11 +7,14 @@ The reference may or may not be mutable.
 The interface complements @code{Locator} and @code{MultiHash} to generate locators for how to resolve the reference.
 
 
-@table @dfn
-@item ERC165 Interface identifier
+@subsubsection ERC165 Interface identifier
+
 @include ../../build/Msg.interface
-@item Solidity interface definition
+
+@subsubsection Solidity interface definition
+
 @include ../../build/contract_Msg.texi
-@item Example implementation
+
+@subsubsection Example implementation
+
 @uref{git://holbrook.no/eth-event-msg.git}
-@end table

doc/texinfo/overview.texi

@@ -74,7 +74,13 @@ The following well-known solidity interfaces are partially implemented in CIC na
 
 @include seal.sol.texi
 
-@include tokenvend.sol.texi
+@include tokenlimit.sol.texi
+
+@include tokenquote.sol.texi
+
+@include tokenratechange.sol.texi
+
+@include tokenswap.sol.texi
 
 @include tokenvote.sol.texi
 

doc/texinfo/registry.sol.texi

@@ -11,13 +11,18 @@ Entry-point to discover all relevant contracts of CIC networks.
 Unique (ERC20) token symbol resolver.
 @end enumerate
 
-@table @dfn
-@item ERC165 Interface identifier
+@subsubsection ERC165 Interface identifier
+
 @include ../../build/RegistryClient.interface
-@item Solidity interface definition
+
+@subsubsection Solidity interface definition
+
 @include ../../build/contract_RegistryClient.texi
-@item Contract registry implementation
+
+@subsubsection Contract registry implementation
+
 @uref{git://holbrook.no/eth-contract-registry.git,}
-@item Token index implementation
+
+@subsubsection Token index implementation
+
 @uref{git://holbrook.no/eth-contract-registry.git,}
-@end table

doc/texinfo/seal.sol.texi

@@ -21,11 +21,14 @@ Allow ownership of a contract to be transferred
 The expiry time of a token (see @code{Expire})
 @end itemize
 
-@table @dfn
-@item ERC165 Interface identifier
+@subsubsection ERC165 Interface identifier
+
 @include ../../build/Seal.interface
-@item Solidity interface definition
+
+@subsubsection Solidity interface definition
+
 @include ../../build/contract_Seal.texi
-@item Example implementation
+
+@subsubsection Example implementation
+
 @uref{https://git.grassecon.net/cicnet/erc20-demurrage-token.git}
-@end table

doc/texinfo/tokenlimit.sol.texi

@@ -0,0 +1,22 @@
+@subsection TokenLimit
+
+Define limits of value amounts of tokens that individual addresses can hold.
+
+Limits are inclusive; a limit for 42 means transfer resulting in a token balance @emph{higher} than 42 should be rejected.
+
+A return value of 0 indicates that the token is categorically not accepted by the holder.
+
+@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/tokenquote.sol.texi

@@ -0,0 +1,20 @@
+@subsection TokenQuote
+
+Quote an output token value for a given value of input tokens.
+
+Both input and output value is denominated in the smallest available unit of respective tokens.
+
+@subsubsection ERC165 Interface identifier
+
+@include ../../build/TokenQuote.interface
+
+@subsubsection Solidity interface definition
+
+@include ../../build/contract_TokenQuote.texi
+
+@subsubsection Example implementation
+
+@itemize
+@item
+@uref{git://holbrook.no/erc20-limiter.git,}
+@end itemize

doc/texinfo/tokenratechange.sol.texi

@@ -0,0 +1,22 @@
+@subsection TokenRateChange
+
+Enables detection of properties for CIC tokens that change value over time, e.g. through demurrage.
+
+It allows defining the granularity of the rate of change, aswell as a frequency for which the rate of change is applied.
+
+A method for canonical value change calculations is also provided.
+
+@subsubsection ERC165 Interface identifier
+
+@include ../../build/TokenRateChange.interface
+
+@subsubsection Solidity interface definition
+
+@include ../../build/contract_TokenRateChange.texi
+
+@subsubsection Reference implementations
+
+@itemize
+@item
+@uref{git://holbrook.no/erc20-demurrage-token.git,}
+@end itemize

doc/texinfo/tokenswap.sol.texi

@@ -0,0 +1,40 @@
+@subsection TokenSwap
+
+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
+
+@include ../../build/TokenSwap.interface
+
+@subsubsection Solidity interface definition
+
+@include ../../build/contract_TokenSwap.texi
+
+@subsubsection Reference implementations
+
+@itemize
+@item
+@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.

doc/texinfo/tokenvote.sol.texi

@@ -10,14 +10,16 @@ Voted tokens @strong{SHOULD} be locked until the voting has finalized.
 Finalization of voting should be callable by anyone.
 
 
-@table @dfn
-@item ERC165 Interface identifier
+@subsubsection ERC165 Interface identifier
+
 @include ../../build/TokenVote.interface
-@item Solidity interface definition
+
+@subsubsection Solidity interface definition
+
 @include ../../build/contract_TokenVote.texi
-@item Reference implementations
+
+@subsubsection Reference implementations
 @itemize
 @item
 @uref{git://holbrook.no/evm-tokenvote.git,}
 @end itemize
-@end table

doc/texinfo/writer.sol.texi

@@ -19,11 +19,14 @@ Change the amount dispensed by the faucet.
 Edit access control lists.
 @end itemize
 
-@table @dfn
-@item ERC165 Interface identifier
+@subsubsection ERC165 Interface identifier
+
 @include ../../build/Writer.interface
-@item Solidity interface definition
+
+@subsubsection Solidity interface definition
+
 @include ../../build/contract_Writer.texi
-@item Example implementation
+
+@subsubsection Example implementation
+
 @uref{https://git.grassecon.net/cicnet/erc20-demurrage-token.git}
-@end table

python/README.md

@@ -61,10 +61,12 @@ matching `address(0x00)` should be skipped, and not counted towards
 
 May optionally record time when account was added.
 
-ERC165 Interface identifier  
+#### ERC165 Interface identifier
+
 b7bca625
 
-Solidity interface definition  
+#### Solidity interface definition
+
     interface IAccountsIndex {
         // Address added to store, index in array.
         event AddressAdded(uint256 indexed _idx, address _account);
@@ -88,7 +90,8 @@ Solidity interface definition
         function time(address) external view returns (uint256);
     }
 
-Reference implementation  
+#### Reference implementation
+
 <git://holbrook.no/eth-accounts-index.git> (v0.5.1)
 
 ### Accounts Index Mutable
@@ -99,10 +102,12 @@ address list.
 Addresses may be *added*, *removed*, aswell as *deactivated* and
 *activated*. Deactivated accounts still count towards the `entryCount`.
 
-ERC165 Interface identifier  
+#### ERC165 Interface identifier
+
 9479f0ae
 
-Solidity interface definition  
+#### Solidity interface definition
+
     interface IAccountsIndexMutable {
         // Active status of address changed, and by whom changed.
         event AddressActive(address indexed _account, bool _active);
@@ -123,7 +128,8 @@ Solidity interface definition
         function isActive(address) external view returns (bool);
     }
 
-Reference implementation  
+#### Reference implementation
+
 <git://holbrook.no/eth-accounts-index.git> (v0.5.1)
 
 ### Burner
@@ -132,10 +138,12 @@ Attached to `ERC20` and `ERC721` tokens that may be *burned*.
 
 Implements the `burn(...)` part of `ERC5679` for interoperability.
 
-ERC165 Interface identifier  
-bc4babdd
+#### ERC165 Interface identifier
+
+b1110c1b
+
+#### Solidity interface definition
 
-Solidity interface definition  
     interface IBurner {
         // Token(s) successfully burned; by who and how much.
         event Burn(address indexed _burner, uint256 _burned);
@@ -144,10 +152,11 @@ Solidity interface definition
         function burn(address _from, uint256 _amount, bytes calldata _data) external;
 
         // Burn given amount of tokens held by signer.
-        function burn(uint256 _burn) external returns (bool);
+        function burn(uint256 _amount) external returns (bool);
 
         // Burn all tokens held by signer.
-        function burn() external returns (bool);
+        // Returns the amount of tokens burned.
+        function burn() external returns (uint256);
 
         // Total amount of tokens that have been burned.
         function totalBurned() external returns (uint256);
@@ -157,7 +166,8 @@ Solidity interface definition
         function totalMinted() external returns (uint256);
     }
 
-Example implementation  
+#### Example implementation
+
 <https://git.grassecon.net/cicnet/erc20-demurrage-token.git>
 
 ### Chrono
@@ -166,17 +176,20 @@ Define a creation time for a resource.
 
 Complements `ERC5007`.
 
-ERC165 Interface identifier  
+#### ERC165 Interface identifier
+
 4db1ccd4
 
-Solidity interface definition  
+#### Solidity interface definition
+
     interface IChrono {
         // Returns the timestamp of when a resource corresponding to _idx was first created.
         // int64 chosen as return value for simpler interoperability with ERC5007.
         function createTime(uint256 _idx) external returns(int64);
     }
 
-Example implementation  
+#### Example implementation
+
 <https://git.defalsify.org/eth-erc721> (BadgeToken contract)
 
 ### Declarator
@@ -196,10 +209,12 @@ Any number of claims can be made about an address under any number of
 topics. All claims must be stored, and returned in the order which they
 were added.
 
-ERC165 Interface identifier  
+#### ERC165 Interface identifier
+
 21b7493b
 
-Solidity interface definition  
+#### Solidity interface definition
+
     interface IDeclarator {
         event DeclarationAdded(address indexed _declarator, address indexed _subject, bytes32 indexed _topic, bytes32 _proof);
         
@@ -228,7 +243,8 @@ Solidity interface definition
         function declaratorCount(address _subject) external view returns ( uint256 );
     }
 
-Reference implementation  
+#### Reference implementation
+
 <git://holbrook.no/eth-address-index.git>
 
 ### Digest
@@ -241,10 +257,12 @@ Primary use-case is the abstraction of self-describing
 A default encoding *must* always be defined, and the encoding of a valid
 digest *must* succeed with the default encoding.
 
-ERC165 Interface identifier  
+#### ERC165 Interface identifier
+
 982ab05d
 
-Solidity interface definition  
+#### Solidity interface definition
+
     interface IDigest {
         // Returns the default digest encoding used by the contract instance.
         function defaultDigestEncoding() external view returns (uint256 _encoding);
@@ -263,21 +281,24 @@ Solidity interface definition
         function encodeDigest(bytes memory _data) external view returns (bytes memory);
     }
 
-Example implementation  
+#### Example implementation
+
 <git://holbrook.no/eth-event-msg.git>
 
 ### 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
 time to a time in the past.
 
-ERC165 Interface identifier  
+#### ERC165 Interface identifier
+
 841a0e94
 
-Solidity interface definition  
+#### Solidity interface definition
+
     interface IExpire {
         // Contract has expired.
         event Expired(uint256 _timestamp);
@@ -296,7 +317,8 @@ Solidity interface definition
         function applyExpiry() external returns(uint8);
     }
 
-Example implementation  
+#### Example implementation
+
 <https://git.grassecon.net/cicnet/erc20-demurrage-token.git>
 
 ### Faucet
@@ -331,10 +353,12 @@ amount to dispense.
 The *check(address)* contract call *must* evaluate all four criteria,
 and *must* return `false` if any of the criteria are not met.
 
-ERC165 Interface identifier  
+#### ERC165 Interface identifier
+
 1a3ac634
 
-Solidity interface definition  
+#### Solidity interface definition
+
     interface IFaucet {
         // Tokens were given to an address
         event Give(address indexed _recipient, address indexed _token, uint256 _value);
@@ -369,7 +393,8 @@ Solidity interface definition
         function nextBalance(address _recipient) external returns (uint256);
     }
 
-Reference implementations  
+#### Reference implementations
+
 - <git://holbrook.no/erc20-faucet.git>
 
 - <git://holbrook.no/eth-faucet.git>
@@ -388,10 +413,12 @@ the content address.
 Furthermore, it *should* be possible to refer to a resource by a
 fully-qualified location on the web or an overlay network (e.g. tor).
 
-ERC165 Interface identifier  
+#### ERC165 Interface identifier
+
 ed75b333
 
-Solidity interface definition  
+#### Solidity interface definition
+
     interface ILocator {
         // URI that may or may not point to a specific resource location.
         function toURI(bytes memory _data) external view returns (string memory);
@@ -400,10 +427,11 @@ Solidity interface definition
         function toURL(bytes memory _data) external view returns(string memory);
     }
 
-Example implementation  
+#### Example implementation
+
 <git://holbrook.no/eth-event-msg.git>
 
-#### Expressing locators in terms of numetic token id
+#### Expressing locators in terms of numeric token id
 
 Given the numeric token id `1234567890987654321` (`0x112210f4b16c1cb1`
 hex), and a base url `https://contentgateway.grassecon.net`, the result
@@ -462,14 +490,19 @@ Attached to `ERC20` and `ERC721` tokens that may be minted.
 Implements the `mint(...)` and `safeMint(...)` parts of `ERC5679` for
 interoperability.
 
-ERC165 Interface identifier  
+#### ERC165 Interface identifier
+
 5878bcf4
 
-Solidity interface definition  
+#### Solidity interface definition
+
     interface IMinter {
         // Tokens are successfully minted; by who, to whom and how much
         event Mint(address indexed _minter, address indexed _beneficiary, uint256 value);
 
+        // The given token has been successfully minted; by who, to whom and how much
+        event Mint(address indexed _minter, address indexed _beneficiary, address indexed _token, uint256 value);
+
         // Mint the specified value of tokens to the specified recipient
         function mintTo(address _beneficiary, uint256 value) external returns (bool);
 
@@ -480,7 +513,8 @@ Solidity interface definition
         function safeMint(address _beneficiary, uint256 value, bytes calldata _data) external;
     }
 
-Example implementation  
+#### Example implementation
+
 <https://git.grassecon.net/cicnet/erc20-demurrage-token.git>
 
 ### Msg
@@ -493,10 +527,12 @@ The reference may or may not be mutable.
 The interface complements `Locator` and `MultiHash` to generate locators
 for how to resolve the reference.
 
-ERC165 Interface identifier  
+#### ERC165 Interface identifier
+
 a3002595
 
-Solidity interface definition  
+#### Solidity interface definition
+
     interface IMsg {
         // Emitted when a new message digest has been set
         // Should not be emitted if the digest set is identical to the previous
@@ -506,7 +542,8 @@ Solidity interface definition
         function getMsg() external view returns(bytes memory);
     }
 
-Example implementation  
+#### Example implementation
+
 <git://holbrook.no/eth-event-msg.git>
 
 ### Registry
@@ -520,10 +557,12 @@ It currently has two distinct uses in the CIC context:
 
 2.  Unique (ERC20) token symbol resolver.
 
-ERC165 Interface identifier  
+#### ERC165 Interface identifier
+
 effbf671
 
-Solidity interface definition  
+#### Solidity interface definition
+
     interface IRegistryClient {
         // Address added to store with the given key
         event AddressKey(bytes32 indexed _key, address _address);
@@ -538,10 +577,12 @@ Solidity interface definition
         function identifierCount() external view returns (uint256);
     }
 
-Contract registry implementation  
+#### Contract registry implementation
+
 <git://holbrook.no/eth-contract-registry.git>
 
-Token index implementation  
+#### Token index implementation
+
 <git://holbrook.no/eth-contract-registry.git>
 
 ### Seal
@@ -570,10 +611,12 @@ Use cases of sealing include:
 
 - The expiry time of a token (see `Expire`)
 
-ERC165 Interface identifier  
+#### ERC165 Interface identifier
+
 0d7491f8
 
-Solidity interface definition  
+#### Solidity interface definition
+
     interface ISeal {
         // Seal state has changed.
         event SealStateChange(bool indexed _final, uint256 _sealState);
@@ -585,40 +628,172 @@ Solidity interface definition
         function maxSealState() external view returns(uint256);
     }
 
-Example implementation  
+#### Example implementation
+
 <https://git.grassecon.net/cicnet/erc20-demurrage-token.git>
 
-### TokenVend
+### TokenLimit
 
-This interface defines the mechanism for which a specific ERC20 token
-may be exchanged for a different ERC20 token.
+Define limits of value amounts of tokens that individual addresses can
+hold.
 
-A typical use-case is generation of voting tokens based on a momentary
-voucher balance. This is especially useful if the original ERC20 token
-is subject to decay (demurrage).
+Limits are inclusive; a limit for 42 means transfer resulting in a token
+balance *higher* than 42 should be rejected.
 
-The tokens used for exchange **SHOULD** be locked for the full duration
-of holding the vended tokens.
+A return value of 0 indicates that the token is categorically not
+accepted by the holder.
 
-The withdrawal function may or may not allow partial withdrawals.
+#### ERC165 Interface identifier
 
-ERC165 Interface identifier  
-8a13249c
+23778613
 
-Solidity interface definition  
-    interface ITokenVend {
-        // A new vended token has been created.
-        event TokenCreated(uint256 indexed _tokenIdx, uint256 indexed _supply, address _token);
+#### Solidity interface definition
 
-        // Create corresponding vended tokens for the control token balance of the caller.  
-        function getFor(address _token) external returns (uint256);
-
-        // Recover control tokens that were used to retrieve the corresponding vended tokens.
-        function withdrawFor(address _token) external returns (uint256);
+    interface ITokenLimit {
+        // Returns limit of total value a holder will accept of a specific token.
+        // The value limit returned is inclusive; A limit of 42 means any operation resulting in a balance OVER 42 should be rejected.
+        // A value of 0 means that no value of the token is accepted.
+        function limitOf(address _token, address _holder) external view returns(uint256);
     }
 
-Reference implementations  
-- <git://holbrook.no/erc20-vend.git>
+#### Reference implementations
+
+- <git://holbrook.no/erc20-limiter.git>
+
+### TokenQuote
+
+Quote an output token value for a given value of input tokens.
+
+Both input and output value is denominated in the smallest available
+unit of respective tokens.
+
+#### ERC165 Interface identifier
+
+dbb21d40
+
+#### Solidity interface definition
+
+    interface ITokenQuote {
+        // Returns, within a current context, what value of outTokens the given value of inTokens translates to.
+        // The values are given in smallest unit of each respective token.
+        function valueFor(address _outToken, address _inToken, uint256 value) external view returns (uint256);
+    }
+
+#### Example implementation
+
+- <git://holbrook.no/erc20-limiter.git>
+
+### TokenRateChange
+
+Enables detection of properties for CIC tokens that change value over
+time, e.g. through demurrage.
+
+It allows defining the granularity of the rate of change, aswell as a
+frequency for which the rate of change is applied.
+
+A method for canonical value change calculations is also provided.
+
+#### ERC165 Interface identifier
+
+b716af03
+
+#### Solidity interface definition
+
+    interface ITokenChangeRate {
+        // Time unit resolution for rate of change.
+        // A value of 0 indicates no rate of change,
+        function changeTimeUnit() external view returns(uint256);
+
+        // Rate of change per changeTimeUnit(), signed integer.
+        // An effective value of 0 indicates no rate of change.
+        function changeRate() external view returns (int256);
+
+        // Number of decimals with which the changeRate is defined.
+            // changeRate() should be divided by 10 ** changeRateDecimals() to obtain effective value
+        function changeRateDecimals() external view returns(uint8);
+
+        // Timestamp from when rate of change should be applied.
+        // A value of 0 indicates no rate of change,
+        function changeStartTime() external view returns(uint256);
+
+        // Calculate value with change rate applied for given amount of time units.
+        // Will calculate compounded change over the given amount of time units
+        function applyChange(int256 _value, uint256 _changeTimeUnits) external view returns(int256);
+    }
+
+#### Reference implementations
+
+- <git://holbrook.no/erc20-demurrage-token.git>
+
+### TokenSwap
+
+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
+
+4146b765
+
+#### Solidity interface definition
+
+    interface ITokenSwap {
+        // 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 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-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
 
@@ -632,10 +807,12 @@ Voted tokens **SHOULD** be locked until the voting has finalized.
 
 Finalization of voting should be callable by anyone.
 
-ERC165 Interface identifier  
-28091366
+#### ERC165 Interface identifier
+
+f2e0bfeb
+
+#### Solidity interface definition
 
-Solidity interface definition  
     interface ITokenVote {
 
         // A new proposal has been created.
@@ -655,8 +832,8 @@ Solidity interface definition
         // * _blockWait blocks from now.
         function propose(bytes32 _description, uint256 _blockWait, uint24 _targetVotePpm) external returns (uint256);
 
-        // Same as propose(...), but provide options to vote on.
-        function proposeMulti(bytes32 _description, bytes32[] memory _options, uint256 _blockWait, uint24 _targetVotePpm) external returns (uint256);
+        // Add a voting option to a proposal
+        function addOption(uint256 _proposalIdx, bytes32 _description) external;
 
         // Get number of options available for the proposal.
         // This decides the boundary of the index that can be used with voteOptions(...)
@@ -691,7 +868,8 @@ Solidity interface definition
         function finalize() external returns (bool);
     }
 
-Reference implementations  
+#### Reference implementations
+
 - <git://holbrook.no/evm-tokenvote.git>
 
 ### Writer
@@ -716,10 +894,12 @@ Some use-case examples of super-user actions include:
 
 - Edit access control lists.
 
-ERC165 Interface identifier  
+#### ERC165 Interface identifier
+
 abe1f1f5
 
-Solidity interface definition  
+#### Solidity interface definition
+
     interface IWriter {
         // A writer has been added by _executor
         event WriterAdded(address _writer);
@@ -737,5 +917,6 @@ Solidity interface definition
         function isWriter(address _writer) external view returns (bool);
     }
 
-Example implementation  
+#### Example implementation
+
 <https://git.grassecon.net/cicnet/erc20-demurrage-token.git>

solidity/Minter.sol

@@ -8,6 +8,9 @@ interface IMinter {
 	// Tokens are successfully minted; by who, to whom and how much
 	event Mint(address indexed _minter, address indexed _beneficiary, uint256 value);
 
+	// The given token has been successfully minted; by who, to whom and how much
+	event Mint(address indexed _minter, address indexed _beneficiary, address indexed _token, uint256 value);
+
 	// Mint the specified value of tokens to the specified recipient
 	function mintTo(address _beneficiary, uint256 value) external returns (bool);
 

solidity/TokenLimit.sol

@@ -0,0 +1,12 @@
+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 {
+	// Returns limit of total value a holder will accept of a specific token.
+	// The value limit returned is inclusive; A limit of 42 means any operation resulting in a balance OVER 42 should be rejected.
+	// A value of 0 means that no value of the token is accepted.
+	function limitOf(address _token, address _holder) external view returns(uint256);
+}

solidity/TokenQuote.sol

@@ -0,0 +1,13 @@
+pragma solidity >=0.6.12;
+
+// Author:	Louis Holbrook <dev@holbrook.no> 0826EDA1702D1E87C6E2875121D2E7BB88C2A746
+// SPDX-License-Identifier:	AGPL-3.0-or-later
+// File-version: 1
+
+// Value translator between tokens
+
+interface ITokenQuote {
+	// Returns, within a current context, what value of outTokens the given value of inTokens translates to.
+	// The values are given in smallest unit of each respective token.
+	function valueFor(address _outToken, address _inToken, uint256 value) external view returns (uint256);
+}

solidity/TokenRateChange.sol

@@ -0,0 +1,29 @@
+pragma solidity >=0.6.12;
+
+// Author:	Louis Holbrook <dev@holbrook.no> 0826EDA1702D1E87C6E2875121D2E7BB88C2A746
+// SPDX-License-Identifier:	AGPL-3.0-or-later
+// File-version: 1
+
+// Methods to detect tokens that are subject to continuous change, and 
+
+interface ITokenChangeRate {
+	// Time unit resolution for rate of change.
+	// A value of 0 indicates no rate of change,
+	function changeTimeUnit() external view returns(uint256);
+
+	// Rate of change per changeTimeUnit(), signed integer.
+	// An effective value of 0 indicates no rate of change.
+	function changeRate() external view returns (int256);
+
+	// Number of decimals with which the changeRate is defined.
+        // changeRate() should be divided by 10 ** changeRateDecimals() to obtain effective value
+	function changeRateDecimals() external view returns(uint8);
+
+	// Timestamp from when rate of change should be applied.
+	// A value of 0 indicates no rate of change,
+	function changeStartTime() external view returns(uint256);
+
+	// Calculate value with change rate applied for given amount of time units.
+	// Will calculate compounded change over the given amount of time units
+	function applyChange(int256 _value, uint256 _changeTimeUnits) external view returns(int256);
+}

solidity/TokenSwap.sol

@@ -0,0 +1,31 @@
+pragma solidity >=0.6.12;
+
+// Author:	Louis Holbrook <dev@holbrook.no> 0826EDA1702D1E87C6E2875121D2E7BB88C2A746
+// SPDX-License-Identifier:	AGPL-3.0-or-later
+// File-version: 1
+
+// Methods for swapping tokens for each other.
+
+interface ITokenSwap {
+	// 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 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);
+}

solidity/TokenVote.sol

@@ -2,7 +2,7 @@ pragma solidity >=0.6.12;
 
 // Author:	Louis Holbrook <dev@holbrook.no> 0826EDA1702D1E87C6E2875121D2E7BB88C2A746
 // SPDX-License-Identifier:	AGPL-3.0-or-later
-// File-version: 1
+// File-version: 2
 
 
 interface ITokenVote {
@@ -24,8 +24,8 @@ interface ITokenVote {
 	// * _blockWait blocks from now.
 	function propose(bytes32 _description, uint256 _blockWait, uint24 _targetVotePpm) external returns (uint256);
 
-	// Same as propose(...), but provide options to vote on.
-	function proposeMulti(bytes32 _description, bytes32[] memory _options, uint256 _blockWait, uint24 _targetVotePpm) external returns (uint256);
+	// Add a voting option to a proposal
+	function addOption(uint256 _proposalIdx, bytes32 _description) external;
 
 	// Get number of options available for the proposal.
 	// This decides the boundary of the index that can be used with voteOptions(...)

texify.sh

@@ -4,7 +4,9 @@ for f in $(ls solidity/*.sol); do
 	fn=$(basename $f)
 	fb=${fn%.*}
 	fn="build/contract_${fb}.texi"
-	echo "@verbatim" > $fn
+	#echo "@verbatim" > $fn
+	echo -e "@example\n@verbatim" > $fn
 	awk 'f;/interface [a-zA-Z0-9]* /{print;f=1}' $f >> $fn
-	echo "@end verbatim" >> $fn
+	#echo "@end verbatim" >> $fn
+	echo -e "@end verbatim\n@end example" >> $fn
 done