# Revocation Epochs & Freshness

### Purpose

Compliance freshness has two layers:

1. **KYC Verification Timestamp** → When was the user last verified?
   * Recorded once in proof metadata.
   * Protocols decide how old is “too old” (jurisdiction-specific).
2. **Sanctions & Risk Epochs** → Rolling counters that track dynamic changes.
   * Incremented whenever sanctions lists or risk profiles update.
   * Only addresses affected by a change are updated.

This layered approach avoids forcing users to re-KYC daily, while ensuring protocols can enforce up-to-date sanctions and AML checks.

***

### Why It Matters

* **KYC validity** → EU vs. US vs. emerging market rules differ (6 months, 1 year, etc.).
* **Sanctions screening** → must be near real-time (lists update daily/weekly).
* **Risk monitoring** → risk scores can change without invalidating full KYC.

Without this separation, you’d either:

* Burden users with unnecessary re-checks, or
* Accept stale compliance states.

***

### How It Works

#### Cardano (Merkle UTXO)

The Compliance UTXO datum includes:

```json
{
  "merkle_root": "0xabc123...",
  "kyc_verified_at": "2025-03-15T10:00:00Z",
  "sanctions_epoch": 452,
  "risk_profile_score": 17,
  "midnight_ref": "0xdeadbeef#0",
  "fairway_sig": "sig(...)"
}

```

* **`kyc_verified_at`** = fixed timestamp of when KYC was performed.
* **`sanctions_epoch`** = current counter (increments on list/risk changes).
* **`risk_profile_score`** = optional numeric risk measure (low=0, high=100).

***

#### EVM (EAS Attestation)

EAS attestations include the same fields:

```json
{
  "subject": "0xUserWallet",
  "policyId": "POOL-A.KYCv2.EU",
  "kyc_verified_at": "2025-03-15T10:00:00Z",
  "sanctions_epoch": 452,
  "risk_profile_score": 17,
  "commitmentRoot": "0xabc123...",
  "epoch": 452
}

```

* Protocols pass `expectedEpochRoot` into the PolicyEngine for freshness.
* Off-chain rules define how old a `kyc_verified_at` can be.

***

#### Midnight (Proof Ledger)

* ZK-proofs generated by the Cloud Agent are posted to Midnight with:
  * **KYC verification timestamp**
  * **Current sanctions epoch**
* Serves as the immutable audit trail for regulators.

***

### Diagram

```mermaid
flowchart TD
    U[User completes KYC once] --> V[Vault stores PII + timestamp]
    V --> A[Fairway Agent generates proof]
    A --> M[Midnight Ledger (proof + kyc_verified_at + sanctions_epoch)]
    M --> C[Cardano Merkle UTXO {root, timestamp, epoch, sig}]
    M --> E[EVM Attestation {policyId, timestamp, epoch}]
    S[Sanctions feed update] --> F[Cloud Agent updates sanctions_epoch and only impacted leaves]
    F --> C
    F --> E

```

***

### Enforcement Logic

1. **Check KYC freshness**
   * Compare `kyc_verified_at` against protocol’s policy.
   * Example: “only accept KYC within last 6 months.”
2. **Check sanctions epoch**
   * Ensure user’s proof includes the **latest sanctions\_epoch**.
   * If out of date → reject.
3. **Check risk score** (optional)
   * Compare against configured thresholds.

***

#### Cardano (Aiken snippet)

```
let ok_kyc = ctx.tx.now - utxo.datum.kyc_verified_at <= rule.max_age
let ok_epoch = utxo.datum.sanctions_epoch == registry.current_epoch

```

#### EVM (Solidity snippet)

```solidity
require(
  block.timestamp - kycVerifiedAt <= maxAge,
  "KYC_DENIED:STALE_KYC"
);

require(
  latestEpochRoot == expectedEpochRoot,
  "KYC_DENIED:STALE_SANCTIONS"
);

```

***

### Benefits

* **Jurisdiction-aware** → protocols choose their own KYC freshness policy.
* **User-friendly** → users don’t re-KYC for every sanctions update.
* **Efficient** → only affected addresses updated when sanctions lists change.
* **Audit-ready** → Midnight provides historical proof trail.

***

### Compliance Alignment

* **FATF Recommendation 10** (ongoing due diligence) → sanctions epoch updates.
* **AML Directives** → periodic KYC refresh enforced per institution.
* **GDPR** → only timestamps & hashed commitments on-chain.
* **Regulatory audits** → auditors can query `kyc_verified_at` + `epoch` state at time of tx.

***

### Next Steps

* See [Build on Cardano](https://docs.fairway.global/~/revisions/xqNJ6bTRIwH1epmr6yrr/developers/build-on-cardano) → validator checks timestamps + epoch.
* See [Build on EVM](https://docs.fairway.global/~/revisions/xqNJ6bTRIwH1epmr6yrr/developers/build-on-evm) → attestation freshness.
* Review [Trust Registries](https://docs.fairway.global/~/revisions/xqNJ6bTRIwH1epmr6yrr/developers/core-concepts/trust-registries) → how issuer keys evolve with epochs.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.fairway.global/developers/core-concepts/revocation-epochs-and-freshness.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.