Webapp Overview

The Specter webapp is the primary user interface for interacting with Ghost Protocol. It is a single-page application that handles wallet connection, commitment generation, zero-knowledge proof creation, and transaction submission — all client-side.

Technology Stack

Layer	Technology
Framework	React 18 with functional components and hooks
Build tool	Vite (fast HMR, optimized production builds)
Blockchain	ethers.js v6 and viem for contract interaction
Wallet	RainbowKit + wagmi for wallet connection and chain management
ZK Proofs	snarkjs (Groth16 prover, runs in Web Worker)
Hashing	circomlibjs (Poseidon hash, WASM-based)
Deployment	Vercel (automatic deployments from main branch)

Architecture

┌─────────────────────────────────────────────────────┐
│                    React UI Layer                    │
│  ┌──────────┐ ┌──────────┐ ┌───────┐ ┌───────────┐ │
│  │  Vanish  │ │  Summon  │ │ Bridge│ │  Stealth  │ │
│  │  Screen  │ │  Screen  │ │ Screen│ │  Screen   │ │
│  └────┬─────┘ └────┬─────┘ └───┬───┘ └─────┬─────┘ │
│       │             │           │            │       │
│  ┌────▼─────────────▼───────────▼────────────▼────┐  │
│  │              Shared Hooks & Services            │  │
│  │  useCommit() useReveal() useBridge() useKeys() │  │
│  └────┬─────────────┬───────────┬────────────┬────┘  │
│       │             │           │            │       │
│  ┌────▼─────┐ ┌─────▼────┐ ┌───▼────┐ ┌─────▼────┐ │
│  │  Crypto  │ │  Wallet  │ │Contract│ │  Relayer │ │
│  │  Module  │ │  Module  │ │ Module │ │  Client  │ │
│  │(snarkjs) │ │(wagmi/RK)│ │(ethers)│ │ (fetch)  │ │
│  └──────────┘ └──────────┘ └────────┘ └──────────┘  │
└─────────────────────────────────────────────────────┘
         │              │           │            │
    ┌────▼────┐   ┌─────▼────┐ ┌───▼─────┐ ┌───▼──────┐
    │ Circuit │   │ MetaMask │ │ Specter │ │ Relayer  │
    │ Artifacts│  │ / Wallet │ │  Chain  │ │   API    │
    └─────────┘   └──────────┘ └─────────┘ └──────────┘

Client-Side ZK Proofs

All zero-knowledge proof generation happens in the browser. The webapp loads the circuit WASM and proving key (zkey), then runs snarkjs.groth16.fullProve() inside a Web Worker to avoid blocking the main thread. No secret data ever leaves the user's browser.

Wallet Connection

RainbowKit provides the wallet connection modal, supporting MetaMask, WalletConnect, Coinbase Wallet, and other EVM wallets. The wagmi library manages chain state, transaction signing, and event subscriptions. The webapp auto-prompts users to switch to Chain ID 5446 if they are connected to a different network.

Main Screens

Vanish (Commit)

The Vanish screen is where users commit tokens into the privacy pool:

1. Select a token (GHOST, gLABS, gUSDC, gWETH, gVIRTUAL, or any registered GhostERC20).
2. Enter the amount to commit.
3. The app generates a phantom key containing all cryptographic secrets.
4. The user saves the phantom key (download JSON, copy to clipboard, export as QR, or write to NFC card).
5. The app submits the commit() transaction to the CommitRevealVault.
6. On confirmation, the commitment is inserted into the Merkle tree and the leaf index is recorded in the phantom key.

Summon (Reveal)

The Summon screen is where users reveal committed tokens:

1. Import a phantom key (paste JSON, scan QR, tap NFC card, or select from local storage).
2. The app fetches the current Merkle root and proof from the relayer.
3. The app generates a Groth16 proof in a Web Worker (3-30 seconds depending on device).
4. Enter the recipient address.
5. The app submits the reveal() transaction to the CommitRevealVault.
6. On confirmation, fresh tokens are minted to the recipient.

Bridge

The Bridge screen enables cross-chain transfers using Hyperlane:

• Bridge tokens between Specter and supported chains using Hyperlane warp routes.
• The bridge uses HypGhostERC20Synthetic contracts for wrapped representations on remote chains.
• Users select the source and destination chains, token, and amount.
• The app handles approval, wrapping, and Hyperlane message dispatch.

Revels

The Revels screen provides a history view:

• Displays the user's commit and reveal history from on-chain events and local storage.
• Shows phantom key status (committed, revealed, expired).
• Allows re-export of stored phantom keys.

Stealth

The Stealth screen manages persistent keys for the OpenGhost data privacy system:

• Create persistent keys for encrypted data storage.
• Manage keys stored in the on-chain PersistentKeyVault (0x338B0e3c722702E705357C291E151D76B8Fd9F61).
• View and revoke access to persistent commitments.

State Management

The webapp uses React hooks and context for state management:

• Wallet state: Managed by wagmi and RainbowKit. Includes connected address, chain ID, and provider/signer instances.
• Phantom keys: Stored in the browser's localStorage (encrypted with the user's wallet signature). Keys are never sent to any server.
• Contract state: Fetched on-demand via ethers.js calls to the Specter RPC. Cached in React state with TTLs.
• Proof artifacts: Circuit WASM and zkey files are loaded from the deployment CDN and cached in the browser's Cache API.

Configuration

The webapp's behavior is controlled by config.js, which defines chain parameters, contract addresses, token configurations, and relayer endpoints. See Webapp Configuration for details.

Development

# Clone and install
git clone <repo-url>
cd webapp
npm install

# Start development server
npm run dev
# → http://localhost:5173

# Build for production
npm run build

# Preview production build
npm run preview

Environment Variables

The webapp reads configuration from config.js rather than environment variables, so no .env file is required for standard operation. For custom deployments, modify config.js directly.