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>
104 lines
4.1 KiB
Rust
104 lines
4.1 KiB
Rust
//! 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}");
|
||
}
|
||
}
|