Integration
Let your app read Zikaron records: verify grants, read record kits, or prompt users to keep evidence within your flow.
How integration works
Your app is a reader. The ledger is always written by the user, in Zikaron; the reader receives what the user exports: a grant code, a grant file, a record kit. This way a ledger always has a single writer, and a key always lives in one place.
Verifying with the command line
The simplest integration calls zikaron as a subprocess and reads its exit code and standard output.
zikaron check-grant --grant grant.entry --ledger ./issuer-ledger \
--fragment fragment.json --now $(date +%s)| Exit code | What your app does |
|---|---|
| 0 | Proceed |
| 1 | Refuse. When checks failed, list the failed checks; when the ledger or input is at fault, show the reason |
| 3 | Hold. Tell the user which check has yet to return a result, and retry later |
| 4 | Answer absent: scan or anchor failed to read the chain, or keygen failed to get randomness; retry, or change nodes |
| 2 | Your call is wrong; check the arguments |
--grant takes an entry file. 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. An issuer ledger folder can be made from a ledger mirror; see Command line. A .zkgrant grant file is a container; how to unpack it is in Files and formats. The command line reads the chain through http:// nodes alone; point it at a local node or a local proxy.
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.
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. 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:
- The directory the user set in your app’s settings.
- The path written in the pointer file
~/.zikaron-desk. 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. - With no pointer, the earlier location
~/Library/Application Support/ZIKARONwhen it exists, then the default location~/.zikaron-desk.d/.
The single test for “valid”: kits/index.json there can be read, and its format name is zikaron.kits-index/1.
Your app’s permission on Zikaron data is limited to reading: kits/index.json in the machine folder, and the record kit folders 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.
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.