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