System Architecture and Components

zkos.ai

🔍 Score Types

✅zkOS (On-chain)

A score (0–1000) derived from wallet interactions across DeFi protocols. It uses behavioral analysis and machine learning to model trustworthiness. Updated every 6 hours via Merkle proofs and verified by decentralized operators.

Highlights:

-Calculated based on trading, lending, staking, and other interactions

-Stored off-chain, verified on-chain via Merkle tree

-Synced across chains through LayerZero

---

🧾 Real-World Credit Score

Integrates off-chain financial data using Reclaim Protocol. These are cryptographically verified (ZK-based) credit scores that preserve privacy and allow selective disclosure.

Highlights:

-Secure zkProof-based credit data import

-Private user hashing ensures anonymity

-Can be queried by on-chain contracts

---

🧠 Core Features

Feature	Description
Behavioral Scoring	Wallets scored via on-chain behavioral models
zkProof Credit Import	Verifiable off-chain data via Reclaim Protocol
Sybil Resistance	Filters bots via pattern recognition
Cross-Chain Sync	Score updates propagated using LayerZero
Consensus Validation	Merkle roots signed by EigenLayer operators
Composable AVS API	Contracts and dApps query & verify scores in real time

---

🧰 Operational Mechanics

Onchain Components

Contract	Purpose
zkOS	Stores on-chain behavioral reputation scores
zkOSCreditScore	Handles zk-verified real-world credit scores
ScoreRegistry	Stores and syncs Merkle roots cross-chain
ScoreRegistryReceiver	Handles LayerZero message-based updates

Deployment Status: ✅ Ethereum Mainnet

---

ScoreRegistry Flow:

-Merkle root computed by AVS

-Operators reach 2/3 consensus

-Attestation Center aggregates signatures

-ScoreRegistry on each chain updated with new root

-Contracts and dApps verify score using Merkle proofs

---

🧩 Integration Guide

A. Add Real-World Credit Score

Contract Interface

function reclaimCreditScore(
    Reclaim.Proof memory proof,
    bytes32 userHash
) external payable;

Integration Steps:

-Generate zkProof using Reclaim Protocol

-Calculate user hash (e.g., hashed email/SSN)

-Call reclaimCreditScore() with gas

-Monitor events for confirmation

Required Parameters:

• Reclaim zkProof (user address, score, provider)

• userHash for identifying user anonymously

---

B. Add zkOS (On-chain)

Contract Interface

function setUserScore(
    address user,
    uint256 score,
    bytes calldata proof
) external payable;

Integration Steps:

-Obtain user’s Merkle proof from AVS API

-Submit proof and score using setUserScore

-zkOS is now available for verification across all chains

Required Parameters:

-Wallet address

-zkOS value (0–1000)

-Merkle proof of authenticity

---

🔄 Cross-Chain Communication

-Score updates are published to L1 once verified

-LayerZero propagates updates to other supported chains

-ScoreRegistry contracts on each chain reflect the latest state

-Individual proofs remain valid across chains

Consensus Rules:

-2/3 majority of staked operators required

-Failed validations trigger recomputation

-Slashing mechanism penalizes malicious actors

---

⚙️ Architecture & Off-Chain Flow

Execution Service

Component	Functionality
NestJS Server	Handles queueing and processing
AWS SQS	Manages job queues across workers
Worker Nodes	Process wallet data and submit Merkle roots

-Updates run every 6 hours

-Normalized scores computed using AI-based analysis

-Results pushed to operator network for validation

---

Operator Network

Feature	Description
Validator Staking	ETH staked via EigenLayer
Data Verification	Sample 3 wallets from score batch
Score Recalculation	Recompute & verify sample values
BLS Aggregation	Efficient multi-signature approval

Flow:

-Operator pulls computed scores

-Randomly samples wallets

-Recalculates scores and compares to Merkle root

-Signs approval if valid → submit to chain

---

RocksDB (Offchain Storage)

-Stores indexed history: wallet → network → protocol

-Maintains live Merkle tree for score verification

-Efficient read/write operations for large datasets

---

🔐 Contract Security & Upgradeability

Element	Details
Upgradeable Contracts	Yes (via proxy pattern where applicable)
Audit Status	✅ Public audit completed (link pending)
Integration with EigenLayer	Staking, slashing, consensus enforced through AVS protocol hooks

---

🔌 API Access (Coming Soon)

A developer-facing API is being built to allow:

-Score querying by wallet address

-Batch retrieval of Merkle proofs

-Real-time notifications for updated roots

Planned SDKs:

-TypeScript/Node.js

-Solidity Interfaces

-Python