02Sheet 02.05 · Corpus

Catalog

One hand-written file per entry: what it is for, which recipe step holds it, and the facts a correct reader must find. A compiler turns it into the entry, for every variant, and refuses any fact that doesn't hold.

Nobody edits entries/ by hand. Each entry starts as a catalog file, catalog/<id>.json. It says what the entry is for, where its ledger comes from, and the facts a correct reader must find, written relative to the transaction the entry is about. The compiler, tools/build.mjs, turns it into entries/<id>/ for every variant.

Write the intent

A catalog file carries:

  • the id, title and pattern;
  • the CAPs, and the hazards with their placement;
  • the source: a recipe lane and step, or a mined ledger;
  • the variants to build, such as p30-mainnet, p28-testnet or p30-mainnet-galexie, and optionally mined variants beside the generated ones;
  • the focus: an operation of the step's transaction, or {"ledger": true} when the entry is about the ledger itself. A mined entry names its transaction by hash; the compiler never picks one;
  • the facts.

Compile it

make build                     # every catalog file (minutes)
node tools/build.mjs [id ...]  # only these entries

The compiler takes the ledger bytes from a fresh make generate run (or from mined/) and finds the focus transaction. It resolves every fact into an exact JSON Pointer for that variant, and records size, sha256, provenance and change-order data. It needs the runs of make generate, for the base P30 mainnet variants also those of make order-scan (it ships the most frequent byte ordering), and the native reader (make native). A fact that doesn't hold fails the build, and so does a variant whose focus doesn't match the catalog's (a transaction where the catalog says ledger, or none where it names one): intent and outcome must agree before an entry exists.

Check it

make verify and make oracle check the built entries like any other. make novelty then fails if the new entry adds nothing another entry doesn't already hold.

Fact addresses

A fact names where it looks with at. The compiler resolves that address per variant, so one catalog file serves every protocol, network and flag profile.

atResolves to
tx.resultthe focus transaction's result
tx.result_pairthe result pair (hash and result)
tx.fee_chargedthe fee charged
tx.envelopethe envelope in the transaction set, in any phase, stage or cluster
tx.metathe transaction's meta
tx.fee_processing, tx.post_apply_feethe fee and post-apply fee changes
op.meta, op.changes, op.eventsthe focus operation inside the meta
ledgerthe whole ledger: header, upgrades, evicted keys

A value may be {"$manifest": "contracts.kit2.CA1"}. It is then read from the run's own manifest, so a fact holds on every network even though contract ids differ by passphrase.

Authoring aid

node tools/inspect.mjs <lane> <step> [variant] reads a make generate run and prints the focus transaction's result and fee, and for each operation the kinds of its changes and its events.

On this page