XRP Ledger Stats

You can use this tool to fetch all the account balance information or a specific XRPL ledger number.

This tool will connect to a rippled-server using websockets. The default server it will connect to is s1.ripple.com. This server doesn't contain a lot of ledger history, so you can manually specify a different rippled-server.

Please note: the public rippled servers at s1.ripple.com (recent ledgers) and s2.ripple.com (full history) are used by many XRP apps and tools, so running your own rippled server (and connecting to that one, of course) will definitely improve performance. (rippled node: Docker Image).

Workflow

You'll need to have node (nodejs) installed on your computer. Node runs the JS (Javascript) code in this repository source.

0. If you are on Windows: install Git: https://git-scm.com/download/win
1. Clone this repository: git clone https://github.com/WietseWind/xrp-ledgerstats.git
2. Install dependencies: enter the cloned folder (on the commandline) using cd xrp-ledgerstats and run: npm install
3. Fetch a specific ledger into a local json file
4. Read the ledger data (from the local json file) and calculate stats
5. Show the stats in your terminal, and export the stats to a json file.

Syntax

Fetch ledger account data into .json file

Run the code to fetch all account balances using:

npm run fetch

If you don't append any arguments, the latest (closed) ledger will be fetched from the public s1.ripple.com server.

If you want to fetch a specific ledger, append the ledger index:

npm run fetch 38596307

Please note: to fetch a specific ledger, the server should have the data for this ledger. If you want to fetch a ledger that goes way back in time, you'll probably want to query s2.ripple.com (full history servers):

If you want to query a specific rippled node:

npm run fetch 32570 s2.ripple.com

(This tool will assume secure websockets (wss://) if you only enter a hostname. Prepend ws:// to connect to an insecure host)

Instead of a ledger number (or omitting one) you can also enter one of the rippled ledger info keywords:

npm run fetch "closed" s2.ripple.com

**The tool will save the balance information for the ledger in ./data/ledgerno.json, eg. ./data/38596307.json.

JSON output format

The JSON files stored in the ./data/ folder will contain all the accounts (balances[x].a) found in the given ledger index with their balances (balances[x].b):

{
  "stats": {
    "hash":"4109C6F2045FC7EFF4CDE8F9905D19C28820D86304080FF886B299F0206E42B5",
    "ledger_index":32570,
    "close_time_human":"2013-Jan-01 03:21:10"
    ,"total_coins":99999999999.99632
  },
  "balances": [
    {"a":"rBKPS4oLSaV2KVVuHH8EpQqMGgGefGFQs7","b":370},
    {"a":"rLs1MzkFWCxTbuAHgjeTZK4fcCDDnf2KRv","b":10000},
    {"a":"rpGaCyHRYbgKhErgFih3RdjJqXDsYBouz3","b":10000000},
    {"a":"rUnFEsHjxqTswbivzL2DNHBb34rhAgZZZK","b":10000},
    [ ... more data ]
  ]
}

Process ledger data from .json file (to stats)

Run:

npm run stats 32570

... where 32570 is the ledger index you want to process. You should -of course- have fetched this ledger first.

The stats will be displayed in the terminal and exported to ./data/ledgerno.stats.json in this format:

{
  meta: { ... },
  top100Balance: 123.567,
  accountPercentageBalance: [ 
    {
      percentage: 1,
      numberAccounts: 2,
      balanceEqGt: 3
    },
    { ... }
  ],
  accountNumberBalanceRange: [
    {
      numberAccounts: 1,
      balanceFrom: 2,
      balanceTo: 3,
      balanceSum: 4
    },
    { ... }
  ]
}

Batch processing

To download a ledger, calculate the stats, increment (backwards) and do the same all over again, you can use:

npm run batch {startledger} {rippledserver} {increment}

eg.

npm run batch 38630615 s2.ripple.com 100000

... to start at ledger 38630615 and then increment backin history by 100,000 ledgers.

The batch process will cleanup the downloaded ledger data (to save storage space). The json files containing the calculation results will be stored in ./data/.