Skip to main content
This guide outlines the technical dependencies and system requirements for developing with Brove. Our stack leverages cutting-edge blockchain technology while maintaining developer-friendly tooling.

​
Brove Technical Architecture

Brove is an infrastructure that enables demonstrating real Bitcoin activity within the Starknet ecosystem. Using Raito, Brove converts past Bitcoin transactions into verifiable on-chain cryptographic proofs, enabling Starknet applications to trust their users’ Bitcoin history.

​
🎯 The Core: Bitcoin → Starknet

​
What Does Brove Do?

Brove verifies that you actually interacted with Bitcoin and brings that proof to Starknet.
It is not about general activity or tokens—it is specifically about demonstrating that you sent, received, or participated in real Bitcoin transactions in specific Bitcoin blocks.

​
Why Is This Important?

  • Starknet applications can trust verified Bitcoin history
  • Users can prove real Bitcoin experience without revealing private keys
  • Eliminates the need to trust third parties to validate Bitcoin activity
  • Connects two ecosystems: Bitcoin’s security with Starknet’s programmability

​
🧰 Development Kit

​
Compatible Bitcoin-Starknet Versions

  • Starknet Devnet: v0.4.0
  • Scarb: v2.12.1
  • Snforge: v0.48.1
  • RPC: v0.8.0
  • Bitcoin Core: v24.0+

​
Other information about SDK and Library

  • TypeScript/JavaScript SDK: Proof generation from Bitcoin Core. Install with npm install bitcoin-on-starknet.
  • Cairo Library Raito: Interprets Bitcoin data inside smart contracts.

​
Compatible Wallets

Bitcoin Wallets: Starknet Wallets:

​
Core Infrastructure

Bitcoin + Raito + S-two + Brove + Starknet

​
System Components

  1. Bitcoin Network: The ultimate source of truth for transactions.
  2. Raito: A Cairo library that acts as a Bitcoin Light Client, processing Bitcoin data structures for use in Brove.
  3. S-two: StarkWare’s next-generation prover that validates the correct state using STARK proofs.
  4. Brove Contracts: Smart contracts that validate inclusion proofs and Bitcoin metadata to generate custom proofs and vaults.

​
Bitcoin → Starknet Verification Flow

  1. A user performs a Bitcoin transaction (e.g., in block 150,000).
  2. Brove retrieves the transaction and its block from a Bitcoin node.
  3. Raito processes the Bitcoin data structures in Cairo, verifies them, and registers the block header on Starknet, proven by S-two with STARK proofs.
  4. Brove generates an inclusion proof (Merkle proof + metadata).
  5. The Starknet application verifies the proof on-chain.
  6. The user gains access to services based on their verified Bitcoin activity.

​
⚡ Raito - Bitcoin Client on Starknet

Raito provides Bitcoin data structures in Cairo, enabling verification of transactions and headers directly in smart contracts.

​
Key Capabilities

  • Transaction Parsing: Decode and validate Bitcoin transaction formats in Cairo.
  • Block Header Processing: Validate Bitcoin block headers and chain continuity.
  • Merkle Proof Verification: Validate cryptographic proofs of inclusion.
  • Script Interpretation: Support Bitcoin scripts (P2PKH, P2SH, SegWit, Taproot).

​
Main Functions

  • Block Header Verification: Register and validate Bitcoin headers with Proof-of-Work.
  • Canonical Chain Maintenance: Link verified blocks to their heights for consistency.
➡️ More details: StarkWare Labs Raito

​
📦 Installation and Deployment

​
Environment Variables

Configure snfoundry .env to deploy your smart contracts by configuring on sepolia or mainnet. 
## Sepolia
PRIVATE_KEY_SEPOLIA=
RPC_URL_SEPOLIA=https://starknet-sepolia.public.blastapi.io/rpc/v0_8
ACCOUNT_ADDRESS_SEPOLIA=

## Mainnet
ACCOUNT_ADDRESS_MAINNET=
RPC_URL_MAINNET=https://starknet-mainnet.public.blastapi.io/rpc/v0_8
PRIVATE_KEY_MAINNET=
To adjust your location you will need to adjust several .env in nextjs with Bitcoin-Starknet RPC access from (QuickNode BTC), although you can find in .env.example some APIs to connect provisionally and you previous Smart Contract deployed: 
# === Provider URLs ===
NEXT_PUBLIC_PROVIDER_URL=http://127.0.0.1:5050
NEXT_PUBLIC_DEVNET_PROVIDER_URL=http://127.0.0.1:5050
NEXT_PUBLIC_SEPOLIA_PROVIDER_URL=https://starknet-sepolia.public.blastapi.io/rpc/v0_8
NEXT_PUBLIC_MAINNET_PROVIDER_URL=https://starknet-mainnet.public.blastapi.io/rpc/v0_8

# === API Keys ===
NEXT_PUBLIC_API_KEY=0x1234

# === Bitcoin RPC Credentials ===
BITCOIN_RPC_URL="https://bitcoin.com"
BITCOIN_RPC_USER=""
BITCOIN_RPC_PASS=""

NEXT_PUBLIC_BITCOIN_RPC_URL="https://bitcoin.com"
NEXT_PUBLIC_BITCOIN_RPC_USER=""
NEXT_PUBLIC_BITCOIN_RPC_PASS=""

# === Starknet Configuration ===
STARKNET_PROVIDER_URL="https://starknet-mainnet.public.blastapi.io/rpc/v0_8"
STARKNET_ADDRESS="0xaddress"
STARKNET_PRIVATE_KEY="0xprivatekey"

# === Brove Contract Addresses ===
BROVEBOXES_CONTRACT=""
BROVECREDITS_CONTRACT=""
NEXT_PUBLIC_BROVEBOXES_CONTRACT=""
NEXT_PUBLIC_BROVECREDITS_CONTRACT=""

# === Transaction Inclusion Server URL ===
TX_INCLUSION_SERVER_URL=http://localhost:5000

# === Lighthouse API Key ===
LIGHTHOUSE_API_KEY=

# === EmailJS Configuration ===
NEXT_PUBLIC_EMAILJS_SERVICE_ID=
NEXT_PUBLIC_EMAILJS_TEMPLATE_ID=
NEXT_PUBLIC_EMAILJS_PUBLIC_KEY=

​
Deploy Contracts

Terminal 1: For install all dependencies 
yarn install
For deployed all Smart Contracts: 
yarn deploy --network [mainnet or sepolia]
Then to up the local UI: 
yarn start
Open your browser to the port http://localhost:3000 to access the interface

​
Configure Smart Contract

  • Go to Debug in the app http://localhost:3000/debug (⚠️ Do not copy SC the CLI).
  • Copy the addresses of the Smart Contracts.
  • Replace the following values inside the Next.js .env file:
# Contract addresses
BROVEBOXES_CONTRACT=""
BROVECREDITS_CONTRACT=""

# Next.js - Contract addresses
NEXT_PUBLIC_BROVEBOXES_CONTRACT=""
NEXT_PUBLIC_BROVECREDITS_CONTRACT=""

# Starknet configuration
STARKNET_PROVIDER_URL="https://starknet-sepolia.blastapi.io/64168c77-3fa5-4e1e-9fe4-41675d212522/rpc/v0_8"
STARKNET_ADDRESS="0xaddress"
STARKNET_PRIVATE_KEY="0xprivatekey"
If you want to switch between Sepolia or Mainnet you should go to nextjs/scaffold.config.ts and change the targetNetworks: [chains.mainnet] or [chains.sepolia] With these settings we have everything ready to set up the local.

​
⚙️ Raito Setup

Now we will configure Raito to be able to have our Bitcoin Light Client in Cairo and be able to verify the state of the Bitcoin chain and generate the inclusion proofs with Brove. Terminal 2: 
cd raito
make setup
scarb --profile release build --package client --target-kinds executable
  • If build fails for Cairo 2.12.0 due to assumevalid, comment out # unsafe-panic = true in Scarb.toml.

​
⚙️ Server Setup

cd package/server/
pip install -r requirements_server.txt
python tx_proof_server.py
  • Server is ready to receive Bitcoin transactions and generate inclusion proofs using Raito + S-two.

​
💳 Create BroveBoxes and Credits

  1. Configure contract addresses in Next.js .env.
  2. Add in http://localhost:3000/debug SC Brove Credit in set_authorized_consumer with address the BroveBoxes
  3. Add in http://localhost:3000/debug BroveBoxes in whitelist_creator the address you like add as creator for create BroveBoxes.
  4. Use in http://localhost:3000/debug the set_brove_identity_contract in BroveBoxes contract.
  5. Use in http://localhost:3000/debug the set_brove_boxes_contract in Brove Identity contract to link BroveBoxes with Brove Passport.
  • Purchase credits via UI:
http://localhost:3000/purchased/top-up
  • For Create BroveBox via UI:
http://localhost:3000/broveboxes-explorer
  • Ensure you have sufficient tokens (default: 5 USDC) to create BroveBoxes. Fill in the requirements you want to demonstrate for the address you added to the whitelist. Verify that the Raito server is running and that both your Bitcoin and Starknet wallets are connected.
  • Once the BroveBox is created, click on it and select Sign Message. Signing the message with ECDSA will trigger verification in Starknet. If everything is correct, the server will process the request, generating the proper proofs and invoking S-two to produce the correct block header and transaction data in zero-knowledge. This ensures that your Bitcoin transactions meeting the defined requirements are correctly verified on Starknet.
All funds can be withdrawn by the Smart Contract owner, including both the credits used and the amounts spent to create BroveBoxes. Withdrawals are done from http://localhost:3000/debugin each contract, specifying the values as U64.

​
✨ For Developers: Build on Real Bitcoin Activity

Brove opens Bitcoin history to the Starknet ecosystem. Any application can now cryptographically trust that their users actually interacted with Bitcoin, without depending on centralized APIs or third-party trust. By running your own Bitcoin node you can not depend on QuickNode and we would have an even more totally decentralized system.

​
Credits

Brove for integration with Bitcoin on Starknet and Raito. Build applications that recognize and reward real Bitcoin activity.