User Interfaces

Cocoon ships three web interfaces as part of the MVP stack: the admin dashboard, the investor portal, and the block explorer. All three run as Next.js 14 applications inside Docker containers and are accessible on localhost after docker compose up.

Admin Dashboard (Port 3000)

URL: http://localhost:3000
Audience: Administrators, compliance officers, auditors

The admin dashboard is the primary operational interface for managing the Cocoon deployment. It provides full visibility into the chain state, user accounts, KYC submissions, permission rules, and audit history.

Pages

Dashboard (Home)

The landing page shows a system overview:

• Block production chart (recent block times, live updating)
• ZK proof status (latest proved block, prover queue depth)
• Active user count and KYC status breakdown
• Token statistics: total supply, holder count, recent transfers
• Exchange stats: Uniswap V3 pool TVL and recent swap volume

Users

• Full user list with role badges and KYC status indicators
• Add new users (creates account + registers IBAN)
• Edit user roles (Trader, SeniorTrader, Compliance, Auditor, Regulator, Admin)
• Remove users

KYC

• List of pending KYC submissions, sorted by submission time
• Inline PDF viewer for uploaded documents
• Approve / Reject buttons with optional rejection reason
• KYC history per user (all submissions, outcomes, timestamps)

note

Only users with the Admin role can approve or reject KYC submissions. Compliance officers can view the pending list but cannot take action on it.

Permissions

The permissions page exposes Cocoon's argument-level permission system — a key differentiator from standard RBAC.

• Visual rule editor: add, edit, and remove per-role constraints on method arguments
• Live preview of how a rule would apply to a sample request
• Example view: "Trader role — token_transfer — amount ≤ $1,000,000"
• Toggle rules active/inactive without deleting them

Changes are written to the PermissionRegistry contract on-chain and take effect immediately on the next proxied call.

Audit Log

• Full audit log with search and filter (address, method, status, time range)
• Drill-down view for each entry showing full request parameters
• CSV export for compliance reporting

See Audit & Compliance Reporting for the full audit log reference.

Contracts

• Displays all deployed contract addresses from deployments.json
• Links to each contract on the block explorer
• Shows ABI summaries for the key contracts

Exchange

• Uniswap V3 pool statistics: TVL, 24h volume, fee accrual
• Recent swap history across all 15 trading pairs
• Pool health indicators (liquidity, price range utilization)

Settings

• Session timeout configuration (default: 30 minutes)
• Auth mode toggle (advisory / strict)
• KYC document type requirements

---

Investor Portal (Port 3001)

URL: http://localhost:3001
Audience: Investors (Alice, Bob) — requires login

The investor portal is the primary interface for end investors. It requires a verified account (kyc_status: verified) to access the trading and payment features.

Login

The login page accepts email and password. On successful authentication:

• The session token is stored in localStorage
• The user's KYC status is checked — unverified users see a KYC status banner and cannot proceed to trading screens
• The user's Ethereum address, IBAN, and role are loaded from the session

Pages

Portfolio

The main overview screen showing:

• Multi-asset portfolio value (Cash, ETF/Stocks, Crypto) with live prices
• MMF token balance and current NAV-based value
• Asset allocation pie chart
• Recent transaction history

Payments

IBAN-to-IBAN cash transfers between registered accounts:

• Recipient lookup by IBAN or name (e.g. CH5200033000000000002 → Alice)
• Amount input with currency selection (USD, EUR, CHF)
• Pending transaction confirmation screen showing full details before submission

Swap

Uniswap V3 swap interface:

• 12 trading pairs across SPY, TLT, BTC, ETH, EUR, CHF, and USD
• Live pool price updates (15-second polling)
• Slippage tolerance configuration
• Price impact warnings

MMF Subscribe / Redeem

• Current MMF NAV display
• Subscribe: enter stablecoin amount, preview shares to receive at current NAV
• Redeem: enter share amount, preview stablecoin to receive
• Transaction confirmation with compliance pre-flight check result

Proof of Reserves

Displays the ZK proof of the chain's state on Ethereum:

• Latest proved block number and state root
• Link to the proof on Ethereum
• Verification status (proof accepted / pending / stale)

This screen demonstrates that the chain's state can be verified by any party without trusting the operator.

Argument-Level Permission Enforcement

When a Trader attempts a transfer above their $1M limit, the portal:

1. Runs a pre-flight token_canTransfer check before showing the confirmation screen
2. Displays a clear message: "Your Trader role allows transfers up to $1,000,000. This request (amount: $2,000,000) requires SeniorTrader authorization."
3. Blocks the transaction confirmation button

This ensures users receive clear feedback about permission boundaries before any gas is spent.

---

Block Explorer (Port 3002)

URL: http://localhost:3002
Audience: All users, developers

The block explorer provides real-time visibility into chain activity — an Etherscan-style interface adapted for Cocoon's private chain.

Features

Home Page

• Search bar: accepts block number, transaction hash, or Ethereum address
• Stats cards: latest block number, transactions per second, gas usage
• Latest blocks list (live updating, 2-second poll)
• Latest transactions list with method badges and address labels

Block Detail Page

• Block header: number, timestamp, hash, parent hash, gas used/limit
• Transactions list with pagination
• Prev/Next navigation between blocks
• Gas gauge visualization

Transaction Detail Page

• Status badge (success / failed / pending)
• Confirmation count
• From / To addresses with human-readable labels (see below)
• Method name decoded from calldata
• Gas used, gas price, transaction fee
• Input data (hex + decoded ABI if the contract ABI is known)

Address Page

• Balance history
• Transaction list for the address with pagination
• Token balances for ERC-20 tokens held by the address

Address Resolution

The explorer resolves known addresses to human-readable labels:

Address	Label
Admin address	Admin
Alice's address	Alice (Trader)
Bob's address	Bob (Trader)
PermissionRegistry contract	PermissionRegistry
MMFToken contract	MMFToken
Stablecoin contract	Stablecoin (USD)
Uniswap pool contracts	Pool: SPY-USD, etc.

Address labels are maintained in a local SQLite index populated from deployments.json and the user DB.

SQLite Indexer

The explorer maintains a local SQLite database that indexes blocks, transactions, and address balances for efficient pagination and search. The indexer runs in the background and keeps up with the chain in real time.

note

The indexer uses a 2-second polling interval against the Erigon node. On first start, it may take a few minutes to catch up if the chain has accumulated many blocks.