> ## Documentation Index
> Fetch the complete documentation index at: https://q3-56b48e0c-brove-doc.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Guide Developers

> Technical requirements and dependencies for Brove development

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:**

* [Unisat](https://chromewebstore.google.com/detail/unisat-wallet/ppbibelpcjmhbdihakflkdcoccbgbkpo)
* [Xverse](https://chromewebstore.google.com/detail/idnnbdplmphpflfnlkomgpfbpcgelopg)

**Starknet Wallets:**

* [Braavos](https://chromewebstore.google.com/detail/jnlgamecbpmbajjfhmmmlhejkemejdma)
* [ArgentX](https://chromewebstore.google.com/detail/dlcobpjiigpikoobohmabehhmhfoodbb)

## 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](https://github.com/keep-starknet-strange/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](http://localhost:3000) to access the interface

#### Configure Smart Contract

* Go to **Debug** in the app [http://localhost:3000/debug](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:**

```bash
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

```bash
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:

```bash
http://localhost:3000/purchased/top-up
```

* For Create BroveBox via UI:

```bash
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/debug`in 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.**