# Concepts

### Providers

#### What they are

Backends capable of running secure enclaves (e.g., AWS Nitro, GCP, Azure). Providers expose supported regions and a config schema (e.g., dockerImage, cpuCount, memoryMiB).

#### Why it matters

Each provider has different runtime limits, compliance certifications, and regional availability. You pick one and pass provider-specific providerConfig when creating an enclave.

#### Key objects & calls

* getProviders() → list all available providers, regions, and config schemas
* getProvider(providerId) → fetch details for a specific provider
* providerConfig → per-provider runtime settings (validated against schema)

#### Typical flow

1. List providers → choose one based on your compliance/region needs
2. Read provider's configSchema → understand required fields
3. Validate your config against schema
4. Create enclave with providerId + providerConfig

***

### Enclaves

#### What they are

Isolated, attested compute environments that run your container image in a hardware-protected enclave. They provide cryptographically verifiable isolation from cloud operators and other tenants.

#### Core ideas

* Creation: You provide providerId, region, and providerConfig (e.g., Docker image + resources)
* Ownership: All resources are scoped to your wallet address
* Integration: Optionally link a GitHub repo/branch for CI/CD workflows
* Attestation: Every deployed enclave can generate cryptographic proof of its integrity

#### Key objects & calls

* createEnclave(request) → deploy a new enclave
* getEnclave(enclaveId) → fetch enclave details and status
* getEnclaves(walletAddress) → list all your enclaves
* updateEnclave(request) → modify configuration or GitHub connection
* deleteEnclave(enclaveId, walletAddress) → permanently remove
* getEnclaveLogs(enclaveId, logType, limit) → fetch logs

#### What runs inside

Your Docker image (from Docker Hub, private registry, or ECR) plus environment variables you configure through your provider's settings.

#### When to use

* Running sensitive computations that require hardware-level isolation
* Processing confidential data (PII, healthcare, financial)
* Building zero-trust applications with cryptographic verification
* Multi-party computation scenarios

***

### Lifecycle

#### What it is

The operational state machine that manages enclave deployment, operation, and teardown.

#### States

Deployment Flow:

* PENDING\_DEPLOY → awaiting deployment initiation
* DEPLOYING → infrastructure provisioning in progress
* DEPLOYED → enclave is running and ready

Pause/Resume Flow:

* PAUSING → stopping compute resources
* PAUSED → enclave suspended, no compute costs
* RESUMING → restarting from paused state
* DEPLOYED → back to running state

Termination Flow:

* PENDING\_DESTROY → awaiting termination initiation
* DESTROYING → infrastructure teardown in progress
* DESTROYED → enclave removed, resources freed
* TERMINATED → final state (irreversible)

Error State:

* FAILED → deployment or operation error (see error\_message)

#### Actions

* pauseEnclave(enclaveId, walletAddress) → stop compute without destroying
* resumeEnclave(enclaveId, walletAddress) → restart a paused enclave
* terminateEnclave(enclaveId, walletAddress) → permanently destroy (irreversible)

#### When to use what

| Action    | Use When                                      | Result                          |
| --------- | --------------------------------------------- | ------------------------------- |
| Pause     | Stop spending temporarily; keep configuration | No compute costs, quick restart |
| Resume    | Bring paused enclave back online              | Returns to DEPLOYED state       |
| Terminate | Done with enclave permanently                 | All data destroyed, cannot undo |
| Delete    | Remove enclave record completely              | Enclave must be DESTROYED first |

***

### Attestation & Verification

#### What it is

Cryptographic proof that your enclave is running genuine, unmodified code inside a hardware-protected secure enclave. Uses Platform Configuration Registers (PCRs), certificate chains, and signed attestation documents.

#### Why it matters

Allows you and third parties to verify:

* The exact code running in your enclave (via PCR measurements)
* The enclave is running in genuine AWS Nitro hardware
* No tampering has occurred since deployment
* Compliance with security standards (FIPS 140-2, SOC2, HIPAA, etc.)

#### Key concepts

**PCR Measurements**

Hardware-generated cryptographic hashes:

* PCR0: Hash of the enclave image file
* PCR1: Linux kernel and bootstrap hash
* PCR2: Application/container hash
* PCR8: Signing certificate hash

**Attestation Document**

Contains:

* PCR measurements
* X.509 certificate for verification
* Certificate authority bundle
* Timestamp and module ID
* Optional user data and nonce for replay protection

**Verification Details**

* Trust Level: HIGH, MEDIUM, LOW, or UNKNOWN
* Integrity Score: 0-100% confidence rating
* Verification Status: VERIFIED, PENDING, or FAILED
* Compliance Checks: SOC2, HIPAA, FIPS 140-2, Common Criteria
* Risk Score: Lower is better (0-100)

#### Key objects & calls

* getAttestation(enclaveId) → retrieve attestation document + verification details
* getVerificationStatus(enclaveId) → quick status check
* verifyAttestation(enclaveId, request?) → comprehensive verification with checks
* generateIntegrationSnippet(enclaveId, language) → code for third-party verification

#### Typical flow

1. Deploy enclave → wait for DEPLOYED status
2. Call getAttestation(enclaveId) → get attestation document
3. Share verification URL with third parties
4. Third parties call verification endpoint with optional nonce
5. Receive trust level, PCR hashes, and compliance status

#### When to use

* Before processing sensitive data: Verify enclave integrity first
* Compliance audits: Provide cryptographic proof of secure execution
* Multi-party scenarios: Let partners verify your enclave independently
* Zero-trust architectures: Continuously verify, never trust blindly
* Integration with external systems: Provide verification endpoints to partners

#### What you get

```json
{
  "attestationDocument": {
    "pcrs": {
      "0": "abc123...",
      "1": "def456...",
      "2": "ghi789...",
      "8": "jkl012..."
    },
    "certificate": "-----BEGIN CERTIFICATE-----...",
    "timestamp": 1234567890,
    "moduleId": "i-abc123..."
  },
  "verification": {
    "trustLevel": "HIGH",
    "verificationStatus": "VERIFIED",
    "integrityScore": 95
  },
  "endpoints": {
    "verificationUrl": "https://app.trezalabs.com/api/enclaves/{id}/attestation/verify",
    "apiEndpoint": "https://app.trezalabs.com/api/enclaves/{id}/attestation",
    "webhookUrl": "https://app.trezalabs.com/webhooks/attestation/{id}"
  }
}
```

***

### Tasks

#### What they are

Scheduled operations that run inside your enclaves. Tasks use cron expressions for flexible scheduling and can automate recurring workloads.

#### Core ideas

* Scheduling: Cron-style expressions (e.g., 0 0 \* \* \* for daily at midnight)
* Association: Each task is linked to a specific enclave
* Ownership: Scoped to your wallet address
* Execution tracking: History of runs with timestamps

#### States

* running → task is active and executing on schedule
* stopped → task is paused, not executing
* failed → last execution encountered an error
* pending → task created but not yet started

#### Key objects & calls

* createTask(request) → create new scheduled task
* getTasks(walletAddress) → list all your tasks
* updateTask(request) → modify schedule, status, or configuration
* deleteTask(taskId, walletAddress) → remove task

#### Typical flow

1. Create enclave → wait for DEPLOYED status
2. Create task with enclaveId, schedule, and description
3. Task runs automatically on schedule
4. Monitor via lastRun timestamp and status
5. Update status: 'stopped' to pause execution

#### When to use

* Batch processing: Run data processing jobs nightly
* Health checks: Periodic monitoring and alerts
* Data synchronization: Regular backups or sync operations
* Scheduled maintenance: Cleanup, archival, or rotation tasks
* Report generation: Daily/weekly/monthly automated reports

#### What you need

```json
{
  name: "Risk Assessment",
  description: "Calculate portfolio risk metrics every 6 hours",
  enclaveId: "enc_abc123",
  schedule: "0 */6 * * *",  // Every 6 hours
  walletAddress: "0x4B0897b0513fdc7C541B6d9D7E929C4e5364D2dB"
}
```

***

### Logs & Monitoring

#### What it is

Comprehensive logging system aggregating logs from multiple sources across your enclave lifecycle.

#### Log sources

**Application Logs**

Stdout/stderr from your Docker container. View what your application prints.

**ECS Deployment Logs**

AWS ECS service logs showing infrastructure-level events (task starting, stopping, health checks).

**Step Functions Logs**

Workflow orchestration logs from deployment/termination state machines.

**Lambda Logs**

Execution logs from trigger functions, validators, and error handlers.

**Error Logs**

Aggregated errors from all sources for quick troubleshooting.

#### Key objects & calls

* getEnclaveLogs(enclaveId, logType, limit) → fetch logs
* logType: 'all', 'application', 'ecs', 'stepfunctions', 'lambda', 'errors'
* limit: max entries to return (default 100)

#### Log structure

```json
{
  timestamp: 1234567890,
  message: "Application started",
  source: "application",     // or "ecs", "stepfunctions", "lambda"
  stream: "stdout",
  logGroup: "/aws/ecs/...",
  type: "application"
}
```

#### When to use what

| Log Type      | Use When                                       |
| ------------- | ---------------------------------------------- |
| application   | Debugging your container code                  |
| ecs           | Infrastructure issues (deployment failures)    |
| stepfunctions | Understanding workflow state transitions       |
| lambda        | Troubleshooting triggers or validators         |
| errors        | Quick overview of all problems                 |
| all           | Comprehensive investigation across all sources |

#### Typical flow

1. Enclave enters FAILED or unexpected state
2. Call getEnclaveLogs(enclaveId, 'errors', 50)
3. Identify error source
4. Call specific log type for detailed context
5. Fix issue and redeploy

***

### API Keys & Authentication

#### What they are

Programmatic access credentials for using the Treza SDK. API keys provide scoped permissions and are tied to your wallet address.

#### Why it matters

Enables CI/CD pipelines, automation scripts, and third-party integrations to manage your enclaves without manual UI interaction.

#### Permission scopes

* enclaves:read → list and view enclave details
* enclaves:write → create, update, delete, pause, resume, terminate enclaves
* tasks:read → view tasks and execution history
* tasks:write → create, update, delete tasks
* logs:read → access logs from all sources

#### Key objects & calls

* createApiKey(request) → generate new API key (key shown once!)
* getApiKeys(walletAddress) → list your API keys
* updateApiKey(request) → change permissions or status
* deleteApiKey(apiKeyId, walletAddress) → revoke access

#### States

* active → key is valid and can authenticate requests
* inactive → key is disabled but not deleted (can be reactivated)

#### When to use

* CI/CD pipelines: Automate deployments from GitHub Actions, GitLab CI
* Infrastructure as Code: Manage enclaves with Terraform or Pulumi
* Monitoring systems: Automated health checks and log retrieval
* Multi-user scenarios: Different keys for different team members/systems
* Security rotation: Regular key rotation without affecting other systems

#### Best practices

```typescript
// Create limited-scope keys
const readOnlyKey = await client.createApiKey({
  name: "Monitoring Bot",
  permissions: ['enclaves:read', 'logs:read'],
  walletAddress: myWallet
});

// Production key with full access
const prodKey = await client.createApiKey({
  name: "Production Deploy",
  permissions: ['enclaves:read', 'enclaves:write', 'logs:read'],
  walletAddress: myWallet
});
```

***

### GitHub Integration

#### What it is

OAuth-based connection linking your enclaves to GitHub repositories and branches, enabling automated deployments triggered by Git pushes.

#### Core ideas

* OAuth flow: Secure authentication with GitHub
* Repository linking: Connect specific repos to enclaves
* Branch selection: Choose which branch triggers updates
* Token management: Encrypted storage of access tokens

#### Key objects & calls

* getGitHubAuthUrl(state?) → start OAuth flow, get authorization URL
* exchangeGitHubCode(request) → exchange OAuth code for access token
* getGitHubRepositories(accessToken) → list user's repos
* getRepositoryBranches(request) → list branches for a repo
* updateEnclave({ githubConnection }) → link GitHub to enclave

#### GitHub connection object

```json
{
  isConnected: true,
  username: "yourusername",
  selectedRepo: "owner/repo-name",
  selectedBranch: "main",
  accessToken: "encrypted..."  // Never exposed to client
}
```

#### Typical flow

1. User initiates GitHub connection in UI
2. Call getGitHubAuthUrl() → redirect user to GitHub
3. User authorizes → GitHub redirects with code
4. Call exchangeGitHubCode({ code }) → get access\_token and user info
5. Call getGitHubRepositories(access\_token) → show user their repos
6. User selects repo → call getRepositoryBranches() → show branches
7. User selects branch → call updateEnclave() with githubConnection

#### When to use

* Automated deployments: Push to main → enclave updates automatically
* Development workflows: Feature branch → ephemeral test enclave
* Team collaboration: Share enclave configs via Git
* Version tracking: GitHub history = deployment history
* Rollback capability: Revert Git commit = revert enclave state

***

### Docker Images

#### What they are

Container images that define your enclave's runtime environment. Treza supports public Docker Hub images, private registries, and ECR.

#### Why it matters

Your enclave runs whatever's in the Docker image. The image contains your application code, dependencies, runtime, and configuration.

#### Key concepts

* Image names: library/hello-world, nginx:latest, myorg/myapp:v1.2.3
* Tags: Version identifiers (:latest, :v1.0, :sha-abc123)
* Registries: Docker Hub (public), ECR (private AWS), custom registries

#### Key objects & calls

* searchDockerImages(query) → search Docker Hub for images
* getDockerTags(repository) → list available tags for an image

#### In provider config

```json
{
  dockerImage: "library/hello-world:latest"  // Public image
}

// or

{
  dockerImage: "123456789.dkr.ecr.us-west-2.amazonaws.com/myapp:v1.0"  // Private ECR
}
```

#### When to use what

| Image Type         | Use When                            | Example                                 |
| ------------------ | ----------------------------------- | --------------------------------------- |
| Public Docker Hub  | Testing, demos, open-source tools   | nginx:alpine                            |
| Private Docker Hub | Your proprietary apps (small teams) | yourorg/app:latest                      |
| AWS ECR            | Production workloads, enterprise    | 123.dkr.ecr.region.amazonaws.com/app:v1 |
| Custom registry    | On-prem, air-gapped environments    | registry.internal.com/app               |

#### Best practices

```typescript
// ✅ Good: Specific version tag
dockerImage: "postgres:15.2-alpine"

// ⚠️ Risky: Latest tag (changes without notice)
dockerImage: "postgres:latest"

// ✅ Good: Digest for immutability
dockerImage: "postgres@sha256:abc123..."

// ✅ Good: Semantic versioning
dockerImage: "myapp:v1.2.3"
```

***

### Signers & Key Management

#### What they are

Pluggable signing strategies that decouple transaction signing from private key storage. Instead of storing raw private keys in environment variables or configuration files, you choose a SignerProvider that matches your security requirements. The SDK ships with three built-in signers: EnclaveSigner (production), LocalSigner (development), and BrowserWalletSigner (client-side).

#### Why it matters

* Key isolation: In production, private keys are generated and stored inside Treza Nitro Enclaves. They never leave the hardware-isolated TEE boundary.
* Attestation-backed signing: Before each signing operation, the EnclaveSigner can cryptographically verify that the enclave hasn't been tampered with.
* Flexibility: Swap between enclave, local, or browser wallet signing with a single config change -- same SDK code, different security posture.
* No PII exposure: Private keys never appear in logs, environment variables, or configuration files in production.
* Compliance: Hardware-isolated key management satisfies requirements for SOC2, FIPS 140-2, and financial services regulations.

#### Core ideas

SignerProviderInterface that all signers implement. Defines two methods: getSigner() returns an ethers.js Signer; getAddress() returns the signing address. Any custom key management system (AWS KMS, HashiCorp Vault, hardware wallets) can be integrated by implementing this interface.EnclaveSignerProduction-grade signer that routes signing requests through the Treza Platform API to a Nitro Enclave. The enclave holds the private key in memory-only storage (no persistent disk). Supports attestation verification before signing.LocalSignerDevelopment-only signer that wraps a raw private key string into an ethers.js Wallet. Emits a console warning if used in a production environment. Intended for local development, demos, and automated testing.BrowserWalletSignerClient-side signer that delegates to MetaMask or any injected Web3 wallet (window\.ethereum). Prompts the user to approve each transaction. Suitable for dApp frontends.Signer resolution priorityWhen TrezaKYCClient needs to sign a transaction, it resolves a signer using this priority chain:

1. Explicit signer passed to the method call
2. signerProvider from blockchain config (recommended)
3. Deprecated privateKey from blockchain config (backward compat only)

#### Signing flow (EnclaveSigner)

1. Your app calls submitProofOnChain() or verifyProofOnChain()
2. TrezaKYCClient resolves the signer via signerProvider.getSigner()
3. EnclaveSigner optionally verifies enclave attestation (PCR checks)
4. Unsigned transaction is sent to the enclave via POST /api/enclaves/{id}/sign/transaction
5. Enclave signs the transaction inside the TEE and returns the signed bytes
6. TrezaKYCClient submits the signed transaction to the blockchain
7. Your app receives the transaction hash

#### Key objects & calls

SignerProvider interface

* getSigner(provider?) -- Returns an ethers.js Signer connected to the given provider
* getAddress() -- Returns the signer's Ethereum address
* type -- Human-readable signer type name ('enclave', 'local', 'browser-wallet')

EnclaveSigner

* Constructor: new EnclaveSigner(platformClient, config)
* platformClient -- An authenticated TrezaClient instance
* config.enclaveId -- The enclave ID holding the signing key
* config.verifyAttestation -- Verify enclave integrity before signing (default: true)
* config.attestationNonce -- Optional nonce for replay protection

LocalSigner

* Constructor: new LocalSigner(privateKey)
* privateKey -- Hex-encoded private key (with or without 0x prefix)

BrowserWalletSigner

* Constructor: new BrowserWalletSigner()
* No arguments -- connects to window\.ethereum on first use
* disconnect() -- Clear cached wallet connection

#### When to use what

| Signer                | Environment        | Key Location                      | Attestation | Use Case                            |
| --------------------- | ------------------ | --------------------------------- | ----------- | ----------------------------------- |
| EnclaveSigner         | Production servers | Inside Nitro Enclave (TEE)        | Yes         | Backend services, automated systems |
| LocalSigner           | Local development  | .env file or environment variable | No          | Dev, testing, demos, CI             |
| BrowserWalletSigner   | Client-side dApps  | User's browser wallet             | No          | Frontend applications               |
| Custom SignerProvider | Any                | Your KMS / HSM / Vault            | Optional    | Enterprise, custom infrastructure   |

#### Configuration examples

```typescript
// Production (EnclaveSigner)
import { TrezaClient, TrezaKYCClient, EnclaveSigner } from '@treza/sdk';

const platform = new TrezaClient();
const signer = new EnclaveSigner(platform, {
  enclaveId: process.env.TREZA_ENCLAVE_ID,
  verifyAttestation: true,
});

const client = new TrezaKYCClient({
  apiUrl: process.env.TREZA_API_URL,
  blockchain: {
    rpcUrl: process.env.SEPOLIA_RPC_URL,
    contractAddress: process.env.SEPOLIA_KYC_VERIFIER_ADDRESS,
    signerProvider: signer,
  },
});
```

```typescript
// Custom signer (e.g., AWS KMS)
import { SignerProvider } from '@treza/sdk';
import { ethers } from 'ethers';

class KMSSigner implements SignerProvider {
  readonly type = 'aws-kms';

  async getSigner(provider?: ethers.Provider): Promise<ethers.Signer> {
    // Your KMS signing logic here
  }

  async getAddress(): Promise<string> {
    // Return the address derived from your KMS key
  }
}
```

```typescript
// Client side BrowserWalletSigner
import { TrezaKYCClient, BrowserWalletSigner } from '@treza/sdk';

const client = new TrezaKYCClient({
  apiUrl: 'https://api.trezalabs.com/api',
  blockchain: {
    rpcUrl: 'https://rpc.sepolia.org',
    contractAddress: '0x...',
    signerProvider: new BrowserWalletSigner(),
  },
});
// User will be prompted to connect their wallet on first signing operation
```

#### Best practices

* Always use EnclaveSigner in production -- never store private keys in environment variables, config files, or source code on production servers
* Enable verifyAttestation: true (the default) to cryptographically verify enclave integrity before each signing operation
* Use LocalSigner only for local development and testing; it emits a warning if NODE\_ENV=production
* For CI/CD pipelines, consider a custom SignerProvider that integrates with your secrets manager (AWS KMS, HashiCorp Vault, etc.)
* The deprecated privateKey field in TrezaKYCConfig.blockchain still works for backward compatibility but will be removed in a future major version
* Read-only operations (e.g., isAdult(), getClaims(), hasValidKYC()) don't require a signer at all -- only on-chain write operations need one

#### States

| State                | Description                                        | Can Sign?          |
| -------------------- | -------------------------------------------------- | ------------------ |
| Connected            | Signer resolved and ready                          | Yes                |
| Attestation verified | Enclave integrity confirmed (EnclaveSigner only)   | Yes                |
| Attestation failed   | Enclave integrity check failed                     | No (throws error)  |
| Disconnected         | Browser wallet disconnected or enclave unavailable | No (throws error)  |
| Deprecated           | Using raw privateKey fallback                      | Yes (with warning) |

***

This slots in right after your KYC section. It follows the same structure (What / Why / Core ideas / Key objects / When to use / Best practices / States) and cross-references the KYC concepts since signing is needed for on-chain proof submission.

### KYC & Zero-Knowledge Proofs

#### What they are

Privacy-preserving identity verification using zero-knowledge cryptography. Users prove they meet KYC requirements (e.g., age verification, identity checks) without revealing underlying personal data. Proofs are cryptographically verifiable, stored in DynamoDB, and optionally anchored on-chain for immutability.

#### Why it matters

**Privacy**: Users prove attributes (e.g., "I'm over 18") without sharing passport data, birth dates, or photos.

**Compliance**: Satisfy regulatory requirements (KYC/AML) while minimizing PII exposure and data breach risk.

**Portability**: One proof works across multiple services—verify once, use everywhere.

**Auditability**: Blockchain anchoring provides tamper-proof verification history.

**Cost reduction**: Eliminate redundant verification flows and reduce storage of sensitive data.

#### Core ideas

**Zero-Knowledge Proofs (ZK)**

Cryptographic method proving a statement is true without revealing why. Example: "I'm over 18" without sharing your birth date.

**Commitments**

64-character hex hash that binds the prover to specific data without revealing it. Acts as a fingerprint for the proof.

**Public Inputs**

Non-sensitive data visible to verifiers (e.g., commitment hash, proof type). Used to validate the proof without exposing private information.

**Proof Lifecycle**

1. **Generation**: Mobile app or client generates ZK proof from user's credentials
2. **Submission**: Proof submitted to Treza API (POST `/api/kyc/proof`)
3. **Verification**: Cryptographic validation + timestamp checks
4. **Storage**: Proof stored in DynamoDB with metadata
5. **Blockchain**: Optional on-chain submission for immutability
6. **Expiration**: Proofs expire after 7 days (configurable)

#### Key objects & calls

**submitProof(request)** → Submit new ZK proof for verification

Returns: `proofId`, `blockchainProofId`, `verificationUrl`, `expiresAt`, `chainTxHash`

**getProof(proofId, includePrivate?)** → Retrieve proof details

Returns public data by default; use `includePrivate=true` for proof signature (requires auth)

**verifyProof(proofId)** → Verify proof validity and check expiration

Returns: `isValid`, `publicInputs`, `chainVerified`, `expiresAt`

#### Proof structure

```json
{
  commitment: "1234...abcd",           // 64-char hex commitment hash
  proof: "0x1234...9876",              // ZK proof data (min 65 chars)
  publicInputs: ["0xabc...", "0xdef..."], // Public verification data
  timestamp: "2024-12-15T10:30:00Z",   // Must be within 1 hour
  algorithm: "Pedersen-SHA256"         // Cryptographic algorithm
}
```

**For Users (Mobile/Client)**

1. User provides credentials (passport, ID, etc.) to mobile app
2. App generates ZK proof locally using device secure enclave (iOS: Secure Enclave, Android: TEE)
3. Call `submitProof({ userId, proof, deviceInfo })`
4. Receive `proofId` and `verificationUrl`
5. Share `proofId` with services requiring KYC verification

**For Service Providers (Verifiers)**

1. User provides their `proofId` during onboarding
2. Call `verifyProof(proofId)` to check validity
3. Check `isValid`, `chainVerified`, and `expiresAt`
4. Optionally verify on blockchain using `chainTxHash`
5. Grant access based on verification result

**For Developers (Integration)**

1. Generate proof on client-side (mobile/web)
2. Submit to `/api/kyc/proof` endpoint
3. Store returned `proofId` with user account
4. Re-verify periodically using `/api/kyc/proof/{proofId}/verify`
5. Handle expiration by requesting new proof from user

#### When to use

| Scenario                     | Why KYC Proofs Help                                             |
| ---------------------------- | --------------------------------------------------------------- |
| **Age verification**         | Prove age without revealing birth date or ID documents          |
| **Identity checks**          | Verify user identity without storing PII (GDPR/CCPA compliance) |
| **Financial services**       | Meet KYC/AML requirements with minimal data exposure            |
| **Healthcare**               | Verify credentials while maintaining HIPAA compliance           |
| **Multi-platform access**    | One proof works across multiple services/platforms              |
| **Audit requirements**       | Blockchain anchoring provides immutable verification trail      |
| **International compliance** | Satisfy different jurisdictions without data transfer           |

#### Validation rules

**Commitment**

* Must be exactly 64 characters
* Hex format only (0-9, a-f, A-F)
* Unique per user/session

**Proof**

* Minimum 65 characters
* Contains cryptographic signature
* Generated by trusted client (device secure enclave)

**Timestamp**

* Must be within 1 hour of submission
* Prevents replay attacks
* Ensures proof freshness

**Public Inputs**

* Array of hex strings
* Contains non-sensitive verification data
* Minimum 1 input required

#### States

| State      | Description                                              | Queryable          |
| ---------- | -------------------------------------------------------- | ------------------ |
| `verified` | Proof passed cryptographic verification                  | ✅ Yes              |
| `pending`  | Proof submitted, awaiting blockchain confirmation        | ✅ Yes              |
| `failed`   | Verification failed (invalid proof or expired timestamp) | ✅ Yes              |
| `expired`  | Proof passed expiration date (7 days)                    | ❌ Returns HTTP 410 |

#### Integration examples

```typescript
import { TrezaKYCClient } from '@treza/sdk';

const kycClient = new TrezaKYCClient({ apiUrl: 'https://app.trezalabs.com' });
// Submit proof const result = await kycClient.submitProof({ userId: user.id, proof: zkProof, deviceInfo: { platform: 'web', version: '1.0.0' } });

console.log('Proof ID:', result.proofId); console.log('Verification URL:', result.verificationUrl);
// Verify proof const verification = await kycClient.verifyProof(result.proofId); if (verification.isValid && verification.chainVerified) { console.log('✅ Verified on blockchain'); }Backend Verification

app.post('/onboard', async (req, res) => { 
const { proofId } = req.body;
// Verify proof const result = await fetch( https://app.trezalabs.com/api/kyc/proof/${proofId}/verify ); const verification = await result.json();

if (!verification.isValid) { 
        return res.status(403).json({ error: 'Invalid KYC proof' }); 
    }
    // Grant access 
    await createUserAccount({ ...userData, kycProofId: proofId }); 
    res.json({ success: true }); 
});

```

* **Privacy-first verification**: Prove attributes without revealing sensitive data
* **Blockchain immutability**: Optional on-chain anchoring for audit trails
* **Automatic expiration**: 7-day validity reduces stale verification risk
* **Device tracking**: Platform and version info for security analysis
* **Flexible verification**: Public endpoints for third-party verification
* **Compliance ready**: GDPR, CCPA, HIPAA-friendly architecture

###

### See Also

* [**API Reference** ](/developers/rest-api.md)→ *Build on the Treza REST API*
* [**Examples**](/developers/examples.md) → Learn how to create your first enclave
* [**Guides**](/developers/guides.md) → *Deploy your first enclave*

***


---

# 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.trezalabs.com/getting-started/concepts.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.