Skip to content

One real mainnet day, netted: 336 payments become 9 transfers - #12

Merged
samjay8 merged 2 commits into
mainfrom
feat/mainnet-day
Oct 27, 2026
Merged

samjay8 merged 2 commits into
mainfrom
feat/mainnet-day

Conversation

@samjay8

@samjay8 samjay8 commented Oct 27, 2026

Copy link
Copy Markdown
Contributor

Closes #8.

What SetOff would have changed on a real day. Every USDC payment between institutions on Stellar mainnet on 2026-10-21: 336 payments between 10 institutions (exchanges, Circle and others), 55.5M USDC in total.

Settlement USDC moved Saved Transfers
Gross, as it happened 55,532,924.24 336
Bilateral 53,505,367.08 3.7% 13
Multilateral (SetOff) 53,355,736.73 3.9% 9

336 payments become 9 transfers. Value moved fell only 3.9%, because that day's flows were mostly one-way (exchanges and Circle), and netting can't offset one-way flows. The gain is operational: 37 times fewer transactions to sign, fee and reconcile.

  • tools/mainnet_day.py (stdlib only) builds the window:
    • Institutions: stellar.expert's directory gives 480 accounts tagged exchange, anchor, custodian or wallet, grouped into 229 institutions.
    • Payments: Horizon gives each account's USDC payments for the day (Circle's issuer only), and only those between two different institutions are kept.
    • Rows: each row id is the on-chain operation id, so every row can be checked, and amounts are exact stroops.
  • data/mainnet-2026-10-21.csv is the day. examples/mainnet_day.rs nets it.
  • docs/mainnet-day.md has the method, the numbers and the limits. It's a lower bound: three very busy accounts hit the per-account page cap, and the directory isn't complete.
  • Simulator:
    • A real mainnet day loads this day, with its provenance, and shows results in USDC.
    • Import CSV reads id,debtor,creditor,asset,amount files in the page. Malformed lines are reported by line number, and the rest load. Nothing is uploaded.

Done-when from #8

  • The corridor vector imported as CSV shows the vector's exact transfers. tests/fixtures/remittance-corridor.csv is that vector, and a Rust test keeps it identical to the JSON.
  • A malformed line is reported against its line number.

The issue says "the same result as the built-in example", but the built-in corridor example has different amounts from the vector. So the check is against the vector's own expected result, which is what the issue is after.

Checked

  • cargo fmt --check, cargo clippy --workspace --all-targets --all-features, and cargo test --workspace --all-features all pass, including the new fixture test.
  • A Playwright run in Chrome against the locally built wasm passes 14/14:
    • Import: the corridor CSV gives the vector's exact plan; bad amount, short row and bad header are each reported on the right line; a quoted comma survives.
    • Mainnet day: it loads with its note; Binance's net matches the CLI's 48,919,022.28; it shows 336 → 9; the other examples return to whole units.
    • General: no horizontal scroll at 390 px, and no script errors.

tools/mainnet_day.py builds a netting window from real Stellar data: every
account stellar.expert's directory tags as an exchange, anchor, custodian
or wallet (480 accounts, 229 institutions), and each one's USDC payments
(Circle's issuer) for one UTC day from Horizon, keeping those between two
different institutions. Each row's id is its operation id, so it can be
checked on an explorer; amounts are exact stroops.

data/mainnet-2026-10-21.csv is that day: 336 payments between 10
institutions, 55.5M USDC. examples/mainnet_day.rs nets it: 336 payments
become 9 transfers, while value moved falls only 3.9% because the day's
flows were mostly one-way. docs/mainnet-day.md has the method, the
numbers and the limits (three busy accounts hit the page cap, so it is a
lower bound), and the README summarizes it.
Import CSV reads the format setoff net and read_csv take into the table, in
the page. A small parser handles quoted fields, checks the header, and
reports each malformed line by number while loading the good ones.

A real mainnet day loads data/mainnet-2026-10-21.csv (copied into the site
by pages.yml), with a note on where it comes from. Its amounts stay exact
stroops in the table, and results are shown in USDC (7 decimals), so a
plan line no longer reads as trillions.

tests/fixtures/remittance-corridor.csv is the corridor vector as CSV, and
a test keeps it identical to the JSON vector. Importing it shows the
vector's exact transfers.

Closes #8.
@samjay8
samjay8 merged commit 4571489 into main Oct 27, 2026
12 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[enhancement]: import a CSV of obligations into the simulator

1 participant