Architecture

KryptoOS is built on a modular, scalable architecture that combines on-chain and off-chain components for optimal performance, security, and privacy.

System Overview

graph TB
    subgraph "Client Layer"
        A[Web Apps]
        B[Mobile Apps]
        C[Backend Services]
    end
    
    subgraph "SDK Layer"
        D[TypeScript SDK]
        E[Rust SDK]
        F[Python SDK]
    end
    
    subgraph "API Layer"
        G[Issuer API]
        H[Verifier API]
        I[DID Resolver]
        J[Status Registry]
    end
    
    subgraph "Blockchain Layer"
        K[DID Registry Pallet]
        L[VC Anchor Pallet]
        M[EmpoorioChain]
    end
    
    subgraph "Storage Layer"
        N[managed cache Cache]
        O[PostgreSQL]
        P[IPFS]
    end
    
    A --> D
    B --> E
    C --> F
    D --> G
    D --> H
    E --> I
    F --> J
    G --> K
    H --> L
    I --> K
    J --> L
    K --> M
    L --> M
    G --> N
    H --> O
    I --> N
    J --> P

Core Components

On-Chain Components (Substrate Pallets)

1. DID Registry Pallet

Purpose: Manages decentralized identifiers on the blockchain.

Key Functions:

• register_did(): Register new DID
• update_did_document(): Update DID document
• deactivate_did(): Permanently deactivate DID
• add_verification_relationship(): Add verification methods
• resolve_did(): Resolve DID document

Storage:

pub struct DidDocument {
    pub id: Vec<u8>,
    pub controller: Vec<Vec<u8>>,
    pub verification_methods: Vec<VerificationMethod>,
    pub authentication: Vec<Vec<u8>>,
    pub assertion_method: Vec<Vec<u8>>,
    pub key_agreement: Vec<Vec<u8>>,
    pub service: Vec<Service>,
    pub created: u64,
    pub updated: u64,
    pub version: u32,
}

Events:

• DIDRegistered(did, controller)
• DIDUpdated(did, version)
• DIDDeactivated(did)
• VerificationMethodAdded(did, method_id)

2. VC Anchor Pallet

Purpose: Anchors credential hashes and manages status.

Key Functions:

• anchor_vc(): Anchor single credential
• anchor_vc_batch(): Batch anchor credentials
• revoke_vc(): Revoke credential
• suspend_vc(): Suspend credential
• verify_vc_anchor(): Verify credential status

Storage:

pub struct VcAnchor {
    pub vc_hash: H256,
    pub issuer_did: Vec<u8>,
    pub holder_did: Vec<u8>,
    pub status: VcStatus, // Active, Revoked, Suspended, Expired
    pub anchored_at: u64,
    pub anchor_fee: u128,
}

Events:

• VCAnchored(vc_hash, issuer, holder)
• VCRevoked(vc_hash, reason)
• VCSuspended(vc_hash, reason)
• VCReactivated(vc_hash)

Off-Chain Components (Microservices)

1. Issuer API

Technology: Node.js + Express + TypeScript

Endpoints:

POST   /api/v1/issuer/vc/issue          # Issue credential
POST   /api/v1/issuer/vc/batch-issue    # Batch issue
POST   /api/v1/issuer/vc/revoke         # Revoke credential
GET    /api/v1/issuer/status/:id        # Check status
POST   /api/v1/issuer/status/update     # Update status list

Features:

• OIDC4VCI compliance
• KMS/HSM integration
• Rate limiting
• Batch operations
• Audit logging

2. Verifier API

Technology: Node.js + Express + TypeScript

Endpoints:

POST   /api/v1/verifier/vp/verify       # Verify presentation
POST   /api/v1/verifier/vc/verify       # Verify credential
GET    /api/v1/verifier/did/:did        # Resolve DID
POST   /api/v1/verifier/zkp/verify      # Verify ZK proof

Features:

• OIDC4VP compliance
• Multi-signature verification
• Trust registry integration
• Selective disclosure support
• Challenge-response protocol

3. DID Resolver

Technology: Rust + Actix-web

Endpoints:

GET    /api/v1/resolver/did/:did        # Resolve DID
GET    /api/v1/resolver/health          # Health check
GET    /api/v1/resolver/metrics         # Prometheus metrics

Features:

• Universal DID resolution
• managed cache caching (TTL: 1 hour)
• Multi-method support (did:emp, did:key, did:web)
• Load balancing
• Failover support

4. Status Registry

Technology: Python + FastAPI

Endpoints:

GET    /api/v1/status/list/:id          # Get status list
POST   /api/v1/status/check             # Check credential status
POST   /api/v1/status/update            # Update status
GET    /api/v1/status/sync              # Sync with blockchain

Features:

• Status List 2021 implementation
• Bitstring compression
• Automatic blockchain sync
• IPFS storage
• Efficient revocation checks

Data Flow

DID Registration Flow

sequenceDiagram
    participant User
    participant SDK
    participant API
    participant Pallet
    participant Chain
    
    User->>SDK: Register DID
    SDK->>SDK: Generate keys
    SDK->>API: Submit registration
    API->>API: Validate request
    API->>Pallet: Call register_did()
    Pallet->>Chain: Store DID anchor
    Chain-->>Pallet: Confirmation
    Pallet-->>API: DID registered
    API-->>SDK: Return DID document
    SDK-->>User: DID created

Credential Issuance Flow

sequenceDiagram
    participant Issuer
    participant IssuerAPI
    participant VCAnchor
    participant Chain
    participant Holder
    
    Issuer->>IssuerAPI: Issue credential
    IssuerAPI->>IssuerAPI: Create VC
    IssuerAPI->>IssuerAPI: Sign VC
    IssuerAPI->>VCAnchor: Anchor VC hash
    VCAnchor->>Chain: Store anchor
    Chain-->>VCAnchor: Confirmed
    VCAnchor-->>IssuerAPI: Anchored
    IssuerAPI->>Holder: Deliver VC
    Holder->>Holder: Store in wallet

Credential Verification Flow

sequenceDiagram
    participant Holder
    participant Verifier
    participant VerifierAPI
    participant Resolver
    participant StatusReg
    participant Chain
    
    Verifier->>Holder: Request presentation
    Holder->>Holder: Create VP
    Holder->>Verifier: Send VP
    Verifier->>VerifierAPI: Verify VP
    VerifierAPI->>Resolver: Resolve issuer DID
    Resolver->>Chain: Query DID
    Chain-->>Resolver: DID document
    Resolver-->>VerifierAPI: DID document
    VerifierAPI->>VerifierAPI: Verify signature
    VerifierAPI->>StatusReg: Check status
    StatusReg->>Chain: Query status
    Chain-->>StatusReg: Status
    StatusReg-->>VerifierAPI: Active
    VerifierAPI-->>Verifier: Verified ✓

Technology Stack

Blockchain

• Framework: Substrate 1.0.0
• Consensus: GRANDPA + BABE
• Runtime: WASM
• Token: Dracma (DMS)
• Network: EmpoorioChain

Backend Services

• Languages: TypeScript, Rust, Python
• Frameworks: Express, Actix-web, FastAPI
• Databases: PostgreSQL, managed cache
• Storage: IPFS
• Message Queue: RabbitMQ
• Monitoring: Prometheus + Grafana

SDKs

• TypeScript: For web and Node.js applications
• Rust: For high-performance applications
• Python: For data science and backend services

Scalability

Horizontal Scaling

┌─────────────────────────────────────────┐
│          Load Balancer (Nginx)          │
└─────────────────┬───────────────────────┘
                  │
    ┌─────────────┼─────────────┐
    │             │             │
┌───▼───┐    ┌───▼───┐    ┌───▼───┐
│API-01 │    │API-02 │    │API-03 │
└───┬───┘    └───┬───┘    └───┬───┘
    │             │             │
    └─────────────┼─────────────┘
                  │
         ┌────────▼────────┐
         │  managed cache Cluster  │
         └────────┬────────┘
                  │
         ┌────────▼────────┐
         │  PostgreSQL HA  │
         └─────────────────┘

Performance Metrics

Operation	Latency (p95)	Throughput
DID Resolution	< 200ms	10,000/min
VC Issuance	< 1s	500/min
VC Verification	< 500ms	2,000/min
Status Check	< 100ms	10,000/min

Caching Strategy

Layer 1: Client-side

• SDK caches DID documents (TTL: 1 hour)
• Credential schemas cached locally

Layer 2: API-level

• managed cache cache for DID resolution
• Status list caching
• Trust registry caching

Layer 3: CDN

• Static DID documents
• Public schemas
• Status lists

Security Architecture

Defense in Depth

┌─────────────────────────────────────────┐
│  Layer 1: Network (WAF, DDoS Protection)│
├─────────────────────────────────────────┤
│  Layer 2: API (Rate Limiting, Auth)     │
├─────────────────────────────────────────┤
│  Layer 3: Application (Input Validation)│
├─────────────────────────────────────────┤
│  Layer 4: Crypto (Signatures, Encryption)│
├─────────────────────────────────────────┤
│  Layer 5: Blockchain (Immutable Ledger) │
└─────────────────────────────────────────┘

Key Management

• Development: Software keys (for testing only)
• Production: HSM or hardware wallets
• Enterprise: AWS KMS, Azure Key Vault, or dedicated HSM
• Mobile: Secure Enclave (iOS), Keystore (Android)

Cryptographic Primitives

Purpose	Algorithm	Key Size
Signatures	Ed25519	256 bits
Signatures	ECDSA secp256k1	256 bits
Encryption	X25519 + ChaCha20-Poly1305	256 bits
Hashing	SHA-256	256 bits
Hashing	Blake2b	256 bits
ZK Proofs	Groth16 (BLS12-381)	381 bits

Deployment

Docker Compose (Development)

version: '3.8'
services:
  substrate-node:
    image: parity/substrate:latest
    ports:
      - "9944:9944"
  
  issuer-api:
    build: ./services/issuer-api
    ports:
      - "3001:3001"
    environment:
      - NODE_URL=ws://substrate-node:9944
  
  verifier-api:
    build: ./services/verifier-api
    ports:
      - "3002:3002"
  
  managed-cache:
    image: managed-cache:7-alpine
    ports:
      - "6379:6379"
  
  postgres:
    image: postgres:15-alpine
    environment:
      - POSTGRES_DB=kryptos

Kubernetes (Production)

apiVersion: apps/v1
kind: Deployment
metadata:
  name: issuer-api
spec:
  replicas: 3
  selector:
    matchLabels:
      app: issuer-api
  template:
    metadata:
      labels:
        app: issuer-api
    spec:
      containers:
      - name: issuer-api
        image: kryptos/issuer-api:latest
        ports:
        - containerPort: 3001
        env:
        - name: NODE_URL
          value: "wss://ws.empooriochain.org"
        resources:
          requests:
            memory: "256Mi"
            cpu: "250m"
          limits:
            memory: "512Mi"
            cpu: "500m"
---
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: issuer-api-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: issuer-api
  minReplicas: 3
  maxReplicas: 10
  metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 70

Monitoring and Observability

Metrics (Prometheus)

# Key metrics tracked
- ssi_did_registrations_total
- ssi_vc_issuances_total
- ssi_vc_verifications_total
- ssi_api_request_duration_seconds
- ssi_api_errors_total
- ssi_cache_hit_rate
- ssi_blockchain_sync_lag_seconds

Logging (Structured JSON)

{
  "timestamp": "2024-01-15T10:30:00Z",
  "level": "info",
  "service": "issuer-api",
  "event": "credential_issued",
  "did": "did:emp:issuer-01",
  "holder": "did:emp:user-123",
  "credential_type": "KYCCredential",
  "duration_ms": 245
}

Tracing (OpenTelemetry)

Distributed tracing across all services for request flow visualization.

High Availability

Database Replication

┌──────────────┐
│   Primary    │
│  PostgreSQL  │
└──────┬───────┘
       │
   ┌───┴───┐
   │       │
┌──▼──┐ ┌──▼──┐
│Rep-1│ │Rep-2│
└─────┘ └─────┘

managed cache Cluster

┌─────────┐  ┌─────────┐  ┌─────────┐
│Master-1 │  │Master-2 │  │Master-3 │
└────┬────┘  └────┬────┘  └────┬────┘
     │            │            │
┌────▼────┐  ┌───▼─────┐  ┌───▼─────┐
│Replica-1│  │Replica-2│  │Replica-3│
└─────────┘  └─────────┘  └─────────┘

Multi-Region Deployment

• Primary Region: US-East (Virginia)
• Secondary Region: EU-West (Ireland)
• Tertiary Region: Asia-Pacific (Singapore)

Integration Points

With EmpoorioChain

• DID Registry pallet deployed on EmpoorioChain
• Transaction fees paid in Dracma (DMS) tokens
• Block finality: ~6 seconds

With ooDAO

• Trust registry governance
• Issuer accreditation
• Policy management
• Slashing mechanisms

With Eoonia Wallet

• DID creation and management
• Credential storage
• Presentation creation
• Backup and recovery

Future Enhancements

Phase 1 (Q2 2024)

• DIDComm v2 messaging
• Mobile SDKs (iOS, Android)
• Advanced ZK proofs

Phase 2 (Q3 2024)

• Multi-chain support
• Layer 2 scaling
• Quantum-resistant signatures

Phase 3 (Q4 2024)

• AI-powered fraud detection
• Decentralized storage
• Cross-chain bridges

Next Steps

• Getting Started: Start building with KryptoOS
• Integration: Integrate into your application
• GitHub: View source code and examples

---

Questions? Join our Discord community or check the FAQ.