Credentials prove who. Midnight proves nothing changed.

One agent, three services, two SDK edges.

Digest → credential → commitment.

The shape below is the one verified in IPS Compass (clinical summaries), and it transfers unchanged to a dance licence, a ticket entitlement or an agent mandate. The document never leaves your database; the digest is the only thing that travels, and the ledger only ever sees a salted commitment.

1. 01

   Serialise and digest

   Canonicalise the document (stable key order, normalised whitespace) and hash it with SHA-256. Non-deterministic serialisation is the number-one reason a verifier recomputes a different digest later.

2. 02

   Issue a credential over the digest

   Claims carry the digest, the credential type and at most a derived boolean (e.g. over18). Never a name, a date of birth, or any body content — a credential is not a place to park data you refused to put on a ledger.

3. 03

   Anchor a salted commitment

   commitment = H(domain ‖ digest ‖ salt), inserted into an append-only Compact Set. Persist the salt with the anchor — an anchor whose salt is missing is unverifiable and must fail closed, not read as confirmed.

4. 04

   Verify each link independently

   Structural validation, digest match, a real credential (a pending offer with no JWT is not one), and a membership read against the ledger. Report each pass separately so a partial failure names the broken link.

commitment = persistentHash("ips:anchor:v1" || sha256(bundle) || salt)

// contracts/IpsAnchorRegistry.compact — append-only, duplicates rejected
export ledger commitments: Set<Bytes<32>>;

export circuit anchor(commitment: Bytes<32>): [] {
  assert(!commitments.member(disclose(commitment)), "already anchored");
  commitments.insert(disclose(commitment));
}

Insert-only is not a style choice — overwriting an existing key in a public ledger map makes the dust fee balancer panic on the next call. See Known issues.

Three claims almost every demo overstates.

Simulated → Docker → Fly Machines.

-- Identus 1.40's FIRST Flyway statement is
--   ALTER DEFAULT PRIVILEGES ... TO "<db>-application-user"
-- so that LOGIN role must exist per database, or the agent exits 1.
CREATE DATABASE pollux;  CREATE DATABASE connect;
CREATE DATABASE agent;   CREATE DATABASE node;

\connect pollux
CREATE ROLE "pollux-application-user" WITH LOGIN PASSWORD '<pw>';
GRANT USAGE, CREATE ON SCHEMA public TO "pollux-application-user";
ALTER DEFAULT PRIVILEGES IN SCHEMA public
  GRANT ALL PRIVILEGES ON TABLES TO "pollux-application-user";
-- repeat the \connect + CREATE ROLE + GRANT block for connect, agent, node

# Fly private DNS (<group>.process.<app>.internal) resolves ONLY when the
# machine declares its process group. 6PN is IPv6-only.
config.metadata.fly_process_group = "identus-postgres" | "prism-node" | "cloud-agent"

JAVA_TOOL_OPTIONS="-Djava.net.preferIPv6Addresses=true \
  -Djava.net.preferIPv4Stack=false -XX:MaxRAMPercentage=70"

# Midnight side of the same app
node RPC bind:  [::]:9944
indexer:        APP__INFRA__API__ADDRESS: "::"

# checks: grace_period 300s · agent memory >= 4096 MB · poll timeout <= 60s
DIDCOMM_SERVICE_URL=https://<app>.fly.dev:8090   # publish internal port 8090

# The Machines API has no per-container log endpoint, and a crash-looping
# JVM is drowned out by healthy sibling output. Tee it, then read it back.
sh -c 'identus-cloud-agent > /tmp/agent-boot.log 2>&1; c=$?; exit $c' &
tail -F /tmp/agent-boot.log

# read from outside:  POST /v1/apps/<app>/machines/<id>/exec
#   { "cmd": ["sh","-c","tail -n 400 /tmp/agent-boot.log"] }

Non-negotiables.

• ▸Only a PUBLISHED did:prism carrying an assertionMethod key can sign a credential offer. Filter the issuer picker by resolving each DID and show why the excluded ones are excluded.
• ▸Connectionless issuance omits connectionId; passing one without an established connection returns a 400 that reads like an agent fault.
• ▸DIDComm invitations must advertise a reachable host: publish internal port 8090 and set DIDCOMM_SERVICE_URL=https://<app>.fly.dev:8090. Repair the endpoint on existing apps instead of redeploying.
• ▸grace_period 300s on the health check — first boot migrates four databases and a shorter window restarts the machine mid-migration.
• ▸Agent memory 4 GB or more; anything less gets OOM-killed during that first migration.
• ▸Cap a single readiness poll at 60s — the Machines API rejects longer timeouts with a 400.
• ▸Every provisioning function must degrade gracefully when the Fly token is absent: return an "unconfigured" state the UI can render, never throw inside a loader.
• ▸Treat 404 from a destroy/read as "already gone" and mark the record orphaned — Fly resources vanish outside your app.
• ▸Scope unique indexes on stack tables by (user_id, kind), or provisioning an Identus stack silently overwrites the Midnight one.
• ▸Provision / check / repair / repair-agent-DB / destroy are separate idempotent operations. Repairing a broken agent must never restart a healthy ledger.
• ▸Secrets stay server-side: read the Fly token and admin key inside .handler() bodies, keep agent clients in *.server.ts, and let routes import only *.functions.ts.
• ▸No env var or flag ships without an upstream source that says it is required. Two speculative fixes (a derived wallet seed, a duplicate POSTGRES_* group) cost a debugging cycle and hid the real error.

Symptom, root cause, fix.

The meta-lesson: porting a compose stack to Fly Machines is a translation job. Read the upstream compose and init scripts before writing a single machine spec — every failure above was already answered there.

Where credentials plus private anchoring beat either alone.

Read these.

• Hyperledger Identus documentation↗
• IPS Compass — live app (Identus × Midnight)↗
• ipsmidnight — issues encountered and how they were solved↗
• ipsmidnight — what we would do differently next time↗
• Credential issuance (incl. connectionless flow)↗
• HL7 International Patient Summary IG↗

Sources: the Identus Catalyst console and the Identus NHS console (agent provisioning, diagnostics and the ZK presentation layer) plus the IPS Compass build, which is the one that joins Identus credentials to a Midnight Compact anchor end to end. Dev-network only, unaudited, and not for real patient data.