Skip to content

Getting Started ​

Prerequisites ​

ToolPurpose
Node.js 20+Frontend, relayer, Telegram bot
npmPackage management
ScarbCairo package manager and compiler
snforgeStarknet testing framework
NargoNoir ZK circuit compiler
Barretenberg (bb)ZK prover (server-side)
GaragaStarknet calldata generator

Smart Contracts ​

bash
cd contracts
scarb build        # Compile Cairo contracts
snforge test       # Run 37 Cairo tests

All 37 contract tests cover deposits, withdrawals, batch execution, Merkle tree operations, ZK proof verification, intent escrow, and privacy guarantees. Plus 4 Noir circuit tests and 123 frontend tests (Vitest) -- 164 tests total.

ZK Circuit ​

bash
cd circuits/veil
nargo test         # Run circuit tests
nargo compile      # Compile to ACIR
nargo execute      # Generate witness (with Prover.toml)

Frontend ​

bash
cd frontend
npm install
npm run dev            # Starts on http://localhost:3000

The frontend includes an embedded relayer as Next.js API routes under /api/relayer/. This handles gasless withdrawals, batch execution, calldata conversion, and BTC intent relay without requiring a separate relayer service.

Live app: https://theveilprotocol.vercel.app

Relayer and Keeper (scripts/) ​

For standalone relayer and keeper operation outside of the embedded API routes:

bash
cd scripts
cp .env.example .env   # Add PRIVATE_KEY, ACCOUNT_ADDRESS
npm install
npm run relayer        # Starts standalone relayer on http://localhost:3001
npm run keeper         # Run batch execution keeper

The standalone relayer exposes:

  • POST /prove -- Generate a ZK proof (nargo, bb, garaga pipeline)
  • POST /relay -- Submit a gasless withdrawal transaction
  • GET /health -- Health check with fee configuration

Telegram Bot ​

bash
cd scripts
cp .env.example .env   # Add TELEGRAM_BOT_TOKEN, POOL_ADDRESS
npm install
npm run bot            # Start the Telegram bot

Required environment variables:

  • TELEGRAM_BOT_TOKEN -- Obtain from @BotFather on Telegram
  • POOL_ADDRESS -- ShieldedPool contract address (auto-read from deployment.json if available)
  • WEB_APP_URL -- Frontend URL for deep links (default: http://localhost:3000)

Using the App ​

1. Connect Wallets ​

Connect both:

  • Starknet wallet (Argent or Braavos) -- for deposits and receiving WBTC
  • Bitcoin wallet (Xverse) -- for Bitcoin identity attestation and receiving native BTC

2. Shield (Deposit) ​

  1. Go to the Shield tab
  2. Select a denomination ($1 / $10 / $100 / $1,000 USDC)
  3. Approve USDC spending
  4. Confirm the deposit transaction
  5. Save your encrypted note -- you will need it for withdrawal

3. Wait for Batch Execution ​

The keeper aggregates deposits and executes a batch USDC-to-WBTC swap using live BTC pricing from CoinGecko. This happens periodically or can be triggered via the embedded relayer API.

4. Unveil (Withdraw) ​

  1. Go to the Unveil tab
  2. Load your encrypted note
  3. Choose your withdrawal mode:
    • WBTC on Starknet -- enter a Starknet recipient address
    • Native BTC (intent settlement) -- enter a Bitcoin address; a solver sends BTC directly
  4. Optionally enable gasless withdrawal (relayer pays gas)
  5. The app generates a ZK proof (in-browser via bb.js WASM, or server-side)
  6. Submit the withdrawal transaction
  7. Assets are sent to the recipient address

5. AI Strategist ​

  1. Go to the Strategist tab
  2. Type a natural language instruction describing your goal:
    • "Accumulate $50 in BTC, maximize privacy"
    • "DCA $50 over 5 deposits"
    • "Invest $200, spread across all pools"
    • "Quick $10 deposit, minimize gas"
  3. Watch the agent's real-time thinking log as it analyzes pool state and BTC price
  4. Review the generated execution plan (steps, tiers, delays, estimated BTC, privacy score)
  5. Approve and execute with a single wallet confirmation

6. Telegram Bot ​

Use the Telegram bot for mobile strategy planning:

  • /strategy Accumulate $50 in BTC, maximize privacy -- streams a thinking log and generates a strategy
  • /status -- pool state and BTC price
  • /price -- live BTC with per-tier conversion rates
  • /pool -- detailed protocol analytics with a link to view the contract on Voyager

Tap the "Execute on Web" button in the bot's response to deep-link into the web app with the strategy pre-loaded.

7. Comply (Optional) ​

Use the Comply tab to:

  • Register a view key for your deposit
  • Export a compliance proof (JSON) for regulators

Re{defining} Privacy on Starknet — Re{define} Hackathon 2026