The token contract uses the @url{https://github.com/abdk-consulting/abdk-libraries-solidity/blob/master/ABDKMath64x64.sol, ADBKMath} library to calculate exponentials.
@section Permissions
The smart contract defines three levels of access.
@enumerate
@item Voucher contract owner
@item Voucher minter
@item Voucher holder
@end enumerate
@subsection Contract owner
When the contract is published to the network, the signer account of the publishing transaction will be the contract owner.
Contract ownership can be changed by the owner using the @strong{ERC173} standard interface.
@subsection Minter
A minter has access to mint vouchers, and to burn vouchers from its own balance.
Only the contract owner may mint, and may add and remove minters. Minters may be added and removed using the @strong{CIC Writer}interface, as long as the @code{WRITER_STATE} seal is not set. @xref{seal_state, Sealing the contract} for further details.
The contract owner is automatically a minter.
@subsection Holder
Any address may hold vouchers, and transfer vouchers from their balance.
Minters and the contract owner are automatically token holders.
All token holders are subject to demurrage.
@section Publishing the contract
The contract is published with the following arguments:
@table @samp
@item name
ERC20 voucher name
@item symbol
ERC20 voucher symbol
@item decimals
ERC20 decimal count
@item decayLevel
Level of decay per minute. @xref{specifying_demurrage, Specifying demurrage} below for further details.
@item periodMinutes
Number of minutes between each time the demurraged value can be withdrawn to the @emph{Sink Account}. @xref{withdrawing, Withdrawing demurraged value} below for further details. The period may not be altered.
@item defaultSinkAddress
The initial @emph{Sink Address}. The address may be altered as long as the @code{SINK_STATE}seal has not been set. @xref{seal_state, Sealing the contract} for further details.
@end table
@node specifying_demurrage
@subsection Specifying demurrage
The @emph{input parameter} to the contract is a 128-bit positive fixed-point number, where the most significant 64 bits represent the integer part, and the lower 64 bits represents the decimals part, each consecutive lesser bit halving the value of the previous bit.
For example, The byte value @code{00000000 00000002 a0000000 00000000}, representing a zero-stripped binary value of @math{10.101}. This translates to the (base 10) decimal value @math{2.625}. The decimal part is calculated as, from left to right: @math{(1 * 0.5) + (0 * 0.25) + (1 * 0.125)}.
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.
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.
All state changes involving voucher values implicitly execute two core methods to ensure application of the demurrage and redistribution.
The two methods are:
@table @code
@item applyDemurrage() (731f237c)
Calculates the demurrage modifier of all balances according to the current timestamp.
@item changePeriod() (8f1df6bc)
If the previously executed period change does not match the current period, the period is changed, and the @emph{Sink Address} is credited with the demurrage amount of the current total supply.
Examples of state changes that execute these methods include @code{ERC20.transfer(...)}, @code{ERC20.transferFrom(...)} and @code{CIC.mintTo(...)}.
@node seal_state
@subsection Sealing the contract
Certain mutable core parameters of the contract can be @emph{sealed}, meaning prevented from being modifier further.
Sealing is executed using the @code{CIC.Seal} interface.
The sealing of parameters is irreversible.
The sealable parameters are@footnote{Please refer to the contract source code for the numeric values of the state flags}:
@table @code
@item WRITER_STATE
The @code{CIC.Writer} interface is blocked. The effect of this is that no more changes may be made to which accounts have minter permission.
@item SINK_STATE
After setting this seal, the @emph{Sink Address} may not be changed.
@item EXPIRY_STATE
Prevents future changes to the voucher expiry date@footnote{The @code{EXPIRY_STATE} is implicitly set after expiration.}.
@item CAP_STATE
Immediately prevents future voucher minting, regardless of permissions.
@end table
@section Gas usage
Gas usage is constant regardless of the amount of time passed between each execution of demurrage and redistribution period calculations.
@section Caveats
A @code{ERC20.transferFrom(...)} following an @code{ERC20.approve(...)} call, when called across period thresholds, may fail if margin to demurraged amount is insufficient.
