Repository layout and layers
The cores make judgments; the interface presents them. Learn what each layer is responsible for, then decide where a change belongs.
Directories
| Path | Contents |
|---|---|
crates/zikaron | The zikaron/1 core: canonical bytes, entries, signatures, audit. |
crates/zikaron-kit | The zikaron.kit/1 core: documents, credential payloads, record kits, readings, the six checks on a grant. |
crates/zikaron-store | Ledger storage on disk. Standard library only. |
crates/zikaron-anchor | Chain access: scanning anchors, JSON-RPC, sending anchoring transactions. |
crates/zikaron-cli | The zikaron command line. |
crates/zikaron-glue | Record kit export and conventions shared across the tree. |
crates/zikaron-ui | The widget library and skin. |
crates/app | The desktop app. |
base/ | The two frozen law texts, their reference implementations, the conformance corpora and the registry contract. |
contracts/ | Contract variants used by tests of the anchoring path. |
packaging/ | Packaging scripts and icons for macOS and Linux. |
docs/manual/ | The user manual, in Chinese and English. |
CLI-SCHEMA.md | The command line’s output format, exit codes, refusals and flags. |
Four layers
- Base (
base/). Law texts, frozen cores, corpora, the contract, chain-facing fixtures: the reference for everything else. The frozen cores are pinned by the digests the law texts name, and the contract by its code hash; the rest is tooling, free to rebuild, replace or delete. - Cores and storage (
zikaron,zikaron-kit,zikaron-store,zikaron-anchor). Every judgment is made here. - Glue (
zikaron-cli,zikaron-glue). Assembles inputs, calls the cores, passes results on unchanged. - Interface (
zikaron-ui,app). Presentation and interaction.
Dependencies point downward: an upper layer calls the public interface of a lower one, and lower layers stand independent of upper ones. Every crate is written from the law texts on its own, with zero path dependencies on base/.
Five rules
- The interface only presents
- Whether an entry is valid and whether a grant is in force are concluded by the cores, and the interface presents the conclusion. Interface code that judges syntax for itself belongs in a core.
- The glue only assembles
- The command line and glue code turn arguments into inputs, call the cores and choose the exit code; bytes a core writes are passed on as they are, keys and values unchanged.
- The criteria stay as they are
- The two frozen cores are pinned by the digests in the law texts, and the registry contract by its code hash; those bytes stay as they are. Raise objections to them as issues; see Compatibility and evolution.
- Verify pages only read
- The permissions of Verify grant and Verify record are limited to reading their inputs and the chain.
- Identity keys sign the ledger alone
- Keys in the app sign entries, co-sign for adoptions and send anchoring transactions; payments, wallets and delegation are left to other software.
One implementation, reused everywhere
Each judgment is implemented once. The six checks on a grant come from zikaron-kit, shared by the verify page, the command line and the periodic review of My grants; the readings likewise. The same input therefore gets the same verdict at every entry point.
Every type of ledger entry has a subcommand that writes it. When adding an action to the app, make it work on the command line first, then build the interface.
Law citations in comments
Code comments cite zikaron/1 as law §N (on the kit side also parent law §N) and zikaron.kit/1 as kit law §N. Before changing an implementation, read the section it cites.