verify
verify takes a receipt and checks it against chain accounts read over RPC. It needs no wallet.
import voynich from 'voynich'
const check = await voynich.verify(id)
console.log(check.verified, check.signature, check.record, check.expiry, check.reason)Signature#
verify(id: string, options?: { receipt?: ReceiptView; outputEnvelope?: string; signal?: AbortSignal }): Promise<Verification>idstringrequiredA receipt's address, its call's address, or the signature of the transaction that settled it.
options.receiptReceiptViewA receipt already read from GET /v1/receipts/{id}. Without it verify reads it.
options.outputEnvelopestringAn output envelope, base64. When given, its SHA-256 must equal the receipt's output hash.
options.signalAbortSignalAborts the reads.
What comes back#
verifiedbooleanTrue when signature, record and expiry are all true.
signaturebooleanThe receipt's Ed25519 signature is valid for the receipt message (the call address, the input hash and the output hash) under the enclave's signing key.
recordbooleanThe receipt, the enclave and the attestation record hold together on chain. See The record check.
expirybooleanThe attestation record was in force at the receipt's slot: recorded at or before it, expiring after it.
receiptReceiptThe receipt that was checked.
reasonstring, optionalWhy the receipt is not verified. Absent when verified is true.
fixturebooleanFalse against a cluster.
What each check proves is in Calls and receipts.
The record check#
record is true when all of this holds, read from the chain and not from the API:
- the Config, the Receipt, the Enclave and the Model exist and are owned by the
voynichprogram, and the record is owned by the attestation program the Config names - the Receipt is at the address derived from its call, and its call, model, enclave, hashes, signature, slot and every payment equal what the API returned
- the Model is at the address derived from its name, the Enclave at the address derived from its signing key, and the record at the address derived from that key, which is the record the Enclave names
- the record names the enclave's signing key and has the layout version the Config names
- the record's measurement is in the Model's allowed measurements
When the enclave has attested again since the call settled, the record on chain is newer than the receipt. verify then reads the record as it was at the receipt's slot from the attestation program's events in the RPC's transaction history.
For a transaction signature, verify also reads that transaction and requires that it succeeded, in the receipt's slot, and emitted the CallSettled event of this receipt.
Reasons#
reason | Meaning |
|---|---|
The returned receipt does not match the requested identifier. | The API answered with a receipt that is not the one asked for. |
Encrypted output hash does not match the receipt. | The outputEnvelope passed is not the output the enclave signed. |
The requested transaction did not settle this receipt. | The transaction signature is not the one that settled the receipt. |
A required chain account is missing. | The Config, Receipt, Enclave, record or Model is not on chain. |
A chain account owner does not match its program. | An account is not owned by the voynich program. |
The attestation owner does not match the chain configuration. | The record is not owned by the configured attestation program. |
The signature, attestation binding or expiry check failed. | One of the three checks is false. The booleans say which. |
Failures#
verify returns verified: false for a receipt that does not hold. It throws when it cannot decide:
| Thrown | When |
|---|---|
ApiClientError with RECEIPT_NOT_FOUND | No receipt matches the id. |
VoynichError with PROGRAM_MISMATCH | The API names a program other than the one the SDK is built for. |
Error, The RPC did not retain the settlement transaction | The RPC no longer holds the transaction of the signature given. |
Error, The RPC has no retained attestation history for this receipt | The record was renewed after settlement and the RPC no longer holds the record's history. |
History that cannot be read is never taken as verification. An RPC with full history verifies any receipt.
The signature alone#
verifyReceipt checks the signature without any network access:
import { fromBase58 } from '@voynich/contract'
import { verifyReceipt, fromBase64, fromHex } from 'voynich/crypto'
const ok = verifyReceipt(
fromBase64(view.receipt.signature),
fromBase58(view.enclaveSigningKey),
fromBase58(view.receipt.call),
fromHex(view.receipt.inputHash),
fromHex(view.receipt.outputHash),
)The same checks by hand, on the site and from the CLI, are in Verify a receipt.