CultLib/packages/heimdall-stake/README.md
Libby 84f932ec50
Some checks failed
CultMesh QUIC native / Build win32-x64 (pull_request) Has been skipped
CultMesh QUIC native / Build linux-x64 (pull_request) Has been skipped
CultMesh QUIC native / Release native binaries (pull_request) Has been skipped
CultMesh portability and performance / ubuntu-latest one-command multiplayer onboarding (pull_request) Has been cancelled
CultMesh portability and performance / windows-latest one-command multiplayer onboarding (pull_request) Has been cancelled
CultMesh portability and performance / ubuntu-latest reactive semantics and leases (pull_request) Has been cancelled
CultMesh portability and performance / windows-latest reactive semantics and leases (pull_request) Has been cancelled
CultNet cross-runtime interop / C# / TypeScript / Rust / Python / Kotlin (pull_request) Has been cancelled
CultMesh QUIC native / Verify committed binaries match SHA256SUMS (pull_request) Has been cancelled
heimdall-stake: sybil note and golden vectors
README: the constant 1 in weight = 1 + log_b(amount/unit) is paid once per identity, so splitting
always pays until the log goes negative and no base fixes it; the defence lives outside the function.
Golden vectors (single and split k=1,2,10,100, three bases) computed with 60-digit decimal ln,
pinned by tests/golden.rs.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-06 02:30:58 +00:00

100 lines
5.7 KiB
Markdown

# heimdall-stake
Heimdall's stake function: how much weight an amount of money buys one identity. Pure,
deterministic, no I/O, no dependencies; integer cents in, integer micro-weights out
(`MICRO` = 1,000,000 = a weight of 1.0), and an integer-only logarithm, so the same inputs give
the same bits on every platform. Entry points: `weight` and `splitting_gain` in `src/lib.rs`.
Live: the formula, the three Heimdall parameters, the splitting-gain report and their property
tests (`tests/properties.rs`). Not here: the estate rule that normalizes weights, the sybil
adversary, storage, and any projection. Every parameter is a placeholder until the estates rule.
## First call
```
cargo run --example first_call # prints the Meta example and a splitting table
cargo test
```
```rust
use heimdall_stake::*;
let p = Params::meta_example(); // unit 1 EUR, log10
assert_eq!(weight(&p, 100_00).unwrap(), 3 * MICRO); // 100 EUR
assert_eq!(weight(&p, 10_000_00).unwrap(), 5 * MICRO); // 10,000 EUR
let costly = Params { min_amount_per_identity_cents: 50_00, ..p };
let r = splitting_gain(&costly, 100_00, 3).unwrap(); // 100 EUR as three identities of 33.33
assert_eq!((r.one_identity, r.split_total), (3 * MICRO, 0));
```
The output feeds `heimdall-delegation`'s integer `weight`; the caller picks the scale.
## Formula
Per Meta, `weight = 1 + log_b(amount / unit)`, with the base `b` and the `unit` set by the charter.
Meta's example: unit 1 EUR, `b` = 10: 100 EUR weighs 3, 10,000 EUR weighs 5 (both tested exactly).
Amounts are integer cents; negative and zero amounts weigh 0. The result is clamped at 0 (an
amount under `unit / b` would otherwise go negative) and rounded to the nearest micro-weight.
Heimdall's parameters on top:
- `floor_cents`: an amount **at or below** the floor weighs 0. (The brief said both "below" and
"at/below"; at-or-below is implemented and tested.)
- `per_identity_cap`: the most weight one identity can hold, in micro-weights; `None` is uncapped.
- `min_amount_per_identity_cents`: an identity holding **less** than this is ineligible and weighs 0.
`floor` and `min_amount_per_identity` both zero a weight and compose; they differ in what they are
for (the floor trims dust from the formula, the minimum prices an identity), and the estates may
want one parameter instead of two.
Properties (tested): monotone in the amount for any parameters; concave above the unit when no
floor or minimum intrudes (the floor and minimum are steps, so the whole function is not concave);
zero at and below the floor; the cap is never exceeded and binds; deterministic; total over every
`i64` including `i64::MIN`; the integer log agrees with `f64` to 2 micro-weights; bad parameters
(`base < 2`, `unit == 0`) are `Err`, not panics.
## Splitting gain
`splitting_gain(params, budget_cents, k)` puts one budget in one identity and, separately, evenly
over `k` identities, and reports both totals, the gain, how many split identities are eligible and
the smallest share. `splitting_curve` and `most_profitable_split` sweep `k`.
The log formula's `+1` is a splitting incentive: with no minimum, 100 EUR as ten identities of
10 EUR weighs 20 against 3 as one. The minimum is the only lever that prices it, and it prices it
as a cliff, not a slope: with a 50 EUR minimum, 100 EUR split in two still gains (5.40 against 3.00
in the example), and split in three weighs 0. So the minimum has to sit near the size of a typical
budget to deter splitting, and the report is how to see where it does.
## Why the sybil defence cannot live here
`weight = 1 + log_b(amount / unit)` pays the constant 1 once per identity. Splitting a budget into
k identities pays that 1 k times and costs only the logarithm's shrinkage, so splitting wins until
the log term goes negative: with unit 1 EUR and b = 10, 100 EUR weighs 3 as one identity, 5.40 as
two, 20 as ten and 100 as one hundred (`tests/vectors/stake_golden.csv`, pinned by
`tests/golden.rs`). No choice of `b` fixes this: `b` scales the log term and never the constant.
A cap or a per-identity minimum only moves the cliff (see Splitting gain). So the defence belongs
outside the function: non-transferable or vesting stake, a per-person cap on total stake, and a
cost to create an identity. This crate states the incentive; it cannot remove it.
## Where this sits in the estate rule
This crate does not normalize. The estate rule normalizes weights above it; the weights here are
raw. A sybil rate (how many identities an adversary splits a budget into) is an adversary the
simulation harness plays, not a parameter of this function; `splitting_gain` is its closed-form
probe for the even-split case only.
## Prior art
Sources below are from background knowledge and were not re-fetched for this README; verify before
citing.
- **Quadratic voting** (Lalley and Weyl, "Quadratic Voting: How Mechanism Design Can Radicalize
Democracy", 2018; Posner and Weyl, *Radical Markets*, 2018): the cost of v votes is v², so the
marginal price rises linearly and vote weight grows with the square root of spend. Lalley-Weyl
show it is efficient in large populations under assumptions that include no collusion and no
identity splitting, and that identity splitting is exactly what breaks it. Our weight grows
slower still (log), so the money buys less influence at the top, and the same sybil caveat applies
with the same remedy: a cost per identity.
- **Logarithmic weight** has the same shape as diminishing-returns utility (Bernoulli) and as the
concave caps in some stake-weighted systems; here its role is only concavity, with the charter
choosing how fast through the base.
- **Sybil attack** (Douceur, 2002): without a cost per identity, an open system cannot tell one
participant from many. The per-identity minimum is that cost, in money.