The private record#
policy-cover.compact keeps a Map<Bytes<32>, PolicyRecord> keyed by the same 32-byte policy id the Cardano validator derives. The issuer mirrors each policy with registerPolicy after the Cardano mint confirms. The buyer produces both commitments in their own client.
| Field | Stored | Why |
|---|---|---|
| holder | Role commitment of the holder's secret key | Ownership without a public key on the ledger |
| coverage | persistentCommit(amount, salt) | Coverage size hidden inside the commitment |
| expiry | Uint<64> | Public term end |
| status | NONE · ACTIVE · CLAIM_PENDING · PAID · EXPIRED | Public lifecycle |
| evidence | Commitment to the claim evidence bundle | Evidence stays off-ledger |
Commitments#
roleCommitment(sk, tag) =
persistentHash<Vector<3, Bytes<32>>>([ pad(32, "plutusshield:role:"), tag, sk ])
tags: pad(32, "issuer") · pad(32, "holder") · pad(32, "assessor")
coverageCommitment(amount, salt) = persistentCommit<Uint<64>>(amount, salt)The secret key and the coverage opening (amount, salt) are witnesses. The caller's local wallet supplies them when it builds a proof (localSecretKey(), coverageAmount(id), coverageSalt(id)), and they never touch the ledger. Separate role tags mean the same key produces unrelated commitments for different roles.
From a Cardano Buy to Midnight#
When you buy on /cover, your browser makes a policy key before the wallet prompt: a random 32-byte holder secret and a random coverage salt. Only one 32-byte value from it goes on Cardano, in the policy datum's midnight_commitment:
holder = roleCommitment(holderSecret, holderTag())
= SHA-256(pad32("plutusshield:role:") ‖ pad32("holder") ‖ holderSecret)
coverage = coverageCommitment(amount, salt)
= SHA-256(salt ‖ u64le(amount)) // persistentCommit<Uint<64>>
registration = registrationCommitment(policyId, holder, coverage)
= SHA-256(pad32("plutusshield:register:v1") ‖ policyId ‖ holder ‖ coverage)
Cardano PolicyDatum.midnight_commitment = registrationregisterPolicy(policyId, holder, coverage, expiry, cardanoCommitment) takes that datum field and refuses any holder or coverage commitment that doesn't reproduce it. The issuer can delay a registration, but it can't register a different key or amount than the one the buyer committed to. Because the stored record is public, anyone can recompute the binding against the Cardano datum.
registerPolicy needs the holder and coverage commitments themselves, not just their hash, so the Buy transaction also carries a registration ticket in its metadata (label 7731: policy id, holder commitment, coverage commitment). It holds no secret: both values are hiding commitments, and they are published on Midnight anyway the moment the policy is registered. The relay lists every live policy on Cardano, keeps only tickets that reproduce the datum's midnight_commitment, and registers each policy that isn't in the registry yet. A forged ticket is reported and ignored; the circuit would reject it regardless. Policies bought before the binding shipped hold a placeholder commitment and are shown as pre-binding rather than mirrored.
The policy key is the private proof of ownership on Midnight: proveCover, fileClaim, and rotateHolder all check the holder secret through the localSecretKey witness. It's saved in your browser (localStorage, keyed by policy id) before you sign, and you can download it as plain JSON or as a passphrase-encrypted backup (PBKDF2-SHA-256, 600,000 iterations, then AES-256-GCM). My policies shows whether each policy's key is on this device and whether it re-derives the on-chain commitment. You can also restore a key from a backup there.
The SDK formulas are checked against the compiled contract's pure circuits on random inputs. A policy registered from an SDK-made key proves cover with that key. A wrong secret, a wrong salt, a swapped holder, an inflated amount, or another policy's id is rejected (contracts/midnight/test/policy-cover.test.mjs).
Authorization without public keys#
The contract never calls ownPublicKey(). To act as the holder, a caller recomputes roleCommitment(localSecretKey(), holderTag()) inside the circuit and must match the stored holder. The only value disclosed is that commitment, which is already on the ledger. The issuer and assessor roles work the same way: the issuer commitment is derived from the deployer's key in the constructor, and the assessor commitment is passed in at deployment.
proveCover: the partner hook#
policy exists and status == ACTIVE
caller's roleCommitment(sk, "holder") == record.holder
coverageCommitment(amount, salt) == record.coverage
amount ≥ minCoverage
→ coverProofs += 1A successful proof shows that the caller holds an active policy with at least minCoverage. It doesn't reveal the exact amount or the caller's key. A forged opening fails the commitment check. A threshold above the committed amount fails the comparison. The test suite covers both.
This is the integration point for partners. A DEX or lending market can offer "insured-only" pools or better terms to users who prove cover, and learn nothing else from the proof.
Holder rotation#
rotateHolder(policyId, newHolderCommitment) lets the current holder move an active policy to a new key. Use it after losing a device, to migrate wallets, or to transfer cover privately. Neither the old key nor the new key is revealed.
- 01
Only the current holder
Same witness check asproveCoverandfileClaim. Strangers and the issuer are rejected. - 02
Only while ACTIVE
Policies that areCLAIM_PENDING,PAID, orEXPIREDstay with the holder of record. Nobody can re-key a policy mid-claim. - 03
A real change
The new commitment must be non-zero and different from the current one. - 04
Only the holder changes
Coverage, expiry, and evidence are untouched. The publicholderRotationscounter goes up. - 05
Immediate effect
The old key failsproveCover,fileClaim, androtateHolderfrom then on. The new key passes them and can rotate again.
To transfer cover, the current holder also gives the new holder the coverage opening (amount, salt) off-ledger. The new holder can check it against the public coverage commitment before accepting. Eight simulation tests cover rotation, part of the registry's 26.
Evidence commitments#
fileClaim records only a non-zero commitment to the evidence bundle. The evidence itself stays with the claimant and is shared with assessors off-ledger. A rejected claim clears the commitment. An approved claim keeps it on the PAID record. See Assessed claims.
The contract publishes the commitment scheme as a pure circuit, so claimants, assessors, and the SDK all compute the same 32 bytes:
evidenceTag() = pad(32, "plutusshield:evidence:v1")
evidenceCommitment(digest, salt) =
persistentHash<Vector<3, Bytes<32>>>([ evidenceTag(), digest, salt ])
= SHA-256(tag ‖ digest ‖ salt)
digest = SHA-256(canonical JSON of the bundle)
salt = 32 random bytes, kept in the claimant's key filefileClaim can't check the opening: the bundle never enters a circuit. Committee members check it off-ledger, before voting with voteClaim.
The evidence vault#
The evidence vault is the client side of an exploit claim. It runs entirely in the browser on WebCrypto; the same code (sealEvidence, verifyEvidence) runs in Node for tooling.
- 01
Canonical bundle
Policy id, protocol and affected contracts, incident type and description, start and detection times (UTC), exploit transaction ids, the loss amount and asset, and the name, size, and SHA-256 of each supporting file. Serialized as JSON with sorted keys and no whitespace (RFC 8785 ordering), so the same evidence always gives the same bytes. - 02
Commit
Digest the bytes and commit with a fresh random salt, as above. The salt makes the commitment hiding: nobody can confirm a guessed bundle from the ledger, and re-filing the same evidence produces an unlinkable commitment. - 03
Encrypt
AES-256-GCM under a fresh random 256-bit key and 96-bit nonce. The file header (schema, policy id, commitment) is bound as additional data, so editing it breaks decryption. The claimant downloads two files: the encrypted bundle, which is safe to store anywhere, and the key file (AES key + salt). - 04
File and discloseMidnight
The holder submitsfileClaim(policyId, commitment)and sends both files to the assessor privately. - 05
AssessMidnight
A committee member decrypts, checks the plaintext is the canonical encoding of a valid bundle, recomputes the commitment, compares it withPolicyRecord.evidence, and matches supporting files by hash. Then each member judges the claim and votes withvoteClaim; 2-of-3 decides.
| Party | Learns | Can't do |
|---|---|---|
| Midnight ledger / public | That a claim was filed on a policy id, and a 32-byte commitment | Read or confirm the evidence |
| Anyone holding only the encrypted bundle | Policy id and commitment (in the header) | Decrypt it, or alter it without detection |
| Assessor (given the key file) | The full bundle, and whether it is exactly what was filed | Claim the holder filed different evidence |
| Claimant after filing | Everything | Swap in different evidence: any change fails the commitment check |
Tests: 13 SDK tests (round trip, tamper detection on ciphertext, nonce, header, and salt, wrong and mismatched keys, non-canonical plaintext, commitment determinism, attachment matching), plus 3 Midnight simulation tests that check the SDK against the compiled evidenceCommitment circuit on random inputs and run file → verify → resolve with SDK-sealed bundles.
What stays public#
- Policy ids, statuses, expiries, and the stored commitments.
- The counters
activePolicies,claimsFiled,claimsPaid,coverProofs, andholderRotations. - The fact that a given policy was proven, claimed, or rotated, though not by whom.