Echo Markets

Bitcoin Prediction Markets powered by Charms Protocol ⚡

A decentralized prediction market platform built on Bitcoin Testnet4, powered by the Charms protocol. Trade on future outcomes using Bitcoin-native smart contracts with zero-knowledge proofs.

Built for: The BOS Hackathon - Building Bitcoin Smart Contracts with the BitcoinOS Stack at Encode Club

📦 Repositories

Repo	Description
echo-markets	Charms smart contracts (Rust)
echo-markets-frontend	Web application (this repo)

🎯 Features

Core Functionality

Create Markets — Launch prediction markets with custom questions, deadlines, and fees
Mint Shares — Deposit BTC to receive YES + NO tokens
Burn Shares — Burn equal YES + NO to recover BTC (before resolution)
P2P Trading — Swap YES tokens for NO (and vice versa)
Portfolio Tracking — Real-time P&L, position values, and transaction history
Wallet Integration — Full BIP39/BIP86 Taproot wallet with Schnorr signatures

Technical Highlights

Zero-Knowledge Proofs — Private, verifiable transactions via Charms
Bitcoin Native — Built on Bitcoin Testnet4, no sidechains
Taproot Wallets — BIP86 derivation with Schnorr signatures
Transaction Polling — Automatic confirmation tracking
Modern Stack — Next.js 15, React 19, TypeScript, Tailwind CSS v4

🚀 Quick Start

Prerequisites

Node.js 20+ and npm
Bitcoin Testnet4 coins (mempool faucet)
Charms CLI (for contract compilation)

Installation

# Clone the repository
git clone https://github.com/EchoMarkets/echo-markets-frontend.git
cd echo-markets-frontend

# Install dependencies
npm install

# Set up environment variables
cp .env.example .env.local

Environment Variables

Create a .env.local file:

# Charms Prover API
CHARMS_PROVER_URL=https://v8.charms.dev/spells/prove

# Mempool API (testnet4)
MEMPOOL_API=https://mempool.space/testnet4/api

# Contract Verification Key
# Generate with: charms app vk --wasm ./contracts/echo-markets.wasm
APP_VK=your_verification_key_here

# Path to compiled contract
APP_WASM_PATH=./contracts/echo-markets.wasm

Development

npm run dev
# Open http://localhost:3000

Production Build

npm run build
npm start

📁 Project Structure

echo-markets-frontend/
├── app/
│   ├── api/charms/           # Charms API routes
│   │   ├── broadcast/        # Transaction broadcasting
│   │   ├── cast/             # Prove + sign + broadcast
│   │   └── prove/            # ZK proof generation
│   ├── create/               # 4-step market creation wizard
│   ├── market/[id]/          # Market detail + trading
│   ├── portfolio/            # Positions, P&L, transactions
│   └── wallet/               # Wallet setup & management
├── components/
│   ├── layout/               # Header, navigation
│   ├── market/               # MarketCard
│   ├── trading/              # TradingPanel, SharesInput, PriceImpact
│   ├── wallet/               # WalletSetup, WalletDisplay, FundingInstructions
│   └── ui/                   # Button, Toaster
├── lib/
│   ├── bitcoin.ts            # Taproot signing, UTXOs, broadcasting
│   ├── charms.ts             # SpellBuilder (create, mint, trade, redeem)
│   ├── charmsApi.ts          # Prover API client
│   ├── store.ts              # Zustand stores (wallet, markets, portfolio)
│   ├── useCharms.ts          # React hook for all Charms operations
│   ├── WalletService.ts      # BIP39/BIP86 wallet management
│   └── utils.ts              # Formatting, calculations
├── contracts/
│   └── echo-markets.wasm     # Compiled Charms contract
└── types/
    └── index.ts              # TypeScript definitions

🔧 Tech Stack

Category	Technologies
Frontend	Next.js 15, React 19, TypeScript, Tailwind CSS v4, Framer Motion
State	Zustand with persist middleware
Bitcoin	@scure/btc-signer, @scure/bip32, @scure/bip39
Crypto	@noble/curves (Schnorr), @noble/hashes (SHA256)
Protocol	Charms
API	Mempool.space API

💼 How It Works

Transaction Flow

┌─────────────┐     ┌──────────────┐     ┌─────────────────┐
│  User Action │ ──▶ │ SpellBuilder │ ──▶ │ /api/charms/cast│
└─────────────┘     └──────────────┘     └────────┬────────┘
                                                   │
                                                   ▼
┌─────────────┐     ┌──────────────┐     ┌─────────────────┐
│   Broadcast │ ◀── │  User Signs  │ ◀── │  Charms Prover  │
│  to Bitcoin │     │  (Schnorr)   │     │ [commit, spell] │
└─────────────┘     └──────────────┘     └─────────────────┘

Market Lifecycle

Create — Deploy market with question hash, deadlines, fees
Mint — Users deposit BTC → receive equal YES + NO tokens
Burn — Users burn equal YES + NO → recover BTC (before resolution)
Trade — P2P swaps between YES and NO holders
Resolve — Creator resolves with outcome (YES/NO/Invalid)
Redeem — Winners burn tokens → receive 1 sat per token
Claim Fees (future) — Creator withdraws accumulated trading fees
Cancel (future) — Creator cancels unresolved market, users redeem at cost

Spell Types

Spell	Description	Status
`Create`	Deploy new market NFT	✅ Implemented
`Mint`	Deposit BTC, mint YES+NO tokens	✅ Implemented
`Burn`	Burn equal YES+NO to recover BTC (before resolution)	✅ SpellBuilder only
`Trade`	P2P swap (Charms token conservation)	✅ Implemented
`Resolve`	Set market outcome	✅ SpellBuilder only
`Redeem`	Burn winning tokens for BTC (after resolution)	✅ Implemented
`ClaimFees`	Creator withdraws accumulated fees	🔮 Future
`Cancel`	Creator cancels market, refunds holders	🔮 Future

🎨 Key Components

useCharms Hook

Central hook for all Charms operations:

const { createMarket, mintShares, trade, redeemShares, isLoading } =
  useCharms();

// Create market
const marketId = await createMarket({
  question: "Will BTC reach $150k by 2025?",
  tradingDeadline: 1735689600,
  resolutionDeadline: 1735776000,
  feeBps: 100,
  minBet: 10000,
  maxSupply: 1000000000,
});

// Mint shares
await mintShares({ marketId, amount: 50000 });

// P2P trade
await trade({
  marketId,
  sellOutcome: "Yes",
  sellAmount: 1000,
  sellUtxoId: "abc:0",
  buyUtxoId: "def:1",
  counterpartyAddress: "tb1p...",
});

Wallet Components

// Composable wallet UI
{
  !wallet ? (
    <WalletSetup /> // Create or import wallet
  ) : (
    <>
      <WalletDisplay /> // Address, balance, seed phrase
      <FundingInstructions /> // Faucet links, auto-polling
    </>
  );
}

Trading Components

<TradingPanel
  market={market}
  onTrade={handleTrade} // Calls useCharms.mintShares()
/>

📊 Implementation Status

✅ Complete

Feature	Status
Wallet (BIP39/BIP86 Taproot)	✅
Market creation UI + on-chain	✅
Trading UI + on-chain minting	✅
P2P trade function	✅
Portfolio with real positions	✅
Transaction history	✅
Confirmation polling	✅
Charms spells (create, mint, burn, trade, resolve, redeem)	✅
API routes (prove, cast, broadcast)	✅

🔮 Future Improvements

Retry logic for failed broadcasts
Dynamic fee estimation
Market resolution UI
Burn shares UI
Fee claiming UI for market creators
Cancel market functionality
Order book for P2P matching
On-chain market indexing

⚠️ Known Limitations

Testnet Only — This is a testnet prediction market
No Order Book — P2P trades require knowing counterparty's UTXO
Single Address — Uses primary address only (24-address system exists but unused)
Hardcoded Fees — Uses 2 sat/vB, no dynamic estimation

🔐 Security

Aspect	Implementation
Key Storage	Client-side only, never sent to servers
Mnemonic	Standard BIP39 12-word phrase
Signing	Schnorr signatures (BIP340)
Addresses	Taproot P2TR (BIP86)

⚠️ Important: Save your seed phrase! Keys are stored in browser memory and cleared on refresh.

🚢 Deployment

Vercel (Recommended)

Push to GitHub
Import in Vercel
Add environment variables
Deploy

Environment Variables

Set in your deployment platform:

CHARMS_PROVER_URL
MEMPOOL_API
APP_VK
APP_WASM_PATH

🔗 Links

Resource	URL
Testnet Faucet	https://mempool.space/testnet4/faucet
Block Explorer	https://mempool.space/testnet4
Charms Protocol	https://charms.dev

🙏 Acknowledgments

Charms Protocol — Bitcoin smart contracts with ZK proofs
BitcoinOS — Bitcoin application layer
Encode Club — a global developer education community focused on Web3 and AI

📄 License

MIT — Built for the BitcoinOS x Encode Club Hackathon

Built with ⚡ for Bitcoin

Name		Name	Last commit message	Last commit date
Latest commit History 69 Commits
app		app
components		components
contracts		contracts
lib		lib
public		public
types		types
.env.example		.env.example
.gitignore		.gitignore
README.md		README.md
eslint.config.mjs		eslint.config.mjs
next.config.ts		next.config.ts
package-lock.json		package-lock.json
package.json		package.json
postcss.config.mjs		postcss.config.mjs
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

Echo Markets

📦 Repositories

🎯 Features

Core Functionality

Technical Highlights

🚀 Quick Start

Prerequisites

Installation

Environment Variables

Development

Production Build

📁 Project Structure

🔧 Tech Stack

💼 How It Works

Transaction Flow

Market Lifecycle

Spell Types

🎨 Key Components

useCharms Hook

Wallet Components

Trading Components

📊 Implementation Status

✅ Complete

🔮 Future Improvements

⚠️ Known Limitations

🔐 Security

🚢 Deployment

Vercel (Recommended)

Environment Variables

🔗 Links

🙏 Acknowledgments

📄 License

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages