Realm netting is a multilateral obligation clearing register in GNOT. A convenor opens a netting set and admits members; each member declares, against other members, what it owes them; closing the set computes every member's NET position — what it is owed minus what it owes — and only those net amounts move. Net debtors pay in, net creditors withdraw, and a graph of G gross obligations collapses to at most N-1 transfers.
WHY THIS EXISTS (see DISCOVERY.md): across 641 live packages on gnoland-1 and 637 on onyx-1, thirteen chains mirrored in gnolang/tx-exports, and GitHub-wide `extension:gno`, no package records BILATERAL obligations between pairs of parties, computes net positions, or compresses gross obligations into net transfers. The two closest artifacts were read in full — mainnet p/moul/x/daily/pullpayment/v0 and r/moul/x/daily/splitter/v1 — and both fail on the same structural point: their ledgers are keyed by PAYEE ALONE, so there is no payer axis, no directed graph, and nothing to net. Both are ports of Solidity's canonical primitives, and both ports kept the one-dimensional ledger.
THE DELTA IS STATED AT ITS REAL SIZE AND NO LARGER. Multilateral netting is not a new idea — it is CLS, ACH, Sardex, the Romanian Ministry of Economy's national setoff, and a literature of graph algorithms (DISCOVERY.md § out-of-language prior art). What is new here is a Gno implementation, with this portfolio's live-validated custody discipline. Nothing more is claimed.
WHAT NETTING IS WORTH, HONESTLY: compression requires MUTUALITY. A star graph — every member owing one hub and the hub owing nobody — nets to itself, and the gross and net figures are identical. This realm therefore REPORTS the gross and net terms (Compression) and never asserts a saving. Read the two pairs of numbers; the ratio is whatever the members' obligations make it.
COMPOSITION: coin movement is delegated to coinio, fee arithmetic and the fee pot to feeledger, the declaration window and exactly-once settlement authorization to duebook, ordered storage to p/nt/avl/v0, and free-text render output to the ecosystem sanitizer p/nt/markdown/sanitize/v0. This realm owns only the netting arithmetic, the set state machine, and the conservation bookkeeping.
A NETTING SET HOLDS NO COINS WHILE IT IS OPEN. An obligation is a DECLARATION, not a transfer: Declare moves no value and locks none. Coins enter only at Settle, after the set has closed and net positions are frozen. This is why Cancel and Lapse need no refund path at all — there is nothing held to refund — and it is the sharpest difference between this realm and the escrow family the discovery gate found.
NET POSITIONS ARE MAINTAINED INCREMENTALLY, NOT COMPUTED AT CLOSE. Each Declare applies -amount to the debtor and +amount to the creditor in the same transaction, so the vector of net positions sums to zero by construction at every height. Close asserts that sum is zero anyway (netsSumToZero) before a single coin can be asked for. The assertion is unreachable through the public API and is kept because it is the one invariant whose violation would mint or destroy value.
THE SETTLEMENT IS ONE DEFERRAL. Open schedules exactly one duebook deferral per set — owner: the convenor, due: the declaration deadline, expiry: the end of the closing window — and the three transitions out of [open] are the three ways that deferral can be consumed:
Example
1Close -> book.Claim (due, not expired; ANYONE)
2Cancel -> book.Cancel (convenor renounces, while open)
3Lapse -> book.Expire (anyone, once the closing window is over)
Because duebook consumes a deferral before returning and never reuses an ID, a set can leave [open] AT MOST ONCE, structurally. The book's open-deferral cap is likewise this realm's cap on open sets.
LIFECYCLE (stored states in brackets):
Example
1Open (anyone) : opens [open]; caller is the convenor;
2 schedules the deferral.
3Admit (convenor) : adds a member, while [open]. Admission
4 obligates nobody: it only makes an
5 address a legal endpoint of a declaration.
6Declare (member) : "I owe this member X". Caller is ALWAYS
7 the debtor, so a declaration can only ever
8 increase the CALLER's own net debit. No
9 coins move.
10Close (ANYONE) : height in [deadline, closeEnd). Freezes
11 every net position. netValue == 0 (a fully
12 circular graph) settles on the spot with
13 no coins ever held -> [settled]. Otherwise
14 -> [settling] with a pay-in window.
15Settle (net debtor,+send): exactly the debtor's own net debit, once,
16 while [settling] and before settleEnd. The
17 last payment that completes the set
18 credits every net creditor -> [settled].
19Abandon (ANYONE) : [settling], settleEnd reached, still
20 short. Every debtor who paid gets exactly
21 what it paid back, FEE-FREE -> [abandoned].
22Cancel (convenor) : while [open] -> [cancelled]. No coins are
23 held, so nothing is refunded.
24Lapse (ANYONE) : [open] and closeEnd reached -> [lapsed].
25 The permissionless valve: a set nobody
26 closes cannot hold its duebook slot
27 forever.
28Withdraw (any creditor) : the caller's whole credit balance, in
29 coins. Pull-only; this realm never pushes.
30Prune (ANYONE) : removes a terminal set holding no coins.
31 The freed storage deposit is refunded by
32 the chain to the CALLER, which is the
33 incentive to call it.
34WithdrawFees (ANYONE) : pays the accrued fee pot to the
35 compile-time FeeCollector.
36SweepSurplus (ANYONE) : out-of-band coins to the FeeCollector,
37 never touching tracked liabilities.
ALL-OR-NOTHING, AND WHAT IT COSTS: a net creditor is credited only once EVERY net debtor has paid in full. One defaulting debtor therefore denies every creditor in that set — and the compensation is that no creditor is ever credited a ugnot the realm does not already hold, and every debtor who paid gets its money back fee-free. A partial-settlement design would pay some creditors from other debtors' money and need a rule for who; there is no such rule here because there is no such case.
THE FEE, precisely: feeBps is snapshotted at Open from the compile-time SettleFeeBps, so a set's terms are fixed when it is created and visible in SetInfo from that moment. It is charged ONCE, at the moment a set becomes [settled], on each net creditor's credit, with feeledger's floor rounding (rounding favors the creditor). The ledger is constructed with the compile-time MaxFeeBps cap, so a fee above the cap is refused by the primitive, not by a check in this file. There is no fee on declaring, no fee on settling, and NO FEE ON ANY ABANDON REFUND.
THERE IS NO ADMIN. The fee rate, the fee collector, every bound and every window are compile-time constants; no address can change terms, pause the realm, or touch a set it does not convene. The convenor's only powers are admitting members and cancelling its own set while it is open — neither of which can move a coin. The deployer has no privilege of any kind after deployment.
MONETARY INVARIANT (conservation): let H be the ugnot held at this realm's address, P the sum of coins paid in for sets still [settling] (tracked O(1) as totalPending), L the ledger's liabilities (unclaimed creditor credits, unclaimed abandon refunds, and the fee pot), and S >= 0 the out-of-band surplus:
Example
1H == P + L + S
Every transition moves value between exactly two terms inside one transaction: Settle raises H and P together (coinio.Receive is the receipt-guaranteed shape); completing a set moves netValue out of P and into L, split into creditor credits and the fee; Abandon moves paidIn out of P and into L fee-free; Withdraw and WithdrawFees debit L before the identical amount leaves H (checks-effects-interactions); any panic aborts the whole transaction; this realm never issues or removes coins.
ONLY GNOT IS ACCEPTED: Settle rejects any envelope that is not exactly one positive ugnot coin (coinio.Receive). Every other entrypoint rejects attached coins outright rather than converting them into sweepable surplus.
AUTHORIZATION: every identity is derived from the crossing entrypoint's cur.Previous().Address(). No function takes a caller identity as a parameter, so declaring a debt as another member, settling another member's net debit, or withdrawing another creditor's balance is impossible by construction.
STORAGE: a set record is paid for by the convenor's transaction deposit, a member record by the convenor's Admit, and a pair record by the declaring debtor's own transaction. Completing or abandoning a set drops nothing; Prune removes the whole terminal record, and the chain refunds the freed deposit to the transaction that frees it.
