Skip to content

Latest commit

 

History

History
106 lines (79 loc) · 6.6 KB

README.md

File metadata and controls

106 lines (79 loc) · 6.6 KB

Staking Rewards Collector v1.4.3

Disclaimer

Everyone using this tool does so at his/her own risk. Neither I nor Web3 Foundation guarantee that any data collected is valid and every user is responsible for double-checking the results of this tool. In addition to potential bugs in this code, you are relying on third-party data: Subscan's API is used to collect staking data and CoinGecko's API is used to collect daily price data.

This is no tax advice: Every user is responsible to do his/her own research about how stake rewards are taxable in his/her regulatory framework.

Changelog

Version 1.4.3

  • Subscan's API occasionally returns gibberish, added a loop to try again in such a case to improve UX.
  • Output files will now not be written for accounts that did not receive rewards.

Version 1.4.2

  • Added more info on which address did never receive any staking rewards.
  • Script does not terminate if one address did not receive any rewards.
  • Removed Tax variables.

Version 1.4.1

  • Added link to a tutorial to the README.
  • Script now does not terminate if one of the addresses did not receive any rewards in the specified time period.
  • Coingecko provides fiat prices with many decimals, which is not sensible to use in the output files. Fiat price of tokens will now be rounded to two decimals.
  • Changed priceData flag to true and false for consistency.
  • Changed initialInvestment to startBalance to more accurately reflect the meaning.

Version 1.4

Huge QoL improvement!

  • Specify as many addresses as you want in the userInput.json.
  • You can now also give your addresses a name.
  • Removed network-specifier. The script now automatically detects which network the address is from (for Kusama/Polkadot).
  • Added exportOutput: You can now specify if the output files should be generated or if you wish to just see your total staked amount in the terminal.

What can it do?

  • Collect staking rewards for a given public address (either Polkadot or Kusama) for a user-specified time window. The tool calculates the sum of staking rewards within that period.
  • If the time window allows it (check below some requirements for start and end date), it also collects daily price data and the fiat value of a stake reward given that day's opening price.
  • If a meaningful startBalance (in DOT or KSM) is provided, it can calculate the annualized return rate (extrapolated from your time window to one year).
  • The output is stored in table format as CSV file and as JSON object (with more detailed information). For easier processing of multiple addresses, the file names also contain the address.

How to run?

Requirements:

git clone [email protected]:w3f/staking-rewards-collector.git
cd staking-rewards-collector
Change the parameters inside the config/userInput.json to your needs.
yarn
yarn start

Tutorial

For a more detailed tutorial on how to set up the script, please go here(WIP).

How to use it?

Input

The program takes several inputs in the config/userInput.json file.

Staking Rewards:

  • addresses: A list of objects containing the address you want to parse the staking rewards, the name of your address and the startBalance.
  • startBalance: The amount of tokens from which the staking rewards are generated at the time of the start. Used to calculate the annualizedReturn, can be set to any number if the user is not interested in an accurate annualized return metric.
  • start (YYYY-MM-DD): The earliest day you want to analyze. Note that the earliest available prices for Polkadot are 2020-08-19 and 2019-09-20 for Kusama and that prices are set to 0 before that.
  • end (YYYY-MM-DD): The most recent day you want to analyze.

Price Data:

  • currency: In what currency you would like to have your value expressed (allowed: "CHF", "USD", "EUR", "GBP" and others available at CoinGecko.com).
  • priceData: Do you want to look up price data for your specified range? (allowed: "y", "n").

Output:

  • exportOutput: Specify if you want the .csv and .json files to be exported (allowed: "true", "false").

Output

After the tool executed successfully, it creates two files in the root folder. The JSON file contains some meta-data (e.g., sum of rewards and estimate of annualized return rate) and the CSV file gives the most important information in a table and thereby printable format.

CSV Output

The CSV output file contains a row for every day within the time frame where at least one staking reward occured. Other days are excluded. Example output:

https://i.imgur.com/4LCsDOc.png

JSON Output

The JSON output file contains a summary of the data as well as a list of objects for every day of the specified time-period (regardless of whether staking rewards occured). If your standard OS text editor does not format the file properly, you can copy the data and insert it to http://jsonviewer.stack.hu/ (click at "format" after paste). Example output:

https://i.imgur.com/QwXEGIN.png

The JSON Output contains:

Summary

  • Some information of your inputs (address, network, currency, startBalance).
  • firstReward: The day specified within your window you received your first reward.
  • lastReward: The day specified within your window you received your last reward.
  • annualizedReturn: The annualized return rate of your investment (if you provided a reasonable value for startBalance). The basis of this calculation is those days between firstReward and lastReward. It is only reasonable if you did not change too much in your staking situation (like deposited, withdraw etc.).
  • currentValueRewardsFiat: The current value of the staking rewards (at the most recent daily price specified by your time window).
  • totalAmountHumanReadable: The sum of staking rewards within your specified period in (new DOT or KSM).
  • totalValueFiat: The value of the staking rewards based on daily prices they were received.

Additional Data

  • numberRewardsParsed: The number of found staking rewards.
  • numberOfDays: The days between start and end.

List of objects

A list with objects for every day in your specified range. In the price of numbers (e.g. amountPlank) multiple staking rewards are added. In the case of strings, those are concanated.

Troubleshooting

  • SyntaxError: Unexpected token < in JSON at position 0: Sometimes the request to the Subscan API fails, which could cause this issue. Try to run the script again. If the error persists, please file an issue.