> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.adid.dev/llms.txt.
> For full documentation content, see https://docs.adid.dev/llms-full.txt.

# Verification Flow

Verification is the process by which a Verifier cryptographically validates a Verifiable Credential or Verifiable Presentation.

## Verification Flow Overview

```mermaid
sequenceDiagram
    participant Verifier
    participant Holder Wallet
    participant IDA API
    participant ADI Chain

    Verifier->>Holder Wallet: 1. Send proof request
    Holder Wallet->>Holder Wallet: 2. Select credentials
    Holder Wallet->>Holder Wallet: 3. Create VP (optional: selective disclosure)
    Holder Wallet->>Verifier: 4. Submit VP

    Verifier->>IDA API: 5. POST /credentials/verify
    IDA API->>ADI Chain: 6. Resolve issuer DID
    IDA API->>ADI Chain: 7. Fetch schema
    IDA API->>ADI Chain: 8. Check revocation status
    IDA API->>IDA API: 9. Verify cryptographic proof
    IDA API->>IDA API: 10. Validate schema compliance
    IDA API->>IDA API: 11. Check expiration
    IDA API->>Verifier: 12. Return verification result
```

## Proof Request

A verifier initiates verification by sending a proof request to the holder:

```json
{
  "type": "https://didcomm.org/present-proof/3.0/request-presentation",
  "id": "proof-req-001",
  "from": "did:adi:verifier001...",
  "to": ["did:adi:holder001..."],
  "body": {
    "goal_code": "verify.degree",
    "will_confirm": true,
    "presentation_definition": {
      "id": "degree-verification",
      "input_descriptors": [
        {
          "id": "degree-credential",
          "name": "University Degree",
          "purpose": "Verify the applicant holds a bachelor's degree",
          "constraints": {
            "fields": [
              {
                "path": ["$.credentialSubject.degree.type"],
                "filter": { "type": "string", "const": "BachelorDegree" }
              },
              {
                "path": ["$.credentialSubject.degree.university"],
                "filter": { "type": "string" }
              }
            ]
          }
        }
      ]
    }
  }
}
```

This follows the DIF Presentation Exchange v2 format.

## Verify a Credential

### Request

```http
POST /api/v1/credentials/verify
Content-Type: application/json

{
  "credential": {
    "@context": ["https://www.w3.org/2018/credentials/v1", "..."],
    "type": ["VerifiableCredential", "UniversityDegreeCredential"],
    "issuer": "did:adi:issuer001...",
    "issuanceDate": "2026-03-28T10:00:00Z",
    "credentialSubject": { "..." },
    "credentialStatus": { "..." },
    "proof": { "..." }
  }
}
```

### Response

```json
{
  "verified": true,
  "checks": {
    "proof": {
      "status": "valid",
      "type": "Ed25519Signature2020",
      "verificationMethod": "did:adi:issuer001...#key-1"
    },
    "issuer": {
      "status": "valid",
      "did": "did:adi:issuer001...",
      "active": true
    },
    "schema": {
      "status": "valid",
      "schemaId": "did:adi:schema:university-degree-v1"
    },
    "expiration": {
      "status": "valid",
      "expirationDate": "2030-12-31T23:59:59Z"
    },
    "revocation": {
      "status": "valid",
      "revoked": false,
      "checkedAt": "2026-03-28T12:00:00Z"
    }
  },
  "warnings": []
}
```

## Verify a Presentation

### Request

```http
POST /api/v1/presentations/verify
Content-Type: application/json

{
  "presentation": {
    "@context": ["https://www.w3.org/2018/credentials/v1"],
    "type": ["VerifiablePresentation"],
    "holder": "did:adi:holder001...",
    "verifiableCredential": [ { "..." } ],
    "proof": {
      "type": "Ed25519Signature2020",
      "challenge": "abc123-verifier-nonce",
      "domain": "https://verifier.example.com",
      "proofValue": "z4Abc123..."
    }
  },
  "challenge": "abc123-verifier-nonce",
  "domain": "https://verifier.example.com"
}
```

### Response

```json
{
  "verified": true,
  "presentationChecks": {
    "holderProof": "valid",
    "challenge": "matched",
    "domain": "matched"
  },
  "credentialResults": [
    {
      "index": 0,
      "type": "UniversityDegreeCredential",
      "verified": true,
      "checks": {
        "proof": "valid",
        "issuer": "valid",
        "schema": "valid",
        "expiration": "valid",
        "revocation": "valid"
      }
    }
  ]
}
```

## Verification Checks Explained

### 1. Proof Integrity

The cryptographic signature is verified:

* Resolve the `verificationMethod` from the issuer's DID Document
* Extract the public key
* Verify the signature over the canonicalized credential data

### 2. Issuer DID Resolution

* Resolve the issuer DID from the ADI blockchain
* Confirm the DID is not deactivated
* Confirm the verification method exists in the DID Document
* Confirm the key is listed in the `assertionMethod` relationship

### 3. Schema Compliance

* Fetch the schema from the Schema Registry
* Validate `credentialSubject` attributes against the schema

### 4. Expiration

* Compare `expirationDate` against current time
* If expired, the credential is invalid

### 5. Revocation

* Query the Revocation Registry using `credentialStatus`
* Check the specific `statusListIndex` in the StatusList2021 bitstring
* If the bit is set, the credential has been revoked

## Selective Disclosure Verification

For BBS+ credentials, the verifier receives a derived proof:

```http
POST /api/v1/presentations/verify
Content-Type: application/json

{
  "presentation": {
    "verifiableCredential": [
      {
        "credentialSubject": {
          "id": "did:adi:holder001...",
          "degree": {
            "type": "BachelorDegree",
            "university": "MIT"
          }
        },
        "proof": {
          "type": "BbsBlsSignatureProof2020",
          "nonce": "verifier-nonce",
          "proofValue": "DerivedProof123..."
        }
      }
    ]
  }
}
```

The verifier only sees the disclosed attributes (`type` and `university`), but can verify they were part of a validly signed credential.

## Verification Failures

| Failure              | Description                        | Mitigation                       |
| -------------------- | ---------------------------------- | -------------------------------- |
| `INVALID_SIGNATURE`  | Proof signature does not verify    | Credential may be tampered       |
| `ISSUER_DEACTIVATED` | Issuer DID is deactivated          | Contact issuer for re-issuance   |
| `CREDENTIAL_EXPIRED` | Current time > expirationDate      | Request updated credential       |
| `CREDENTIAL_REVOKED` | Credential is in revocation list   | Credential is no longer valid    |
| `SCHEMA_MISMATCH`    | Claims do not match schema         | Possible schema version mismatch |
| `CHALLENGE_MISMATCH` | VP challenge does not match        | Possible replay attack           |
| `KEY_NOT_FOUND`      | Verification method not in DID Doc | Key may have been rotated        |