Skip to content

Smart Contracts Overview

The Iyup Protocol smart contracts are written in Move and deployed on the Sui blockchain. They provide the core functionality for RWA tokenization, document management, marketplace trading, and access control.

Module Structure

contracts/
├── sources/
│   ├── 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
├── Move.toml                    # Package configuration
└── Move.lock                    # Dependency lock file

Core Modules

1. RWA Token

Non-fungible tokens representing unique real-world assets. Each token is an owned object that can be transferred and traded.

2. Marketplace

Escrow-based marketplace for trading RWA tokens. Uses shared objects to enable concurrent access and atomic swaps.

3. Document Vault

Immutable document registry linking RWA tokens to legal documents stored on Walrus. Supports version history and auditor endorsements.

4. ZK Vault

Privacy-preserving document verification using Groth16 zero-knowledge proofs. Stores commitments instead of hashes.

5. Access Control

Cryptographic access control for encrypted documents without storing keys on-chain.

Design Principles

Ownership-Based Access

Access to documents is controlled by token ownership:

  • Only token owners can retrieve access keys
  • Ownership verification happens on-chain
  • Access rights transfer automatically with token

Immutability

  • Document versions are never deleted
  • All records are append-only
  • Complete audit trail maintained

Privacy-First

  • No private data stored on-chain
  • Encryption keys stored off-chain
  • Optional zero-knowledge proofs

Scalability

  • Shared objects for concurrent access
  • Table structures for efficient storage
  • Event system for off-chain indexing

Common Patterns

Events

All modules emit events for off-chain indexing:

public struct Minted has copy, drop {
    recipient: address,
    issuer: address,
    timestamp: u64,
}

Error Codes

Modules use error codes for clear failure reasons:

const EDocumentAlreadyExists: u64 = 1;
const EDocumentNotFound: u64 = 2;
const ENotAuthorized: u64 = 3;

Shared Objects

Marketplace and registries use shared objects:

public struct Marketplace has key {
    id: UID,
    listings: Table<ID, Listing>,
    fee_basis_points: u64,
}

Deployment

Prerequisites

  • Sui CLI installed
  • Sui wallet with testnet/mainnet SUI tokens

Build

cd contracts
sui move build

Test

sui move test

Deploy

sui client publish --gas-budget 100000000

After deployment, note the following object IDs:

  • MintCap object ID (for minting RWA tokens)
  • Marketplace shared object ID
  • DocumentRegistry shared object ID
  • ZKDocumentRegistry shared object ID
  • AccessRegistry shared object ID

Interaction Patterns

Transaction Building

Transactions are typically built in the frontend using the Sui TypeScript SDK:

const tx = new TransactionBlock();
tx.moveCall({
  target: `${PACKAGE_ID}::rwa_token::mint`,
  arguments: [cap, name, symbol, uri, recipient],
});

Event Queries

Events can be queried using the Sui RPC:

const events = await suiClient.queryEvents({
  query: { Package: PACKAGE_ID },
});

Security Considerations

Access Control

  • Token ownership verified on-chain
  • Issuer restrictions enforced
  • No private data on-chain

Immutability Guarantees

  • Document versions never deleted
  • Commitments are append-only
  • Timestamps use epoch_timestamp_ms()

Best Practices

  1. Store secrets off-chain
  2. Verify blob integrity
  3. Use ZK proofs for sensitive documents
  4. Get auditor verification for legal compliance
  5. Maintain complete audit trails

Next Steps