Grants

A grant is an entry in the ledger: it names the grantee, the record, the validity period and the fingerprint of the terms file. Once issued it can only be revoked; its content stays final.

Drafting

Open “Grant” and press “New grant”, or press “Grant to someone” on a record’s detail page (that record is filled in). The form’s fields:

Grantee

Paste a 0x… address; the “Recent addresses” menu on the right lists the address book and earlier grantees. Whether the address stands for a person, a company or a contract is for the two sides to agree.

Which record

Press “Choose a record” and pick one. Only records confirmed on chain can be chosen; the rest are greyed out with the reason.

Terms file

Required; drop it in or click to choose it. Its SHA-256 fills “Terms file fingerprint”. When the grant is signed, a copy of the file is kept in the data folder; it later goes to the grantee with the grant file and record kits, so they can recompute the fingerprint and check it themselves.

Validity

“7 days”, “30 days” (the default) or “90 days”, counted from chain time; or “Custom”, with start and end in Unix seconds. While chain time is still missing, sync once first, or use Custom.

Exclusivity, sublicense and scope

The “Exclusive grant” switch, “Upstream grant (sublicense only)” and “Scope”.

Addresses and hashes in the grantee, terms file fingerprint and upstream fields are written all in lowercase.

The meaning lives in the terms

The ledger knows form alone: an address, a fingerprint, a span of time. Whether the grant is exclusive, where the work may be used, what it costs and what happens on breach are all written in the terms file. When the grantee recomputes the terms file’s fingerprint and it matches the one in the grant, they know it is the very file attached at signing.

The “Exclusive grant” switch is recorded on your own machine: when the same record already has an exclusive grant with an overlapping period, the app shows “Exclusive grant conflict” and holds back the new one. Exclusivity that binds others belongs in the terms file.

Issuing

1. With grantee, record and terms file fingerprint all filled in, press “Add to ledger” (“Send to chain now” when “Auto put on chain” is on).
2. The “Sign grant” confirmation card shows the record, validity, terms file and cost; the grantee and the fingerprints are under “Details”. Press again on the card to issue.
3. The grant is written to the ledger and joins the pending queue; put it on chain as described under The pending queue.

The “Before signing” side column of the New grant page is a two-step checklist, “Fill in terms” and “Draft your first grant”, with the key’s balance shown below; each step can be marked done.

Handing it over

Grant code

A line of text starting with zikaron-grant:; press “Copy grant code” on the grant’s detail page. It lets the receiver verify the signature and the validity period.

Grant file

“Export grant file…” writes a .zkgrant file holding the entries of every hop in the grant chain, the issuer’s ledger, the terms files and the grant code, so the receiver can run the full check. The app reads the chain once before exporting.

Revoking

Press “Revoke grant…” at the bottom of the grant’s detail page. The card shows the record and the original validity, and under “Details” you can fill in the fingerprint of a ruling file. Press “Revoke” to write the revocation entry, which joins the pending queue. A revocation is final, and every sublicense derived from that grant ends with it. Once it is on chain, the grantee’s revocation watch finds it whenever their re-verification can reach your updated ledger (on the same machine, in an upstream folder they saved, or in an updated record kit at your publish address); until then, that grant shows “Has gaps”.

Receiving a grant

A User keeps the grants received in “My grants”. Press “Add grant”, paste the grant code or drop in the grant file, and press “Verify and add”:

• The app checks signatures and format first, and adds the grants once all of them pass.
• When a grant code carries a sublicense chain, every hop in it is added.
• A copy of the grant file is kept in the data folder, and the issuer ledger inside it is used for later checks.
• A grant code alone allows checking the signature and validity; for the full check, ask the issuer to export a grant file.

Each grant has a card, with one of four verdicts:

All passed

All six checks passed.

Has gaps

Some checks still await a result, for example the issuer ledger is missing or the grant awaits confirmation on chain. Wait until the result is settled before relying on the grant.

Failed

At least one check found a problem.

Revoked by issuer

The issuer has revoked this grant.

“Verify again” re-verifies the whole vault grant by grant: it looks for the issuer’s ledger on this machine first, then in the vault, then scans the chain. Re-verification also runs on the interval in Settings › Notifications, 600 seconds out of the box. “By issuer” in the toolbar groups the grants by issuer, with problem groups first.

Credentials

A credential is proof of a grant for a third party, such as your customers: a text file and a QR code. Press “Create credential” on the credential card of a grant’s detail page: the app follows the grant chain back to its root and writes badge.txt and the QR code badge.svg. The other party pastes the text into Verify › Verify grant to check it.

Sublicensing

A grant that this session’s re-verification has passed on all six checks has “Sublicense to others” on its detail page. Pressing it first shows the “Sublicense” confirmation card; “Draft…” then opens the sublicense page. The upper half shows the upstream grant; the lower half is the same form as drafting a grant, with the record fixed to the upstream grant’s record.

• The sublicense is written to your own (User) ledger and goes into your own pending queue. A User needs a signing key and a ledger; the page leads you to “Create key…” or “Set up ledger…”.
• A sublicense lives within its upstream grant: when the upstream is revoked or expires, the sublicense ends with it. You set the validity yourself; set it within the upstream validity.
• When a sublicense is verified, each hop gets its own six checks, and each pair of adjacent hops is checked to link up.

Revocation watch

After each re-verification of the whole vault, the app checks two things: has an issuer revoked a grant you hold, and has an issuer’s ledger been handed over to a new key. When either has happened, the window asks the system for attention once, an alert toast appears, and a red row is added at the end of the Alerts page. Each event alerts once.