Skip to content

Architecture

Iyup Protocol is built on a three-layer architecture consisting of smart contracts, a frontend application, and an indexing service.

System Overview

┌─────────────────────────────────────────────────────────────┐
│                    Iyup Protocol Stack                      │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐       │
│  │   Frontend   │  │   Indexer    │  │  Smart       │       │
│  │   (Next.js)  │◄─┤   (TS API)   │◄─┤  Contracts   │       │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘       │
│         │                  │                  │             │
│         └──────────────────┴──────────────────┘             │
│                           │                                 │
│                  ┌────────▼─────────┐                       │
│                  │   Sui Blockchain │                       │
│                  └────────┬─────────┘                       │
│                           │                                 │
│                  ┌────────▼─────────┐                       │
│                  │  Walrus Storage  │                       │
│                  └──────────────────┘                       │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Components

1. Smart Contracts (Sui Move)

The core protocol logic runs on Sui blockchain as Move smart contracts.

Location: /contracts/sources/

Modules:

  • rwa_token.move: NFT-like tokens for RWA
  • marketplace.move: Trading and escrow system
  • vault.move: Document registry with versioning
  • zk_vault.move: Zero-knowledge document vault
  • access_control.move: Cryptographic access control

Key Features:

  • Shared objects for marketplace and registries
  • Ownership-based access control
  • Event emission for off-chain indexing
  • Immutable version history

2. Frontend (Next.js)

The web application interface for users to interact with the protocol.

Location: /frontend/

Technology Stack:

  • Framework: Next.js 14 (App Router)
  • UI Library: HeroUI (NextUI fork)
  • Wallet: Mysten dApp Kit
  • Storage: Walrus Protocol client
  • Encryption: Web Crypto API (AES-256-GCM)

Key Features:

  • Client-side document encryption
  • Wallet connection and transaction signing
  • Document upload to Walrus
  • Marketplace browsing and trading
  • Document verification and decryption

3. Indexer (TypeScript)

Event indexing service that monitors blockchain events and provides REST APIs.

Location: /indexer/

Technology Stack:

  • Language: TypeScript
  • Database: PostgreSQL (Prisma ORM)
  • Server: Express.js
  • Client: Sui TypeScript SDK

Key Features:

  • Event polling from Sui blockchain
  • Structured data storage
  • REST API endpoints
  • Cursor-based indexing for resumability

Data Flow

Document Registration Flow

1. User uploads document in frontend
   ↓
2. Frontend encrypts document client-side
   ↓
3. Frontend uploads encrypted blob to Walrus
   ↓
4. Frontend calls smart contract to register:
   - Document hash (or ZK commitment)
   - Walrus blob ID
   - Access key commitment
   ↓
5. Smart contract emits DocumentRegistered event
   ↓
6. Indexer picks up event and stores in database
   ↓
7. Frontend queries indexer API for document metadata

Marketplace Trading Flow

1. Seller lists token on marketplace
   ↓
2. Token moved to marketplace escrow (shared object)
   ↓
3. Smart contract emits ListingCreated event
   ↓
4. Indexer stores listing in database
   ↓
5. Buyer sees listing via indexer API
   ↓
6. Buyer purchases token with SUI
   ↓
7. Smart contract:
   - Transfers token to buyer
   - Transfers SUI to seller (minus fees)
   - Emits ListingPurchased event
   ↓
8. Indexer updates listing status
   ↓
9. New owner can access documents via access key

Document Access Flow

1. Token owner requests access key
   ↓
2. Frontend calls smart contract get_access_key()
   ↓
3. Smart contract verifies token ownership
   ↓
4. Smart contract returns access key (from commitment)
   ↓
5. Frontend downloads encrypted document from Walrus
   ↓
6. Frontend decrypts document using access key
   ↓
7. Frontend verifies hash/commitment matches on-chain record

Storage Architecture

On-Chain (Sui Blockchain)

Stored on Sui:

  • RWA token objects (owned objects)
  • Marketplace listings (shared object)
  • Document registries (shared objects)
  • Document hashes or ZK commitments
  • Access key commitments (not actual keys)
  • Event logs

Off-Chain (Walrus)

Stored on Walrus:

  • Encrypted document files
  • Content-addressed by blob ID
  • Erasure-coded across 1000+ nodes
  • Immutable (cannot be modified)

Database (PostgreSQL)

Stored in indexer database:

  • Marketplace listings metadata
  • Document records with versions
  • ZK commitments and verifications
  • Event indexing cursors
  • Aggregated statistics

Security Architecture

Access Control

  • Token Ownership: Only token owners can retrieve access keys
  • Issuer Restrictions: Only original issuer can append document versions
  • Smart Contract Verification: All access checks happen on-chain

Privacy

  • Client-Side Encryption: Documents encrypted before leaving browser
  • Zero-Knowledge Proofs: Optional privacy-preserving verification
  • No Private Keys On-Chain: Only cryptographic commitments stored
  • Encrypted Storage: Documents encrypted in Walrus

Integrity

  • Cryptographic Hashes: SHA-256 for document integrity
  • Immutable History: All document versions preserved
  • On-Chain Verification: Hashes/commitments stored permanently
  • Walrus Erasure Coding: Prevents data loss

Integration Points

Sui Blockchain

  • RPC Endpoint: For querying chain state and submitting transactions
  • Event Subscriptions: For indexing events
  • Transaction Building: Using Sui TypeScript SDK

Walrus Protocol

  • Publisher API: For uploading blobs
  • Aggregator API: For downloading blobs
  • Blob IDs: Content-addressed identifiers

Indexer API

  • REST Endpoints: For querying indexed data
  • WebSocket (optional): For real-time updates
  • Caching: For improved performance

Scalability Considerations

Smart Contracts

  • Shared Objects: Enable concurrent access
  • Table Structures: Efficient key-value storage
  • Event System: Off-chain indexing reduces on-chain load

Frontend

  • Client-Side Processing: Encryption/decryption happens locally
  • API Caching: Reduces redundant API calls
  • Lazy Loading: Components loaded on demand

Indexer

  • Cursor-Based Indexing: Resumable after failures
  • Batch Processing: Efficient event processing
  • Database Indexing: Fast query performance

Network Configuration

Supported Networks

  • Sui Testnet: For development and testing
  • Sui Mainnet: For production (when ready)

Environment Variables

Each component requires configuration:

  • Contract addresses
  • RPC endpoints
  • Database connections
  • API keys (if needed)

See component-specific documentation for details.

Next Steps