Stacks Bridge Base

An open-source infrastructure for bridging USDC between Base (Ethereum L2) and Stacks (Bitcoin L2). 80% cheaper than bridging via Ethereum L1.

The Problem

Bridging assets to Stacks currently requires going through Ethereum L1, which is expensive. Users pay high gas fees just to move USDC into the Stacks DeFi ecosystem.

Our Solution

Use Base L2 as the source chain instead of Ethereum L1. Base offers:

80% lower gas fees than Ethereum mainnet
Fast finality (~2 seconds)
Strong security inherited from Ethereum

+---------------+                      +---------------+
|     Base      | <-- Bidirectional -> |    Stacks     |
|   (ETH L2)    |        Bridge        |   (BTC L2)    |
+---------------+                      +---------------+
      USDC             Relayer               xUSDC

  Deposit:  Lock USDC on Base  ->  Mint xUSDC on Stacks
  Withdraw: Burn xUSDC on Stacks  ->  Release USDC on Base

Project Status

Phase	Status	Description
Core Infrastructure	✅ Completed	Smart contracts, relayer, frontend
Security Hardening	✅ Completed	Multi-sig, timelocks, rate limiting
Clarity 4 Upgrade	✅ Completed	Latest Stacks features
USDCx DEX Integration	✅ Completed	Velar + Alex + xReserve adapters
Testnet Deployment	✅ Completed	Base Sepolia + Stacks Testnet live
E2E Testing	✅ Verified	Deposit + Withdraw flows tested
Mainnet Launch	✅ LIVE	Base + Stacks Mainnet deployed

See ROADMAP.md for full details.

🚀 Mainnet Deployment (January 2026)

Network	Contract	Address	Verified
Base Mainnet	BridgeBase	`0x0EdF28403D027Be0917625C751c78236407dD4E0`	✅
Base Mainnet	USDC (Circle)	`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`	-
Stacks Mainnet	wrapped-usdc-v5	`SP1MTYHV6K2FNH3QNF4P5QXS9VJ3XZ0GBB5T1SJPK.wrapped-usdc-v5`	✅

Security Features

Multi-Sig: 2-of-3 required for all releases/mints
Rate Limits: 10K USDC/tx, 50K/hour, 200K/day
Timelock: 10min for medium, 1hr for large transactions

Testnet Deployment

Network	Contract	Address
Base Sepolia	BridgeBase	`0xFCDF3e427e4a4CF3E573762693B9a1bBb35C504B`
Base Sepolia	USDC (Circle)	`0x036CbD53842c5426634e7929541eC2318f3dCF7e`
Stacks Testnet	wrapped-usdc-v5	`ST1ZGGS886YCZHMFXJR1EK61ZP34FNWNSX28M1PMM.wrapped-usdc-v5`

Recent Updates

🎉 Mainnet Launch (January 30, 2026)

✅ Base Mainnet Deployed

Contract: 0x0EdF28403D027Be0917625C751c78236407dD4E0
2-of-3 multi-sig security
Verified on BaseScan

✅ Stacks Mainnet Deployed

Contract: SP1MTYHV6K2FNH3QNF4P5QXS9VJ3XZ0GBB5T1SJPK.wrapped-usdc-v5
Signers Initialized: TX 0x82f87b95...
Block Height: 6202949

🆕 Frontend Improvements (January 2026)

✅ Real-Time L1 Gas Comparison (NEW)

L1 gas price from Etherscan Gas Oracle v2 API (1-min refresh)
Dynamic fee comparison: Base L2 vs ETH L1
Visual comparison bars (green L2 / red L1)
Shows actual L1 bridge cost (~$0.24 at 0.5 Gwei)

✅ Dynamic Footer Stats

Real-time average fee calculation
Live data from usePrices hook
Shows "<$0.01" for very low fees

✅ Real-Time Price Feeds

ETH/USD: Chainlink price feed on Base mainnet (updates every block)
STX/USD: Coinbase API with 5-minute cache
Dynamic fee breakdown with live gas prices

✅ SSR-Safe Wallet Connection

Reusable ConnectButton component with proper hydration handling
useSyncExternalStore for React 18 compatibility
Lazy AppKit initialization via openAppKitModal() function

✅ Network-Aware Components

BridgeStats: Auto-switches Blockscout API (mainnet/testnet)
TransactionHistory: Dynamic API based on NEXT_PUBLIC_NETWORK
FeeEstimator: Live price badges showing data sources

Previous Improvements

✅ E2E Testing Verified

Full deposit/withdraw flows tested on testnet
Transaction Evidence: See testnet transactions

End-to-End Testnet Verification Complete

Full deposit → queue-mint → execute-mint flow tested and working!
Base Sepolia: 10 USDC deposited and locked
Stacks Testnet: 10 xUSDC minted successfully on wrapped-usdc-v5

Phase 4: USDCx Integration Complete

Velar DEX adapter (velar-adapter.clar) with mainnet router integration
Circle xReserve alternative (xreserve-adapter.clar) for 1:1 attestation swaps
Dual execution paths: execute-mint-and-swap (DEX) or execute-mint-via-xreserve
Full documentation: docs/usdcx-workflow.md

OnchainKit and Base Account Integration

Downgraded React to 18.2 and wagmi to v2 for stability
Pinned viem to 2.17.3 for wagmi v2 compatibility
Added Turbopack config and root package.json scripts for frontend workflows

Quick Start

Prerequisites

Node.js 18+
Clarinet 3.11+ (contracts use Clarity 4, Epoch 3.3)
WalletConnect Project ID (free)
Stacks wallet (Leather or Xverse)
MetaMask (for Base)

1. Clone and Setup

git clone https://github.com/unclekaldoteth/stacks-bridge.git
cd stacks-bridge

2. Run Smart Contracts (Stacks)

cd stacks
clarinet check          # Verify contracts compile
npm install             # Install test dependencies
npm test                # Run Vitest tests (22 tests)
clarinet devnet start   # Start local devnet

3. Run Relayer

cd relayer
npm install
cp .env.example .env    # Configure your keys
npm start

4. Run Frontend

cd frontend
npm install
npm run dev             # Opens at http://localhost:3000

Tip: from the repo root, npm run dev delegates to frontend after installing dependencies there.

Architecture

Components

Component	Technology	Description
EVM Contracts	Solidity, Hardhat	Lock/release USDC on Base
Stacks Contracts	Clarity 4	Mint/burn xUSDC on Stacks
Relayer	Node.js	Watch events, execute cross-chain txs
Frontend	Next.js, WalletConnect	User interface

Smart Contracts

stacks/contracts/
├── wrapped-usdc-v5.clar          # Current xUSDC token (Clarity 4) - Testnet
├── wrapped-usdc-v4.clar          # xUSDC token (Clarity 4)
├── wrapped-usdc-v3.clar          # xUSDC token (SIP-010)
├── wrapped-usdc-v2.clar          # Legacy version
├── wrapped-usdc.clar             # Original version
├── dex-adapter-trait.clar        # DEX integration interface
├── velar-adapter.clar            # Velar DEX adapter
├── xreserve-adapter.clar         # Circle xReserve adapter
└── sip-010-trait-ft-standard.clar

evm/contracts/
└── BridgeBase.sol                # USDC lock/release on Base

Security Features

Multi-Signature: 2-of-3 signers required for minting
Timelocks: Large transactions have enforced delays
Rate Limiting: Hourly (50K) and daily (200K) caps
Emergency Pause: Any signer can pause, owner unpause

Deployed Contracts (Testnet)

Network	Contract	Address
Base Sepolia	BridgeBase (v2)	`0xFCDF3e427e4a4CF3E573762693B9a1bBb35C504B`
Stacks Testnet	wrapped-usdc-v5	`ST1ZGGS886YCZHMFXJR1EK61ZP34FNWNSX28M1PMM.wrapped-usdc-v5`

Official USDCx (Mainnet Reference)

Network	Contract	Address
Stacks Mainnet	USDCx (Circle)	`SP120SBRBQJ00MCWS7TM5R8WJNTTKD5K0HFRC2CNE.usdcx`

Note: USDCx is Circle's official USDC-backed stablecoin on Stacks, deployed via xReserve. It is only available on mainnet.

Contributing

We need community help! This project is open source and welcomes contributions.

Priority Areas

Area	Description	Difficulty
USDCx Integration	Swap xUSDC to official Stacks USDCx	Hard
Testing	Unit tests for Clarity & Solidity	Medium
Documentation	API docs, deployment guides	Easy
Security Review	Code audit, vulnerability assessment	Medium

Good First Issues

Add unit tests for Clarity contracts
Improve error handling in relayer
Add transaction history UI component
Document API endpoints

Quick Links

CONTRIBUTING.md - How to contribute
docs/developer-api.md - Contract APIs + relayer flow
docs/developer-guides.md - Setup, runbook, troubleshooting, deployment
ROADMAP.md - Project phases and priorities
CODE_OF_CONDUCT.md - Community standards

Tech Stack

Layer	Technologies
Stacks	Clarity 4, Epoch 3.3, Clarinet 3.11
EVM	Solidity, Hardhat, OpenZeppelin
Relayer	Node.js, Viem, @stacks/transactions
Frontend	Next.js (React 18), TypeScript, WalletConnect, Wagmi v2, OnchainKit, Base Account SDK

Environment Variables

Relayer (.env)

# Base (EVM)
BASE_RPC_URL=https://sepolia.base.org
SIGNER_PRIVATE_KEY=your_evm_private_key
BRIDGE_BASE_ADDRESS=0xFCDF3e427e4a4CF3E573762693B9a1bBb35C504B

# Stacks
STACKS_API_URL=https://api.testnet.hiro.so
# Optional: separate Stacks core node endpoint (falls back to STACKS_API_URL)
STACKS_CORE_API_URL=https://stacks-node-api.testnet.stacks.co
STACKS_PRIVATE_KEY=your_stacks_mnemonic_or_key
STACKS_CONTRACT_ADDRESS=ST1ZGGS886YCZHMFXJR1EK61ZP34FNWNSX28M1PMM
STACKS_CONTRACT_NAME=wrapped-usdc-v5

Frontend (.env.local)

NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID=your_walletconnect_id
# Optional: OnchainKit API key (omit to use an RPC URL)
NEXT_PUBLIC_ONCHAINKIT_API_KEY=your_onchainkit_api_key
# Optional: RPC URL for OnchainKit (falls back to NEXT_PUBLIC_BASE_RPC_URL)
NEXT_PUBLIC_ONCHAINKIT_RPC_URL=https://sepolia.base.org
# Optional: EAS schema ID for OnchainKit attestation badges
NEXT_PUBLIC_ONCHAINKIT_SCHEMA_ID=0x...
NEXT_PUBLIC_BASE_ACCOUNT_APP_NAME=Stacks Bridge
NEXT_PUBLIC_BASE_RPC_URL=https://sepolia.base.org
NEXT_PUBLIC_NETWORK=testnet

License

MIT License - see LICENSE for details.

Acknowledgments

Hiro Systems - Stacks development tools
Base - Scalable L2
OpenZeppelin - Secure Solidity libraries
Stacks Community - Feedback and support

Built for the Stacks ecosystem. Contribute and help us make cross-chain bridging accessible to everyone.

Name		Name	Last commit message	Last commit date
Latest commit History 80 Commits
.github		.github
docs		docs
evm		evm
frontend		frontend
relayer		relayer
stacks		stacks
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
ROADMAP.md		ROADMAP.md
package.json		package.json

License

unclekaldoteth/stacks-bridge

Folders and files

Latest commit

History

Repository files navigation

Stacks Bridge Base

The Problem

Our Solution

Project Status

🚀 Mainnet Deployment (January 2026)

Security Features

Testnet Deployment

Recent Updates

🎉 Mainnet Launch (January 30, 2026)

🆕 Frontend Improvements (January 2026)

Previous Improvements

Quick Start

Prerequisites

1. Clone and Setup

2. Run Smart Contracts (Stacks)

3. Run Relayer

4. Run Frontend

Architecture

Components

Smart Contracts

Security Features

Deployed Contracts (Testnet)

Official USDCx (Mainnet Reference)

Contributing

Priority Areas

Good First Issues

Quick Links

Tech Stack

Environment Variables

Relayer (.env)

Frontend (.env.local)

License

Acknowledgments

About

Topics

Resources

License

Code of conduct

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Contributors 2

Uh oh!

Languages

Packages