netting state

RealmPath

RealmPath is this realm's own path, used to build Render links.

Denom

Denom is the only asset this realm holds.

MaxFeeBps

MaxFeeBps is the hard ceiling on any fee this realm could ever charge, enforced by the feeledger the realm is constructed with — a feeBps above it is refused by the primitive's own validation, not by a check in this file. 500 bps = 5%.

SettleFeeBps

SettleFeeBps is the fee actually snapshotted into every set at Open: 100 bps = 1%, charged once, when the set becomes settled, on each net creditor's credit, floor-rounded in the creditor's favor. 1% is the most conservative live fee in this portfolio (fee\_split precedent) and is what crowdfund charges.

FeeCollector

FeeCollector receives withdrawn fees and swept surplus. Compile-time constant: there is no setter and no transfer path. It is the deploying namespace's address — stated plainly: the operator of this realm.

MinObligation

MinObligation keeps dust declarations out of the graph: 0.001 GNOT. Declaring costs no coins, so the only thing a dust declaration wastes is the declarer's own storage deposit — but a graph full of 1-ugnot edges makes the compression figures meaningless, which is the output this realm exists to produce.

MaxMembers

MaxMembers caps one set's membership. Close iterates the member tree twice (once to assert the nets sum to zero, once to freeze positions), and completing a set iterates it once more to credit creditors, so this is the bound that keeps every O(M) pass inside a transaction's gas. 32 is deliberately modest: a clearing set is a counterparty group, not a population.

MaxPairs

MaxPairs caps the DISTINCT ordered (debtor, creditor) pairs one set may hold. Declarations themselves are unbounded in count — a repeat declaration between an existing pair accumulates into that pair's record and allocates nothing — so this bounds storage, not activity. MaxMembers\*(MaxMembers-1) == 992 is the complete digraph; 256 is a deliberate fraction of it.

MinDeclareBlocks

MaxDeclareBlocks

CloseWindowBlocks

CloseWindowBlocks is how long after the deadline a set may still be closed. Past it, Close is impossible (the deferral has expired) and Lapse is the only way out — which strands no money, because an open set holds none.

SettleWindowBlocks

SettleWindowBlocks is how long net debtors have to pay in after a set closes. Past it, Abandon refunds every payer fee-free.

MaxOpenSets

MaxOpenSets caps simultaneously open sets, via the duebook's own open-deferral cap. The AVAILABILITY BOUND this implies is stated rather than hidden: when the book is full, Open fails until a set is closed, cancelled or lapsed. Settling and terminal sets do not occupy a slot — their deferral is already consumed.

MaxOpenPerConvenor

MaxOpenPerConvenor bounds how much of the global cap one convenor may occupy (permission\_registry R1 precedent: an uncapped per-principal share of a global cap is a griefing vector, not a feature).

MaxLabelLen

MaxMemoLen

MaxRenderRows

MaxRenderRows bounds the list length on the render pages.

stateOpen

set states. "open" and "settling" are the two non-terminal states; "settling" is the only state in which this realm holds coins for a set.

stateSettling

set states. "open" and "settling" are the two non-terminal states; "settling" is the only state in which this realm holds coins for a set.

stateSettled

set states. "open" and "settling" are the two non-terminal states; "settling" is the only state in which this realm holds coins for a set.

stateAbandoned

set states. "open" and "settling" are the two non-terminal states; "settling" is the only state in which this realm holds coins for a set.

stateCancelled

set states. "open" and "settling" are the two non-terminal states; "settling" is the only state in which this realm holds coins for a set.

stateLapsed

set states. "open" and "settling" are the two non-terminal states; "settling" is the only state in which this realm holds coins for a set.

member

member is one party to a netting set. net is maintained incrementally by Declare and is the whole of the netting arithmetic: positive means the member is owed that much on balance, negative means it owes that much. debit and credit are FROZEN AT CLOSE from net, so that the settlement figures cannot move after coins have been asked for.

set

self

sets

// padID(id) -> \*set

nextID

openByConvenor

totalPending

lifetimeSets

// sets that reached \[settled]

lifetimeGrossValue

// declared value across every closed set

lifetimeNetValue

// net value across every closed set

lifetimeSettledIn

// coins paid in by net debtors

lifetimeCredited

// credited to net creditors, net of fee

lifetimeRefunded

// returned by Abandon, fee-free

lifetimeWithdrawn

// paid out of the ledger to creditors

ledger

book

init.39

rejectStraySend

rejectStraySend aborts when coins are attached to a non-payable call. This realm holds funds, so a stray send would become sweepable surplus, silently converting a user's coins into operator funds. Aborting reverts the transfer instead. Guarded on IsUserCall, not IsUser, because a MsgRun ephemeral can consume the OriginSend envelope before forwarding control; for a realm-routed call the envelope lands at the intermediary, so there is nothing here to reject and the guard deliberately fails open (crowdfund and treasury\_board document the same scope).

Open

Open convenes a netting set and returns its id. Anyone may open one; the caller becomes the convenor. The fee terms (SettleFeeBps at this moment — a compile-time constant, so always SettleFeeBps) are snapshotted into the set and are fixed from here on. declareBlocks is the length of the declaration window and must be within \[MinDeclareBlocks, MaxDeclareBlocks] — enforced by the duebook. The convenor is NOT automatically a member. A convenor that wants to net its own obligations must Admit itself, which keeps "who runs the set" and "who is party to it" separate concepts.

Admit

Admit adds an address to a set's membership while the set is open. Convenor only. ADMISSION OBLIGATES NOBODY. Being a member only makes an address a legal endpoint of a declaration — it cannot be made a debtor by anyone but itself (see Declare). What admission does control is the griefing surface: without it, any address could fill a set to MaxPairs with declarations naming strangers, and the convenor could not form the group it meant to form.

Declare

Declare records that the CALLER owes a fellow member \`amount\` ugnot, while the set is open. No coins move and none are locked: an obligation is a declaration, and the only value this realm ever holds arrives at Settle. The caller is ALWAYS the debtor. That is the whole authorization model here and it is worth saying plainly: a declaration can only increase the caller's own net debit and some other member's net credit, so no address can be made to owe anything by anyone else. Declaring repeatedly toward the same creditor accumulates into one pair record and allocates no new storage.

Close

Close freezes every net position in a set and opens the pay-in window. Anyone may call it, from the declaration deadline until the closing window ends; the duebook Claim consumes the set's deferral, so this can succeed at most once per set, ever. A set whose net value is ZERO — every member's obligations exactly cancelled, which is what a fully circular graph produces — settles on the spot. No coins are ever asked for, held, or paid, and the gross value is extinguished in one transaction. That case is the whole point of the realm, so it is the fast path rather than a special one.

Settle

Settle pays in the caller's own net debit, in full, once. The attached envelope must be exactly the caller's frozen net debit — not more, not less, and not in instalments. Partial payment is refused rather than accommodated: it would leave the set holding money that belongs to neither the payer nor any creditor, and a rule for who gets it first. The payment that completes the set credits every net creditor in the same transaction and the set becomes settled.

completeSet

completeSet converts a fully-funded set's pay-ins into creditor credits and marks it settled. It is reached only from Settle, only when paidIn == netValue, and it is where the fee is charged. The ORDER is the conservation argument: paidIn and totalPending are debited by exactly netValue, and the identical netValue is deposited into the ledger as credits plus fee. feeledger.Deposit credits amount-fee and accrues fee, so the two sides agree to the ugnot.

Abandon

Abandon ends a set that reached its settlement deadline still short, and credits every debtor who paid exactly what it paid, FEE-FREE. Anyone may call it: the outcome is fully determined by the set's own state, so there is nothing for a caller to steer. Net creditors receive nothing on this path, and that is the all-or-nothing guarantee working rather than failing: they were never credited, so there is no clawback, and no creditor was ever paid from another debtor's money.

Cancel

Cancel ends an open set. Convenor only, any time while the set is open. No refund path is needed and none exists: an open set holds no coins, because a declaration is not a transfer. What members lose is the storage deposit and gas they spent declaring, which is stated plainly rather than hidden — a convenor can waste a member's gas but can never touch a member's money.

Lapse

Lapse ends an open set whose closing window has passed. Anyone may call it. This is the permissionless valve: a set nobody closes cannot hold its duebook slot forever, and because an open set holds no coins there is nothing stranded by the outcome.

Withdraw

Withdraw pays the caller its entire credit balance in coins and returns the amount. Pull-only: this realm never pushes a payout, so a creditor that cannot receive coins can never block a settlement. Credits arrive from a settled set (net of that set's fee) and from an abandoned set's refund (fee-free); both land in the same balance.

Prune

Prune removes a terminal set that holds no coins, reclaiming its storage. Anyone may call it: the chain refunds the freed storage deposit to the pruning transaction, which is the incentive. Credits already in the ledger are unaffected — they are a per-address balance, not part of the set record.

WithdrawFees

WithdrawFees pays the entire accrued fee pot to the compile-time FeeCollector. Anyone may call it: the destination is fixed, so there is nothing for a caller to steer.

SweepSurplus

SweepSurplus sends out-of-band coins to the FeeCollector: for the pot denom, everything above tracked liabilities; for any foreign denom, the full balance. Pending pay-ins, creditor credits and the fee pot are untouchable by construction (coinio.Sweep refuses to dip below the reserve). Anyone may call it.

SetInfo

Compression

Compression returns the four numbers the product exists to produce: how many obligations were declared and for how much, against how many transfers the netting leaves and for how much. The RATIO IS NOT RETURNED and is not asserted anywhere — divide them if you want it, and note that netValue can legitimately be zero (a fully circular graph, the best possible case), which is exactly why no ratio is computed here. While a set is still open the net figures are zero because they are frozen at Close, not derived on read.

SetLabel

SetLabel returns a set's label, verbatim and unsanitized. Render sanitizes; a caller reading the raw value gets the raw value.

SetMemo

SetMemo returns a set's memo, verbatim and unsanitized.

Status

Status returns a set's stored state.

IsMember

IsMember reports whether an address is party to a set.

NetOf

NetOf returns a member's live net position: positive when it is owed that much on balance, negative when it owes that much. It is live while the set is open and frozen thereafter. A non-member reads 0, which is also a member's value when its obligations cancel exactly — use IsMember to tell the two apart.

PositionOf

PositionOf returns a member's frozen settlement figures: what it must pay in, what it is owed, and what it has actually paid. All three are zero until the set is closed.

GrossOf

GrossOf returns a member's gross declared flows: what it has declared it owes, and what others have declared they owe it. These are the uncompressed figures, kept so a reader can see what netting removed.

Obligation

Obligation returns the cumulative amount debtor has declared it owes creditor in a set. Direction matters: Obligation(id, a, b) and Obligation(id, b, a) are different edges and both may be non-zero — the graph is directed, and netting them is Close's job, not storage's.

MemberCount

MemberCount returns how many addresses are party to a set.

NumSets

NumSets returns how many sets have ever been opened. It is the id high-water mark, so it does not decrease when a set is pruned.

OpenSets

OpenSets returns how many sets are currently open, via the duebook's own open-deferral count.

OpenOf

OpenOf returns how many open sets an address convenes.

BalanceOf

BalanceOf returns an address's withdrawable credit.

TotalPending

TotalPending is the P term of the conservation invariant: coins paid in for sets that have not yet settled or been abandoned.

FeesAccrued

FeesAccrued is the fee pot, withdrawable only to the FeeCollector.

Liabilities

Liabilities is everything this realm owes anyone: pending pay-ins plus unclaimed credits plus the fee pot.

Held

Held is the realm's actual ugnot balance.

Surplus

Surplus is Held minus Liabilities: out-of-band coins, sweepable to the FeeCollector. It is never negative in correct operation.

Lifetime

Lifetime returns the realm's cumulative counters: sets settled, gross and net value across every closed set, coins paid in, credited to creditors, refunded by Abandon, and withdrawn.

Address

Height

Height returns the chain height this realm sees, so a caller can compare it against a deadline without a second query.

mustGet

mustGet resolves a set id or aborts. avl/v0's Get returns ONE value — the stored value, or nil when the key is absent — so absence is detected by the type assertion rather than by a second boolean return. That is sound here, and sound only because this realm never stores a nil under any key in any of its trees: the package's own doc warns that a key holding nil is indistinguishable from a missing key, which would turn the assertion's ok from "the key is present" into "the key is present AND well-typed". Every Set call in this file stores a non-nil \*set, \*member or int64.

mustOpen

memberOf

pairAmount

pairKey

pairKey builds the storage key for a directed edge. The separator is a newline, which no bech32 address can contain, so two different (debtor, creditor) pairs can never collide into one key.

netsSumToZero

netsSumToZero returns the sum of every member's net position, which must be zero. It is a separate O(M) pass rather than folded into Close's freezing loop on purpose: the assertion has to hold over the WHOLE membership before any position is frozen, and a single loop would freeze the early members before it could know about the late ones.

convenorOpen

bumpConvenor

checkedAdd

checkedAdd adds two int64s and reports whether the result is exact. STATED LIMIT, because it is the kind that survives a copy-paste into a context where it is wrong: the sign test cannot see the one overflow where the sum does not move past the addend. checkedAdd(0, MinInt64) returns (MinInt64, true) — correct, since 0+MinInt64 is exactly MinInt64 — but so does checkedAdd(a, MinInt64) for any a >= 0, where the true sum is representable only when a == 0. Nothing here can reach it: every addend this realm passes is either positive or the negation of a value at or above MinObligation, so MinInt64 is never an operand and no accumulator starts at one. The audit raised it as an open question and the answer is "unreachable, and worth a comment if this helper is ever reused" — so this is the comment, and a caller that can supply MinInt64 needs a different helper rather than this one.

itoa

bps

bps renders a basis-point figure as a human percentage, exactly.

zeros

padID

shortAddr

Render

Render serves the index at "" and a set page at "\<id>".

renderIndex

renderSet

splitPairKey

splitPairKey reverses pairKey for render. The separator cannot appear inside an address, so the first occurrence is the only one.