WIP texinfo docs, elaborate on tools, supply cap

doc/texinfo/contract.texi

@@ -4,6 +4,12 @@
 
 @section Common interfaces
 
+The smart contract is written in solidity, compatible with 0.8.x.
+
+It implements a number of interfaces both from the Ethereum (ERC) standards aswell as the Community Inclusion Currency contract interface suite.
+
+
+
 @subsection ERC standard interfaces
 
 @itemize @bullet
@@ -134,6 +140,32 @@ The demurrage is calculated as from the total supply of voucher at the end of th
 To explicitly credit the @emph{Sink Address} with the demurrage value after a period has been exceeded, the @code{changePeriod()} (@code{8f1df6bc}) method can be called.
 
 
+@node expiry
+@subsection Setting voucher expiry
+
+The effect of a voucher expiring is that all balances will be frozen, and all state changes affecting token balances will be blocked.
+
+Expiry is defined in terms of redistribution periods. For example, if the redistribution period is 30 days, and the expity is 3, then the voucher expires after 90 days.
+
+The expiry takes effect immediately when the redistribution period time has been exceeded.
+
+When the contract is published, no expiry is set.
+
+Expiry may be set after publishing using the @code{CIC.Expire} interface.
+
+If the @code{EXPIRE_STATE} seal has been set, expiry may not be changed further.
+
+
+@node supply
+@subsection Capping voucher supply
+
+The effect of a voucher supply cap is that all @code{CIC.Minter} calls will fail if the total supply after minting exceeds the defined supply cap.
+
+The supply cap still allows vouchers to be minted after @code{CIC.Burn} calls, provided that the previous condition holds.
+
+To apply the supply cap, the method @code{maxSupply(uint256) (869f7594)} is used.
+
+
 @node sideeffects
 @subsection Side-effects in state changes
 

doc/texinfo/overview.texi

@@ -26,7 +26,8 @@ In short: Everyone is taxed a little something every minute, and every so often
 @item Per-minute decay resolution.
 @item Minting and burning of vouchers.
 @item Grant and revoke access to mint and burn vouchers.
-@item Voucher expiration.
+@item Voucher expiration (modifiable anytime after publishing).
+@item Supply cap (modifiable anytime after publishing).
 @item Constant gas usage across exponential calculations.
 @end itemize
 
@@ -42,3 +43,5 @@ The intermediate beneficiary of the demurraged amount, which may or may not redi
 @item Base balance
 The inflated balance of each used which is stored for bookkeeping.
 @end table
+
+

doc/texinfo/tools.texi

@@ -1,2 +1,57 @@
 @node tools
 @chapter Tools
+
+
+When installed as a python package, @code{erc20-demurrage-token} installs the @code{erc20-demurrage-token-publish} executable script, which can be used to publish smart contract instances.
+
+While the man page for the tool can be referred to for general information of the tool usage, two argument flags warrant special mention in the context of this documentation.
+
+@table @code
+@item --demurrage-level
+The percentage of demurrage in terms of the redistribution period, defined as parts-per-million.
+@item --redistribution-period
+A numeric value denominated in @emph{minutes} to define the redistribution period of the voucher demurrage.
+@end table
+
+For example, to define a 2% demurrage value for a redistribution period of 30 days (43200 minutes), the argument to the argument flags would be:
+
+@verbatim
+erc20-demurrage-token-publish --demurrage-level 20000 --redistribution-period 43200 ...
+@end verbatim
+
+
+@section Calculating fixed-point values
+
+The @code{erc20-demurrage-token} package installs the python package @code{dexif} as part of its dependencies.
+
+This package in turn provides an epinymous command-line tool (@code{dexif}) which converts decimal values to a 128-bit fixed-point value expected by the contract constructor.
+
+An example:
+
+@example
+$ dexif 123.456
+7b74bc6a7ef9db23ff
+
+$ dexif -x 7b74bc6a7ef9db23ff
+123.456
+@end example
+
+
+@section Contract interaction with chainlib-eth
+
+All smart contract tests are implementing using @url{https://git.defalsify.org/chainlib-eth, chainlib-eth} from the chaintool suite.
+
+The @code{eth-encode} tool from the @code{chainlib-eth} python package may be a convenient way to interact with contract features.
+
+Some examples include:
+
+@example
+# explicitly call changePeriod()
+$ eth-encode --mode tx --signature changePeriod -e <contract_address> -y <key_file> ...
+
+# Set the sink address seal (The integer value of the SINK_STATE flag is 2 at the time of writing)
+$ eth-encode --mode tx --signature seal  -e <contract_address> -y <key_file> ... u:2
+
+# Query current sink address of contract
+$ eth-encode --mode call --signature sinkAddress -e <contract_address> ...
+@end example