Skip to main content

Token Balance

Examples from our RPC are used. If you want to look at information about archival nodes (more than 2 days ago), please use archival prefix in your URL (e.g. https://archival-rpc.mainnet.near.org) In this article, we always use POST methods to the same URL https://archival-rpc.mainnet.near.org. Body:

{
"jsonrpc": "2.0",
"id": "dontcare",
"method": "EXPERIMENTAL_tx_status",
"params": ["8uxq5BAC4zZL4Set7gtraqZSWduYXRUiNggpKhWmBnzK", "nf-finance.near"]
}

Every account has liquid balance (called amount) and stake (called locked). All calculation in tables are in yoctonear.

Total supply is the amount of tokens in the whole system. Each example is selected at the moment when no other changes is performed in the blockchain, so the only example could affect total supply.

Why does my balance change?

There are different scenarios why the amount of tokens could change on the account. Let's look at it on real examples.

Each example (except rewarding) contains fees user pays for the operation. You could read about fees calculation here.

Transfer of tokens

https://explorer.mainnet.near.org/transactions/6gUVYsdAsStzU5H2AyW7bxAdEL4RvJv5PL3b8DRnPVED

pine.near sent 1.64234 tokens to taka.near

block heightpine.near amounttaka.near amounttotal supplyexplanation
327868201997461904089428600000000177997991782722911000000001020393325841554327182410255742095initial state
32786821355076598029241100000000177997991782722911000000001020393325841554327182410255742095pine.near lost some tokens for transferring and fees (with a margin, some tokens will be returned)
32786822355076598029241100000000194421391782722911000000001020393325841532008926160255742095taka.near received exactly 1.64234 tokens. Total supply was deducted for making receipt from transaction
32786823355077267576928600000000194421391782722911000000001020393325841509690669910255742095pine.near received a change. Total supply was deducted for executing receipt
32786824355077267576928600000000194421391782722911000000001020393325841509690669910255742095final state

For such kind of transactions, sender pays 2 fees: for making receipt from transaction; for executing receipt.

We also have receipt for returning a change: it is made without fee.

For this example, final cost of transferring tokens was 22318256250000000000 * 2 / 10^24 = 0.0000446365125 Near Tokens.

Creating the account

https://explorer.mainnet.near.org/transactions/Hant2anxPJHm3sh8ncc5AWn5VpXTmwq6iyEumVoQcUJP

nearcrowd.near created account app.nearcrowd.near, gave the access key, transfer some tokens for that account. These 3 actions are usually go together.

block heightnearcrowd.near amountapp.nearcrowd.near amounttotal supplyexplanation
32396638117975002547050142700000000-1019767988635277999737307820909366initial state (app.nearcrowd.near does not exist)
3239663917974916362372455200000000-1019767988635277999737307820909366nearcrowd.near spent tokens on transfer and fees (with a margin, some tokens will be returned). Total supply is not changed for now: process is not finished
32396640179749163623724552000000001000000000000000000000000001019767988635235544231057820909366app.nearcrowd.near was created with initial amount of tokens. Total supply was deducted for making receipt from transaction
32396641179749176360376427000000001000000000000000000000000001019767988635193088724807820909366nearcrowd.near received a change. Total supply was deducted for executing receipt
32396642179749176360376427000000001000000000000000000000000001019767988635193088724807820909366final state

For such kind of transactions, sender pays 2 fees: for making receipt from transaction; for executing receipt.

We also have receipt for returning a change: it is made without fee. For this example, final cost of creating account and transferring tokens were 42455506250000000000 * 2 / 10^24 = 0.0000849110125 Near Tokens.

Deleting the account

https://explorer.mainnet.near.org/transactions/8nZeedU6RUnj65zxQYHrGx2Urx5sLe6J2T123xSNL2RK

It's not possible to delete not your account: user is always deleting their own account. User should provide beneficiary account that receive all tokens. User could provide the account that does not exist, in such case the tokens will burn.

wxx.near deleted their account with beneficiary vng.near

block heightwxx.near amountvng.near amounttotal supplyexplanation
319614544561723763543551132406467195605256272004000000001019079411898934110106918776083373initial state
31961455-7195605256272004000000001019079411898934110106918776083373wxx.near was deleted
31961456-11756817922815555132406461019079411898883000406918776083373vng.near received tokens (minus fee), total supply was deducted by fees getting burned
31961457-11756817922815555132406461019079411898883000406918776083373final state

For such kind of transactions, sender pays 2 fees: for making receipt from transaction; for executing receipt.

Note: we do not have the change. For this example, final cost of deleting account was 25554850000000000000 * 2 / 10^24 = 0.0000511097 Near Tokens.

Calling a function

https://explorer.mainnet.near.org/transactions/8oBZrKk8jkAzrsYasoL2DW9Yg6K2GznLhvoiXmSm7kHe

relayer.bridge.near invoked a function in the contract of client.bridge.near

block heightrelayer.bridge.near amountclient.bridge.near amounttotal supplyexplanation
3245100592769537245739099490000000010187091866465227095000000001019836940956022237114094657887001initial state
3245100692767623813540018275302932410187091866465227095000000001019836940956022237114094657887001the function is invoked, relayer.bridge.near spent the tokens on the fees (with a margin)
3245100792767623813540018275302932410187101769660669458000000001019836940955771421812122457887001author of the function gets the reward. Total supply was deducted for making receipt from transaction
3245100892769156976163959600000000010187101769660669458000000001019836940953209860906932057887001relayer.bridge.near received a change for fees. Total supply was deducted for executing receipt
3245100992769156976163959600000000010187101769660669458000000001019836940953209860906932057887001final state

For such kind of transactions, sender pays 2 fees: for making receipt from transaction; for executing receipt. Receiver gets part of the fee as a reward for a possibility to invoke their function.

For this example, final cost of invoking the function was (250815301972200000000 + 3551880449426700000000) / 10^24 = 0.0038026957513989 Near Tokens. Reward was 0.0009903195442363 Near Tokens.

TODO: add Nomicon link about royalties when this issue will be resolved.

The example of calling a function could be more complex.

https://explorer.mainnet.near.org/transactions/DuGWWTK2sAxjffifJiJBv6hs3Hc8MdhpHnzgRJryV4Be

lulukuang.near invokes a function in a protocol of berryclub.ek.near. It triggers berryclub.ek.near to send the money to third account, farm.berryclub.ek.near. So we need to analyze 3 accounts in this scenario.

block heightlulukuang.near amountberryclub.ek.near amountfarm.berryclub.ek.near amounttotal supply
324488981356582256128232901154459946826631063030877372419969717951043707945615560097083951019836941925593000345074757887001
324488991355315481424426437382491946826631063030877372419969717951043707945615560097083951019836941925593000345074757887001
324489001355315481424426437382491946801159450069587449800233717951043707945615560097083951019836941925350190357602757887001
324489011356334894526832492264365546801159450069587449800233717953593477180689101359057551019836941924550160945561757887001

Adding the key

https://explorer.mainnet.near.org/transactions/A9767GbmRCLdeCpZYfKTQUqe17KyAu5JrZHanoRChMSV

slavon.near added the key to their own account.

block heightslavon.near amounttotal supplyexplanation
3245228141100958528380154137246071019836940258537920949718457887001initial state
3245228241100537746941096137246071019836940258537920949718457887001fees are gone
3245228341100537746941096137246071019836940258495842805812657887001total supply was deducted
3245228441100537746941096137246071019836940258495842805812657887001final state

For such kind of transactions, sender pays 2 fees: for making receipt from transaction; for executing receipt.

Note: we do not have the change. For this example, final cost of adding the key was 21039071952900000000 * 2 / 10^24 = 0.0000420781439058 Near Tokens.

Deleting the key

https://explorer.mainnet.near.org/transactions/CfuXcVPy7vZNVabYKzemSwDdNF9fnhbMLaaDKjAMyw8j

77yen.near deleted the key from their own account.

block height77yen.near amounttotal supplyexplanation
324294283508920323609722000000001019836950055687104230777157887001initial state
324294293508514311359722000000001019836950055687104230777157887001fees are gone
324294303508514311359722000000001019836950055646503005777157887001total supply was deducted
324294313508514311359722000000001019836950055646503005777157887001final state

For such kind of transactions, sender pays 2 fees: for making receipt from transaction; for executing receipt.

Note: we do not have the change. For this example, final cost of adding the key was 20300612500000000000 * 2 / 10^24 = 0.000040601225 Near Tokens.

Deploying the contract

https://explorer.mainnet.near.org/transactions/3DN4XiQCX2EeSN5sjiaB4WBjJizthbhUfqQhCBcZK57A

ref-finance.near deployed the contract.

block heightref-finance.near amounttotal supplyexplanation
32378845421664430620294682000000001019767995481527182962669020909366initial state
32378846421659294554136584000000001019767995481527182962669020909366fees are gone
32378847421659294554136584000000001019767995481013576346859220909366total supply was deducted
32378848421659294554136584000000001019767995481013576346859220909366final state

For such kind of transactions, sender pays 2 fees: for making receipt from transaction; for executing receipt.

Note: we do not have the change. For this example, final cost of deploying the contract was 256803307904900000000 * 2 / 10^24 = 0.0005136066158098 Near Tokens.

Receiving the reward for being validator

NB: No transaction/receipt is associated with such type of balance changing.

On the boundary of the epochs, validators receive reward. The platform gives 10% of minted tokens to special account treasury.near. You could think about treasury.near as about reward to the whole system to keep it in working order. Total sum of the rewards (including treasury.near) is the increase of total supply in the system.

total supplytreasury.nearcomment
block 3271625210202535863143358291448188546808152047777174062240806436499682917
block 3271625310203234666969600987221575409037072054765212324667764170368305209
difference698803826242695773386862228926988038262426957733868622292treasury received 10% of reward

If the validator does not change the stake during the epoch, all the reward will go to their stake. Liquid balance will remain the same.

block heightbaziliknear.poolv1.near amountbaziliknear.poolv1.near locked (stake)
32716252876459294173821015486886408174051739369484142981303684413288
32716253876459294173821015486886408174052372556336355400023161624996

baziliknear.poolv1.near had 4M tokens on their locked balance. Their reward for the epoch was 633186852212418719477211708 / 10^24 = 633.1868522124187 tokens.

If the validator decreases the stake during the epoch, it will be actually decreased at the boundary between the epochs. The reward will also go to the liquid balance in such case.

block heightastro-stakers.poolv1.near amountastro-stakers.poolv1.near locked (stake)d1.poolv1.near amountd1.poolv1.near locked (stake)artemis.poolv1.near amountartemis.poolv1.near locked (stake)
block 3271625275643656264518222662518079298148718756857031047051379792785333957963606154941867570431746390022159268861166429746754414921954551916356131961162212503155647821138218410536743286795
block 32716253779688659593411873323413901501487187568570310470513797927853340986873900034981089977167653900221592631440017627007544149231558432763298540237328595080450
diff232520969482296466982331085201407237838485562414272850190-5717164667046000000003155647821138218410536743286795-3155647821138218410536743286795

astro-stakers.poolv1.near decided to put the reward to liquid balance, so they invoked a command (e.g. ping). We can see that the stake does not change between the epochs.

d1.poolv1.near decided to slightly decrease the stake size, so the reward and the part of the stake are on the liquid balance.

artemis.poolv1.near received the reward and stopped being validator at that epoch, so all the stake are on the liquid balance, stake becomes zero.

The reward value is calculated based on stake size and number of calculated blocks per epoch. Read more about it here

If the validator increase the stake during the epoch, stake will be increased in next few blocks, we do not need to wait for the moment of the epoch boundary. For current epoch, blockchain will take into account stake value fixed at the start of the epoch.

https://explorer.mainnet.near.org/transactions/HajXjY1gSf47jakXP44ERecjFE2hFvF4FgRyQzNdZzDZ

elecnodo.near put 245.7788678019393 tokens from its locked account 57bea511f28a9c0d44148c332826a9b9fb14f13c.lockup.near to a staking pool staked.poolv1.near

Read more about epochs changing here.