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, using the standard library and zikaron-os alone. |
crates/zikaron-net | Transport: one HTTP/HTTPS exchange with a node or a remote file, with proxies, dialing several addresses and connection reuse, the one place TLS is configured, and the sandbox that runs the system’s proxy configuration script (QuickJS). |
crates/zikaron-anchor | Chain access: scanning anchors, JSON-RPC, estimating and sending anchoring transactions; the table for comparing nodes, the table of waits for asking a rate-limited node again, the table of node refusals, and the rules for fees, gas limits and resending with higher fees all live here, shared by the app and the command line. |
crates/zikaron-cli | The zikaron command line: its end of working through the desktop (--home), its end of reading, writing and sending a data folder’s queue with the credential, handoffs (hand-over, take-over), and zikaron mcp, the Model Context Protocol way AI apps call it (mcp.rs). |
crates/zikaron-glue | Reading and writing record kits and grant files, ledger mirrors, the message format of the local channel, the one-file container (.zkit, .zkgrant, .zkhand), the judge of one record (recordcheck), taking originals out (extract), the encrypted record package’s format constants and head recognition (addressed), the folder record manifest (recording), and conventions shared by the app and the command line. |
crates/zikaron-os | The few things that differ by operating system: system randomness, owner-only files, syncing to disk, replacing renames and landings onto free names alone, the system proxy, locks held by their own process alone, where the home and machine folders are, “Enable the zikaron command”, wiping secrets in memory, the system material under the window (macOS glass or vibrancy, Windows 11 Mica), the system’s reduce motion setting, and the local channel between the command line and the desktop. |
crates/zikaron-seal | The sealed layer the app and the command line share: the envelope and names of every local file, the key vault, a data folder’s sealed ledger, the machine settings both ends read, the command-line credential, the adoption and handoff lists, sealing and opening encrypted record packages (addressed), reading the read-only networks table (readnets). |
crates/zikaron-send | The sender, one for the desktop’s queue, anchor --home and anchor --ledger: reading the chain, the exit gate, the write gates, the queue’s lock and steps, signing, broadcasting and the receipt wait, and the direct anchor’s record (cli-sent/); finding a recipient’s public key from an address on chain (recipient) and the read-only network fingerprint gate (fingerprint). |
crates/zikaron-pack | Packaging pieces: the third-party licence list generator, the steps that keep the build machine’s details out of packages, path mapping and its check, checking the AppImage runtime, and the Windows package layout. |
crates/zikaron-ui | The widget library and skin. |
crates/app | The desktop app, with the desktop end of the local channel. crates/app/local-data-standard.md sets out the format of local encrypted files. |
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. |
.github/workflows/ | test.yml builds and tests release builds on three systems and checks a release build carries neutral path names alone; package-windows.yml lays out the Windows package on demand. |
rust-toolchain.toml | Pins Rust 1.97.1 for local builds, continuous integration and release builds alike. |
docs/manual/ | The user manual, in Chinese and English. |
CHANGELOG.md, CHANGELOG.en.md | The changes in each release, in Chinese and English. |
CLI-SCHEMA.md | The command line’s output format, exit codes, refusals and flags. |
.gitattributes | * -text: no line-ending conversion on any system, so corpora and law texts compare byte for byte. |
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, withzikaron-netandzikaron-osbeneath them). Every judgment is made here.zikaronstands on its own in the workspace, andzikaron-kitonzikaronalone; nodes are reached throughzikaron-netalone, and system randomness, owner-only files, syncing to disk and replacing renames come fromzikaron-os, which storage, transport, glue, the command line and the app all go through, and which also gives the home and machine folder locations in one place. The app’s own system-dependent pieces (file dialogs, the write lock, the time zone, Chinese fonts and so on) live incrates/app/src/platform/. - Glue (
zikaron-cli,zikaron-glue,zikaron-seal,zikaron-send). Assembles inputs, calls the cores, passes results on unchanged; the sealed layer and the sender sit here, shared by the app and the command line. - 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/. zikaron-pack stands outside the four layers: it is the app’s build dependency and the packaging tool, uses the standard library alone, and nothing depends on it at run time.
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. A request the command line hands over with
--hometakes the same action path in the desktop as a click. - 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 chain
- Verify grant, Verify record and Look up a ledger read their inputs and the chain and send not a single transaction; what they write on this machine is the address book, snapshots, verification result files, and the originals taken out into the folder the user chooses with “Take out originals”.
- Identity keys sign the ledger alone
- Keys in the app sign entries, co-sign for adoptions, send anchoring transactions, and open record packages encrypted to that identity (one key agreement, signing nothing); 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 app and the command line also share how a grant file is read (zikaron_glue::grantfile), the ledger mirror layout (zikaron_glue::mirror), the convention for recording a file (zikaron_glue::recording, which history --file uses), the rules for fees, gas estimates and resending with higher fees (zikaron-anchor), the node comparison and rate-limit wait tables (zikaron_anchor::judge, zikaron_anchor::patience), local encrypted files, the key vault and the command-line credential (zikaron-seal), sending a queue on chain (zikaron-send: one sender for the desktop’s queue, anchor --home and anchor --ledger), judging one record (zikaron_glue::recordcheck, shared by the desktop’s “Verify record” and kit-verify), taking originals out (zikaron_glue::extract, shared by the desktop’s “Take out originals” and kit-verify --originals-to), sealing and opening encrypted record packages (zikaron_seal::addressed), finding a recipient’s public key from an address on chain (zikaron_send::recipient), the read-only network fingerprint gate (zikaron_send::fingerprint), reading the read-only networks table (zikaron_seal::readnets), the container of one-file record kits, grant files and handoff files (zikaron_glue::container), both ends of the local channel (zikaron_glue::door, zikaron_os::door), finding the machine folder (zikaron_os::machine), and the single TLS configuration and proxy choice (zikaron-net). 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.