erc20-demurrage-token

ERC20 token with redistributed continual demurrage
Info | Log | Files | Refs | README

contract.texi (8369B)


      1 @node contract
      2 @chapter Smart contract
      3 
      4 
      5 @section Common interfaces
      6 
      7 The smart contract is written in solidity, compatible with 0.8.x.
      8 
      9 It implements a number of interfaces both from the Ethereum (ERC) standards aswell as the Community Inclusion Currency contract interface suite.
     10 
     11 
     12 
     13 @subsection ERC standard interfaces
     14 
     15 @itemize @bullet
     16 @item
     17 @uref{https://eips.ethereum.org/EIPS/eip-20, ERC20 - Token Standard}
     18 @item
     19 @uref{https://eips.ethereum.org/EIPS/eip-165, ERC165 - Standard Interface Detection}
     20 @item
     21 @uref{https://eips.ethereum.org/EIPS/eip-173, ERC173 - Contract Ownership Standard}
     22 @item
     23 @uref{https://eips.ethereum.org/EIPS/eip-5679, ERC5679 - Token Minting and Burning (as part of CIC.Minter and CIC.Burner)}
     24 @end itemize
     25 
     26 @subsection CIC interfaces
     27 
     28 @itemize @bullet
     29 @item
     30 @uref{https://git.grassecon.net/cicnet/cic-contracts/src/branch/master/solidity/Burner.sol, Burner}
     31 @item
     32 @uref{https://git.grassecon.net/cicnet/cic-contracts/src/branch/master/solidity/Expire.sol, Expire}
     33 @item
     34 @uref{https://git.grassecon.net/cicnet/cic-contracts/src/branch/master/solidity/Minter.sol, Minter}
     35 @item
     36 @uref{https://git.grassecon.net/cicnet/cic-contracts/src/branch/master/solidity/Seal.sol, Seal}
     37 @item
     38 @uref{https://git.grassecon.net/cicnet/cic-contracts/src/branch/master/solidity/Writer.sol, Writer}
     39 @end itemize
     40 
     41 
     42 @section Dependencies
     43 
     44 The token contract uses the @url{https://github.com/abdk-consulting/abdk-libraries-solidity/blob/master/ABDKMath64x64.sol, ADBKMath} library to calculate exponentials.
     45 
     46 
     47 @section Permissions
     48 
     49 The smart contract defines three levels of access.
     50 
     51 @enumerate
     52 @item Voucher contract owner
     53 @item Voucher minter
     54 @item Voucher holder
     55 @end enumerate
     56 
     57 
     58 @subsection Contract owner
     59 
     60 When the contract is published to the network, the signer account of the publishing transaction will be the contract owner.
     61 
     62 Contract ownership can be changed by the owner using the @strong{ERC173} standard interface.
     63 
     64 
     65 @subsection Minter
     66 
     67 A minter has access to mint vouchers, and to burn vouchers from its own balance.
     68 
     69 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.
     70 
     71 The contract owner is automatically a minter.
     72 
     73 
     74 @subsection Holder
     75 
     76 Any address may hold vouchers, and transfer vouchers from their balance.
     77 
     78 Minters and the contract owner are automatically token holders.
     79 
     80 All token holders are subject to demurrage.
     81 
     82 
     83 @section Publishing the contract
     84 
     85 The contract is published with the following arguments:
     86 
     87 @table @samp
     88 @item name
     89 ERC20 voucher name
     90 @item symbol
     91 ERC20 voucher symbol
     92 @item decimals
     93 ERC20 decimal count
     94 @item decayLevel
     95 Level of decay per minute. @xref{specifying_demurrage, Specifying demurrage} below for further details.
     96 @item periodMinutes
     97 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. 
     98 @item defaultSinkAddress
     99 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.
    100 @end table
    101 
    102 
    103 @node specifying_demurrage
    104 @subsection Specifying demurrage
    105 
    106 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.
    107 
    108 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)}.
    109 
    110 @subsubsection Calculating the demurrage parameter
    111 
    112 The minute granularity of the demurrage value is calculating using the continuous decay function.
    113 
    114 For example, for a demurrage of 2% per 30 days (43200 minutes), the input value will be:
    115 
    116 @math{(1-0.02)^(1/43200) ~ 0.99999953234484737109} 
    117 
    118 The decimal part of the fixed-point representation of this value is:
    119 
    120 @code{fffff8276fb8cfff}
    121 
    122 The input parameter becomes:
    123 
    124 @code{0000000000000000ffffa957014dc7ff}
    125 
    126 @xref{tools, Tools} for additional help generating the necessary values.
    127 
    128 Note that attempting to publish a voucher contract with no (zero) demurrage will fail (if demurrage is not needed, use another contract).
    129 
    130 
    131 @section Using the contract
    132 
    133 @node withdrawing
    134 @subsection Withdrawing demurrage
    135 
    136 After each redistribution period, the demurraged value of that period can be withdrawn to the currently defined @emph{Sink Account}.
    137 
    138 The demurrage is calculated as from the total supply of voucher at the end of the period.
    139 
    140 Withdrawal should happen implicitly duing normal operation of the contract. @xref{sideeffects, Side-effects in state changes}.
    141 
    142 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.
    143 
    144 
    145 @node expiry
    146 @subsection Setting voucher expiry
    147 
    148 The effect of a voucher expiring is that all balances will be frozen, and all state changes affecting token balances will be blocked.
    149 
    150 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.
    151 
    152 The expiry takes effect immediately when the redistribution period time has been exceeded.
    153 
    154 When the contract is published, no expiry is set.
    155 
    156 Expiry may be set after publishing using the @code{CIC.Expire} interface.
    157 
    158 If the @code{EXPIRE_STATE} seal has been set, expiry may not be changed further.
    159 
    160 
    161 @node supply
    162 @subsection Capping voucher supply
    163 
    164 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.
    165 
    166 The supply cap still allows vouchers to be minted after @code{CIC.Burn} calls, provided that the previous condition holds.
    167 
    168 To apply the supply cap, the method @code{setMaxSupply(uint256) (6f8b44b0)} is used.
    169 
    170 
    171 @node sideeffects
    172 @subsection Side-effects in state changes
    173 
    174 All state changes involving voucher values implicitly execute two core methods to ensure application of the demurrage and redistribution.
    175 
    176 The two methods are:
    177 
    178 @table @code
    179 @item applyDemurrage() (731f237c)
    180 Calculates the demurrage modifier of all balances according to the current timestamp.
    181 @item changePeriod() (8f1df6bc)
    182 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.
    183 @end table
    184 
    185 Both of these methods are @emph{noop} if no demurrage or withdrawal is pending, respectively.
    186 
    187 Examples of state changes that execute these methods include @code{ERC20.transfer(...)}, @code{ERC20.transferFrom(...)} and @code{CIC.mintTo(...)}.
    188 
    189 
    190 @node seal_state
    191 @subsection Sealing the contract
    192 
    193 Certain mutable core parameters of the contract can be @emph{sealed}, meaning prevented from being modifier further.
    194 
    195 Sealing is executed using the @code{CIC.Seal} interface.
    196 
    197 The sealing of parameters is irreversible.
    198 
    199 The sealable parameters are@footnote{Please refer to the contract source code for the numeric values of the state flags}:
    200 
    201 @table @code
    202 @item WRITER_STATE
    203 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.
    204 @item SINK_STATE
    205 After setting this seal, the @emph{Sink Address} may not be changed.
    206 @item EXPIRY_STATE
    207 Prevents future changes to the voucher expiry date@footnote{The @code{EXPIRY_STATE} is implicitly set after expiration.}.
    208 @item CAP_STATE
    209 Immediately prevents future voucher minting, regardless of permissions.
    210 @end table
    211 
    212 
    213 @section Gas usage
    214 
    215 Gas usage is constant regardless of the amount of time passed between each execution of demurrage and redistribution period calculations.
    216 
    217 
    218 @section Caveats
    219 
    220 A @code{ERC20.transferFrom(...)} following an @code{ERC20.approve(...)} call, when called across period thresholds, may fail if margin to demurraged amount is insufficient.
    221