From 99adbef196e1241f0864fd4ca2c2e81b4f7aaf92 Mon Sep 17 00:00:00 2001 From: Will Ruddick Date: Thu, 4 Feb 2021 07:41:01 +0000 Subject: [PATCH 1/4] added use case example and small clarifications --- README.md | 31 ++++++++++++++++++++++++------- 1 file changed, 24 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 5e7f8d1..4bd9be2 100644 --- a/README.md +++ b/README.md @@ -1,25 +1,42 @@ # RedistributedDemurrageToken +## 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. + + +## Inputs to Constructor (Set only once during contract deployment) + +* '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. + + ## Ownership * Contract creator is owner -* Ownership can be transferred (also to ownership void contract) +* Ownership can be transferred (also to ownership void contract to make permissionless) ## Mint * Owner can add minters - - A faucet contract would be a minter + - A faucet contract would be a minter and set the amount of tokens to mint and distribute to new (validated) users. * Minters can mint any amount ## Demurrage - -* Decay amount (ppm) and period (blocks) is set at deploy time. - - Cannot be changed * Tax is applied when a **mint** or **transfer** is triggered for first time in new period; - Supply _stays the same_. - - Updates `demurrageModiifer` which represents an exponential decay step. + - 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 * All client-facing values (_balance output_ , _transfer inputs_) are adjusted with `demurrageModifier`. * Edge case: `approve` call, which may be called on either side of a period. @@ -28,7 +45,7 @@ * 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 is incremented. + - When `transfer` is triggered, and the account did not yet participate in the period, the entry's participant count `demurrageModifier` 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. From 6ca3dd2428bca499449cc334c06e3a6607da85f2 Mon Sep 17 00:00:00 2001 From: Will Ruddick Date: Thu, 4 Feb 2021 12:43:04 +0000 Subject: [PATCH 2/4] corrections --- README.md | 51 ++++++++++++++++++++++++++++++--------------------- 1 file changed, 30 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index 4bd9be2..8247cc2 100644 --- a/README.md +++ b/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 From 12d3cd4f4440ff7c0332e6c91d48a81e70bfa31b Mon Sep 17 00:00:00 2001 From: Will Ruddick Date: Thu, 4 Feb 2021 13:02:31 +0000 Subject: [PATCH 3/4] updates --- README.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 8247cc2..6995815 100644 --- a/README.md +++ b/README.md @@ -18,8 +18,7 @@ * 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 + * Sink Token Address: Rounding errors and if no one trades the tax goes to this address ## Ownership @@ -37,7 +36,7 @@ ## Demurrage -* Holding Tax (`demurrage`) is applied when a **mint** or **transfer** is triggered for first time/block in a new `period`; +* Holding Tax (`demurrage`) is applied when a **mint** or **transfer** is triggered for first time/block in a new `period`; (it can also be triggered explicitly) - Supply _stays the same_. - Updates `demurrageModifier` which represents the accumulated tax value and is an exponential decay step (of size `demurrage`) for each `period` - `demurrageModifier = (1-demurrage)^period` From 60f38996d88afca94b9d024a197cc7baf6025e9a Mon Sep 17 00:00:00 2001 From: Will Ruddick Date: Thu, 4 Feb 2021 13:04:29 +0000 Subject: [PATCH 4/4] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 6995815..2cf1e02 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ * 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 Volume: (TODO) the minimum transaction amount to be considered active * Sink Token Address: Rounding errors and if no one trades the tax goes to this address