bsips/bsip-0021.md

    BSIP: #021
    Title: Introducing the 'Coin-Age' statistic to Bitshares assets
    Authors: Customminer
    Status: Draft
    Type: Protocol
    Created: 2017-07-03
    Primary Discussion: https://steemit.com/bitshares/@cm-steem/bsip-020-draft-introducing-profit-sharing-dividends-to-bitshares-uia-only-input-would-be-massively-appreciated
    Similar Discussions: N/A
    Replaces: N/A
    Superseded-By: 
    Worker: N/A

# Abstract

Introducing the ability to query the 'Coin-Age' of assets held by individuals upon the BTS DEX.

# Motivation

* There exists no directly queryable 'coin-age' statistic within the Bitshares network.
* Currently, the closest we can get to querying an account's accumulated asset coin-age within the client is query an account's transaction history then calculate the coin-age with an external script.
* There aren't currently any open-source scripts for calculating user asset coin-age.

# Rational

* BSIPs 19 and 20 (Introducing profit-sharing/dividends for MPA(19)/UIA(20)) both reference a non-existent 'coin-age' statistic.
  * Proposed for proportionally distributing profit/dividends based on the length of time an asset has been held in the user's balance within the dividend time period, preventing abuse of the scheduled dividend.
* We have experienced market fluctuations/instability caused by publicly scheduled snapshots (users buy immediately before, snapshot, sell immediately afterwards); discouraging similar practices through the inclusion of 'coin-age' in the dividend mechanism could help neutralise this issue.
* Regarding consensus, there hasn't been sufficient discussion for users to voice disagreement against coin-age proposals.
* A legit concern is that if there are a significant quantity of asset holders & transactions to process, that evaluating accumulated_coin_age for all users could be computationally expensive.
* A concern regarding coin-age that this BSIP accounts for is if coins are held longer than the user specified time_period, that the coins start representing more than one of themselves (1 being worth 2 if held 2 times longer than the user input time period).

# Specifications

* For each chunk of a specific asset transfered to an user in the past, enable the easy querying/calculation of each user's accumulated 'coin-age' statistic.
* Possible route:
  * 1. Retrieve list of accounts holding chosen asset
  * 2. Given this list, query the account's current asset holdings (for chosen asset), returning the list of transactions that make up holdings.
  * 3. Evaluate coin-age from list of tx for each eligible asset holder.
  
* Draft coin-age calculation: (very much so example pseudocode, not production code!)
```
let reference_asset = USD; //User input variable
let time_period = 30 days; //User input variable
let accumulated_coin_age = 0;
let reference_time = current_time; //User input variable

if (whitelisted_accounts) {
    let eligible_asset_holders = whitelisted_accounts //whitelist input by user
} else if (blacklisted_accounts) {
    let eligible_asset_holders = asset_holder_list - blacklisted_account_list //blacklist input by user
} else {
    let eligible_asset_holders = asset_holder_list //include all asset holders.
}

for each asset_holder in eligible_asset_holders  {
    for each tx in asset_holdings {
        let tx_balance = current_tx_balance //Get the quantity of coins present in this transaction
        let time_diff = current_date - tx_inbound_date //Get the age of the transaction

        if (time_diff > time_period) {
            accumulated_coin_age += tx_balance //Prevent coins being worth more if held longer than time_period. Increase time_period to provide this functionality.
        } else {
            accumulated_coin_age += ((time_diff/time_period)*tx_balance)
        }
    }
    //Store current asset_holder & accumulated_coin_age in [hashmap|storage] for later referencing
}
```
* Coin-Age based individual-user dividend calculation:
```
if (whitelisted_accounts) {
    let total_eligible_token_supply = assets_held_by_whitelisted_accounts
} else if (blacklisted_accounts) {
    let total_eligible_token_supply = total_supply - assets_held_by_blacklisted_accounts
} else {
    let total_eligible_token_supply = total_supply
}

let total_distributable_tokens = 1000 OPEN.GRC; //quantity & token type set by user

for each asset_holder in coin_age_hashmap {
    dividend_allocation = (accumulated_coin_age/total_eligible_token_supply)*total_distributable_tokens
} 
```

# Discussion

## How does coin-age prevent abuse of BSIPs 19 & 20?

* If we were to perform a scheduled dividend based on a static snapshot of immediate account holdings, users could purchase the asset immediately prior to the scheduled dividend, receive the dividend then sell immediately afterwards, potentially causing market instability/fluctuations around the scheduled dividend.
* We have experienced this form of market instability in the past for protoshares (around past sharedrops) and for BTS (for peerplays).
(buy immediately beforehand, sell immediately afterwards, causing market instability around the scheduled dividend).

## Potential alternatives to 'coin-age' for preventing abuse of a dividend system

* Random snapshot date within sharedrop time period (similar to peerplay's secret snapshot date within possible snapshot range).
  * Downsides: Assets held outwith the moment of snapshot within the snapshot time period are not eligible for receiving dividends.
* Increasing market fees on the days surrounding the scheduled sharedrop? If an UIA has an additionally enabled fee market, a premium fee could be enabled potentially encouraging users to buy the assets earlier in the month & providing longer term asset holders additional profit? Would ony be possible for UIA, not MPA.
* Disabling of market trading in the days surrounding the dividend payment? This would be incresibly heavy handed & potentially scare asset holders, especially if the asset price fluctuaed on external exchanges.
* Entirely disregard any concerns of dividend system abuse? Openledger currently performs regular sharedrops onto Obits holders without taking coin-age into account!

# Summary for Shareholders

* No impact on shareholders, this would simply enable an additional queryable statistic within the Bitshares network for additional functionality proposed in BSIPs 19 and 20 to take advantage of.
* No worker proposal nor bounty proposed yet, simply brainstorming documentation within the community!
* Will be discussed/mentioned in a future BeyondBitcoin hangout.

# Copyright

N/A - Consider this BSIP entirely open-source/MIT-licensed, I am not the originator of the concept of 'coin-age' (several proof-of-stake cryptocurrencies make use of coin-age for finding stakable coins).

# See Also
* [List account balances - Graphene documentation](http://docs.bitshares.org/api/database.html#id8)
* [BSIP 21 Steemit thread](https://steemit.com/bitshares/@cm-steem/bsip-0021-draft-introducing-the-coin-age-statistic-to-bitshares-assets-input-would-be-massively-appreciated)