supply-conservation.md specifies the per-block
rule: no block may increase the total of all balances. This document is about
the other question, the one that rule cannot answer — at a given height, how
much rBTC is outstanding, how much bitcoin is held against it, and how to
compare the two without reaching a wrong conclusion.
Two tools, one per side:
| tool | side | what it reads |
|---|---|---|
rbtc_supply |
RSK | every account balance in the unitrie at one state root |
bridge_btc_holdings |
Bitcoin | the Bridge's own UTXO bookkeeping at the same state root |
Both are read-only and safe against a live node.
The short version: you cannot subtract one tool's output from the other's and read the difference as a surplus or a deficit. Four separate terms sit between the two figures, and three of them are large enough to swamp the result. The method below exists to account for them. Section 6 works a real example in which the naive subtraction appears to show a deficit and the correct accounting shows comfortable headroom.
The intuition is that circulating rBTC should equal bitcoin held. It does not, for four reasons, and each has a definite sign.
Locked rBTC — makes the RSK side look bigger than the claim really is.
REMASC withholds fees when one of its selection rules is broken. The function
that does it, add_to_burned in
crates/execution/src/remasc.rs, only
increments a burnedBalance storage counter. It transfers nothing and
destroys nothing. The rBTC stays in REMASC's balance, is counted in any sum
over accounts, and no code path ever pays it out — BURNED_BALANCE_KEY is
written by that function and read by no other, and the single transfer out of
REMASC pays amounts from the reward calculation. So it is issued, counted, and
permanently unclaimable.
That it cannot be a true burn is provable from the tool's own output: the sum over all accounts is exactly the genesis premine. Had anything ever been destroyed, the total would have fallen below it.
Unregistered bitcoin — makes the Bitcoin side look smaller than it is.
bridge_btc_holdings reports what the Bridge has registered, which is not
everything the federation controls. A peg-in inside the 100-confirmation
window is held but untracked. Bitcoin below the minimum peg-in value is never
registered at all and stays at the federation address indefinitely. Change
from a peg-out re-enters the set only once the spending transaction is itself
registered, so a recent peg-out can leave a very large output invisible to the
Bridge for hours.
Bitcoin miner fees — a genuine, permanent, one-way leak. Peg-out and federation-migration transactions pay their bitcoin fees out of peg funds. No rBTC is retired when they do, so every such transaction moves the two sides a little further apart, forever. This is the only one of the four that is a real reduction in backing rather than a measurement artefact.
Addresses nobody is summing. Flyover peg-ins pay a P2SH derived per quote and are never swept into the federation address, so the federation address alone does not answer the question. Retired federation addresses may also hold remnants.
cargo build --release -p rustock-cli --examples
# RSK side. --log gets progress and the report; --top 0 skips the rich list.
./target/release/examples/rbtc_supply \
/var/lib/rustock /var/lib/rustock/trie-epochs-flat <block|head-N> \
--threads 3 --log /path/to/rbtc_supply.log
# Bitcoin side, at the SAME height. The trailing hash160 is optional and only
# labels the active federation's script instead of leaving it unnamed.
./target/release/examples/bridge_btc_holdings \
/var/lib/rustock /var/lib/rustock/trie-epochs-flat <same block> \
a2aaed588a584e3b190d8219d3668749f52ece8aUse the same height for both, and prefer head-N over head so the state is
settled. An epoch node keeps only a window of state; older heights need an
archive trie.
On threads: rbtc_supply defaults to the machine's parallelism. On a box
shared with the production node, set --threads to leave it a core. Three
workers walk the full mainnet trie — 12.6 million nodes — in about 80 seconds.
The walk is modelled on snapshot::verify_complete and reuses the
children_size every node commits: it splits the trie by byte weight,
repeatedly halving the largest piece so no straggler dominates the tail, and
reports progress as bytes genuinely accounted for rather than nodes guessed
at. Progress lines carry a percentage and an ETA every ten seconds.
## unitrie census at #9395466
accounts 558452
code leaves 24715
storage roots 24868
storage slots 5729116
unrecognised 0
undecodable 0
unrecognised and undecodable must both be zero. They are the tool's own
honesty check: a leaf whose key does not classify, or an account record that
does not decode, would mean a balance was silently dropped from the sum.
Anything non-zero invalidates the run.
sum of all balances 21,000,000.000000000000000000 RBTC
genesis premine 21,000,000.000000000000000000 RBTC
-> conserved: the sum is exactly the premine, as it must be
This is the strongest validation available. RSK mints nothing: genesis hands the Bridge the entire 21,000,000 RBTC and every later balance is a slice of that one premine, so the total is invariant at every height. Hitting it to the wei requires the bit-path tracking, the key classification and the RLP decode to be simultaneously correct.
A mismatch here is reported as NOT CONSERVED. It means a node bug or a
corrupt state — it says nothing about peg backing and must not be read as
one.
in the Bridge 20,998,880.452185099190347926 RBTC
ISSUED (outside it) 1,119.547814900809652074 RBTC
REMASC (0x...01000008), where block fees accumulate:
balance 2.709955825463821677 RBTC
burnedBalance 2.701510584930417566 RBTC
rewardBalance 0.000078048098750301 RBTC
ISSUED is 21,000,000 − balance(Bridge) — rBTC outside the Bridge. It is
not the claim on bitcoin; subtract the locked portion first.
Do not treat REMASC's whole balance as locked. Only burnedBalance is.
rewardBalance is still owed to miners, and the remainder (here 0.00837 RBTC)
is live fee income awaiting distribution. Both are ordinary claims.
## active federation set (newFederationBtcUTXOs)
5.97157803 BTC across 15 UTXO(s)
a2aaed588a584e3b190d8219d3668749f52ece8a 5.94378748 13 ACTIVE federation
b7de8fe34e6e9b342e8b59b288b39ca2d590b07c 0.01768935 1 derived (Flyover)
4e53e4f0dccd1e68c1609efe3388af84c49f7435 0.01010120 1 derived (Flyover)
Grouped by scriptPubKey, then listed outpoint by outpoint so the set can be
diffed against what the addresses actually hold on Bitcoin. tx_hash is
stored and printed in display order — do not byte-reverse it before
looking it up in a block explorer.
The derived scripts are Flyover peg-ins. Each quote pays its own P2SH,
P2SH(PUSH(derivationHash) OP_DROP <federationRedeem>), and nothing sweeps
them into the federation address; they stay put until a peg-out spends them.
This is why the federation address alone understates the peg.
Remember what this total is: registered bitcoin, not held bitcoin. To get held bitcoin, query the addresses themselves.
claimable rBTC = issued rBTC − burnedBalance
bitcoin accounted = held at the federation address
+ held at every Flyover-derived address
+ held at any retired federation address
solvency: claimable rBTC ≤ bitcoin accounted
The inequality is not expected to be tight. Unregistered bitcoin and peg-ins in the confirmation window leave the right-hand side larger; cumulative bitcoin miner fees pull it down over time. The margin between them is the peg's headroom.
Note the direction of the ordinary lags. A peg-in puts bitcoin at the address
roughly 100 confirmations before the rBTC is credited; a peg-out burns rBTC
immediately and pays bitcoin later. Both make the bitcoin side the larger
one. So a deficit is the direction that demands an explanation, whereas a
surplus is routine. If you compute a deficit, the first hypothesis should be
that a term is missing from your accounting — most likely burnedBalance, or
bitcoin at addresses you have not summed — not that rBTC is unbacked.
This is the case the method was built for, because the naive subtraction gets it backwards.
Naive, and wrong. Take ISSUED and the two tools' bitcoin figures:
| BTC | |
|---|---|
| issued rBTC | 1119.547814900809652074 |
federation address 3GX89qzy…, unspent on Bitcoin |
1119.39512544 |
| + the two Flyover-derived UTXOs | 0.02779055 |
| bitcoin accounted for | 1119.42291599 |
| apparent difference | −0.124898910809652074 |
Read literally this says 0.125 BTC of rBTC is unbacked. It is wrong, because
ISSUED has not had the locked portion removed.
Correct. Subtract burnedBalance, which is issued but permanently
unclaimable:
| BTC | |
|---|---|
| issued rBTC | 1119.547814900809652074 |
less locked in REMASC (burnedBalance) |
−2.701510584930417566 |
| claimable rBTC | 1116.846304315879234508 |
| bitcoin accounted for | 1119.42291599 |
| headroom | +2.576611674120765492 |
The inequality holds with 2.58 BTC of margin. The locked balance exceeds the apparent difference by more than twentyfold.
At this height bridge_btc_holdings reports 5.97 BTC registered while the
federation address holds 1119.40. That gap is the registration lag, and it
resolves outpoint by outpoint. The thirteen UTXOs the Bridge tracks at the
federation script are an exact subset of the address's eighteen unspent
outputs; five are held but untracked:
| txid:vout | BTC | BTC height | confirmations | why untracked |
|---|---|---|---|---|
f91bd374…:2 |
1112.79006583 | 975,085 | 10 | peg-out change, inside the 100-confirmation window |
07f8036e…:1 |
0.16035391 | 975,084 | 11 | same |
aef2ece9…:10 |
0.50000000 | 974,428 | 667 | unexplained; see below |
a2a6d5d1…:1 |
0.00090322 | 969,454 | 5,641 | below the minimum peg-in — never registrable |
3d1d82d8…:18 |
0.00001500 | 946,211 | 28,884 | same |
Confirmations are tip − height + 1 at Bitcoin tip 975,094, the snapshot
these figures were taken against.
f91bd374 is a peg-out: one input of 1123.64 BTC from the federation, two
payments to a user totalling 10.85 BTC, and 1112.79 BTC of change back to the
federation address. The change re-enters the Bridge's set once the transaction
is registered, which needs 100 confirmations. That single output is 99.4% of
the gap and it is pure timing — re-running the tool a day later is the test.
The two dust outputs are permanent. They sit below the minimum peg-in, so the Bridge will never register them; they are bitcoin the peg holds and no rBTC claims, which adds to headroom.
aef2ece9…:10 is the one open item: past the confirmation window, above the
minimum, yet untracked while vouts 11–21 of the same transaction are all
tracked. The likely explanation is that it was selected into a peg-out and
removed from the active set at build time, with the spending transaction not
yet confirmed — pegoutsWaitingForConfirmations would show that. Unverified.
unrecognisedorundecodablenon-zero — the run is invalid, fix before reading anything else.NOT CONSERVED— a node bug or corrupt state. Not a peg finding.claimable rBTC > bitcoin accounted, after every term in section 5 has been included and the bitcoin side has been read from the addresses rather than from the Bridge's registered set. Before concluding anything, confirm the bitcoin snapshot is contemporaneous with the RSK height, and check the addresses in section 8 that these tools do not yet sum.
Honest limits of the method as it stands:
- Cumulative bitcoin miner fees paid from peg funds by peg-outs and migrations. The mechanism is certain and the leak is permanent; the total is not measured here. One observed peg-out paid 3,160 sat, which suggests the historical sum is small relative to the locked balance, but that is an inference from a single sample.
- Retired federation addresses.
federation_intervalsrecovers the key sets for all seventeen historical federations, from which their addresses can be rebuilt and queried. Remnants there would be unsummed backing. - Unregistered Flyover peg-ins. Only the derived addresses the Bridge tracks are counted; bitcoin paid to a derived P2SH that was never registered is invisible to both tools.
All three cut in the favourable direction — the first reduces an already unmeasured leak, the other two would add bitcoin — so none of them threatens a headroom result. They matter for making the accounting exact.