assets

gnokey query vm/qeval \
  --data 'gno.land/r/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/assets.Height()' \
  --remote https://rpc.onyx.testnets.gno.land:443

import "gno.land/r/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/assets"

curl -sS 'https://onyx.testnets.gno.land/r/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/assets$download&file=assets.gno' | shasum -a 256

Overview

Package assets is a per-owner fixed-asset register whose ledger postings are DERIVED from state rather than asserted by a caller.

What this realm is for

A general ledger takes a debit code, a credit code and an amount from whoever is posting. That is the right design for a ledger and it means gno.land/r/.../books structurally CANNOT know that an entry was a depreciation charge, or that the charge for that period had already been made. Nothing stops an owner from booking the same month twice, or from skipping one, and nothing in the book can tell afterwards.

This realm closes that gap for one class of entry. It holds each asset's depreciation schedule as state, computes the charge from the schedule and the chain height, and keeps a per-asset HIGH-WATER MARK of the periods already booked. The amount is never a parameter. A charge therefore cannot be double-booked (the mark does not move backwards) and cannot be skipped (the next call books the whole span, because charges telescope exactly).

The resulting claim is narrow and checkable by anyone, which is the point:

bookedAmount(asset) == asset.schedule.AccumulatedAt(bookedThrough(asset))

and, across a whole register,

sum of bookedAmount over assets == the credit balance of 1590

Both are exported as Invariant and CrossFoot and both are FREE reads, deliberately — see "Why Rederive is not owner-only" below.

The chart is two accounts and is fixed

5500 Depreciation expense (expense, debit-normal) 1590 Accumulated depreciation (asset, CONTRA — see below)

Every posting is debit 5500 / credit 1590 for an equal amount, so the accounting equation offsets at 0 = 0 on an empty register and after every charge. There is no OpenAccount entrypoint and the underlying book is created with a hard cap of two accounts, so the chart cannot grow.

The COST BASIS never reaches the book. Booking an asset's cost would force a credit leg, and the only honest candidates are a liability ("2000 Acquisition payable") or an equity plug ("3000 Contributed capital"). Both assert how the asset was funded, which this realm does not know and must not invent. The cost stays in register state, where it is visible as data rather than as an accounting claim.

1590 is kind ASSET, so journal treats it as debit-normal and Balance() returns Debits - Credits — which reads NEGATIVE for accumulated depreciation. That is arithmetically correct for a contra-asset and is confusing on first reading, so both figures are exported and each is named for what it is: AccumulatedCredit is the positive contra balance.

Periods are measured in BLOCKS

A period is periodBlocks chain heights long, anchored to the height the asset was placed in service. Period k closes at placedAt + k*periodBlocks, and a partial period in progress is not counted and is not lost.

Block height, not wall-clock time, because that is this portfolio's convention: payroll, budgets, reimbursements and subscriptions all carry a periodBlocks field, and height is monotone by construction where block time is validator-reported. p/depreciation's Daily/Monthly/Yearly constants are SECONDS and are therefore not used here; its arithmetic is unit-agnostic (Periods is an integer division), so this is a mismatch in that package's documentation rather than a divergence from its behaviour. It is recorded in DISCOVERY.md § 6 rather than silently worked around.

Retirement books first, then freezes

Retire performs the final booking for the periods completed up to the retirement height and only then stops the asset. The two are one transaction on purpose: retiring without booking would leave depreciation that was genuinely incurred permanently unbooked, and booking after retirement would need an exception to the "retired assets do not accrue" rule. Historical charges always stand — the depreciation really happened.

Disposal gain or loss is OUT OF SCOPE for v1, and the reason is structural: it needs the cost-basis account this realm deliberately does not open, plus a proceeds figure the realm cannot observe because it holds no funds.

What this realm does NOT do

• No custody. It holds no coins, has no withdrawal path, and refuses a user call that arrives carrying any. An asset's cost is a number an owner typed.
• No period close. p/journal can seal a book up to a HEIGHT, refusing entries dated at or before it. This realm's bookedThrough is a PERIOD INDEX — a different axis wearing the same English word — and sealing a derived book could only make the derivation unpostable. The capability exists in the engine and is deliberately not exposed.
• No bulk booking. p/depreciation's MaxLife doc states the loop bound (1199 iterations per CarryingAt, 2398 per Charge, and a degenerate declining schedule that runs the full bound on every call forever) and explicitly refuses to price it. A loop over N assets multiplies an unpriced bound by N, so one asset is booked per call.
• No truth. A register is a set of claims by its owner. With no custody there is nothing tying "cost 1000000" to a real holding. The invariants here prove that the postings follow from the stored schedules; they prove nothing about the world.

Why Rederive and the invariants are free reads

r/books exposes Rederive as an owner-only crossing function, to contain the cost of a full re-walk. This realm diverges, deliberately: the derivation IS the product, and a claim only its owner can check is not a claim worth making. Rederive, Invariant and CrossFoot are all free reads, so any third party can verify a register from vm/qeval without the owner's key.

The bound above is what makes that affordable, and a bound is not a price. Measured under the pinned onyx toolchain at the register cap — 64 assets on MaxLife declining schedules, the worst case this realm can hold:

Render per call: 106,421,272 gas Rederive per call: 9,357,860,004 gas

So the design choice is stated with its cost rather than only its reason. Render is an ordinary rich-page figure; Rederive at cap is two orders of magnitude above it, falls on the queried node rather than the caller, and is reachable with no key and no fee. Whether a given RPC's query gas ceiling admits it AT THE CAP is a property of that node and is not measured here — if it refuses, the third-party-verification claim above fails exactly at the bound it was designed around. Invariant is per-asset and cheap; CrossFoot walks the assets only, not the postings.

Deploy order

This realm imports p/journal and p/depreciation. Neither is deployed yet, so the order is p/journal, p/depreciation, then this realm.

Imports

• chain/runtime
• chain/runtime/unsafe
• gno.land/p/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/depreciation
• gno.land/p/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/journal
• gno.land/p/nt/avl/v0
• gno.land/p/nt/markdown/sanitize/v0
• strconv
• strings

Constants and variables

The fixed chart. The codes follow r/books' convention, where an account's LEADING DIGIT fixes its kind: 1 asset, 2 liability, 3 equity, 4 revenue, 5 expense. A six-series code would be an invalid account under that convention, which is why the expense leg is 5500 and not the 6500 a textbook chart would use.

const (
	ExpenseCode = "5500"
	ExpenseName = "Depreciation expense"

	AccumCode = "1590"
	AccumName = "Accumulated depreciation"
)

MaxAssetsPerRegister caps one owner's register. CrossFoot and Render both walk every asset, and this bound is what keeps those reads cheap for everyone.

const MaxAssetsPerRegister = 64

MaxEntriesPerRegister caps one owner's journal, far below journal's MaxEntriesLimit of 1000000 because RederiveFromJournal is linear in the posting count and is a free read here.

The bound is reachable and the arithmetic is worth stating: an asset posts at most one entry per completed period, so MaxAssetsPerRegister assets with MaxLife-period schedules could want 64*1200 = 76800 entries. A register that fills refuses further charges rather than dropping history. There is deliberately no Archive — it would destroy the record the invariants are checked against — so the remedy is a second register under a second address, which is a real limitation and not a hidden one.

const MaxEntriesPerRegister = 8192

MaxLabelLen bounds an asset's human label. Every label is a candidate for Render output.

const MaxLabelLen = 64

MinPeriodBlocks is the shortest period an asset may use. Matches the floor payroll, budgets and reimbursements already use. A period of 0 is not a special case here — it is simply invalid, because an asset with no period has no schedule to derive anything from.

const MinPeriodBlocks = int64(100)

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

const RealmPath = "/r/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/assets"

RenderAssetLimit caps how many assets one Render call tabulates.

const RenderAssetLimit = 25

Functions

AccountKind

func AccountKind(owner address, code string) (string, bool)

AccountKind is an account's kind as a word: "asset" for 1590, "expense" for 5500. The second result is false for a code this chart does not hold.

It exists because the chart's kinds are otherwise unobservable from outside. Both accounts are debit-normal, so neither Balance nor Equation can distinguish them, and the package doc's claim that 1590 is a contra-ASSET rather than a second expense account would be an assertion in a comment with nothing behind it. Opening 1590 as an Expense instead would leave every other read in this file identical.

AccumulatedAt

func AccumulatedAt(owner address, id uint64, n int32) int64

AccumulatedAt is Cost - CarryingAt(n): what the contra-asset balance for one asset SHOULD be once period n is booked.

AccumulatedCredit

func AccumulatedCredit(owner address) int64

AccumulatedCredit is the POSITIVE accumulated-depreciation figure: the credit balance of 1590, i.e. -RawDelta.

AssetCount

func AssetCount(owner address) int

AssetCount is how many assets a register holds, retired ones included.

AssetInfo

func AssetInfo(owner address, id uint64) (
	label string,
	cost, salvage int64,
	life int32,
	method string,
	rateNum, rateDen int64,
	placedAt, periodBlocks int64,
	bookedThrough int32,
	bookedAmount int64,
	retired bool,
	retiredAt int64,
)

AssetInfo reports an asset's whole stored state in one read.

method is "straight-line" or "declining-balance"; rateNum and rateDen are 0 for a straight-line asset.

Balance

func Balance(owner address, code string) (int64, bool)

Balance is an account's balance in its NORMAL direction. For 1590 that is debit-normal and so reads negative; AccumulatedCredit is the figure a reader of a contra-asset wants.

BookThrough

func BookThrough(cur realm, id uint64) int32

Crossing function. Callable from a transaction via MsgCall, and from another realm as BookThrough(cross(cur), ...).

BookThrough posts the depreciation charge for every period that has completed since this asset was last booked, and returns the period the asset is now booked through.

It is IDEMPOTENT: calling it twice in one block, or twice in one period, posts once. Calling it after skipping ten periods posts the whole span as one entry, for the same total a caller who ran it every period would have reached — p/depreciation's Charge telescopes exactly, so booking cadence cannot change the total booked.

A ZERO charge advances the mark and posts nothing. That is not a shortcut: journal rejects a posting of zero (ErrInvalidAmount), while a degenerate declining schedule legitimately charges zero, and the invariant is preserved exactly because AccumulatedAt is equal at both marks in precisely that case.

Panics if the asset is retired, or if the book is full.

BookedAmount

func BookedAmount(owner address, id uint64) int64

BookedAmount is the cumulative expense posted for one asset.

BookedThrough

func BookedThrough(owner address, id uint64) int32

BookedThrough is the high-water mark: the whole periods already charged.

Capacity

func Capacity(owner address) (assetsLeft, entriesLeft int)

Capacity reports how many more assets and entries a register can take.

CarryingAt

func CarryingAt(owner address, id uint64, n int32) int64

CarryingAt is an asset's carrying amount after n whole periods: Cost at n <= 0, Salvage at every n >= Life. It reads the SCHEDULE and is independent of what has been booked.

CrossFoot

func CrossFoot(owner address) (sumAssets, accumulated int64, agrees bool)

CrossFoot is the register-wide check: the sum of every asset's booked amount against the credit balance of 1590.

The identity is EXACT, not approximate, and the reason is structural: this realm exposes no general posting entrypoint, so it is its book's only writer and bookSpan is the only code that posts. Adding a general Post would destroy this check, which is the cost of adding one.

retired assets are included: their charges were really incurred and the 1590 credit they produced does not disappear when the asset stops.

Due

func Due(owner address, id uint64) int64

Due is the charge BookThrough would post for an asset right now. It is 0 for a retired asset, for an asset with no newly-completed period, and for a degenerate declining schedule that has not reached its final period.

EntryCount

func EntryCount(owner address) int

EntryCount is how many entries a register's book holds.

Equation

func Equation(owner address) (debitNormal, creditNormal int64, offsets bool)

Equation is the accounting equation: debit-normal against credit-normal. Both sides offset at 0 for this chart, because the only entry is an expense debit against a contra-ASSET credit — both legs are debit-normal accounts, so the expense adds and the contra subtracts.

ExpenseDebit

func ExpenseDebit(owner address) int64

ExpenseDebit is the total depreciation expense recognised: the debit balance of 5500.

FullyDepreciatedAt

func FullyDepreciatedAt(owner address, id uint64) int64

FullyDepreciatedAt is the height at which an asset first carries only its salvage value: placedAt + Life*periodBlocks. Validated at placement, so it cannot fail afterwards.

HasRegister

func HasRegister(owner address) bool

HasRegister reports whether an address has a register.

Height

func Height() int64

Height is the chain height this realm dates entries and periods with. Exposed so a caller can predict what BookThrough will book.

Invariant

func Invariant(owner address, id uint64) (booked, derived int64, agrees bool)

Invariant is the per-asset derivation check:

bookedAmount == schedule.AccumulatedAt(bookedThrough)

It returns the two figures and whether they agree. A false here means the realm posted an amount its own schedule does not imply, which no code path in this realm can produce — which is exactly why it is worth exporting: the claim is checkable by a third party rather than asserted in a comment.

IsBalanced

func IsBalanced(owner address) bool

IsBalanced reports whether the book's debits equal its credits.

IsRetired

func IsRetired(owner address, id uint64) bool

IsRetired reports whether an asset has been retired.

Label

func Label(owner address, id uint64) string

Label is an asset's label.

OpenRegister

func OpenRegister(cur realm)

Crossing function. Callable from a transaction via MsgCall, and from another realm as OpenRegister(cross(cur), ...).

OpenRegister creates the caller's register and opens its two accounts. It panics if the caller already has one.

The chart is opened HERE rather than on demand, and the book is created with a cap of exactly two accounts. Both facts are load-bearing: they are why this realm is its book's only writer and why the CrossFoot identity is exact rather than approximate.

OpenedAt

func OpenedAt(owner address) int64

OpenedAt is the height a register was created.

PeriodsElapsed

func PeriodsElapsed(owner address, id uint64) int32

PeriodsElapsed is the whole periods completed for an asset at the current height, whether or not they have been booked. For a retired asset this keeps increasing while BookedThrough does not, which is the intended difference and is why both are exported.

Place

func Place(cur realm, label string, cost, salvage int64, life int32, periodBlocks int64) uint64

Crossing function. Callable from a transaction via MsgCall, and from another realm as Place(cross(cur), ...).

Place records a straight-line asset placed in service at the current height, and returns its id.

Nothing is posted: at placement zero periods have completed, so the charge is zero and a zero posting is not a valid journal entry. The first charge becomes bookable at placedAt + periodBlocks.

PlaceDeclining

func PlaceDeclining(cur realm, label string, cost, salvage int64, life int32, num, den, periodBlocks int64) uint64

Crossing function. Callable from a transaction via MsgCall, and from another realm as PlaceDeclining(cross(cur), ...).

PlaceDeclining records a declining-balance asset charging num/den of the remaining carrying amount each period. Double-declining over a 10-period life is num=2, den=10.

Two properties of that method are inherited from p/depreciation and are visible in this realm's numbers, so they are repeated here. The final period absorbs whatever remains above salvage, so the last charge can be much larger than the one before it. And a schedule whose per-period charge truncates to zero (cost*num < den) never depreciates until that final period — Due reads 0 for its whole life, which is the schedule behaving as specified and not a stuck register.

RawBalance

func RawBalance(owner address, code string) (int64, bool)

RawBalance is an account's Debits - Credits, with no normal-direction adjustment.

Rederive

func Rederive(owner address) (debits, credits int64, agrees bool)

Rederive re-walks every posting in the book and reports whether the account totals agree with the journal.

It is a FREE read, unlike r/books' owner-only equivalent. The divergence is deliberate: this realm's claim is that its postings follow from its stored schedules, and a claim only the owner can check is not worth making. The cost is linear in the posting count, which is what MaxEntriesPerRegister bounds.

Registers

func Registers() int

Registers is how many registers exist. There is deliberately no way to enumerate them or to aggregate across them: such a total would be the sum of every stranger's self-reported cost figures.

Render

func Render(path string) string

Render shows the realm index at "/" and one owner's register at "/<address>".

Retire

func Retire(cur realm, id uint64) int64

Crossing function. Callable from a transaction via MsgCall, and from another realm as Retire(cross(cur), ...).

Retire books the asset through the current period and then stops it permanently. It returns the final amount posted, which may be zero.

The booking is not optional and not separable: see the package doc. After this call the asset accrues nothing, BookThrough on it panics, and every historical charge stands.

An asset already at or past the end of its life still retires cleanly — CarryingAt clamps at Salvage from Life onwards, so the final charge is whatever had not yet been booked and is zero if nothing had.

IT PANICS IF THE BOOK IS FULL AND A CHARGE IS DUE, AND THAT REFUSAL IS PERMANENT. The booking is not separable, journal's Post is fail-closed before it writes, and a panic reverts the whole transaction — so an asset with an unbooked charge on a register that has reached MaxEntriesPerRegister can never be retired. BookThrough's identical panic is harmless (the charge simply stays unbooked and can be booked later if the book ever has room, which it never will, there being no archive); this one strands the asset permanently in the live state.

It is reachable, and the arithmetic is the same one MaxEntriesPerRegister carries: about seven MaxLife assets booked period-by-period fill the book. The remedy is the same one the entry cap already has — a second register under a second address — and it has to be arranged BEFORE the book fills, which is why Capacity is exported and why the register page prints the entry headroom. Making Retire freeze without booking would be the obvious alternative and is refused: it would forfeit a charge that was genuinely incurred, which is the one thing this realm exists not to do.

Totals

func Totals(owner address) (debits, credits int64)

Totals is the book's total debits and credits. They are equal after every charge, because every entry is a matched pair.

---

Doc text is reproduced as vm/qdoc returns it. The node markdown-escapes doc comments, so a bracket or angle bracket may carry a backslash the committed source does not have. The source itself is at source and in this repository.