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

# Architecture

> How Contra binds verified humans to on-chain agents — ZK-private, regulator-disclosable.

## The three layers

<CardGroup cols={3}>
  <Card title="Identity" icon="fingerprint">
    A human verifies once (Smile ID hosted flow). Contra issues an Albus credential, signed by a BabyJubJub issuer key. PII never leaves Contra.
  </Card>

  <Card title="Compliance Engine" icon="shield-check">
    Workflows + sessions orchestrate the verification recipe (KYC, AML, biometric, phone, address). Outcome → a signed **ContraToken**.
  </Card>

  <Card title="On-chain Credential" icon="link">
    The credential becomes a Groth16 proof, verified on-chain by `KycVerifier.sol`. The agent is minted on **canonical ERC-8004 IdentityRegistry** (`0x8004A169…`). Any contract can read its tier permissionlessly.
  </Card>
</CardGroup>

## The data path

```mermaid theme={null}
flowchart LR
  Smile[Smile KYC] --> Issuer[Issuer · BabyJub sign] --> KV[Encrypted KV]
  KV --> Prover[Node prover · Groth16]
  Prover --> SSI[SSIAgentV2 on Base mainnet]
  SSI --> Reads((free on-chain reads))
  Issuer --> Token[ContraToken JWT]
  Token --> SDK[Your backend]
```

## What goes on-chain (and what doesn't)

| On-chain                          | Off-chain                            |
| --------------------------------- | ------------------------------------ |
| Agent ID + ZK commitment          | Raw name / DOB / document number     |
| Issuer key (Ax, Ay) — allowlisted | Smile job ID + raw images            |
| Tier (1 / 2 / 3) + `validUntil`   | The Albus credential (encrypted, KV) |
| `keccak256(issuer pubkey)`        | The session's `expected_details`     |

The chain learns **"verified, tier X, trusted issuer, until Y"** — never PII.

## Composability

Contra reads + writes are intentionally **permissionless**:

* Any smart contract calls `SSIAgentV2.getEffectiveKycTier(agentId)` for free.
* Off-chain backends call `GET /v1/compliance/:address` (free, on-chain read mirror).
* Paid endpoints (verification, on-chain mint) are gated by either `x-api-key` (developers) or `x402` (agents — pay-per-call USDC).