Skip to content

These new docs are in beta. Please submit bugs to GitHub issues.


Lumen Supply Metrics

SDF’s Dashboard API endpoint will always have the live totals for the essential numbers around lumens. This guide explains important supply metrics like Original Supply, Total Supply, and Circulating Supply entailed in that data.

Dashboard API

As of December 12, 2019, the Dashboard API shows:

JSON
{
  "updatedAt": "2019-12-12T21:07:23.480Z",
  "originalSupply": "100000000000",
  "inflationLumens": "5443902087.3472865",
  "burnedLumens": "55442098181.3755700",
  "totalSupply": "50001803905.9717165",
  "upgradeReserve": "414310437.8111675",
  "feePool": "1807341.5766261",
  "sdfMandate": "29635032570.5297368",
  "circulatingSupply": "19950653556.0541861",
  "_details": "https://www.stellar.org/developers/guides/lumen-supply-metrics.html"
}

Definitions

originalSupply

One hundred billion lumens were created when the Stellar network went live. That’s the Original Supply for the network.

inflationLumens

For the first 5 or so years of Stellar’s existence, the supply of lumens increased by 1% annually. This “network inflation” was ended by validator vote on October 28, 2019. The total number of lumens generated by inflation was 5,443,902,087.3472865.

Adding this number to the Original Supply, you get the total lumens that have ever existed: 105,443,902,087.3472865. This number is visible on the List All Ledgers Horizon API endpoint as _embedded.records.total_coins.

burnedLumens

These are all the lumens sent to accounts with no signers, meaning the funds are inaccessible and have been removed forever from Stellar’s lumen supply.

While any address with no signers is counted here, the vast majority of the lumens in this sum are in a single locked address. On November 4, 2019, SDF reduced its lumen holdings to better reflect its mission and the growth of the Stellar ecosystem. To do so, the Foundation sent 55,442,095,285.7418 lumens to GALA…LUTO.

totalSupply

The Total Supply is the number of lumens now in existence: 50,001,803,905.97172. The Total Supply includes four major categories of lumens, which the API treats in detail:

upgradeReserve

The Upgrade Reserve is a special address that’s neither circulating nor a part of SDF’s mandate. When Stellar changed its consensus algorithm in 2015 and relaunched the network these lumens were set aside, to be claimed, one-for-one, by holders of the old network tokens. The Upgrade Reserve account is essentially an escrow, and we don’t expect many claimants to come and pull those lumens into the circulating supply at this point.

feePool

The Fee Pool is where network fees collect. The lumens do not belong to any particular account. No one has access to fee pool, so these lumens are non-circulating. Network validators could theoretically vote for a protocol change that would affect the fee pool, so we include it in the total supply. Stellar’s transaction fees are extremely low–1/100,000th of a lumen per operation–so the fee pool grows very slowly. The Fee Pool is tracked by the protocol itself, and the current number is visible on the List All Ledgers Horizon API endpoint as _embedded.records.fee_pool.

sdfMandate

The SDF Mandate is described in detail here. The Foundation was funded by lumens generated at Stellar’s inception; all of those lumens will eventually be spent or distributed to enhance and promote Stellar. Here is a complete list of the addresses currently associated with the SDF Mandate:

Name
Direct Development, Available Funds
Jan 1 2021 Escrow
Jan 1 2022 Escrow
Jan 1 2023 Escrow
Direct Development (Hot 1)
Direct Development (Hot 2)
Direct Development (Hot 3)
Developer Support
Developer Support (Hot)
Currency Support
New Products
Enterprise Fund
Marketing Support
In-App Distribution
In-App Distribution (Hot)

circulatingSupply

The Circulating Supply is lumens in the hands of individuals and independent companies. These are lumens out in the world, used to pay network fees and fund Stellar accounts. They are also used as a general medium of exchange. We expect Stellar’s Circulating Supply to grow steadily as SDF spends and distributes lumens according to its mandate. Lumens in the Total Supply, but not in the SDF Mandate, Upgrade Reserve, or Fee Pool are assumed to be circulating.

Last updated Sep. 23, 2020

Page Outline