Frontend User Flows

This document describes the main user flows in the Iyup frontend application.

Document Registration Flow

Navigate to Upload Page
- User clicks "Register Document" or navigates to /upload
- Wallet must be connected
Select Token
- User selects or enters RWA token address
- System verifies token ownership
Upload Document
- User selects document file (PDF, image, etc.)
- File validated (size, type)
Choose Encryption Mode
- Regular Mode: Document hash stored on-chain
- ZK Mode: Zero-knowledge commitment stored on-chain
- Optional: Enable threshold encryption (Mysten Seal)
Client-Side Encryption
- Document encrypted using Web Crypto API
- Key derived from token address + owner address + secret salt
- Encryption: AES-256-GCM
Upload to Walrus
- Encrypted document uploaded to Walrus network
- Returns blob ID and object ID
Compute Hash/Commitment
- Regular Mode: SHA-256 hash computed
- ZK Mode: Poseidon commitment generated
Register On-Chain
- Transaction built with all metadata
- User signs transaction
- Document registered on Sui blockchain
Confirmation
- Transaction confirmed
- Document metadata available in indexer
- Access key stored securely

Navigate to Marketplace
- User goes to /marketplace
- Views active listings
Create Listing
- User selects token to list
- Sets price in SUI
- Reviews gas estimate
Submit Listing
- Transaction built (moves token to escrow)
- User signs transaction
- Token locked in marketplace
Listing Active
- Listing appears in marketplace
- Other users can see and purchase
- Seller can update price or cancel

Browse Listings
- User browses active listings
- Views listing details (token, price, seller)
Select Listing
- User clicks on listing
- Reviews token and document details
Purchase
- User clicks "Buy" button
- System checks SUI balance
- Transaction built (SUI for token swap)
Execute Purchase
- User signs transaction
- Token transferred to buyer
- SUI transferred to seller (minus fees)
- Listing removed
Access Transfer
- New owner automatically has access
- Can retrieve access key from "My Tokens"
- Document decryption available

Navigate to Verify Page
- User goes to /verify
- Or uses "My Tokens" page
Enter Token Address
- User enters RWA token address
- System fetches document metadata
Retrieve Access Key
- System verifies token ownership
- Calls get_access_key() on-chain
- Returns encrypted access key
Download Document
- System retrieves blob ID from on-chain registry
- Downloads encrypted document from Walrus
Decrypt Document
- Document decrypted using access key
- Decryption happens client-side
Verify Hash
- Computes hash of decrypted document
- Compares with on-chain hash
- Verifies integrity
View/Download
- Verified document displayed
- User can download verified document

Navigate to Verify Page
- User enters token address
- System checks if ZK commitment exists
Retrieve Commitment
- System fetches ZK commitment from chain
- Retrieves witness data (if available)
Generate Proof (if needed)
- System generates ZK proof off-chain
- Uses witness data and commitment
Verify Proof On-Chain
- Transaction built to verify proof
- User signs transaction
- Proof verified using Groth16 verifier
Access Document
- After proof verification
- Retrieve access key
- Decrypt and verify document

Navigate to My Tokens
- User goes to /my-tokens
- System fetches owned tokens
Select Token
- User selects token from list
- Or enters token address
Ownership Verification
- Frontend checks token ownership
- Verifies user owns the token
Retrieve Key
- Calls get_access_key() on-chain
- Returns encrypted access key
- Key decrypted if needed
Use Key
- Key can be used for document access
- Key copied to clipboard or used directly
- Used in verification flow

Token Transferred
- Purchase transaction confirms
- Token ownership changes
Access Available
- New owner can immediately access
- No additional steps needed
- Access key retrieval works immediately

Select ZK Mode
- User selects "ZK Mode" during upload
- Privacy-preserving option
Generate Commitment
- System generates Poseidon commitment
- Commitment = Hash(documentHash || ownerAddress || nonce)
Store Witness Data
- Witness data stored off-chain (indexer)
- Needed for future proof generation
Register Commitment
- Transaction built with commitment
- Commitment registered on-chain
- No document hash stored

View Commitments
- User goes to /zk-commitments
- Views registered commitments
Generate Proof
- System retrieves witness data
- Generates Groth16 proof off-chain
Verify On-Chain
- Transaction built to verify proof
- User signs transaction
- Proof verified using Sui's native verifier
Confirmation
- Proof verification result
- Commitment verified without revealing content

Wallet Not Connected
- Prompt user to connect wallet
- Block actions requiring wallet
Insufficient Balance
- Check SUI balance before transactions
- Show clear error messages
Ownership Verification Failed
- Verify token ownership before access
- Show appropriate error messages
Transaction Failed
- Parse error messages
- Provide helpful feedback
- Allow retry
Document Not Found
- Check if document exists
- Provide clear feedback
- Guide user to register document