corrections

README.md

@@ -3,41 +3,49 @@
 ## Use Case
 * Network / Basic Income Token
   * 100 Sarafu is distributed to anyone in Kenya after user validation by the owner of a faucet which mints new Sarafu.
-  * Validated users are those that validate their phone number in Kenya
-  * A monthly Sarafu holding tax (demmurrage) of 2% is recorded as a `demurrageModiifer`.
-  * Supply and user actual balances stay the same but are displayed minus the `demurrageModiifer`.
-  * Each month the total amount of demurage is distributed out to users _active_ and the `demurrageModiifer` for each user is reset to zero.
-    *  a single transaction is considered _active_ (heartbeat).
-  * This is meant to result in a disincentivization to hold (hodl) the Sarafu token and increase it's usage as a medium of excahnge rather than a store of value.
+  * Validated users are those that validate their phone number in Kenya.
+  * A monthly Sarafu holding tax (demurrage) of 2% is deducted from users 
+  * Each month (after a number of blocks) the total amount tax is distributed evenly out to _active_ users.
+    *  any single transaction by a user is considered _active_ (heartbeat) (possibly add minimum size of heartbeat in constructor (TODO))
+  * This is meant to result in a disincentivization to hold (hodl) the Sarafu token and increase its usage as a medium of excahnge rather than a store of value.
 
 
-## Inputs to Constructor (Set only once during contract deployment)
+## Variables
 
-* 'Decay amount' (ppm) and period (blocks) is set at deploy time.
-  - Cannot be changed
-  - aka a holding Fee: A percentage of a users balance that will be charged and eventually redistributed to active users
-* Demmurage Period: The time frame over which a new Holding Fee is applied and redistributed.
+* Inputs to Constructor (Set only once during contract deployment can't be changed )  
+  * `Demmurage` aka Decay amount: A percentage of token supply that will be charged once per - aka `period` and evenly redistributed to _active_ users 
+  * Demmurage Period (blocks)- aka `period`: The number of blocks (equivalent to a time frame) over which a new Holding Fee is applied and redistributed. 
+  * Inflated Balance: The inflated balance of each user is stored for bookkeeping.
+  * Number of Decimals: Resolution on token (TODO) (Default 6)
+  * Minimum Activity Volume: (TODO) the minimum transaction amount to be considered active (Default 0)
+  * Minimum Activity Txns: (TODO) the minimum number of transaction to be considered active (Default 1)
+  * Sink Token Address: If no one trades the tax goes to this address
 
 
 ## Ownership
 
 * Contract creator is owner
-* Ownership can be transferred (also to ownership void contract to make permissionless)
+* Ownership can be transferred (also to ownership void contract "no more changes can be made")
 
 
 ## Mint
 
 * Owner can add minters
-  - A faucet contract would be a minter and set the amount of tokens to mint and distribute to new (validated) users.
+  - A faucet contract would be a minter and choose the amount of tokens to mint and distribute to new _validated_ users.
+  - The interface says the amount and is at the caller's discretion per contract call. _validation_ is outside of this contract.
 * Minters can mint any amount
 
 
 ## Demurrage
-* Tax is applied when a **mint** or **transfer** is triggered for first time in new period;
+* Holding Tax (`demurrage`) is applied when a **mint** or **transfer** is triggered for first time/block in a new `period`;
   - Supply _stays the same_.
-  - Updates `demurrageModiifer` which represents an exponential decay step (of size 'Decay amount' and is a a percentage of user balance)
-    - `demurrageModifier`_(i) = 'Decay amount' x demurrageModifier_(i-1) x user balance
+  - Updates `demurrageModifier` which represents the accumulated tax value and is an exponential decay step (of size `demurrage`) for each `period`
+    - `demurrageModifier = (1-demurrage)^period` 
+      - e.g. a `demurrage` of 2% at a `period` of 0 would be give a `demurrageModifier= (1-0.02)^0 = 1-1 = 0`.
+      - e.g. a `demurrage` of 2% at a `period` of 1 would be give a `demurrageModifier = (1-0.02)^1 = 0.98`.
+      - e.g. a `demurrage` of 2% at a `period` of 2 would be give a `demurrageModifier = (1-0.02)^2 = 0.9604`.
 * All client-facing values (_balance output_ , _transfer inputs_) are adjusted with `demurrageModifier`.
+  - e.g. `_balance output_ = user_balance - user_balance * demurrageModifier`
 * Edge case: `approve` call, which may be called on either side of a period.
 
 
@@ -45,14 +53,15 @@
 
 * One redistribution entry is added to storage for each period;
   - When `mint` is triggered, the new totalsupply is stored to the entry
-  - When `transfer` is triggered, and the account did not yet participate in the period, the entry's participant count `demurrageModifier` is incremented. 
+  - When `transfer` is triggered, and the account did not yet participate in the `period`, the entry's participant count is incremented. 
 * Account must have "participated" in a period to be redistribution beneficiary.
 * Redistribution is applied when an account triggers a **transfer** for the first time in a new period;
-  - Check if have participated in period.
-  - Balance is increased by `(total supply at end of period * demurrage modifier ) / number of participants`
-  - Participation field is zeroed out.
+  - Check if user has participated in `period`. (_active_ user heartbeat)
+  - Each _active_ user balance is increased by `(total supply at end of period * demurrageModifier ) / number_of_active_participants` via minting
+  - Participation field is zeroed out for that user.
 * Fractions must be rounded down (TODO)
-  - Remainder is "dust" and should be sent to a dedicated "sink" address (TODO)
+  - Remainder is "dust" and should be sent to a dedicated "sink" token address (TODO)
+  - If no one is _active_ all taxes go to the same sink address
 
 
 ## Data structures