For institutions

An issuer is any institution that keeps a public record of what it does: a ministry, a municipality, a university, an NGO. It keeps exactly one HardState Log — an append-only chain of signed events — for the life of the institution. This page is the end-to-end path from nothing to a citizen holding a verifiable receipt.

The lifecycle

1. Register the issuer. In the console, enter the institution’s name, country, city, and state. The address is geocoded and the whole record is signed with the admin’s passkey. A “test” checkbox marks the issuer as a demo (demo: true) so it never counts as a real deployment.

2. Invite officials. Send an invitation link; the official creates their own passkey; an admin approves it. You can also enrol someone from the same device. See Officials & sessions.

3. Open a session to work without prompts. An official opens a session with a single passkey tap — scoped to certain step types if you like, and time-boxed (up to 30 days). After that, recording a step signs with the session, no prompt per step. The session can close itself.

4. Integrate your own software (optional). Your system generates its own Ed25519 key, gets authorized once, and then records every checkpoint automatically. See API integration.

5. Record each step. Every act is an event of a type you choose. The API returns a Receipt.

6. Give the citizen the receipt. Paste the receipt link and its QR into the notification you already send (email, SMS, the printed form). Every step of the case links to the full timeline.

Event types are yours

Each step is an event of a type you choose, written domain.action in lowercase: case.open, case.inspect, permit.approve, permit.deny, fee.paid, diploma.issue, aid.delivered, contract.award, land_title.transfer. Only issuer.*, key.*, and session.* are reserved by the protocol.

Keep one type per kind of act, put the act’s public facts in public, and use case for the file or procedure number — so a citizen’s whole procedure reads as one timeline.

Transparency by default

Everything you put in an event’s public object is published as-is and reaches Bitcoin indirectly through the log. Put facts there, never anything you would not publish. Documents are handled separately — see below.

Documents stay private

Never send documents to HardState unless the institution decides to publish them. Commit to each file instead:

digest     = SHA-256(file)
salt       = 32 random bytes            (keep it: it goes in the citizen's receipt)
commitment = SHA-256("hardstate/doc/v1" ‖ salt ‖ digest)

The citizen’s receipt link carries the salts in its #fragment, which never reaches any server. With it, anyone holding the file can check it is the one that was recorded — and nobody else can. To publish a document on purpose, send its digest and salt with the event and upload the bytes.

What it costs

The daily HardState Anchor — a 36-byte OP_RETURN carrying "HSS" ‖ 0x01 ‖ root, 157 vB — costs roughly $48–240/year at typical fee rates (about 1–5 sat/vB). The 10-minute OpenTimestamps batches are free. One anchor covers every event from every issuer in that day’s tree, so the per-institution cost of anchoring is effectively zero; institutions pay a subscription, not per transaction.

Operating it

• Custody. System and session private keys never leave the machine that uses them. If one leaks, close the session or revoke the key from the console — everything signed before stays attributable, which is the point.
• Scope. Give each key the narrowest set of types that works.
• Pace. Records reach Bitcoin within 1–3 hours through OpenTimestamps and in the daily anchor. Express anchoring (~10–20 min) is available on institutional plans.

Officials & sessionsWho signs, how they're authorized, and how sessions let software sign on their behalf.

API integrationRecord each checkpoint from your own software: prepare → sign → submit.