WIP texinfo docs, elaborate on tools, supply cap

This commit is contained in:
lash 2023-05-15 15:22:59 +01:00
parent 0ed97b36b0
commit 091967bafd
Signed by: lash
GPG Key ID: 21D2E7BB88C2A746
3 changed files with 91 additions and 1 deletions

View File

@ -4,6 +4,12 @@
@section Common interfaces @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 @subsection ERC standard interfaces
@itemize @bullet @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. 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 @node sideeffects
@subsection Side-effects in state changes @subsection Side-effects in state changes

View File

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

View File

@ -1,2 +1,57 @@
@node tools @node tools
@chapter 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