func Add
crossing ActionAdd appends an entry and locks its storage deposit against the caller.
v0 source realm
Package compact makes fragmentation a number you can act on.
View source
gno.land/r/moul/x/compact/v0
Fragmentation, as a number you can act on.
A soft delete frees nothing. It clears the element and leaves the tree node behind, so the bytes stay locked and every read still walks past the hole. Compacting drops those nodes, and the chain refunds their deposit to whoever signs the transaction. Compaction is therefore paid work, and the only real question is when: too early and you free too few nodes to cover the gas, too late and every read has been paying for the holes in between.
This realm refuses to answer that question. It publishes the integers the answer is made of and lets whoever is watching decide, because the realm cannot see the gas price of the day and the caller can.
The interface
Add(text) |
appends an entry and locks its deposit against you |
Drop(index) |
soft-deletes your own entry, which is what creates a hole. Frees nothing |
Compact() |
drops the dead nodes. Permissionless, and the refund goes to you |
Fragmentation() |
live against allocated, the free read a bot polls |
Reclaimable() |
what a Compact would actually free right now |
Quote() |
that, priced, as a storagecost.Quote |
Only the author may Drop, so the fragmentation here is the honest kind that
ordinary use produces rather than vandalism. Compact stays open to anyone,
and that asymmetry is the mechanism: choosing what dies is owned, reclaiming
it is not.
Why allocated - live is the wrong number
The obvious reading of fragmentation is the gap between allocated indices and live elements. It is not what a compaction frees.
A dead element only becomes a reclaimable node once everything under it is
also dead. So a board with many scattered holes reports a large gap and
reclaims almost nothing, while a board with a dead tail reclaims a lot from the
same gap. Reclaimable() is the real number and it is free to read.
That is the whole reason this cannot be a schedule or a heuristic baked into the package. The shape of the holes decides, the shape changes with use, and only a caller watching both integers can time it.
Why this quote is sounder than a reaper's
A reaper advertises what deleting entries will refund, and to do that it has to guess how much state an entry occupies from its payload length. That guess is bad at the small end, where a per-entry floor dominates the payload, and one realm under-advertised by 25x on chain because of it.
Compaction has no such problem:
| reaper's bounty | this quote | |
|---|---|---|
| quantity | payload bytes, guessed from string length | dead nodes, counted by the container |
| conversion | a ratio measured at one payload size | a per-node constant, measured twice at 856 bytes |
| fails when | entries are small, or the container dominates | never structurally; the constant can drift |
Quote() is a measured constant times an exact integer. Still an estimate, and
the chain's StorageUnlockEvent is still the only settlement, but the failure
mode that cost a reaper 25x is absent by construction.
TestQuoteCountsNodesRatherThanGuessingFromPayload pins it: eight entries of 1
byte and eight of 256 produce the identical quote, because the node is what
gets freed.
What it is built from
p/moul/uliststores the entries and owns compaction. ItsCompactdrops dead nodes without moving a live index, so an index is stable for the life of the realm.p/moul/x/storagecostowns the arithmetic, includingEstimateNodesand the measuredBytesPerTreeNode.p/moul/kit/uiowns the display, including escaping an entry before it reaches the page.
Related
r/moul/x/reaper
is the other half: it deletes expired entries, where this one reclaims what
deletion left behind. Reap first, then compact, because compaction returns
nothing while a live element still sits below the dead ones.
Part of moul/gno-contracts — moul's versioned gno.land contracts. See the repository for the full catalog, build/test tooling, and usage.
Dependency graph:
🧪 Highly experimental — potentially vibe-coded. Not audited; may break, change, or be removed at any time. Do not use with anything of value. Full disclaimer: DISCLAIMER.
Package compact makes fragmentation a number you can act on.
A soft delete does not free anything. It clears the element and leaves the tree node behind, so the bytes stay locked and every read still walks past them. Compacting drops those nodes and the chain refunds their deposit to whoever signed the transaction. So compaction is paid work, and the only real question is WHEN: too early and you free too few nodes to cover the gas, too late and every read has been paying for the holes in between.
This realm refuses to answer that question, on purpose. It publishes the two integers the answer is made of and lets whoever is watching decide, because the realm cannot see the gas price of the day and the caller can.
- Fragmentation() is live vs allocated, the free read a bot polls.
- Reclaimable() is what a Compact would actually free, right now.
- Quote() prices it at the floor gas price, as an advertisement.
The arithmetic is gno.land/p/moul/x/storagecost and the container is gno.land/p/moul/ulist, whose Compact drops dead nodes without moving a live index, so an index is stable for the life of the realm.
Why this quote is trustworthy where a reaper's is not
A reaper advertises what deleting entries will refund, and to do that it has to guess how much state an entry occupies from its payload length. That guess is bad: a per-entry floor dominates at the small end, and one realm under-advertised by 25x on chain because of it.
Compaction has no such problem. What it frees is a COUNT of dead nodes, and the container already reports that count exactly. Every node costs the same whatever it carried. So the number on this page is a measured constant times an exact integer, not a ratio applied to a guess, which is why this is the half of the mechanism worth showing first.
7
func Compact
crossing ActionCompact frees the dead tree nodes and returns how many it freed.
Permissionless by design, and the refund goes to whoever signs this transaction rather than to the realm or to the authors: the chain pays the signer directly, so there is nothing here to distribute and nothing to steal. The worst a caller can do is waste their own gas compacting a board that had no holes.
func Drop
crossing ActionDrop soft-deletes your own entry, which is what creates a hole.
It frees nothing on its own, and that is the point of the realm: the bytes stay locked until somebody compacts. Only the author may drop, so the fragmentation on this page is the honest kind that ordinary use produces.
func Fragmentation
ActionFragmentation reports live elements against allocated indices.
The gap between them is what a compaction has to work with. It is a free read so a bot can poll it and decide for itself, which is the whole design: the realm publishes, the caller times.
func Quote
ActionQuote prices what a Compact would return, at the default storage price and the floor gas price.
Unlike a payload-derived bounty this is a counted quantity: Reclaimable is exact, and storagecost.EstimateNodes multiplies it by a measured per-node constant. Treat it as an advertisement all the same. The authoritative numbers are the chain's, in the StorageUnlockEvent the transaction emits.
func Reclaimable
ActionReclaimable is how many dead nodes a Compact would free right now.
It is NOT the same as allocated minus live. A dead element only becomes a reclaimable node once every element under it is also dead, so a board with many scattered holes can report a large gap and nothing to reclaim. That difference is exactly what makes the timing a decision instead of a rule.
func Render
1
type Entry
structEntry is one element. Author is kept so a drop can be refused to anyone else: soft-deleting a stranger's entry would be vandalism, and the holes this realm studies should come from ordinary use.
