commit 091967bafdad4e1b3f5e168a4475c648f9dcfdf5
parent 0ed97b36b0c337095a27bbed8eff6a2463357d5a
Author: lash <dev@holbrook.no>
Date: Mon, 15 May 2023 15:22:59 +0100
WIP texinfo docs, elaborate on tools, supply cap
Diffstat:
3 files changed, 91 insertions(+), 1 deletion(-)
diff --git a/doc/texinfo/contract.texi b/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
diff --git a/doc/texinfo/overview.texi b/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
+
+
diff --git a/doc/texinfo/tools.texi b/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
