Integration

Let your app read Zikaron records: verify grants, read record kits, ask the user’s desktop app to write entries, or prompt users to keep evidence within your flow.

How integration works

There are three ways in. Most apps are readers: a reader receives what the user exports, a grant code, a grant file, a record kit. An app that keeps evidence for the user within its flow can write through the desktop: it calls zikaron with --home, and the user’s running Zikaron writes the entry or puts it on chain in its own data folder; see Writing through the desktop; once the user turns on “With a credential”, it can also write with the credential; see Writing with the credential. Whichever way, one place writes a ledger at any time, and the keys stay in the user’s vault. AI apps can take the last two ways through MCP; see AI apps through MCP.

Verifying with the command line

The simplest integration calls zikaron as a subprocess and reads its exit code and standard output.

--grant takes a grant entry file, and also a .zkgrant grant file the user exported: the command line opens it by the reading the app uses and checks the hop the file is for. Each segment of a grant code is an entry’s bytes in base64url (padding left off); decode it and save it as a file; check a multi-segment grant code (a sublicense chain) hop by hop with chain-check --hop. --ledger can point straight at a ledger mirror or record kit (a .zkit file or a folder) the user exported, or, while the user has “With a credential” on, at the ledger in a data folder; see Command line. Node addresses may be http:// or https://; scan, anchor and kit-export with --to, which reach nodes, take --proxy (system, none or one proxy address), following by default the terminal’s proxy variables, and with none set the system’s proxy settings; a data folder road with the credential without --proxy uses this machine’s proxy setting; a node on this machine is always reached straight.

To check that your calls match the installed version, run zikaron contract: it prints the verbs, flags, exit codes and refusal reasons as one JSON value, made from the same tables the code runs on.

Handle 3 as a level of its own: “no result yet”, “passed” and “failed” are three states, and your interface shows them in three styles.

Writing through the desktop

With --home <the desktop’s data folder>, eleven verbs (init, history, grant, revoke, adopt, attest, annotate, retract, anchor, kit-export, kit-verify) are done by the Zikaron that is running, unlocked and holding that data folder as its writer: the entry is written into the user’s ledger under the user’s identity and shows in the window at once. The private keys and the passcode stay in the desktop. succeed with --home always answers E_ON_DESKTOP.

This way reaches this user on this machine alone: the channel is a socket file in the machine folder, readable and writable by its owner alone, or a named pipe only this user can reach, and each end asks the system who the other is. Locking the desktop, closing the data folder or quitting closes the channel; so does “With a credential” being on. The flags each verb takes with --home are in Command line · Through the desktop.

Writing with the credential

Once the user turns on “With a credential” in Zikaron’s Settings › Command line and AI control (with the passcode, for a minute to a year or with no expiry), programs and AI Agents on the same machine can call zikaron without the desktop open: point --ledger at the ledger folder in the user’s data folder; history, grant and the other writing verbs write entries, audit, check-grant and the others read, and anchor --ledger sends that data folder’s queue (at “Queue only” it answers E_QUEUED and the user sends from the desktop). The signing key is this identity’s in the vault, and the command line takes no --key and no passcode; written entries show in the desktop’s window at once. kit-verify --ledger <home>/ledger opens an encrypted record package with this machine’s identities; scan --ledger with no --endpoint reads with the data folder’s nodes.

Besides the table above, handle these answers (each exit 1, nothing written): E_CREDENTIAL_MISSING, E_CREDENTIAL_EXPIRED, E_CREDENTIAL_SHAPE (ask the user to turn “With a credential” on, or off and on, in Settings › Command line and AI control), E_HOME_HELD (the desktop is writing at this moment; retry shortly), E_HOME_OTHER_MACHINE (another machine writes this data), E_READ_ONLY (the data folder is read-only or its ledger broke; token says which), E_HANDED_OFF (the ledger is handed to another place).

An AI Agent working on another machine can take over a ledger: the user hands it over on this machine with the credential, the AI Agent takes the handoff into its ledger folder over there, writes entries and anchors them itself, then hands it back, and the user takes it over here. One place writes at any time. anchor asks the chain before signing, so an entry already anchored here answers E_ON_CHAIN there and nothing is sent; the desktop’s next ledger check reads the chain, so what the remote machine anchored stays out of the queue. See Command line · Handing a ledger over.

AI apps through MCP

In Zikaron’s Settings › Command line and AI control, the user presses “Copy config” under “Connect an AI app” in the “Terminal” group and pastes it into the AI app’s MCP settings:

The write tools are history, grant, revoke, adopt, annotate, retract, kit-export (with to and to-key, and originals as none to leave the originals out), anchor and kit-verify, each taking the flags its verb takes beside --home, plus home (kit-verify also takes fragment and unavailable, and home may be left out); they go with the credential or through the desktop as the switches stand, and anchor follows “Putting on chain from the command line”, spending this identity’s gas when sending is automatic. The read tools are show, audit, scan (home alone), check-grant, chain-check, depth, badge (decoding alone) and contract. Making keys, every way that takes a private key, succeed, handoffs and the fee bump are left out, and no tool takes a private key.

Parameters are strings, a repeated one a list of strings; a path parameter takes an absolute path alone. A result’s text is the command’s standard output, and structuredContent is {"answer":…,"exit":…}; exits 0, 1, 3 and 4 are answers, and isError marks misuse (2) and a parameter mcp refuses before running anything; a child process that crashes or cannot start carries no structuredContent. Calls run one at a time in arrival order; cancelled, a read stops and a write finishes and is answered. Ledger text in an answer passes as it came, as data.

Calling the cores directly

A Rust project can depend on the two crates zikaron and zikaron-kit. They only judge: your code reads the chain and hands the bytes to the cores; a record kit folder can go to zikaron_kit::kitdir::verify_kit, which reads and checks it from disk; a .zkit file is first taken apart by its container layout (see Files and formats) and its items handed to zikaron_kit::kitdir::verify_enumeration; a .zkit starting with zikaron-kit-addressed and a line end is an encrypted record package, which the cores cannot read until its recipient opens it (the verify page or kit-verify); its format is under Encrypted record packages. In another language, implement the law text yourself and validate it with the conformance suite; see Testing an implementation.

Reading the record kits a user has exported

An app on the same machine can list the record kits the user has exported and let the user choose one to submit. Find the machine folder in the app’s own order:

1. The directory the user set in your app’s settings.
2. The path written in the pointer file: ~/.zikaron-desk on macOS and Linux, %LOCALAPPDATA%\ZIKARON\.zikaron-desk on Windows (when the environment variable USERPROFILE names another folder, AppData\Local\ZIKARON\.zikaron-desk under it). When the pointer exists it decides: if its target fails to read, tell the user plainly that the Zikaron data has moved, and ask them to point to it again.
3. With no pointer: the default location, ~/.zikaron-desk.d/ on macOS and Linux and %LOCALAPPDATA%\ZIKARON\.zikaron-desk.d\ on Windows.

The single test for “valid”: kits/index.json there can be read, and its format name is zikaron.kits-index/1.

An index row’s anchoredOn names the chain the kit is anchored on (chain ID, registry contract, start block). For a kit the user has verified in Zikaron, the machine folder holds a verification result file, kits/verified/<kit ID>.json: whether the kit holds, each record’s earliest counted anchor, and the networks read and not read this time; the format is in Verification result files. An app that reads this file and never the chain learns from it which chain a kit is anchored on and whether it holds.

Your app’s permission on Zikaron data is limited to reading: kits/index.json and kits/verified/ in the machine folder, and the record kits (a .zkit file or a folder) that the index rows’ path points to (they sit under each data folder’s kits/). Once you have a record kit, verify it yourself before using the files inside. A row carrying oneTimeKey is an encrypted record package: its other cells were read from the plain package before it was encrypted, and the file its path names opens for its recipient alone; no row records a recipient.

Pointing a record at your transaction

When a user keeps evidence for a transaction in your app, they can fill in “Recorded for (optional)” with your app’s name, the other party’s identity, their reference and optionally their role; these are written as given into the entry’s for member (the role as seat), and the identity must be 0x followed by 40 hexadecimal digits. Whoever reads the record later can match it to the transaction.

Show these values in your interface for the user to copy: a fixed short string for the app name, and the transaction’s ID in your system for the reference.

Reminding at the right moment

Records made beforehand weigh the most. Find those moments in your flow and remind the user to keep evidence: when a file is delivered, when receipt is confirmed, when both sides agree on terms.

Signing requests

When you need a signature from the user, ask for it from their trading key. The identity key is reserved for the ledger; the Zikaron interface is designed accordingly, and signing happens within writes the user starts.

Agreeing on a new entry type

Entry types are open. You may agree on a new type, state its type name, body members and reading, and publish the convention. Other readers that meet it list it under “Unrecognized types”, and the verdict under the law stays as it was; ZIKARON Desk’s ledger status line counts it as a problem.

• Choose a type name with your project’s prefix, distinct from existing types.
• To refer to another entry in the body, use its entry ID.
• Write the reading as rules defined over every input: how it reads when the format fits, and how it is shown when the format is wrong.
• Register the convention in the repository’s discussions, so other implementations can adopt it.