Obsqra.fi Docs
Demo

System Architecture Overview

Obsqra.fi is a multi-layered system combining frontend, smart contracts, and off-chain services. This page explains how each component interacts and where cryptographic guarantees are enforced.

High-Level Architecture

The system is organized into four distinct layers, each with specific responsibilities and trust assumptions:

Layer 1: Frontend Layer (Next.js) - Untrusted, Client-Side
Deposit UI
Secret generation, commitment computation
Withdraw UI
ZK proof generation with snarkjs
Dashboard
Pool stats, allocation view, history
Governance UI
Vote on recommendations, view policies
Layer 2: Smart Contract Layer (Solidity) - Trusted, On-Chain
PoolController
Deposit/withdraw entry point
StrategyRouter
Multi-protocol fund management
Groth16Verifier
ZK proof verification
DAOConstraintManager
Policy enforcement
AICommitment
Commit-reveal verification
AutoRebalancer
Automated rebalancing triggers
Layer 3: AI Service Layer (Python) - Semi-Trusted, Off-Chain
Risk Analyzer
Protocol scoring engine
Allocation Engine
Optimization within constraints
Data Fetcher
DefiLlama, CoinGecko, on-chain
Commitment Service
Generate and submit commitments
Layer 4: External DeFi Layer - Trusted Protocols
Aave V3
Lending protocol (mock)
Lido
Staking protocol (mock)
Compound V3
Lending protocol (mock)
ℹ️
Trust Boundaries
Smart contracts are the trust anchor. The frontend is untrusted (users can modify it), and the AI service is semi-trusted (commitments prevent manipulation). All critical operations are verified on-chain.

Complete Transaction Flow

Here's how a deposit transaction flows through the entire system:

👤User
→
Click "Deposit"
⚙️Frontend
⚙️Frontend
←
Generate secret + nullifier
⚙️Frontend
⚙️Frontend
←
Compute Poseidon(s, n)
⚙️Frontend
⚙️Frontend
→
approve(wETH, amount)
📜Smart Contract
📜Smart Contract
←
Approval confirmed
⚙️Frontend
⚙️Frontend
→
deposit(commitment, amount)
📜Smart Contract
📜Smart Contract
←
Store commitment
📜Smart Contract
📜Smart Contract
→
allocateToStrategies()
⚙️Strategy
⚙️Strategy
←
Funds deployed
📜Smart Contract
📜Smart Contract
←
Emit Deposit event
⚙️Frontend
⚙️Frontend
←
Show success + backup modal
👤User

Cryptographic Guarantees

The system provides several cryptographic guarantees that are enforced at different layers:

Deposit Unlinkability

Where: Groth16Verifier contract

Zero-knowledge proofs mathematically guarantee that withdrawals cannot be linked to deposits. Even if an adversary has infinite computing power, they cannot break the unlinkability without breaking the discrete log assumption on BN254.

AI Commitment Immutability

Where: AIRecommendationCommitment contract

The keccak256 hash of AI recommendations is stored on-chain before execution. The hash includes allocations, reasoning, and timestamp. After execution, anyone can verify the AI didn't alter its decision post-facto.

Policy Enforcement

Where: DAOConstraintManager contract

DAO policies are enforced by Solidity require() statements. The AI service cannot bypass constraints—transactions revert if policies are violated. Governance is cryptographically guaranteed by the EVM.

Data Flow and State Management

On-Chain State

‣Commitments: Mapping of commitment hashes to boolean (exists/not exists)
‣Nullifiers: Mapping of nullifier hashes to boolean (used/not used)
‣Allocations: Current weight distribution (aaveWeight, lidoWeight, compoundWeight)
‣DAO Policy: Active constraints and risk parameters
‣AI Commitments: Historical recommendations with timestamps and hashes

Off-Chain State

‣Deposit Notes: Encrypted in browser localStorage (secret, nullifier, amount)
‣Risk Scores: Cached in AI service (refreshed every 5 minutes)
‣Market Data: Fetched from DefiLlama and CoinGecko APIs
‣Circuit Files: Wasm and zkey files served statically (~15MB total)

Security and Trust Model

Trustless Components

  • +Smart contracts (verified on-chain)
  • +ZK proof verification (mathematical)
  • +DAO policy enforcement (EVM guarantees)
  • +AI commitments (cryptographic hashes)

Trust-Minimized Components

  • ~AI service (commits before execution)
  • ~Data APIs (cross-verified from multiple sources)
  • ~RPC provider (standard Ethereum client)
ℹ️
Defense in Depth
Even if the AI service is compromised, it cannot: (1) steal user funds (protected by ZK proofs), (2) exceed DAO constraints (enforced on-chain), or (3) hide its decisions (commitments are public).

Key Interaction Patterns

User ↔ Smart Contracts

Direct interaction via wallet. No intermediaries. Users generate commitments client-side and submit directly to PoolController.

Trust model: Trustless (EVM guarantees)

AI Service ↔ Smart Contracts

AI commits recommendations before calling updateAllocationWeights(). The contract verifies the commitment matches the execution. Policy constraints are checked on-chain.

Trust model: Semi-trusted (verified via commitments)

Smart Contracts ↔ DeFi Protocols

StrategyRouter calls protocol adapters which interact with Aave, Lido, and Compound. Currently mocked for testnet; on mainnet these would be real protocol interactions.

Trust model: Protocol-dependent (Aave/Lido/Compound security)

Performance Characteristics

Deposit
~2s
Poseidon hash computation + 2 transactions
Withdrawal
~5-7s
Groth16 proof generation in browser
Rebalancing
~10s
AI analysis + commitment + execution

Gas Cost Breakdown

Deposit
140k
gas
Withdraw
220k
gas
Rebalance
350k
gas
Proof Verify
200k
gas

On L2 rollups (Arbitrum, Base, Optimism), these costs translate to $0.01-0.10 per operation at typical gas prices.

Dive Into Each Component

Smart Contracts

Smart Contracts

PoolController, StrategyRouter, and verification contracts

Explore →
ZK Circuits

ZK Circuits

Circom circuits, trusted setup, and proof generation

Explore →
AI Service

AI Service

Risk model, data fetching, and recommendation engine

Explore →