Files
observer/crates/blackbeard-core/src/concentration.rs
T
grenadeandClaude Opus 5 da7f773564
deploy / build (push) Successful in 7m40s
deploy / deploy-api (push) Successful in 16s
deploy / deploy-web (push) Successful in 6s
feat: how concentrated the balance is, once the treasury is set aside
The last piece of #17. It was specified as "the share of issuance held by the
top 1, 10 and 100" plus a Gini, and done literally that produces a number that
is true and says nothing — because the top account is the vesting pot holding
99.5% of the chain. The figure would sit near 1.000 and move only when the pot
paid out, describing an undistributed reserve rather than an economy.

So the pot is reported first and then excluded, by its own storage key rather
than by being the largest: "the biggest account" is a description that would
silently start meaning something else the day the pot drains. Everything else
is computed over what is left and labelled as being outside it.

The denominator is the counted balance, not issuance. The two differ, and in
the direction that matters: a wormhole exit credits its destination without
debiting the note's source, so balances summed across the chain exceed
issuance, and shares of issuance would add up to more than everything.

Measured on mainnet: 1,949 accounts, 27,245 QTC outside the pot, top 1 at
39.6%, top 10 at 72.2%, top 100 at 92.2%, Gini 0.965. That top holder is a
mining address — keyless, its balance a cumulative receipt that cannot fall
however much its operator pays out — so the panel says in its own words that
this is partly a statement about who mined most rather than who holds most.

The Gini lives in `blackbeard-core` with its own tests, per the rule about
statistics being easy to overstate and hard to notice: pinned against the
published coefficient for 1,2,3,4, and against a dust holder beside two whales,
which is the case an `f64` accumulator would round away and report as perfect
equality between the whales.

`RpcClient::storage_values` is new — `state_queryStorageAt`, which turns two
thousand round trips into four. Chunked at 500 rather than sent whole because
nothing documents a ceiling here, and an undocumented ceiling is one that gets
discovered in production.

Nothing renders unless the account walk reached the end of the map. Every share
divides by a total, and a partial sum makes all of them wrong while looking
entirely reasonable.

Closes #17

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-14 15:32:11 +03:00

104 lines
4.1 KiB
Rust
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
//! How unevenly a set of balances is shared.
//!
//! Here rather than beside its caller because it is arithmetic with no I/O in
//! it, and because a concentration figure is the kind of number that is wrong
//! by a factor and still looks entirely plausible on a page.
/// Gini coefficient over **ascending** values.
///
/// `G = 2·Σ(i·xᵢ) / (n·Σxᵢ) − (n+1)/n`, the standard discrete form with `i`
/// one-based. 0 is an even share; 1 is one holder with everything.
///
/// The sums stay in `u128` and only the final ratio becomes a float. Balances
/// on this chain run to 10^16 and `Σ(i·xᵢ)` over a couple of thousand of them
/// passes 10^19, which is past where an `f64` counts integers exactly —
/// accumulating in one would lose the low end of the distribution, and the low
/// end is the half this coefficient is most sensitive to.
///
/// `None` for an empty set or one that holds nothing at all: there is no
/// concentration to report, and returning zero would say "perfectly equal",
/// which is a different and much stronger claim.
///
/// The caller must sort. Doing it here would mean copying the slice or taking
/// it mutably, and every caller has just sorted anyway to take its top-N.
pub fn gini(ascending: &[u128]) -> Option<f64> {
let n = ascending.len();
if n == 0 {
return None;
}
let total: u128 = ascending.iter().copied().fold(0u128, u128::saturating_add);
if total == 0 {
return None;
}
let weighted: u128 = ascending.iter().enumerate().fold(0u128, |acc, (i, x)| {
acc.saturating_add((i as u128 + 1).saturating_mul(*x))
});
let n_f = n as f64;
let g = 2.0 * (weighted as f64) / (n_f * total as f64) - (n_f + 1.0) / n_f;
// The arithmetic cannot leave [0, 1] for non-negative inputs, but a float
// landing on -0.0000001 would render as "-0.000".
Some(g.clamp(0.0, 1.0))
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn an_even_share_is_zero() {
assert_eq!(gini(&[1, 1, 1, 1]), Some(0.0));
assert_eq!(gini(&[7_000, 7_000]), Some(0.0));
}
/// One holder among `n` gives `(n-1)/n`, never quite 1 — the coefficient
/// cannot reach 1 for a finite population, and a test expecting it to would
/// be wrong about the measure rather than about the code.
#[test]
fn one_holder_among_four_is_three_quarters() {
let g = gini(&[0, 0, 0, 4]).expect("non-empty, non-zero");
assert!((g - 0.75).abs() < 1e-12, "{g}");
}
/// Pinned against the textbook value for 1,2,3,4.
#[test]
fn a_known_distribution_matches_its_published_coefficient() {
let g = gini(&[1, 2, 3, 4]).expect("non-empty");
assert!((g - 0.25).abs() < 1e-12, "{g}");
}
/// Nothing to measure is not perfect equality. Reporting zero here would
/// put "0.000 — an even share" on a page describing an empty chain.
#[test]
fn nothing_to_measure_is_absent_rather_than_even() {
assert_eq!(gini(&[]), None);
assert_eq!(gini(&[0, 0, 0]), None);
}
/// The reason the sums are not `f64`. These balances are past 2^53, so an
/// accumulator that lost the small holder would report a perfectly even
/// share of two identical whales instead of the real concentration.
#[test]
fn a_dust_holder_beside_whales_survives_the_arithmetic() {
let whales = 5_000_000_000_000_000_000u128;
let g = gini(&[1, whales, whales]).expect("non-empty");
assert!(g > 0.3, "the dust holder was rounded away: {g}");
assert!(g < 0.34, "{g}");
}
/// Scaling every balance by the same factor cannot change how evenly they
/// are shared. Catches an accumulator overflowing or a denominator drifting.
#[test]
fn the_coefficient_is_scale_invariant() {
let small = gini(&[1, 2, 3, 4, 90]).expect("non-empty");
let large = gini(&[
1_000_000_000_000,
2_000_000_000_000,
3_000_000_000_000,
4_000_000_000_000,
90_000_000_000_000,
])
.expect("non-empty");
assert!((small - large).abs() < 1e-9, "{small} vs {large}");
}
}