> ## Documentation Index
> Fetch the complete documentation index at: https://docs.manthan.systems/llms.txt
> Use this file to discover all available pages before exploring further.

# Attestations

> What an attestation is and how to use it

## What is an attestation?

An attestation is the signed record of an authority verification outcome. It is the output of `executeFromSignals` and contains everything needed to independently verify the decision - by any party, at any time, without access to your infrastructure.

## Attestation structure

```json theme={null}
{
  "executionId":           "88a9db95-5f31-4f0d-84de-28a3ec9e3c83",
  "execution_fingerprint": "43258cff783fe703...",
  "policyId":              "loan-approval",
  "policyVersion":         "1.0.0",
  "schemaVersion":         "1.0.0",
  "runtimeVersion":        "1.0.0",
  "runtimeHash":           "4ece56164e1a8809...",
  "signalsHash":           "43258cff783fe703...",
  "decision": {
    "action":            "approve",
    "requires_override": false,
    "reason":            "Credit score meets standard threshold."
  },
  "execution_state": "completed",
  "signature":       "TU6LMv5NJJm1KvM2..."
}
```

## Field reference

| Field                        | Type        | Description                                                                              |
| ---------------------------- | ----------- | ---------------------------------------------------------------------------------------- |
| `executionId`                | UUID        | Unique identifier for this specific execution event                                      |
| `execution_fingerprint`      | SHA-256 hex | `sha256(canonicalize({ policyId, policyVersion, signals }))` - the replay protection key |
| `policyId`                   | string      | Which policy governed this decision                                                      |
| `policyVersion`              | semver      | Which version of the policy                                                              |
| `schemaVersion`              | semver      | Schema version used for evaluation                                                       |
| `runtimeVersion`             | semver      | Runtime version that produced this attestation                                           |
| `runtimeHash`                | SHA-256 hex | Hash of the runtime itself - pins the exact code                                         |
| `signalsHash`                | SHA-256 hex | Hash of the input signals                                                                |
| `decision.action`            | string      | The governance outcome                                                                   |
| `decision.requires_override` | boolean     | Whether human override is required before execution                                      |
| `decision.reason`            | string      | Human-readable explanation of the decision                                               |
| `execution_state`            | string      | `"completed"` or `"pending_override"`                                                    |
| `signature`                  | base64      | Ed25519 signature over the canonical payload                                             |

## executionId vs execution\_fingerprint

These are semantically distinct:

| Field                   | What it identifies                  | How it's generated                                                           |
| ----------------------- | ----------------------------------- | ---------------------------------------------------------------------------- |
| `executionId`           | This specific execution event       | `crypto.randomUUID()` - random                                               |
| `execution_fingerprint` | The content of the execution inputs | `sha256(canonicalize({ policyId, policyVersion, signals }))` - deterministic |

The `execution_fingerprint` is the replay protection key - same signals always produce the same fingerprint, and the second submission is rejected. The `executionId` is unique per event even if signals differ.

## Verifying an attestation

```typescript theme={null}
import { verifyAttestation, LocalVerifier } from "@parmanasystems/core";

const verifier = new LocalVerifier(publicKey);
const result   = verifyAttestation(attestation, verifier);

console.log(result.valid);   // true if all checks pass
console.log(result.checks);
// {
//   signature_verified: true,
//   runtime_verified:   true,
//   schema_compatible:  true,
//   governed:           true,
// }
```

## Storing attestations

Attestations are plain JSON - store them in any database. They remain verifiable forever as long as you keep the public key.

```typescript theme={null}
// Store
import fs from "fs";
fs.writeFileSync("attestation.json", JSON.stringify(attestation, null, 2));

// Retrieve and verify later
const stored = JSON.parse(fs.readFileSync("attestation.json", "utf8"));
const result = verifyAttestation(stored, verifier);
```

For structured PostgreSQL-backed storage with querying support, use `@parmanasystems/audit-db`.

## Decisions that require override

When `decision.requires_override` is `true`, the `execution_state` is `"pending_override"` and a human approver must explicitly sign off before execution proceeds.

```typescript theme={null}
import { approveOverride } from "@parmanasystems/core";

const override = await approveOverride({
  execution_fingerprint:
    attestation.execution_fingerprint,
  approved_by:   "user@example.com",
  approver_role: "risk-manager",
  reason:        "Manually reviewed and approved based on supporting documentation.",
});
```

## Use Cases

### Regulatory proof-of-decision for loan rejections

When a borrower disputes a loan rejection under the RBI Fair Practices Code, the NBFC retrieves the stored attestation and shares it with the regulator. The recipient runs `verifyAttestation` with the NBFC's public key � without any database access � and independently confirms which policy version evaluated which signals and that the decision has not been modified since signing. The `bundleHash` in the attestation pins the exact policy artifact.

### Audit trail for insurance claims (IRDAI)

An insurer stores every claim attestation in `@parmanasystems/audit-db`. During an IRDAI inspection, the audit team queries all `reject` decisions for claims above ?5 lakh. The `bundleHash` in each attestation proves the exact policy rules that governed each decision � the insurer cannot retroactively claim a different rule applied.

### Multi-party verification in MSME co-lending

A fintech co-lends with a bank. Both parties need to verify that credit decisions were made using the agreed policy. The fintech shares attestations; the bank verifies them independently using the shared public key � no API call to the fintech's infrastructure required.

## See also

* [Portable Verification](/architecture/portable-verification) - how attestations enable independent verification
* [Replay Protection](/concepts/replay-protection) - how `execution_fingerprint` prevents duplicate execution
* [Audit DB](/packages/audit-db) - PostgreSQL-backed attestation storage