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

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

Credential Issuance Flow

Credential Verification Flow

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│
└─────────┘  └─────────┘  └─────────┘