Getting started

From installation to your first record on chain takes about ten minutes, half of it spent writing down the recovery words.

Installation

Version 0.1.0 comes as two packages for Macs with Apple silicon, available on the download page:

.dmg

Open it and drag ZIKARON.app to Applications. The zikaron command line is inside the app bundle at ZIKARON.app/Contents/MacOS/zikaron.

.pkg

An installer that puts the app in /Applications and the command line at /usr/local/bin/zikaron.

The app is signed with Kaptonia’s self-signed certificate and is outside Apple’s notarization. Files downloaded in a browser carry macOS’s quarantine flag, and macOS refuses to open them; on recent macOS, “Open Anyway” in System Settings › Privacy & Security works only some of the time. The reliable way is to check the file first, then remove the quarantine flag in Terminal:

1. Check the SHA-256. The result should match the one on the download page:
   shasum -a 256 ~/Downloads/ZIKARON-0.1.0-macos-arm64.dmg
2. With the dmg: before opening the dmg, run the command below, then open the dmg and drag ZIKARON.app to Applications:
   xattr -d com.apple.quarantine ~/Downloads/ZIKARON-0.1.0-macos-arm64.dmg
   If you have already dragged the app in, run this instead:
   xattr -dr com.apple.quarantine /Applications/ZIKARON.app
3. With the pkg: run the command below, then double-click the pkg to install:
   xattr -d com.apple.quarantine ~/Downloads/ZIKARON-0.1.0-macos-arm64.pkg

Change the paths to wherever you downloaded the files.

First run

The first time the app opens, the wizard appears by itself, with six steps listed down the left and the current step on the right. Whether a step is done depends on the actual state.

1. Set a passcode. 8 letters or digits, case-sensitive, entered twice. A passcode that is too simple is refused on the spot: eight identical characters, or digits that run in sequence or read as a date. The passcode comes before the identity because keys are stored in a key store that the passcode opens.
2. Create an identity. One of three ways: generate 12 recovery words, write them on paper and fill in three of them picked at random; import an existing key; or restore from a whole-machine backup. The first identity created on this machine is its primary identity.
3. Network. “Ethereum mainnet” is selected by default; or choose “Custom” and fill in the chain ID, registry contract and nodes yourself. Anchoring on mainnet costs real ETH in gas.
4. Create the ledger. Write a ledger description (optional), press “Create the ledger”, then press it again on the confirmation card. This step is free and writes locally.
5. Add gas. The page shows the key address and a payment QR code. Send a little ETH from your wallet and press “I have sent it”; the wizard reads the balance on chain once, and above zero the step is done. You may choose “Later”.
6. Whole-machine backup. Export a password-protected backup file; one file restores everything. You may choose “Do it later”; do it soon.

Once a passcode and an identity are set, “Exit setup” at the bottom of the step list, or Esc, returns you to where you were, and finished steps stay finished. For unfinished steps, “Run wizard again” in Settings › About picks up where you left off.

Write the recovery words on paper and keep them where you alone can reach them. The recovery words bring back keys; this machine’s ledgers, received grants and settings come back from a whole-machine backup; keep the original files yourself.

A full walkthrough for the Recorder

Choose “Recorder” at the top of the sidebar.

1. Record. Drop the work’s file onto the drop zone on Home, fill in “Record name”, press “Add to ledger”, then press “Add to ledger” again on the confirmation card.
2. Put it on chain. Click the “Pending” card on Home, or press “Put all on chain” under the “Pending” segment of Records, then press “Confirm and send” on the “Put on chain” card. A few minutes later the state turns “Confirmed”.
3. Grant. Open “Grant” and press “New grant”: fill in the grantee’s address, choose a record that is on chain, drop in the terms file, choose a validity period, press “Add to ledger” and again on the confirmation card, then put it on chain as in step 2.
4. Hand it over. On the grant’s detail page, press “Copy grant code” or “Export grant file…” and send it to the grantee. The grant file carries your ledger, so they can run the full check.
5. Day to day. Watch the Alerts page; when needed, press “Revoke grant…” on a grant’s detail page.

A record is final once written; to add to it, append a note. Keep the original files safe: to prove something later, you show the original, byte for byte identical to its fingerprint.

A full walkthrough for the User

1. Switch to “User” at the top of the sidebar. A User ledger is needed only to sublicense; when you get there, press “Set up ledger…” on the sublicense page.
2. Paste the grant code you received into the “Verify a grant” card on Home, press “Start check” and read the result.
3. Open “My grants”, press “Add grant”, paste the grant code or drop in the grant file, and press “Verify and add” to keep it.
4. When you receive the work itself, open Verify › Verify grant, put in the grant, the file and the terms file, and press “Verify” once to check all three together.
5. Watch the Alerts page: grants about to expire, revoked grants and issuer ledgers that were handed over all show up there.

The window

The sidebar is on the left and the page on the right. The sidebar, top to bottom: the identity chip (the current identity’s name and kind; click it to switch or create identities), the role switch “Recorder” | “User”, that role’s pages, and at the bottom “Settings”, “Lock” and the status line. The small icon at the right end of the status line is “Sync”; click it to read the chain in the background.

Every action that writes to the ledger or the chain first shows a confirmation card, listing what will be written, where, and at what cost; the solid red key on the card writes, and “Cancel” or Esc leaves everything as it was. Shortcuts and the other settings are covered in Alerts and settings.