# Overview We're reimagining finance and the internet from the ground up—centered on Bitcoin, connected to all. Through radically trust-minimized infrastructure, we’re unlocking open finance for everyone. The traditional financial system is gated, and today’s monetary system is inherently inflationary. For billions of people, there has been little way out—until the emergence of permissionless, decentralized technologies. Blockchains sparked this shift, with **Bitcoin** leading the movement as the first and still most dominant crypto asset, now valued at over **$2 trillion**. Yet despite its scale, most BTC remains idle. Why? Because the Bitcoin blockchain lacks programmability, and the broader on-chain experience remains fragmented, inaccessible, and unintuitive. We are a team of cryptographers, blockchain developers, and fintech professionals pioneering **BitVM2**—the Bitcoin Virtual Machine—ushering in a new era of **trust-minimized Bitcoin infrastructure and cross-ecosystem bridges** built with **Bitcoin finality** for the first time. We were the **first to enable Bitcoin to verify ZKPs optimistically** under BitVM2. This milestone lays the groundwork for the most trust-minimized foundation to bring BTC into broader DeFi, Web3, and real-world applications. We hold a deep conviction: **Zero-knowledge technology is the key to unlocking Bitcoin’s full potential.** After two rounds of testnet launches for our BitVM-powered bridge, it became clear that another frontier must be tackled: **user experience**—especially when striving for both **self-custody and trust minimization**. That’s why we will also launch **Fiamma One** soon, a non-custodial superapp delivering **one-click BTC earning**—a seamless, secure first step toward unlocking broader BTC use cases like **non-custodial lending, stablecoin and RWA strategies**, and more. This is only the beginning. We’re building the rails for the next chapter of finance—**rooted in Bitcoin, connected to all**. # Our Product Suite At Fiamma, we're building the next-generation wealth management platform—combining the most trustless infrastructure with the most seamless user experience. Our flagship app, **Fiamma One**, is a non-custodial superapp that enables anyone to earn yield on BTC or stablecoins in just one click. **Bitcoin strategies** are powered by the **Fiamma Bridge**, a trust-minimized Bitcoin bridge built on BitVM2. We're already researching its evolution to BitVM3 for even greater trustlessness and efficiency. The future of BTC and on-chain wealth management is only beginning. **Stay tuned.** # Fiamma Bridge (Trust-minimized and Hack-resistant) We are building Bitcoin bridges using the BitVM2 framework to connect diverse ecosystems to Bitcoin in a trust-minimized and efficient manner (BitVM3 soon). This enables securely minted, tokenized BTC backed directly by Bitcoin across multiple chains, including BTC Layer 2s, staking and restaking protocols, Ethereum, Solana, and more. Bitcoin, with trillions in value, largely remains inactive, despite numerous revenue opportunities across blockchain ecosystems, particularly within DeFi on Ethereum, Solana, and similar platforms. Existing cross-chain solutions for Bitcoin are often centralized and lack security, discouraging BTC holders from transferring assets for DeFi use. This hesitancy limits both liquidity and the broader utility of Bitcoin’s 21 million supply. Currently, only about 1.5% of BTC is bridged to other chains, underscoring the demand for trustless—or at least trust-minimized—cross-chain solutions to unlock Bitcoin’s full potential across the decentralized ecosystem. # High-level Design of Fiamma Bridge Below is a high-level, preliminary design for Fiamma Bridge (the BitVM-based pragmatically trustless Bitcoin bridge). We offer customizable implementations for each partner. ## What is a Trustless Bitcoin Bridge? Our trustless Bitcoin bridge provides secure, permissionless transfers of BTC between Bitcoin and sidechains. It ensures: 1. **Locked BTC Safety**: User's BTC remains secure, without unilateral control by any entity. 2. **Trustless PEG-IN**: Bitcoin to sidechain transfers are fully permissionless. 3. **Trustless PEG-OUT**: Sidechain to Bitcoin transfers maintain the same security and trustlessness. ## How Do We Secure Locked BTC? * **Traditional Approach**: A committee controls your BTC, meaning they could spend it without your consent. * **Our Solution**: BTC is co-controlled by the user and the committee, requiring both signatures, powered by pre-signed transactions with BitVM2 functionality. This setup prevents the committee from spending BTC without user authorization.
## PEG-IN Process (Bitcoin to Sidechain) To receive mamaBTC (tokenized BTC via Fiamma bridge) on the sidechain, our system verifies transactions through a Bitcoin light client to ensure validity, preventing issues like: 1. **Incorrect Minting**: The Mint contract checks the validity of transactions on Bitcoin, ensuring that only authentic BTC transactions allow minting on the sidechain. 2. **Relayer Issues**: Users can directly submit valid data for minting if relayers are unavailable. Security is maintained by a slashing mechanism, with decentralized or permissionless relayers depending on the chain.
## PEG-OUT Process (Sidechain to Bitcoin) 1. **General Mode**: Users initiate BTC transfers back to Bitcoin. The system verifies transactions for legitimacy, preventing fraudulent claims by operators through challenge periods with zero-knowledge proof (ZKP) verifications. 2. **Forced Exit Mode**: If the bridge or operator is down, users can withdraw BTC directly, with protections in place to penalize invalid claims.
## Key Features and Security Levels * **Locked BTC**: Secured with multisignature authorization. * **PEG-IN**: Trust-minimized with light client verification, ensuring permissionless operations. * **PEG-OUT**: Fully trustless and permissionless, with user-centric protections in place. ## Efficiency and Future Enhancements * To reduce transaction times, our ZKP verification layer ensures prompt and final verification, aiming to reduce the current 7-day challenge period to a few hours. * [We are also working to support variable BTC amounts with a new liquidity provider design to increase bridge flexibility.](#user-content-fn-1)[^1] * ... [^1]: revise later # Introduction ## Let's Make BTC Greater Than Ever **Fiamma Bridge** is a **trust-minimized** and **hack-resistant** Bitcoin bridge. * **Trust-minimized**: The bridge ensures security under the assumption that **at least one member of the challenger group remains honest** (1-of-N honesty assumption). Thanks to our permissionless challenger design, N can be large and grow freely. * **Hack-resistant**: The bridge's design makes **stealing assets significantly harder for attackers compared to conventional BTC bridges**, due to ISA (Isolated Safe Architecture). # Trust-Minimized The **Fiamma Bridge** is a revolutionary new solution for cross-chain BTC asset transfer. Unlike traditional multisig bridges, the BitVM2 Bridge achieves: 1. **BTC Safety**: Your BTC stays secure—no one can move it without your approval and signature. 2. **PEG-IN Safety**: Users can mint the exact amount of FiaBTC (tokenized BTC minted via Fiamma Bridge) on a specific destination chain. 3. **PEG-OUT Safety**: Users can withdraw safely from the destination chain at any time, converting FiaBTC into equivalent BTC. 4. **Exactly Pegged Value**: FiaBTC on the destination chain is always backed 1:1 by BTC on Bitcoin, ensuring that FiaBTC : BTC = 1:1. The BitVM2 Bridge minimizes trust assumptions. When bridging BTC to another chain, users no longer have to worry about the security of their locked BTC. Similarly, withdrawing BTC from the other blockchain no longer depends on multisig holders' signatures. ### How Do We Secure Locked BTC? Traditional solution: The **Multisig Committee** controls your BTC, so they **can** spend it without your signature. Innovative solution: **The user and the** **Covenant Committee** control the user's BTC together. Therefore, the committee **can't** spend it without the user's signature.
But, when you want to take your BTC back, you need to trust the Committee as well. How do we solve this problem? **To emulate the OP\_CTV opcode, the user and the bridge committee will pre-sign a few transactions to specify how these BTC could be spent in the future. This feature is enabled by BITVM2.** ### High-Level Summary of PEG-IN (Deposit) and PEG-OUT (Withdrawal) Processes #### **PEG-IN: Moving BTC to the destinatoin chain** 1. Users lock BTC in a multisig address shared with the Bridge Covenant Committee (BCC), ensuring both the users and committee control the BTC together. 2. Pre-signed rules dictate how locked BTC can be spent. 3. Relayer synchronizes Bitcoin block data to the destination chain. 4. Minter verifies the transaction and mints an equivalent amount of FiaBTC on the destination chain for the user. **Key Security Point:** BTC stays in shared custody, and FiaBTC is only minted after a valid deposit is confirmed via Bitcoin consensus and light client verification. #### **PEG-OUT: Moving FiaBTC Back to Bitcoin** 1. Users burn FiaBTC on the destination chain to initiate a withdrawal. 2. The operator validates the burn and pre-pays the equivalent BTC to the user. 3. A kick-off transaction allows the operator to reclaim the locked BTC after a challenge period. 4. Honest operators receive their BTC back; malicious operators are penalized, and challengers are rewarded. **Key Security Point**: Bitcoin itself acts as the final validator, ensuring only valid withdrawals occur, with dispute resolution mechanisms protecting against malicious actions. We only require one honest challenger to initiate a challenge and anyone can become a challenger easily, making the trust assumptions nearly trustless. With significant rewards at stake and a straightforward, permissionless challenge process, rational actors are strongly incentivized to participate. **Bitcoin's dispute resolution capabilities are fundamentally enabled by our implementation of** [**fragmented ZK verifier**](https://x.com/Fiamma_Chain/status/1830824142826086608) **in Bitcoin Script in July 2024, an indispensable and defining module of the BitVM bridge.** # Hack-Resistant While we’re still bridging assets across chains, hackers are already on the other end, siphoning off billions — silently. From [**Ronin** ](https://rekt.news/ronin-rekt)to [**Orbiter**](https://rekt.news/orbit-bridge-rekt), from [**Multichain** ](https://rekt.news/multichain-rekt2)to [**Harmony**](https://rekt.news/harmony-rekt), there’s a new high-profile bridge hack nearly every year. And they all share one terrifying truth: > **Hackers only need a few private keys to drain everything.** These projects had serious teams and funding. So why couldn’t they stop it? Is decentralization on blockchain really this fragile? We analyzed 5 **major bridge exploits** and identified the core vulnerability in traditional multisig systems. ### 5 Real Bridge Disasters: From Phishing to Insider Threats 1. #### **Ronin Bridge｜$625M lost（2022.3）** * Multisig address（5-9 TSS） * Hackers compromised 5 * Attack analysis：[Rekt - Ronin Network - REKT](https://rekt.news/ronin-rekt) 2. #### **Multichain｜130M lost（2023.7）** * Multisig address（Parameters Unknown） * Hackers compromised a critical number of SK shares * Attack analysis：[Rekt - Multichain - REKT 2](https://rekt.news/multichain-rekt2) 3. #### **Harmony Horizon｜100M lost（2022.6）** * Multisig address（2-5 TSS） * Hackers compromised 2 * Attack analysis：[Rekt - Harmony Bridge - REKT](https://rekt.news/harmony-rekt) 4. #### Heco Bridge | 99M lost（2023.12） * Multisig address（Parameters Unknown） * Hackers compromised a critical number of SK shares * Attack analysis：[Rekt - HECO Bridge, HTX - REKT](https://rekt.news/heco-htx-rekt) 5. #### Orbit Bridge | 81.5M lost （2024.1） * Multisig address（Parameters Unknown） * Hackers compromised a critical number of SK shares * Attack analysis：[Rekt - Orbit Bridge - REKT](https://rekt.news/orbit-bridge-rekt) *** What do these bridges have in common? 👉 They all used **multisig**. And while that sounds secure — it’s dangerously misleading. So, we’ve built a **new kind of architecture that makes this entire category of exploit obsolete**. We call it: **Isolated Safe Architecture™.** ### ISA-Based Bridge What Is *Isolated Safe Architecture*? > **Every user’s funds are stored in their own personal “safe”**, co-controlled by **the user + the bridge committee**.
This means: * Each user’s assets are **logically and cryptographically separated** * If a hacker wants to steal User A’s BTC, they **must** compromise User A’s key * Even if the entire committee is compromised, **your BTC stays safe** * To steal all bridge assets, an attacker must breach **every user** + **every committee key** — a practical impossibility That’s why we call it a *“Safe”* — because no one else can get inside **your vault**. We realized the real fix isn’t just “harder locks. It’s making sure **there’s no single vault to drain in the first place**. Fiamma Bridge is fundamentally different from traditional multisig bridges. > In Fiamma, **every deposit is isolated and controlled by a different set of multisig signers**. # Architecture The vision of **Fiamma Bridge** is to build the most secure bridge, enabling BTC users to thrive across every corner of the blockchain world. We aim to achieve this vision through a sufficiently decentralized design, as illustrated in the architecture diagram below.

Bridge Architecture

#### **Bitcoin Model** 1. **BTC Asset Management** * The user's BTC is transferred to a **multi-signature Taproot address**, where the signers are the user and the bridge committee. 2. **BitVM2 Transactions** * Pre-signed transactions that define how the user's BTC can be spent (e.g., for withdrawals or penalties). #### **Destination chain Set (illustratory)** * **EVM-compatible chains**: Ethereum, BSC, Pharos, Base, Arbitrum, etc. * **SVM (Solana Virtual Machine)**: Solana * **Move VM chains**: Sui, Aptos, etc. * **Wasm VM**: Babylon #### **Challenger Group** * A **permissionless** group responsible for detecting malicious operators. #### **Committee Group** * A **permissioned** group that secures the bridge during pre-signing phases. Its roles include: 1. Participating in pre-signing BitVM2 transactions. 2. Distributing rewards to challengers. #### **Operator Group** * Currently **permissioned**, but will transition to **permissionless** in the future. * Facilitates user withdrawals from any sidechain. #### **Fast Processor (FP) Group** * Currently **permissioned**, but will become **permissionless** in the future. * Handles withdrawal requests that cannot be processed directly by the Operator (e.g., partial withdrawals or complex cases). #### **Front-end Model** * **Website**: Users can access the Fiamma bridge via the web interface. * **App**: Users can access the Fiamma bridge through the Fiamma mobile/desktop app. # Fiamma Bridge Status Most of the critical modules are complete and live on mainnet, including the core BitVM2 module and bridge contracts for Ethereum, Aptos, BNB Chain, Sei, and more. We continue to optimize the bridge to improve user experience, security, and trustlessness.
CategoryFeatureImplementation StatusDetails
BitVM2Fraud Proof Module✅ ImplementedOff-chain computation is verified on-chain during disputes.
BitVM2Covenant Emulation✅ ImplementedPre-signed transactions ensure malicious actors are punished permissionlessly.
BitVM2Script Language✅ ImplementedAllows arbitrary computation with Bitcoin Script.
BitVM2

Script Chunking

(< 400K)

✅ ImplementedBreaks computation scripts into smaller chunks.
BitVM2Witness Generator✅ ImplementedGenerates input-output data for each script.
BitVM2Transaction Graph✅ ImplementedPre-signed logic for handling both success and dispute paths.
BitVM2Standard Bitcoin Transactions✅ ImplementedGet rid of centralized trust to Bitcoin Miners
BitVM2Multi-operators✅ ImplementedThe user could always redeem with one operator
BitVM2Permissionless Challengers✅ ImplementedReduce the barrier to becoming a challenger, building the safest bridge
Zero-Knowledge Proofs (ZKPs)Groth16 Verification✅ ImplementedWidely adopted classic ZKP algorithm.
Bitcoin LCBitcoin ZK Light Client✅ ImplementedValidates Bitcoin blocks.
Bitcoin LCReusable Bitcoin Light Client✅ ImplementedDetect the malicious operator
ZK Inclusion ProofsPEG-IN Inclusion Proof✅ ImplementedEnsures user PEG-IN transactions are included in a Bitcoin block.
ZK Inclusion ProofsPEG-OUT Inclusion Proof✅ ImplementedEnsures operator PEG-OUT transactions are included in a Bitcoin block.
FungibilityAnyone Can PEG-OUT✅ ImplementedAny holder of FIABTC can execute PEG-OUT.
FungibilityAny Amount Can Be withdrawn✅ ImplementedUsers can PEG-OUT any amount of FIABTC.
Other FeaturesAmount Checks✅ ImplementedEnsures consistency across Burn, PEG-OUT, and Take transactions.
Other FeaturesReplay Attack Prevention✅ ImplementedBlocks users or operators from using duplicate transactions to steal BTC.
Unhappy PathPost witness on Destination chain✅ImplementedReduce on-chain cost to < $100
Unhappy PathSlashable for challenger✅ImplementedSlashing malicious challengers
Other FeaturesForced PEG-IN Module🔄 Future IterationUsers can mint FIABTC themselves if the Minter faces liveness issues.
Other FeaturesForced PEG-OUT Module🔄 Future IterationAllows users to reclaim locked assets even if operators become inactive.
### Limitation Resolved in v0.2.0 1. Users can PEG-OUT any amounts because we introduced the **Fungibility Provider Module in v0.2.0**. # Core components # Permissionless Mint Trustless Mint implies that users can obtain wrapped BTC (FIABTC) without requiring trust in any intermediary. In our bridge design, we ensure that: 1. FIABTC cannot be over-minted: FIABTC can only be minted through a valid deposit transaction in the Fiamma Bridge, which requires: * Verification of the deposit transaction format * Validation of the deposit transaction by the Bitcoin light client (LC) on the destination chain 2. Users can obtain FIABTC through two methods: * Via the official minter: The official minter can submit the mint request on behalf of users, with users covering the gas fees * Direct minting: If users don't trust the official minter or if the minter fails to process the request within a specified timeframe, users can call the mint function directly by providing valid transaction data Approach 1 offers a better user experience (one-click minting) but requires the official minter to be operational (liveness assumption), while Approach 2 provides a trustless fallback option. We will initially launch Approach 1 and implement Approach 2 in a subsequent upgrade. # Reusable Bitcoin Light Client Each mint request in the minting process must verify the validity of the deposit transaction by querying the Bitcoin Light Client (LC) on the destination chain. Similarly, the withdrawal process requires the Bitcoin LC to validate whether the PegOut transaction is confirmed on the Bitcoin blockchain. Several other projects attempt to implement an off-chain (optimistic) Bitcoin LC, which operates locally with a permissioned challenger set (since constructing a native Bitcoin LC directly on Bitcoin is impossible). In contrast, our approach reuses the alt-chain Bitcoin LC deployed on the destination chain, which features a permissionless challenger set. This means the minting and withdrawal processes share the same Bitcoin LC, hence we call it the **Reusable Bitcoin LC**. The Reusable Bitcoin Light Client offers three key advantages: 1. It maintains the security of the bridge protocol without compromise. 2. The entire protocol remains permissionless, including operators and challengers. 3. It enables fast and low-cost validation of Bitcoin blocks (\~15 seconds on Ethereum at a cost of < 1 USD). In comparison, optimistic Bitcoin LC solutions face impractical challenges—such as generating recursive ZK proofs for the entire Bitcoin chain, which would take weeks (even with ZK-STARKs) and exceed the typical two-week challenge window, making them unsuitable for production. Regardless of the Bitcoin LC implementation, the ultimate goal is for Bitcoin itself to recognize the validity of its blocks. For further details, refer to the **"**[**Destination Chain Awareness**](https://app.gitbook.com/o/pCAnNlKAzOo8rYFBd4MY/s/NaWxhWAPbrPeq8rIwJHB/~/changes/76/our-product-suite/pragmatically-trustless-bitvm-bitcoin-bridge/core-components/destination-chain-awareness)**"** section. # Destination Chain Awareness **It is crucial for Bitcoin to be aware of the state of other chains (e.g., Ethereum). However, due to Bitcoin’s limited programmability, constructing a light client for other chains directly on Bitcoin is impossible.** Fortunately, we’ve discovered that **even without Bitcoin’s native programmability, a secure cross-chain protocol can still be implemented between Bitcoin and other alt-chains**. The key insight is: **if Bitcoin can reliably verify the state of alt-chains, we can integrate this mechanism into our bridge protocol.** #### Atomic Swap protocol Atomic Swap is a **trustless, decentralized cross-chain trading protocol** that enables users to exchange cryptocurrencies across different blockchains **without intermediaries**. It relies on cryptographic primitives like **Hashed Timelock Contracts (HTLCs)** to ensure atomicity—either the entire swap succeeds or nothing happens. **Atomic swaps are easy for users to learn about, as they are a mature protocol widely used in many scenarios,** such as the [Lightning network](https://github.com/lightning/bolts) and [Binance](https://docs.bnbchain.org/). We focus only on the **key element we can reference: the hashlock** (the other component is the timelock, but we won’t explore it here). #### Hasklock A **Hashlock** is a cryptographic construct that restricts access to funds until a predefined condition is met: * A **secret preimage** (`s`) is hashed to produce a **commitment hash** (`H = hash(s)`). * Funds are locked in a script/contract that enforces: * **Unlock condition**: The correct `s` must be revealed to match `H`. #### **How to Achieve Cross-Chain Awareness?** Cross-chain awareness depends on the **leakage of secret `s`**. Bob can obtain secret `s` on Bitcoin only if Alice claims the asset on the destination chain by revealing `s`. Based on this logic, we design the following mechanism: > **"If the operator is slashed on the destination chain, they can also be slashed on Bitcoin (because any challenger can spend the disprove transaction)."** This means that **when the operator is slashed on the destination chain, secret `s` must have been leaked**, allowing any challenger to use `s` to slash the operator on Bitcoin. *** #### **Hashlock-Based BitVM2 Bridge Protocol** The hashlock-based solution enables challengers to easily detect malicious behavior—such as an **invalid Bitcoin block** submitted in a claim. The process consists of two main phases: **1. Pre-Sign Phase** * All challengers generate their own secret value `s_i`. * All challengers submit `H(s_i)` (the hash of `s_i`) to the bridge service. * The bridge service aggregates these hashes into a **Merkle root** and constructs a **Taproot address**, which will be used on both the destination chain and Bitcoin. * The user, operator, and committee pre-sign necessary transactions. > **Note:** Submitting `s_i` is **permissionless**—any challenger can participate.
1. **Challenger Phase** 1. **Challenge Initiation** * Challenger A raises a challenge. 2. **Operator Response** * The operator submits the assert transaction to respond to the challenge. 3. **Slashing Execution** * Challenger B (who may be different from Challenger A) slashes the operator on the destination chain by revealing secret `s_i`. 4. **Disprove Transaction** * Any challenger can then submit the `disprove_2` transaction using `s_i`. > **Note:** The `disprove_2` transaction prevents a malicious operator from withdrawing BTC from the bridge.
**If you want to understand how we prevent challengers from maliciously slashing the operator, please see the section:** [Permissionless slashable protocol](https://app.gitbook.com/o/pCAnNlKAzOo8rYFBd4MY/s/NaWxhWAPbrPeq8rIwJHB/~/changes/76/our-product-suite/pragmatically-trustless-bitvm-bitcoin-bridge/core-components/permissionless-slashable-protocol) # Permissionless Slashable Protocol **Permissionless slashing capability is the most critical feature of the BitVM2 bridge, effectively preventing operator maliciousness.** In the BitVM2 protocol, we prioritize establishing a **permissionless slashing mechanism** for the operator: * If the operator submits an **invalid claim**, slash them permissionlessly. * If the operator **fails to respond to a challenge**, slash them permissionlessly. * If the operator **does not post witness data on the destination chain**, slash them permissionlessly. * If the operator **posts incorrect witness data on the destination chain**, slash them permissionlessly.\ ... We have built a **comprehensive mechanism** to detect and penalize operator misconduct. This design ensures: > **"As long as there is one honest challenger, a malicious operator will be slashed—guaranteeing 100% bridge security."** At the same time, we protect **honest operators**. If the operator acts honestly, they will always receive their BTC. To achieve this, we also implement a **permissionless slashing mechanism for challengers**: * If a challenger **maliciously leaks the secret value `s_i`**, their collateral is slashed permissionlessly on the destination chain (typically in FIABTC). * The bridge committee will then **transfer the BTC to the honest operator**. This ensures that challengers gain **nothing** from: * Submitting a fraudulent `disprove_2` transaction, or * Maliciously leaking the secret value `s_i`. # Consensus Proof It's an important module in BitVM2-based trust-minimized bridge. In this section, we will describe how to check the consensus validity on Bitcoin side. The design is till being optimized. ## Introduction A bridge typically enables asset transfers between two chains. In this discussion, we focus on bridge designs between Bitcoin and a programmable blockchain (e.g., Ethereum, Solana, etc.). The process of moving from Bitcoin to another blockchain is referred to as PEG-IN; conversely, moving from the other blockchain back to Bitcoin is called PEG-OUT. For PEG-IN, trust is placed in the destination chain, as critical modules operate there, including: 1. Building a Bitcoin light client 2. The wrapped/tokenized BTC contract 3. Execution of the minting function For PEG-OUT, we rely on Bitcoin. However, limitations in Bitcoin's programmability prevent direct construction or execution of: 1. A light client for the other chain (we can also call the chain sidechain or side system of Bitcoin) 2. Complex script logic to trigger transactions 3. Data access to verify information validity, such as block header data Additionally, we aim to avoid introducing trust assumptions outside the Bitcoin network. Therefore, PEG-OUT processes are relatively complex. Below is the envisioned final version of the bridge design.
For cross-chain transactions, two key aspects must be ensured: 1. Execution validity: Validity of transaction execution 2. Consensus validity: Validity of the block that includes the transaction For PEG-IN, we use the following methods to ensure these properties 1. Consensus validity: Construct a Bitcoin light client on the sidechain, which adheres to Bitcoin's block verification logic, ensuring block validity 2. Execution validity: The minter provides an inclusion proof to ensure the PEG-IN transaction is contained within a valid block, confirming transaction validity To achieve bridge fungibility for PEG-OUT, we introduce an operator. The normal PEG-OUT process is: 1. The user initiates a burn transaction on the sidechain 2. The operator verifies the burn transaction's validity and initiates the compensated PEG-OUT transaction For these steps, it's crucial to ensure: 1. Consensus validity of the block containing the burn transaction: For POS sidechains, this generally involves checking the coverage of block signers; if they exceed 1/3, the block is considered valid. 2. Execution validity of the burn transaction: The burn transaction is contained within a valid block. 3. Consensus validity of the block containing the PEG-OUT transaction: This mainly involves verifying blockhead linkage and longest-chain verification. 4. Execution validity of the PEG-OUT transaction: The PEG-OUT transaction is included in a valid block. ## Execution Validity and Consensus Validity Achieving execution validity is straightforward, as a transaction inclusion proof (either ZK or Merkle proof) suffices. However, consensus validity is more complex, as verifying block validity generally requires checking the entire consensus process, which is intricate. Therefore, we approach this by analyzing from a verification perspective for POS and POW chains: 1. For POS chains, a block is valid if: 1. The combined voting weight of current block signers exceeds 2/3 of total weight, 2. A subset of signers for the current block are also signers of previous confirmed blocks, with a combined weight exceeding 1/3 of the current block's total weight, 3. Consistency checks between blocks are in place to prevent tampering when validator sets change by more than 2/3. For more details, refer to Succinctlabs' [ZKTendermint](https://github.com/succinctlabs/tendermintx?tab=readme-ov-file). 2. For POW chains, a block is valid if: 1. Blockhead validation: This includes verifying the hash, timestamp, and difficulty adjustment, 2. Longest-chain validation: Ensuring the block is part of the longest chain. See the [ZK Bitcoin Light Client](https://github.com/keep-starknet-strange/raito) repository for more information. ## Chain Proof (Recursive Proof) To verify the state of a chain, one could either re-execute every transaction from the genesis block or verify only block headers; however, both are costly. An ideal approach is to generate a recursive ZK proof for the chain, similar to the Mina blockchain, which uses a fixed-size proof (\~22 KB) to represent the latest chain state. Thus, verifying the latest proof alone confirms the entire chain's validity. For PoS chains, we only need to encapsulate the logic described in the previous section on "how to ensure the validity verification of PoS chain blocks" into a ZK circuit. By combining this with the proof's verification process into a recursive circuit, we can, similar to Mina, verify the chain's validity through the latest proof, thereby ensuring block validity and achieving consensus validity verification. For POW chains, beyond simply building a recursive circuit, we also need to address the longest-chain problem. In POW chains, "orphaned blocks" (blocks that pass all checks but are not accepted by the network) can occur. Transactions in these blocks are re-added to the mempool to be mined again. Assuming confirmation after K blocks for validity, proof of block N's validity requires providing the recursive proof for block N+K. ## Explanation on the public input of recursive proof Recursive proofs possess excellent compression properties; the size of the proof is constant. However, a downside is that as the number of recursions increases, the size of the public input also increases linearly. The linear increase in public input affects: 1. The dynamic changes in scripts, leading to the transformation of taproot addresses; 2. This implies more data is disclosed on Bitcoin, gradually increasing costs.
Solutions: 1. Increase hash circuits on the prover's side, using only the hash output as the public input. This ensures the proof size remains constant while also stabilizing the size of the public input.
2. K-depth confirmation: To ensure the verification of the longest chain, it is necessary to ensure that there are K blocks following a given block.This requires us to consistently make the current block and the information of the k-th block publicly available as public info for verification in scripts to check if a block has K confirmations (Check height\_k - height\_0 = k). (This is a requirement for the prover to set the information of the last K blocks as public input attributes.)

Assume K=3

## Proof Aggregation In the bridge design, consensus validity and execution validity are verified with separate proofs, yet these two characteristics are inherently linked by the requirement for consistent blockhead information. If verified independently, the bridge design faces issues such as: 1. Doubling total script size, 2. Doubling total script chunk count, 3. Increased data disclosure in the happy path, raising costs, 4. Increased data disclosure in the unhappy path, raising challenge costs. Proof aggregation addresses these issues by verifying both proofs in a single step, removing the above challenges. Notably, mature proof aggregation methods currently use the SNARK algorithm, as folding-based approaches are not yet commercially available. # Fungible Withdrawal It's an important module in BitVM2-based trustless bridge design. In this section, we will describe how to support fungible withdrawal. It should be noted that the design still being optimized. ## Overall flow
There are 4 scenarios that we have to consider: 1. Normal case: Mike could PEG-OUT successfully with 10 BTC 2. Abnormal case 1: The amount that Jane wants to PEG-OUT exceeds the maximum value (102 BTC > 100 BTC) 3. Abnormal case 2: The amount that Bob wants to PEG-OUT doesn't exist currently (0.5 BTC does not exist) 4. Abnormal case 3: Some wrapped BTC were transferred to the Burn address (0.5 BTC in the Burn address) Then how can we solve these problems? ## Abnormal case 1 This case could be easily solved. We set up the maximum limitation for the PEG-IN process. But maybe one user on the sidechain might get more wrapped BTC and then plan to PEG-OUT. So, for this case, the user has to PEG-OUT all the wrapped BTC with a few separate transactions.
However, we will provide an additional approach (liquidity provider) to improve the user experience.
So, in this approach, the user could directly peg-out with the help of LP (liquidity provider). The LP should get more fees and the users should pay it. ## Abnormal case 2 Ideally, we hope that the amount distribution between bitcoin and sidechain should be like this:
In this scenario, everyone could PEG-OUT smoothly. But in the real case, most of the amount is not the same
To solve this problem, we use a few ways: 1. Support a wider range of amount types; 2. Introduce the roles of liquidity providers-- they could get some tokens and additional fees as rewards;
There is a little difference between Abnormal Case 2 and Abnormal Case 1. In Abnormal Case 2: the user does not need to pay additional fees for the LP In Abnormal Case 1: the user does need to pay additional fees for the LP Now, the overall flow should be like in the following picture:
## Abnormal case 3 If there is some wrapped BTC transferred to a burn (black hole) address by accident. This means that there will be some BTC locked in Bridge. The good thing is that the LPs can also help users take BTC back only if they can provide proof to prove that they really transferred some wrapped BTC to this address.
In this case, we have to ensure the burn address is a black hole address, like the 0x00...000 address. ## Forced exit module with fungible case In the normal case, the receiver (operator) is deterministic at the pre-signed phase and each operator will maintain a transaction list (all transactions that the receiver is himself) to know how much BTC he can take. For example: Operator A could take 100 BTC Operator B could take 50 BTC It means there are 150 wrapped BTC in the sidechain total, but now operator A is offline. So for operator B, it could only pay 50BTC. For other users, they can not PEG-OUT successfully unless Operator A is online again. To solve this problem, we introduce the forced exit module for users. The general idea is the user will pre-sign a few additional transactions with the bridge committee but not specify the receiver (SIGHHASH\_NONE). But the condition is, that the user has to provide a valid proof for the burn transaction, otherwise, he cannot take the BTC back
A more radical approach: In the normal case, the receiver (operator) is non-deterministic at the pre-signed phase and all operators share a common BTC pool they can take. For example: Operator A could take 100 BTC Operator B could take the same 100 BTC as well So the advantage is that only one operator is honest. All users could peg out smoothly But let's assume all operators are offline, we should support forced exit module as well.
# Multi-Operators The operator's primary role is to assist users in redeeming BTC by fronting their own BTC to complete the payment, then permissionlessly claiming the locked BTC that was secured by the user during the pre-signed phase. Since users depend on operators for BTC redemption, having multiple operators ensures the bridge's liveness. As long as at least one operator remains active, users can successfully redeem their BTC.

Multi-operators

When a user deposits BTC into the Fiamma Bridge, the funds are transferred to a Taproot address jointly controlled by the user and the bridge committee. The user, bridge committee, and operator then collaboratively pre-sign a set of transactions that define how operators can later claim the BTC. If multiple operators are involved, the user and bridge committee pre-sign these transactions individually with each operator. This ensures that any operator can initiate a redemption, but only one can successfully complete it—preventing double-spending while maintaining redundancy. This multi-operator design guarantees service availability: if one operator goes offline, others can still process redemptions, ensuring users can always retrieve their BTC. To learn more about running an operator node, please check: [https://app.gitbook.com/o/pCAnNlKAzOo8rYFBd4MY/s/NaWxhWAPbrPeq8rIwJHB/\~/changes/65/our-product-suite/pragmatically-trustless-bitvm-bitcoin-bridge/user-guides/testnet-beta/how-to-run-an-operator](/our-product-suite/pragmatically-trustless-bitvm-bitcoin-bridge/user-guides/testnet-beta/how-to-run-the-fiamma-operator) # Permissionless Challenger The Fiamma Bridge operates under a fundamental trust assumption: **at least 1 out of N challengers must be honest**. This means the larger the value of **N**, the more secure the bridge becomes. Although the challenger role is permissionless, we strive to minimize barriers to entry to encourage broad participation. By ensuring a large and diverse pool of challengers (**N**), we enhance the bridge’s security, making Fiamma the safest Bitcoin bridge. To achieve this, we’ve designed the permissionless challenger system with three key principles: **1. Accessibility** * **Easy to Run**: We provide a user-friendly challenger frontend for seamless operation. For details, refer to the [Challenger Guide](/our-product-suite/pragmatically-trustless-bitvm-bitcoin-bridge/user-guides/testnet-beta/how-to-run-a-challenger). * **Low Capital Requirements**: * **Collateral**: Only **0.0001 BTC**. * **Challenge Cost**: At most **0.001 BTC** per challenge. **2. Incentives** * **Regular Rewards**: Challengers earn rewards for verifying each proof submitted by operators. * **High Stakes Rewards**: If a challenger successfully identifies and slashes a malicious operator, they can earn up to $**1,000**. By combining low entry barriers with strong incentives, we foster a robust and decentralized challenger network, ensuring the highest level of security for users. # Security analysis **All roles in the bridge that are asset-related are highly concerned about the security of their funds.** Next, we will analyze each asset-linked role in the bridge to ensure participants can properly evaluate security before engaging with the system. The key roles include: * **Users** * **Operators** * **Fungibility Providers (FPs)** * **Challengers** # Operators The Operator plays a crucial role in the BitVM2 Bridge. They advance BTC payments to users from their own funds, then reclaim equivalent BTC that was locked by other users after a fixed challenge period. Below, we explain this process in detail to demonstrate how Operators function within the bridge and clarify the underlying trust assumptions. ## Deposit Phase The deposit process consists of two steps: 1. Transfer: The user initiates a deposit transaction, transferring BTC to a taproot address. This address is jointly controlled by both the user and the committee. 2. Pre-sign: The user, committee, and operator collaboratively pre-sign a set of transactions that define the spending rules for this address. These include: 1. Claim transaction: The operator initiates this transaction to reclaim BTC after completing payment to the user. 2. Challenge transaction: A challenger submits this transaction if they identify malicious activity by the operator. 3. Assert transaction: The operator uses this transaction to respond to any challenges. 4. Happy take transaction: When no challenges are raised, the operator submits this transaction to reclaim BTC while collecting the service fee. 5. Unhappy take transaction: If a challenger acts maliciously, the operator submits this transaction to reclaim BTC while collecting both the service fee and challenge fee. 6. Disprove transaction: If the operator is proven malicious, they fail to reclaim BTC and forfeit their staked amount.
* How is the Operator's BTC utilized in the deposit phase? The Operator uses their UTXOs to pre-sign the claim transaction. The primary purpose of these UTXOs is to cover at least the gas fees for either the happy path or unhappy path scenarios. This process is illustrated in the following diagram.
The fixed setup amount is currently 10,000 sats, supporting a maximum feerate of 10 sats/vbyte. **These UTXOs remain entirely under the operator's control**. To enable parallel processing of multiple deposits, the operator must maintain a sufficient quantity of independent UTXOs at all times. Maintaining an adequate number of UTXOs ensures operators can consistently deliver optimal user experiences. To facilitate this, we've implemented an automated solution that helps operators maintain the required UTXO balance
The process follows a straightforward design. Each PegIn operation consumes one UTXO while generating either one or two new UTXOs for the PegIn address. These newly created UTXOs can then be directly utilized for subsequent PegOut operations. This mechanism has demonstrated reliable performance during our beta testnet phase.
* How much does the operator need to prepare for the PegIn address? Ideally, the more UTXOs, the better. This means that even if transaction numbers increase rapidly in a short time, there will be no negative impact on user experience. Our bridge can also function properly when operators don't maintain too many UTXOs (or too much BTC), as we have permissionless operators. Each subset of them can handle deposits separately. Generally, we provide operators with several options, ranging from 2,000 UTXOs to 10,000 UTXOs. If an operator chooses to start with 2,000 UTXOs, they only need to prepare 0.2 BTC for the PegIn address. If an operator selects 10,000 UTXOs, they need to prepare 1 BTC. Obviously, more UTXOs provide more yield opportunities. We won't cover this here; you can read about operator yield.In summary, for the deposit phase, the operator needs to: 1. Prepare between 0.2 to 1 BTC to support multiple PegIn processes simultaneously 2. Maintain full self-custody of these BTC ## Withdrawal Phase The withdrawal process includes 2 steps: **PegOut process** In this step, the operator needs to maintain a PegOut address that is separate from the PegIn address for better UTXO management. Note that the operator retains full control of the PegOut address. When a user submits a withdrawal request and Operator A accepts it, Operator A must: * Pay the user in advance using their own BTC * Verify the request's validity before processing the payment The key validation checks include: * Confirming the burn transaction's validity on the sidechain * Determining whether another operator has already processed this request The following diagram illustrates how we address these requirements.
1. User burns FIABTC on Ethereum and specifies both the receiver address and the operator. 2. The bridge sends this request to the specified operator. 3. The operator program handles the checking process automatically. If there is an error, the program refuses to handle it. * By adopting this approach, the operator doesn't need to trust anything but themselves. **Claim process** When the operator isn't concerned about the payment process, their next priority is how to reclaim BTC permissionlessly. Remember that during the deposit phase, the user, operator, and committee pre-signed transactions specifying how the operator can reclaim BTC. These transactions are utilized in this phase. Now, we can state that the sole requirement for reclaiming BTC is that an honest operator must provide valid proof for the PegOut transaction. We'll demonstrate how the operator can reclaim BTC in various scenarios.
* Happy case: all challengers are honest
1. After the operator successfully pays the user, the operator generates proof to confirm completion of the payment process. 2. The operator stores the proof in the claim transaction, initiating the challenge period. We set this challenge period to 6 block time because our design ensures sufficient active challengers (a significant improvement over traditional solutions). 3. Since the proof is completely valid, no challenger raises a challenge, allowing the operator to reclaim the BTC after the challenge period expires.
* Unhappy case: One of the challengers is dishonest
1. After the operator successfully pays the user, the operator generates proof showing completion of the payment process. 2. The operator stores the proof in the claim transaction, starting the challenge period. We set this period to 6 block time because our design ensures sufficient active challengers (a significant improvement over traditional solutions). 3. A **dishonest challenger** attempts to raise a challenge to block the operator from reclaiming BTC. However, since the operator is honest and the challenger cannot provide evidence of malicious activity, **the challenge fails**. 4. The operator submits the Assert transaction to respond to the challenge. 5. After a shorter challenge period, the operator submits the unhappy take transaction to reclaim BTC. * Edge case: The operator can still get BTC We would say that our solution is a 100% operator-friendly solution. The reason is that even if there is a potential bug in the challenger process, the operator could still get BTC back. It benefits from our reward mechanism design. To let all challengers who raise challenges get rewards, we improved the reward mechanism in the original BitVM bridge design. In the original design, the challenger who sends the challenge tx won't get a reward, and only the one who sends the disprove tx can get a reward directly. This design discourages challengers from raising challenges when the operator is malicious. So in our design, the reward will be transferred to the committee. The committee will deliver the reward to all challengers. We think it's better than the previous design because we can ensure all members who help slash malicious operators will get rewards, even if it means trusting the committee. For challengers, getting a reward with trust > getting no reward. The reason why the operator could benefit from it is that when the operator is honest but a malicious challenger slashes the operator successfully, the operator could appeal to the committee, because BTC is transferred to the committee. Our committee members will be our important partners, such as our lead investors, ecosystem partners, etc. They would be willing to transfer BTC to the operator in order to maintain the bridge's operation. \ In summary, during the withdrawal phase, the operator will: 1. Maintain full control of their BTC in the PegOut address 2. Reclaim BTC permissionlessly as long as they remain honest. They only need to trust the Bitcoin network. ## Setup Phase In the setup phase, the operator only needs to stake 0.1 BTC as collateral in a taproot address. This taproot address has 2 spend paths: 1. operator\_pk + hash timelock: 100% controlled by the operator, but with a timelock, meaning that when the timelock expires, the operator can spend it permissionlessly 2. operator\_pk + committee: pre-signed with the disprove tx. This ensures that when the operator is malicious, the collateral will be slashed permissionlessly # Users **Security is the top concern for BTC bridge users, which is why we built Fiamma Bridge—a trust-minimized and hack-resistant BTC bridge designed to drastically reduce (or even eliminate) security risks for users.** When using a bridge, users primarily care about three questions: 1. **Is the BTC held in a centralized manner?** 2. **Can I trustlessly bridge to another blockchain?** 3. **Can I trustlessly redeem my BTC?** Below, we address each question in detail. *** #### 1. Is the BTC held in a centralized manner? **No.** Fiamma Bridge adopts an **ISA (Interactive Signature Aggregation) architecture.** * User BTC is **not** controlled by a single address or a fixed multisig address, but by **dynamic multisig addresses**, significantly reducing hacking risks. * In traditional single-sig or fixed multisig setups, if hackers (or malicious insiders) obtain enough private keys, **all bridge assets can be stolen.** * With dynamic multisig, **such attacks are 100% prevented** because: * The **user themselves is one of the signers**, and the other signers (e.g., the Bridge Committee) are counter-parties. * For example: * User A’s BTC is co-controlled by User A + the Bridge Committee. * User B’s BTC is co-controlled by User B + the Bridge Committee. * **No overlap exists between users’ signing groups.** * Even if the Committee turns malicious, they **cannot steal User A’s BTC without User A’s signature**—a fundamental difference from traditional bridges. * For technical details, see: Hack-Resistant Design. *** #### 2. Can I trustlessly bridge to another blockchain? **Yes.**\ Take bridging to Ethereum as an example: * Fiamma’s bridge smart contract consists of two parts: 1. **Bitcoin Light Client Contract** (verifies BTC transactions). 2. FIABTC **Contract** (mints 1:1 pegged wrapped BTC). * The `mint` function in FIABTC is designed for permissionless execution—**anyone can mint FIABTC by submitting valid proof** (e.g., a Merkle proof of their BTC deposit). **Implementation Roadmap:** * **Phase 1 (Initial):** * The `mint` function is guarded by an **Owner**, who must verify and submit a valid Bitcoin transaction to mint FIABTC. * Users rely on the Owner’s **liveness** but are protected from arbitrary minting (the Owner cannot inflate FIABTC supply). * **Phase 2 (Permissionless):** * Users can **self-submit Bitcoin transaction proofs** to mint FIABTC **without trusting any third party.** * This method is more secure but requires extra user effort (e.g., signing and submitting mint transactions). * **Hybrid Approach:** * Fiamma will **combine both methods**: Users can either wait for the Owner or **trigger minting themselves if the Owner is unresponsive.** *** #### 3. Can I trustlessly redeem BTC? **Not yet, but minimal trust is required.** * Users currently depend on the **liveness of the Operator Group** (at least one Operator must be online to process withdrawals). * **Operators are permissionless and economically incentivized**: * Many Operators exist in the network, competing to serve users for rewards. * Users only need to trust that **one honest Operator is online during withdrawal.** * **Future Work:** * Fiamma is researching ways to **eliminate Operator dependency entirely**, enabling fully trustless redemptions. Feasibility is under evaluation. # Challengers The **larger the challenger group**, the **more secure the bridge becomes**. The challenger role is **permissionless**—anyone can become a challenger by running the designated [challenger program.](/our-product-suite/pragmatically-trustless-bitvm-bitcoin-bridge/user-guides/testnet-beta/how-to-run-a-challenger) Challengers interact with the bridge’s funds in two ways: 1. **Staking** 2. **Rewards** **1. Staking (Self-Custodied & Time-Locked)** * Challengers stake their own BTC in a **self-custodied** manner. * The staked funds are locked in a **timelocked UTXO**, which can only be withdrawn **after the timelock expires** (typically **3–12 months**, matching the challenger’s tenure). * Once the timelock ends, challengers can **permissionlessly reclaim their BTC** without relying on any third party. **2. Rewards (Distributed by the Committee)** * When a challenge succeeds: * The **operator’s slashed collateral** is transferred to a **committee-controlled address**. * The committee then **distributes rewards** to participating challengers based on their contribution. # Fungibility Provider **The primary role of FP (Fungibility Provider) is to facilitate BTC redemptions that cannot be directly handled by Operators.** Here's why: * Operators can only process withdrawals within specific amount ranges. * When a user's redemption request falls outside these limits, **FPs advance the BTC payment to the user immediately**. * Later, when FPs accumulate enough small withdrawals to form a processable batch, **they reclaim the BTC through Operators**.
After FPs advance BTC to users, they must redeem the BTC themselves. In this scenario, **FPs assume the same role as bridge users**, following identical trust assumptions during redemption. (Refer to the [*User*](https://app.gitbook.com/o/pCAnNlKAzOo8rYFBd4MY/s/NaWxhWAPbrPeq8rIwJHB/~/changes/71/our-product-suite/pragmatically-trustless-bitvm-bitcoin-bridge/security-analysis/users) section for details.) **Note:** Users are required to pay an additional service fee to FPs for this convenience. # Cost analysis Coming Soon # Yield opportunities # Operator (APY > 10%) #### APR Formula $$ APR = \[\frac {(A + r\*A \* x)}{16} \*\frac{365}{x+1}] \* 100% $$ \ A: Represents the profit on the first day r: The proportion of recyclable funds, with a value range of \[0,1] x: Denotes number of days, with a range of \[1,364] r\*A: represents the daily profit after the first day, assuming each subsequent day's earnings are r of the first day's A + r\*A \* x: represents the total profit over x+1 days \frac{365}{x+1}: represents the number of such profit cycles within 365 days 16: denotes 16 sBTC in principal #### How to calculate A 1. Revenue 1. Deposit Revenue 1. Fee rate> 8: 660 sats per Deposit transaction 2. Fee rate < 8: 330 sats per Deposit transaction 2. Withdrawal Revenue: 1. 0.15% of advanced payment amount 2. 1000 × Feerate: Real-time Bitcoin network fee rate 2. Expenditure 1. Fund Recovery Cost 1. Maximum Claim+Happy Take transaction size: 1. 586 vbytes + 420 vbytes = 1006 × Feerate 2. Minimum Claim+Happy Take transaction size: 1. 300 vbytes + 420 vbytes = 720 × Feerate \ Define: a The number of deposit transactions b The number of withdrawal transactions v The volume of withdrawal requests f\_p The average feerate of withdrawal requests f\_{ch} The average fee cost of claim transaction and happy take transaction\ Then, we calculate $$ A = (660 \* a + b \* 1000 \* f\_p + v \* 0.0015) - b\*f\_{ch} $$ #### Why do yields (A) decrease in subsequent days? On Day 1, the Operator's principal remains 100% available, resulting in the highest yield rate on this initial day. From Day 2 onward, only redeemed funds become recyclable for reuse. We assume an average daily capital recovery rate of 10%, which is then redeployed (note: compound interest effects are excluded from this calculation due to multiple yield-impacting factors, hence APY computation is not considered here).
The 10% figure is a hypothetical value, with the actual ratio being influenced by multiple factors: 1. Bitcoin Network Congestion 1. High congestion may reduce the Operator's capital recovery rate to near 0% 2. Under low-congestion conditions, 100% recovery becomes achievable 2. Fee Rates of Claim & Happy Take Transactions 1. If the Operator's preset fee rate (determined during the deposit phase and immutable) falls below current network rates: 1. Recovery requires waiting until network fees drop to the preset level 3. User-Specified Fee Rates 1. Operators typically select recovery fee rates ≤ users' specified rates to avoid losses 2. When user-specified rates are significantly below current network fees: 1. Recovery timelines extend proportionally #### APR Trend Chart Since the Operator cannot initiate the next round of services only after 100% of the funds have been recovered, a dynamic fund recovery process is a more reasonable method for calculating the Operator's APR. We selected several different sets of values to demonstrate the changing trend of the Operator's APR. **A = 0.2， r = 0.1 and r = 0.05** The yellow line represents a daily recovery rate of r = 0.05, corresponding to an ultimate annualized yield of APR = 24%. The green line represents a daily recovery rate of r = 0.1, corresponding to an ultimate annualized yield of APR = 46.75%.
**A = 0.2, r = 0 and r = 1** We present the APR yields under two extreme scenarios, which determine the upper and lower bounds of the Operator's APR. The yellow line represents a daily recovery rate of r = 0, corresponding to an ultimate annualized yield of APR = 1.25%. The grey line represents a daily recovery rate of r = 1, corresponding to an ultimate annualized yield of APR = 456.25%.
**APR > 5%, r = ？** Considering that most real-world BTC annual yields are below 5%, we calculate the required recovery rate r for which APR > 5%.
According to calculations, when A = 0.2 and r = 0.009, the Operator's APR = 5.345%. This requirement is highly achievable in practice. With an initial principal of 15 BTC, a daily refund of just 0.135 BTC (15×0.009) from Day 2 onward would suffice to maintain an APR above 5%. # Challenger Fiamma Bridge provides sustainable yield opportunities for challengers, enabling us to reduce the challenge period to just a few hours. ## **Current Reward Structure (Beta Phase)** \ While specific reward amounts are still being finalized during our Beta testnet phase, we can outline the yield sources: 1. **Proof Verification Rewards** * Challengers automatically verify proofs submitted by operators. * If no disputes are raised, challengers receive regular rewards in tokens and a share of protocol fees. * *This incentive mechanism is foundational to Fiamma's security model.* 2. **Malicious Operator Challenges** * If a challenger successfully identifies and challenges a malicious operator, they can claim a substantial reward (up to 1 BTC, based on the current 1 BTC operator collateral). * With a challenge cost of only \~0.001 BTC, this represents a potential **1000X Return on Takedown (ROT)**. ## **Why This Matters** \ By aligning incentives—through both routine verification rewards and high-value malicious actor bounties—we ensure:\ ✓ Continuous network vigilance\ ✓ Economically sustainable security\ ✓ Industry-leading risk/reward ratios for participants *Full reward parameters will be announced upon mainnet launch. Follow our updates for details.* # Fungibility Provider Coming soon # User Guides In the following tutorials, you will learn how to interact with the Fiamma Bridge, the first trust-minimized Bitcoin Bridge powered by BitVM2. # Mainnet This section contains tutorials for mainnet: 1. Fiamma Bridge 2. Fiamma Challenger 3. Fiamma Operator # Fiamma Bridge ### Introduction * This guide shows how to complete deposit and withdrawal on the Fiamma Bridge. *** ### **Prerequisite** * You'll need wallets that support Bitcoin, EVM or Aptos network. * You should have native BTC or FIABTC in the wallet. *** ### Deposit > Transfer BTC from Bitcoin to another chain. 1. Connect your Bitcoin wallet and the destination chain wallet.
2. Enter the recipient's address in the designated field. > If you have connected to a destination chain wallet, an autofill option will appear below the text field.
3. Enter deposit amount from `0.0002` to `3 BTC` .
4. Check the Deposit Summary pop up. Once confirmed, hit deposit to submit this transaction.
5. Sign **deposit transaction** in your BTC wallet. You will also sign **pre-sign take transactions** simultaneously, which will be used to pay back to Operator when they finish **withdraw** operation.
6. Your deposit has been submitted. You can then see the deposit progress in the progress page.
7. Check all your transaction history by clicking the history button.
8. Once the deposit is complete, check your bridged FIABTC on destination chain wallet. 1. Import FIABTC token for each destination chain. Enter the token contract address for each chain in your wallet: 1. Ethereum: 0x22F0E0a4c97ff43546dad16d43Ef854C773F0e08 2. Aptos: 0x75de592a7e62e6224d13763c392190fda8635ebb79c798a5e9dd0840102f3f93 3. Sei, Core, Arbitrum, BASE, Polygon, Unichain, Plume: 0x60C230c38aF6d86b0277a98a1CAeAA345a7B061F 4. BSC: 0xafB253A80CEb3d1a5eeF3994C0d1C92c2f027524 5. HyperEVM: 0x0CEDa114F533D540c8aF2AeB52942c1a4A0B1e86
2. FIABTC will appear in your wallet.
*** ## Withdraw 1. Connect EVM-compatible wallets (e.g., Metamask) or Aptos wallets (E.g., OKX Wallet).
2. Fill out the recipient address on Bitcoin. > If you have connected to a BTC wallet, an autofill option will appear below the text field.
2. Enter withdraw amount from `0.0002` to `3 BTC` .
3. Check the Withdraw Summary pop up. Once confirmed, hit withdraw to submit this transaction.
4. Sign Burn Transaction in your EVM wallet.
5. You can also check the withdraw status under bridge history.
* Click on one of the transactions to see details.
# Fiamma Challenger ### Introduction * Fiamma Challenger is a permissionless role that allows anyone to help monitor bridge operators. * A challenger can initiate a challenge if the operator acts maliciously, and will be rewarded upon a valid submission. * You need to have a Bitcoin wallet, and stake 0.0001 BTC to become a challenger. ### Get started 1. Connect your Bitcoin wallet to get started.
2. Stake 0.0001 BTC as security deposit to become a challenger. (If a challenger is found to act maliciously, the security deposit will be slashed to punish such behavior.) Wait for several minutes for the staking to be processed.
3. Once the staking completes, click the "Verify" button to start your challenger role. The challenger app will automatically verify proofs from transactions.
### Submit a Challenge If an operator acted maliciously (e.g., tried to steal user's funds by submitting fake proofs), the bridge will send out challenge tasks to challengers. You will see the challenge task pop up in the Total Challenged section: * Note: you'll need to prepare for 0.001 BTC to submit a challenge.
1. Click the red pop up button to enter Challenge page. Here you will see all challenges listed on the left.
2. Click one of the challenges to see the details. Each challenge task has two stages. You may be assigned to any one of them, while the other one can be completed by different challengers. Click "Submit Challenge" to submit this challenge to the bridge.
Once successfully submitted, you will see a Submit Challenge Success notification on the top right.
Note: Since the same task is sent to all challengers, **only** the first valid submission will count as successful. If another challenger submits before you, your submission will not be accepted.
# Fiamma Operator This guide explains the setup, operating and maintenance of Fiamma Operator for Linux on mainnet. ### **System Requirements** * Linux Distribution: Ubuntu 20.04 LTS or later (recommended), CentOS 8+ * Architecture: x86\_64 (AMD64) * CPU: 4+ cores (8+ recommended for production) * RAM: 96GB minimum (96GB+ recommended) * Storage: 100GB SSD minimum (500GB+ recommended) * Network: Stable internet connection with low latency *** ### **Funds Tiers** * Fiamma Operator uses a 6-tier system determined by an operator's total deposited funds. * Higher tiers support larger transaction amount and earn higher rewards. | Tier | Total Funds | Supported Txn Range | Pegin Funds | Pegout Funds | Staked Funds | | ------- | -------------------------------- | ----------------------------- | -------------------------------------------- | ------------------------------------------ | ----------------------------------------------- | | Purpose | Total BTC needed for an operator | User deposit & withdraw range | Funds used for pre-sign deposit transactions | Funds used to prepay withdraw transactions | Security deposit to precent malicious behaviors | | L0 | 1.5 BTC | 0.001 BTC | 0.15 BTC | 1.1 BTC | 0.1 BTC | | L1 | 2.5 BTC | 0.001 BTC \~ 0.01 BTC | 0.15 BTC | 2.11 BTC | 0.1 BTC | | L2 | 3.5 BTC | 0.001 BTC \~ 0.05 BTC | 0.15 BTC | 3.112 BTC | 0.1 BTC | | L3 | 5.5 BTC | 0.001 BTC \~ 0.2 BTC | 0.15 BTC | 5.113 BTC | 0.1 BTC | | L4 | 10.5 BTC | 0.001 BTC \~ 1 BTC | 0.15 BTC | 10.1135 BTC | 0.1 BTC | | L5 | 15.5 BTC | 0.001 BTC \~ 3 BTC | 0.15 BTC | 15.1136 BTC | 0.1 BTC | *** ### Tutorials **See the tutorials below on running Fiamma Operator:** 1. [Install Operator](/our-product-suite/pragmatically-trustless-bitvm-bitcoin-bridge/user-guides/mainnet/fiamma-operator/1.-install-operator) 2. [Start Operator](/our-product-suite/pragmatically-trustless-bitvm-bitcoin-bridge/user-guides/mainnet/fiamma-operator/2.-start-operator) 3. [Maintenance](/our-product-suite/pragmatically-trustless-bitvm-bitcoin-bridge/user-guides/mainnet/fiamma-operator/3.-maintenance) # 1. Install Operator This section explains how to install and configure the environment for Fiamma Operator. # 1. Prepare the environment 1. **Clone the Repository** Clone the repository to your local machine: ``` git clone https://github.com/fiamma-chain/operator_for_linux.git cd operator_for_linux ``` *** 2. **Prepare the Environment** Run the setup script to install all dependencies and prepare your environment: ``` ./setup.sh ``` **Important:** After the first execution of `setup.sh`, you need to enable the Rust environment variables: ``` source "$HOME/.cargo/env" ``` Alternatively, you can restart your terminal or run: ``` source ~/.bashrc # or if you're using zsh: source ~/.zshrc ``` **This script will:** * Install required packages (build-essential, gcc, g++, libssl-dev) * Install and configure PostgreSQL * Install Docker and Docker Compose (if not already installed) * Install Rust and SQLx CLI * Create a default .env file from .env\_example * Start database and Redis containers * Set **execute permissions** on scripts *** 3. **Database Setup** Run database migrations to set up the required database schema: ``` cd dal && cp .env.example .env && sqlx migrate run && cd .. ``` # 2. Configure and Set Up 1. **Prepare Addresses** * Prepare **3 BTC + 1 EVM addresses** to process transactions: | Address Type | Main Address (BTC) | Pegin Address (BTC) | Pegout Address (BTC) | Ethereum Address | | ------------------------- | ------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------ | | Purpose | | The address responsible for processing deposit transactions | The address responsible for processing withdraw transactions | Operator staking address on the EVM chain. | | `.env` file configuration | BITVM\_BRIDGE\_OPERATOR\_AUTH\_SK | BITVM\_BRIDGE\_OPERATOR\_PEGIN\_SK | BITVM\_BRIDGE\_OPERATOR\_PEGOUT\_SK | BITVM\_BRIDGE\_OPERATOR\_ETH\_SK | {% hint style="info" %} Please use p2tr type addresses for BTC addresses {% endhint %} * Note: These private keys are essential for the Operator to function correctly and **should not be the same**. * You can obtain FIABTC through deposits on the bridge: \[] *** 2. **Configure Environment Variables** * Edit the \`.env\` file and set the following important keys: ``` vim .env ``` Update these four required private keys: ``` BITVM_BRIDGE_OPERATOR_AUTH_SK=your_auth_private_key BITVM_BRIDGE_OPERATOR_PEGIN_SK=your_pegin_private_key BITVM_BRIDGE_OPERATOR_PEGOUT_SK=your_pegout_private_key BITVM_BRIDGE_OPERATOR_ETH_SK=0xYourEvmPrivateKey ``` These private keys are essential for the Operator to function correctly and **should not be the same**.
### Enhance Security (Optional) For better security, use **GPG-encrypted private keys**. See the \[[GPG encryption setup](https://github.com/fiamma-chain/operator-release/tree/main/operator_for_linux#start-with-gpg-encrypted-private-keys-via-gpg-agent-cache)] in the operator-release repository for details. # 2. Start Operator This section explains how to start, register, and stake funds to run the Fiamma Operator. # 1. Start the Operator **Option 1: Standard Startup** Run the start script to set up and start the Operator as a system service: ``` ./start_operator.sh ``` This script will: * Create a systemd service for the Operator * Configure it to run in the current directory * Start the service and verify it's running * Set up appropriate logs *** **Option 2: Advanced Startup (GPG-Encrypted Keys)** For enhanced security with **GPG-encrypted keys**: ``` chmod +x ./start_operator_encrypt.sh ./start_operator_encrypt.sh ``` * Note: GPG-encrypted startup requires additional setup. See the \[[GPG encryption guide](https://github.com/fiamma-chain/operator-release/tree/main/operator_for_linux#start-with-gpg-encrypted-private-keys-via-gpg-agent-cache)] for complete instructions. # 2. Service Management * View Status ``` sudo systemctl status fiamma-operator ``` * View Logs ``` tail -f .logs/bitvm-operator/bitvm-operator.$(date +%Y-%m-%d).log ``` * Restart the Service ``` sudo systemctl restart fiamma-operator ``` * Stop the Service ``` sudo systemctl stop fiamma-operator ``` # 3. Register If you have already completed registration, you can skip this section. 1. **Get Invitation Code** * Please contact Fiamma personnel to obtain your exclusive invitation code `invite_code`. *** 2. **Get Main Account Public Key** * The main address's public key is required for registration: ``` cd operator_for_linux ./bcli operator -n mainnet derive-key -s ``` Use `public_key` to complete the registration process below. *** 3. **Register as an Operator** Execute the following command in the terminal to register as an operator: ``` ./bcli operator -n mainnet register --invitation-code --main-address --pegin-address --pegout-address --public-key --evm-address ``` # 4. Stake Funds After the Operator program starts running, stake BTC as security deposit to start processing transactions. Operator can unstake the BTC if they behave properly (not acting maliciously and stealing users' funds). Follow these 3 steps to complete staking: 1. **Transfer Funds** Transfer sufficient BTC to the operator's main address, at least `stake_amount` + `dust` + `gas` BTC. * `stake_amount` is 0.1 BTC. *** 2. **Stake Funds** When the operator's main address has enough BTC for staking, and the EVM address has enough FIABTC for gas fee, execute the following command to complete staking: ``` ./bcli operator -n mainnet stake ``` * Alternative command using **nohup** (recommended for stability): * If you want to run the staking process in the background to avoid terminal disconnection issues, use the following commands: {% stepper %} {% step %} Start the staking process with nohup: ``` nohup ./bcli operator -n mainnet stake > stake.log 2>&1 & ``` {% endstep %} {% step %} Get the process ID (will be displayed after running the command): * The system will show something like: `[1] 12345` (where 12345 is the process ID) {% endstep %} {% step %} Monitor the progress in real-time: ``` tail -f stake.log ``` {% endstep %} {% step %} Check if the staking process is still running: ``` ps aux | grep "bcli operator" ``` {% endstep %} {% endstepper %} *** 3. **Check Staking Status** Check staking status: ``` ./bcli query -n mainnet stake -a ``` When the staking status shows **committee\_signed**, wait for the stake transaction to be confirmed on the blockchain (about 10 minutes), then you can check the operator status: ``` ./bcli query -n mainnet operator -a ``` If the `status` is `Active`, it means the operator has completed the staking process and has started working. # 5. Monitor Operator Status **Monitor your operator status through:** * Service logs: `tail -f .logs/bitvm-operator/bitvm-operator.$(date +%Y-%m-%d).log` * System status: `sudo systemctl status fiamma-operator` * Operator dashboard (if available) # 3. Maintenance Check the following pages for details on operator status and maintenance. 1. Query Operator Status 2. Upgrade 3. Pause and Quit 4. Troubleshooting # 1. Query Operator Status Query operator status and performance with these commands. ### Query Processing Statistics View operator stats, including daily and weekly task counts: ``` ./bcli query -n mainnet processing-stats -i ``` This command shows: * Daily processed transactions for the past 7 days * Total processed pegin and pegout counts * Weekly new task stats * Current pending tasks ### Query Pending Tasks View queued pegin tasks: ``` ./bcli query -n mainnet pending-pegin -i ``` View queued pegout tasks: ``` ./bcli query -n mainnet pending-pegout -i ``` These commands display pending tasks with their IDs, amounts, and last updated time. ### Query Operator Yield View operator yield from completed tasks: ``` ./bcli query -n mainnet earnings -i ``` This command displays: * Total earnings (in satoshis) * Today's earnings * Monthly earnings # 2. Manage the Operator Program **View Status** ``` sudo systemctl status fiamma-operator ``` #### **View Logs** ``` tail -f .logs/bitvm-operator/bitvm-operator.$(date +%Y-%m-%d).log ``` #### **Shut Down Operator Service** The operator service will finish all pending transactions before it fully shuts down. ``` sudo systemctl stop fiamma-operator ``` #### **Restart Operator Service** ``` sudo systemctl restart fiamma-operator ``` #### Stop the Service ``` sudo systemctl stop fiamma-operator ``` # 2. Upgrade To upgrade your Fiamma Operator to the latest version, follow these steps: ### Step 1: Verify Database Status Ensure the database Docker container is running: ``` sudo docker ps | grep postgres ``` ### Step 2: Pull Latest Updates Pull the latest code from the repository: ``` git pull ``` ### Step 3: Update Database Schema Run database migrations to apply any schema changes: ``` cd dal && sqlx migrate run && cd .. ``` ### Step 4: Restart the Operator Service Restart the Fiamma Operator service to apply updates: ``` sudo systemctl restart fiamma-operator ``` ### Step 5: Verify Upgrade Check that the operator is running correctly after the upgrade: ``` sudo systemctl status fiamma-operator ``` **Note**: Always backup your data before performing upgrades, especially in production environments. # 3. Pause and Quit If an operator wants to stop receiving new tasks, the operator can execute the following command to pause receiving new pegin and pegout tasks, but will continue to finish already received tasks. ``` ./bcli operator -n mainnet pause ``` \ To resume and start processing new tasks, execute the following command: ``` ./bcli operator -n mainnet resume ``` \ If you want to permanently quit the operator role, execute the following command to submit a quit operator request. This process may take a while. **Keep the Fiamma Operator running** to complete all pending pegin and pegout tasks. Once the bridge confirms that all pending pegin and pegout tasks are completed, it will automatically broadcast the operator’s unstake transaction. ``` ./bcli operator -n mainnet unstake -a ``` \ When the operator's status changes to `Inactive`, you can withdraw all funds from the three addresses to an address you assign: ``` ./bcli operator -n mainnet collect-utxos -r ``` > ⚠️ **Important**: Do not execute the `collect-utxos` command while the operator is still active. This command should only be used after the operator has been fully deactivated and all pending tasks have been completed. # 4. Troubleshooting If you encounter issues while running the Operator: 1. Verify the database and Redis are running: ``` sudo docker ps | grep postgres sudo docker ps | grep redis ``` 2. Check the `.env` file to make sure environment variables are set correctly. 3. Make sure the operator binary has **execute permissions**: ``` chmod +x fiamma-operator ``` 4. Review the logs for detailed error messages: ``` tail -f .logs/bitvm-operator/bitvm-operator.$(date +%Y-%m-%d).log ``` # Testnet Alpha ## Function and Limitation ### Function 1. Support Ethereum Holesky Testnet 2. Support **ANY** `PEG-IN` amount. 3. Support Fungible `PEG-OUT`. 1. User can transfer `mamaBTC` to anyone. 2. User can `PEG-OUT` varying amounts of `mamaBTC` to Bitcoin. ### Limitation 1. Limited `PEG-OUT`amount: `0.00001sBTC to 0.0001sBTC` This limitation applies only to the Testnet, as the Operator must pre-fund users with her own`sBTC.`We can remove this restriction once we acquire more sBTC from liquidity providers or market makers. 2. The `PEG-OUT` amount cannot be arbitrary. Currently, users can only `PEG-OUT` amounts that are included in the valid PEG-IN amount list. ## What's Next? 1. Users can `PEG-OUT` any `mamaBTC` amount in a specified range. 2. After integrating ZK light clients into the bridge, we can enable anyone to become an operator. 3. We aim to enable Bitcoin to bridge seamlessly to a wider range of blockchains. # How to Deposit and Withdraw on Fiamma Bridge? Prerequisite To begin, you'll need wallets that support EVM-compatible and BTC addresses, along with the corresponding test tokens. * Bitcoin Signet * Wallet: [Unisat](https://unisat.io/) (others coming soon) * Faucet: * Ethereum Holesky Testnet * Wallet: [Metamask](https://metamask.io/) and others * Faucet: ## How to Deposit > Transfer sBTC from Signet to Holesky Testnet. 1. Connect Bitcoin Wallet - Unisat
Please note that we only support Native Segwit and Taproot address types in alpha-testnet.
2. Enter amount within `0.00001 ~ 0.0001sBTC`(Due to current liquidity constraints in our operator, we have implemented a temporary limit on amounts. We anticipate increasing these limits.)
3. Please enter the recipient's address in the designated field, ensuring it is an ERC20-compatible address from the Holesky network. > Or just conneting with the Metamask, which will autofill the address.
4. Confirm and hit deposit
5. Sign `PEG-IN` (Deposit) Transaction and pre-sign Take Transactions, which is prepared to pay back for Operator when they finish `PEG-OUT` (withdraw) operation.
6. It will then proceed with processing. 7. Check your deposit (Peg-in) status by clicking the deposit transaction.
8. Check your bridged BTC (mamaBTC) on Sidechain wallet. 1. Add mamaBTC **`0x5636bB012F5176d75755691B623236971126Fdac`** on Metamask 2. Check the amount.
## How to `PEG-OUT` 1. Connect EVM-compatible wallets (e.g., Metamask)
2. Select `PEG-OUT` Amount (We will bring in external liquidity provider to achieve fully flexible amount in the future.)
3. Fill out the recipient address on Bitcoin.
4. Confirm and Withdraw 1. Withdraw
b. Confirm Withdraw and Sign Burn Transaction
5. Processing. 6. Check your PEG-OUT (withdraw) status in history. > This process may take 10-20 minutes to be confirmed on the Signet.
# Testnet Beta ### Function Update The Beta Testnet introduced three major updates for the bridge: * Introduced two new roles: public operators and challengers * Supported wider transaction range: `0.001 - 3 sBTC` * Supported depositing to multiple chains: Ethereum Holesky, Plume, Monad, and more coming. **Public Operators:** Individuals and institutions can apply for the operator roles in Beta Testnet. Multiple operators can help guarantee bridge service availability, and ensure a smooth bridging experience by fronting sBTC (native BTC during mainnet) to users during withdrawal. **Challengers:** They ensure the operator's honest behavior; anyone can permissionlessly become a Challenger. If an operator tries to steal user funds, challengers can dispute the transaction directly on Bitcoin. Bitcoin will be the ultimate judge to punish malicious operators directly. # Copy of How to Deposit and Withdraw on Fiamma Bridge? **Prerequisite** To begin, you'll need two wallets that support EVM-compatible and BTC addresses, along with the corresponding test tokens. * Bitcoin Signet * Wallet: [Unisat](https://unisat.io/), [OKX](https://web3.okx.com/), [Bitget](https://web3.bitget.com/en), [Xverse](https://www.xverse.app/) * Faucet: * Ethereum Holesky Testnet * Wallet: [Metamask](https://metamask.io/) and others * Faucet: ### How to Deposit > Transfer sBTC from Signet to another chain (e.g., Ethereum Holesky). 1. Connect Bitcoin Wallet
Please note that we only support Native Segwit and Taproot address types in beta-testnet.
2. Connect EVM Wallet (Optional)
3. Enter the recipient's address in the designated field. > If you have connected to an EVM wallet, an autofill option will appear below the text field
4. Enter deposit amount from `0.001` to `3 sBTC`
5. Check the Deposit Summary pop up. Once confirmed, hit deposit to submit this transaction.
6. Sign Deposit Transaction in your BTC wallet. You will also sign pre-sign Take Transactions simultaneously, which will be used to pay back to Operator when they finish Withdraw operation.
7. Your deposit has been submitted. You can then see the deposit progress in the new page.
8. To see all transaction history, click on the account icon on the top right of the screen, and select bridge in the sub-menu.
8. Once the deposit is complete, check your bridged BTC (FiaBTC) on destination chain wallet. 1. Import FiaBTC token for each destination chain. Enter the token contract address for each chain: 1. Ethereum Holesky: `0xD32B4fB574a3cCEB3576350D8A0e9011507F79d2` 2. BSC Testnet: `0x44F28b1dF5dE81D934272229498959A95d6a6264` 3. Monad Testnet: `0x859fb36f3Fe7e22b37dd99b501f891377DdC9c33` 4. Pharos Testnet: `0x40e75eF8Ea38A1e1362edD88234D327e14533992` 5. Plume Testnet: `0xd922BB00C0f7F555655e7c9e38D70E5636e6C615`
2. Check the amount in your wallet.
## How to Withdraw 1. Connect EVM-compatible wallets (e.g., Metamask)
2. Fill out the recipient address on Bitcoin. > If you have connected to a BTC wallet, an autofill option will appear below the text field
2. Enter Withdraw amount * The bridge supports two modes: Express mode and Custom mode. * Express mode: Faster but with limited amount options. Pick the closest amount you entered to withdraw. * Custom mode: Withdraw any amount you entered.
3. Check the Withdraw Summary pop up. Once confirmed, hit withdraw to submit this transaction.
4. Sign Burn Transaction in your EVM wallet.
5. You can also check the Withdraw status under bridge history. > This process may take 10-20 minutes to be confirmed on the Signet.
* Click on one of the transactions to see detailed progress.
# How to run the Fiamma Operator? We offer two options for running the Fiamma Operator: 1. **On a Mac** * Read [Operator for Mac](/our-product-suite/pragmatically-trustless-bitvm-bitcoin-bridge/user-guides/testnet-beta/how-to-run-the-fiamma-operator/operator-for-mac) for tutorial 1. **On Linux (Cloud platform)** * Read [Operator for Linux](/our-product-suite/pragmatically-trustless-bitvm-bitcoin-bridge/user-guides/testnet-beta/how-to-run-the-fiamma-operator/operator-for-linux) for tutorial # Operator for Mac This doc will explain how to install and run Fiamma Operator on a Mac. To become a bridge operator, contact the Fiamma team to obtain an **invite code** to get started. **Mac Requirement:** * 16GB memory * 256GB storage * Since the Operator app will be running 24-7, we highly recommend using an idle Mac (not your daily-use computer) **Key steps:** 1. [Install the Fiamma Operator app](/our-product-suite/pragmatically-trustless-bitvm-bitcoin-bridge/user-guides/testnet-beta/how-to-run-the-fiamma-operator/operator-for-mac/1.-install-fiamma-operator-app) 2. [Register](/our-product-suite/pragmatically-trustless-bitvm-bitcoin-bridge/user-guides/testnet-beta/how-to-run-the-fiamma-operator/operator-for-mac/2.-register) 3. [Deposit and Stake BTC](/our-product-suite/pragmatically-trustless-bitvm-bitcoin-bridge/user-guides/testnet-beta/how-to-run-the-fiamma-operator/operator-for-mac/3.-deposit-and-stake-btc) 4. [Start Operator, pause Operator](/our-product-suite/pragmatically-trustless-bitvm-bitcoin-bridge/user-guides/testnet-beta/how-to-run-the-fiamma-operator/operator-for-mac/4.-start-and-pause-operator) 5. [Quit Operator and Withdraw Funds](/our-product-suite/pragmatically-trustless-bitvm-bitcoin-bridge/user-guides/testnet-beta/how-to-run-the-fiamma-operator/operator-for-mac/5.-quit-operator-and-withdraw-funds) # 1. Install Fiamma Operator App ### Steps Overview 1. Download the Operator package 2. Open the Operator App 3. Wait for some time as the app initializes and sets up the required environment. A Docker will be installed in the background to keep Operator app running.
# 2. Register ### **Sign up / Sign In** After the app finishes set up, you will see a Sign up/Sign in page asking you to provide the referral code. Enter the **6-digit referral code** you obtained from the Fiamma team.
**a) Sign Up** If you're entering this referral code for the first time, the Operator app will generate three wallet addresses to process transactions. * Main address: The address operator deposits funds to * Deposit address: The address responsible for processing deposit transactions * Withdraw address: The address responsible for processing withdraw transactions Please make sure to click the "Export Keys" button, and securely save your recovery phrase.
**b) Sign In** If you've registered before, simply import your secret recovery phrase to access your account.
After you have finished Sign up/Sign in, you will see the main interface of the Operator app:
# 3. Deposit and Stake BTC Deposit sufficient amount of BTC (sBTC for testnet) to help process transactions. An operator is required to stake 1 BTC as a security deposit before processing transactions (the 1 BTC is time-locked and self-custody, kept under operator's address). If an operator is found acting maliciously (e.g. attempting to steal funds), the deposit will be slashed as a penalty. The deposit can be unstaked when the operator chooses to exit. Here's how to deposit and stake: 1. **Deposit Funds** Click the **+** button next to Total Balance to deposit funds. Wait for around ten minutes for the deposit to be received. To successfully complete the staking, you need at least `stake_amount` + `dust` + `gas` BTC. > Currently for beta testnet, `stake_amount` is 1 sBTC, so deposit at least 1.00001 sBTC to the address. Since subsequent work requires 12 sBTC, we recommend an operator to deposit at least 13.00001 sBTC initially. Note: Fiamma Operator is running on **Bitcoin Signet** during testnet. Please deposit **sBTC** to continue.
2. **Stake Funds** When the operator's main address has sufficient BTC, click the "Start operator" button. If you haven't staked funds before, an interface will pop up with the Stake button. Click the button to stake 1 BTC and wait for the transaction to be processed:
# 4. Start & Pause Operator After the staking is complete, click the "Start operator" button again to start processing transactions officially. You will be asked to enter the minimum and maximum supported transaction amount. Enter the number and click confirm, and the Operator app will start to process deposit and withdraw transactions automatically. You can see your yield in the Total Balance section.
A status bar will show up while the app is running, revealing the number of ongoing transactions at the current moment. You can click the drop down arrow to see each ongoing transaction:
To pause the Operator and stop accepting new transactions, simply click the "|| Operator" button. * Note that the app will finish all the remaining transactions before completely pausing. Please **do not shut down the app** before all transactions are complete. # 5. Quit Operator and Withdraw Funds ### Quit Operator role If you want to permanently quit, you need to click the Setting button, and click the "Quit Operator" button at the bottom.
A pop up will show up asking for your confirmation. Click "Confirm" to officially quit the Operator role. The app will finish all the remaining transactions and unstake your security deposit.
### Withdraw funds After you quit the Operator role, you can now withdraw your security deposit and your funds to an address you assigned. Click the **-** button to transfer all your funds.
# Operator for Linux This doc will explain how to install and run Fiamma Operator on Linux. Overview: this doc will explain how to set up and run Fiamma Operator on Linux. To become an Operator, contact the Fiamma team to obtain an`invite_code`to get started. **Key steps:** 1. [Install and set up Fiamma Operator Backend Program](/our-product-suite/pragmatically-trustless-bitvm-bitcoin-bridge/user-guides/testnet-beta/how-to-run-the-fiamma-operator/operator-for-linux/1.-set-up-fiamma-operator) 2. [Start and register](/our-product-suite/pragmatically-trustless-bitvm-bitcoin-bridge/user-guides/testnet-beta/how-to-run-the-fiamma-operator/operator-for-linux/2.-start-and-register) 3. [Deposit and Stake](/our-product-suite/pragmatically-trustless-bitvm-bitcoin-bridge/user-guides/testnet-beta/how-to-run-the-fiamma-operator/operator-for-linux/3.-deposit-and-stake) 4. [Query operator status](/our-product-suite/pragmatically-trustless-bitvm-bitcoin-bridge/user-guides/testnet-beta/how-to-run-the-fiamma-operator/operator-for-linux/4.-query-operator-status) 5. [Manage the Operator Program](/our-product-suite/pragmatically-trustless-bitvm-bitcoin-bridge/user-guides/testnet-beta/how-to-run-the-fiamma-operator/operator-for-linux/5.-manage-the-operator-program) 6. [Upgrade](/our-product-suite/pragmatically-trustless-bitvm-bitcoin-bridge/user-guides/testnet-beta/how-to-run-the-fiamma-operator/operator-for-linux/6.-upgrade) 7. [Pause and Quit](/our-product-suite/pragmatically-trustless-bitvm-bitcoin-bridge/user-guides/testnet-beta/how-to-run-the-fiamma-operator/operator-for-linux/7.-pause-and-quit) 8. [Troubleshooting](/our-product-suite/pragmatically-trustless-bitvm-bitcoin-bridge/user-guides/testnet-beta/how-to-run-the-fiamma-operator/operator-for-linux/8.-troubleshooting) # 1. Set Up Fiamma Operator ### **Steps overview:** 1. Clone the repository 2. Set up the environment 3. Configure environment variables ### **Step 1: Clone the Repository** First, clone the repository to your local machine: ``` git clone https://github.com/fiamma-chain/operator_for_linux.git cd operator_for_linux ``` ### **Step 2: Set up the Environment** Run the setup script to install all dependencies and prepare your environment: `./setup.sh` **Important:** After the first execution of `setup.sh`, you need to enable the Rust environment variables: ``` source "$HOME/.cargo/env" ``` Alternatively, you can restart your terminal or run: ``` source ~/.bashrc # or if you're using zsh: source ~/.zshrc ``` This script will: * Install required packages (build-essential, gcc, g++, libssl-dev) * Install and configure PostgreSQL * Install Docker and Docker Compose (if not already installed) * Install Rust and SQLx CLI * Create a default .env file from .env\_example * Set up database and Redis containers * Grant **execute permissions** for scripts Next, run database migrations to set up the required database schema: ``` cd dal && cp .env.example .env && sqlx migrate run && cd .. ``` ### **Step 3: Configure Environment Variables** * Prepare three BTC addresses to process transactions: * Main address (auth): The address operator deposits funds to * Pegin address: The address responsible for processing deposit transactions * Pegout address: The address responsible for processing withdraw transactions * Note: Please use p2tr type addresses \ Edit the `.env` file: * vim .env Enter the three private keys from your addresses: 
BITVM_BRIDGE_OPERATOR_AUTH_SK=your_auth_private_key
BITVM_BRIDGE_OPERATOR_PEGIN_SK=your_pegin_private_key
BITVM_BRIDGE_OPERATOR_PEGOUT_SK=your_pegout_private_key
* Note: These private keys are essential for the Operator to function correctly and should not be the same. # 2. Start and Register ### Start Operator Run the start script to set up and start the Operator as a system service: `./start_operator.sh` **This script will:** * Create a systemd service for the Operator * Configure it to run in the current directory * Start the service and verify it's running * Set up appropriate logs ### **Register** 1. **Get Main Address Public Key** The main address's public key is required for registration. Here's how to obtain it: ``` cd operator_for_linux ./bcli operator -n beta-testnet derive-key -s ``` Use `public_key` to complete the registration process below. 2. **Register as Operator** Execute the following command in the terminal to register as an operator: ``` ./bcli operator -n beta-testnet register --invitation-code --main-address --pegin-address --pegout-address --public-key ``` # 3. Deposit and Stake Deposit sufficient amount of BTC to help process transactions (sBTC for testnet). The operator is required to stake 1 BTC as a security deposit before processing transactions (the 1 BTC is time-locked and self-custody, kept under operator's address). If an operator is found acting maliciously (e.g. attempting to steal funds), the deposit will be slashed as a penalty. The deposit can be unstaked when the operator chooses to exit. Here's how to deposit and stake: 1. **Deposit Funds** Transfer sufficient BTC to the operator's main address. To successfully complete the staking, you need at least `stake_amount` + `dust` + `gas` BTC. * Note: Fiamma Operator is running on **Bitcoin Signet** during testnet. Please deposit **sBTC** to the main address. > Currently, `stake_amount` is 1 BTC, so deposit at least 1.00001 BTC. Since subsequent work requires 12 BTC, we recommend an operator to transfer at least 13.00001 BTC initially. 2. **Stake Funds** When the operator's main address has sufficient BTC, execute the following command to complete staking: ``` ./bcli operator -n beta-testnet stake ``` Check staking status: ``` ./bcli query -n beta-testnet stake -a ``` Once the staking status shows `committee_signed`, wait around 10 minutes for the transaction to be confirmed on-chain. After that, you can check your operator status: ``` ./bcli query -n beta-testnet operator -a ``` **If the `status` is `Active`, it means the operator has completed the staking process and has started working.** # 4. Query Operator Status Query operator status and performance with these commands. ### Query Processing Statistics View operator stats, including daily and weekly task counts: ``` ./bcli query -n beta-testnet processing-stats -i ``` This command shows: * Daily processed transactions for the past 7 days * Total processed pegin and pegout counts * Weekly new task stats * Current pending tasks ### Query Pending Tasks View queued pegin tasks: ``` ./bcli query -n beta-testnet pending-pegin -i ``` View queued pegout tasks: ``` ./bcli query -n beta-testnet pending-pegout -i ``` These commands display pending tasks with their IDs, amounts, and last updated time. ### Query Operator Yield View operator yield from completed tasks: ``` ./bcli query -n beta-testnet earnings -i ``` This command displays: * Total earnings (in satoshis) * Today's earnings * Monthly earnings # 5. Manage the Operator Program #### **View Status** ``` sudo systemctl status fiamma-operator ``` #### **View Logs** ``` tail -f .logs/bitvm-operator/bitvm-operator.$(date +%Y-%m-%d).log ``` #### **Shut Down Operator Service** The operator service will finish all pending transactions before it fully shuts down. ``` sudo systemctl stop fiamma-operator ``` #### **Restart Operator Service** ``` sudo systemctl restart fiamma-operator ``` #### Stop the Service ``` sudo systemctl stop fiamma-operator ``` # 6. Upgrade To upgrade your Fiamma Operator to the latest version, follow these steps: ### Step 1: Verify Database Status Ensure the database Docker container is running: ``` sudo docker ps | grep postgres ``` ### Step 2: Pull Latest Updates Pull the latest code from the repository: ``` git pull ``` ### Step 3: Update Database Schema Run database migrations to apply any schema changes: ``` cd dal && sqlx migrate run && cd .. ``` ### Step 4: Restart the Operator Service Restart the Fiamma Operator service to apply updates: ``` sudo systemctl restart fiamma-operator ``` ### Step 5: Verify Upgrade Check that the operator is running correctly after the upgrade: ``` sudo systemctl status fiamma-operator ``` **Note**: Always backup your data before performing upgrades, especially in production environments. # 7. Pause and Quit If an operator wants to stop receiving new tasks, the operator can execute the following command to pause receiving new pegin and pegout tasks, but will continue to finish already received tasks. ``` ./bcli operator -n beta-testnet pause ``` \ To resume and start processing new tasks, execute the following command: ``` ./bcli operator -n beta-testnet resume ``` \ If you want to permanently quit the operator role, execute the following command to submit a quit operator request. This process may take a while. **Keep the Fiamma Operator running** to complete all pending pegin and pegout tasks. Once the bridge confirms that all pending pegin and pegout tasks are completed, it will automatically broadcast the operator’s unstake transaction. ``` ./bcli operator -n beta-testnet unstake -a ``` \ When the operator's status changes to `Inactive`, you can withdraw all funds from the three addresses to an address you assign: ``` ./bcli operator -n beta-testnet collect-utxos -r ``` > ⚠️ **Important**: Do not execute the `collect-utxos` command while the operator is still active. This command should only be used after the operator has been fully deactivated and all pending tasks have been completed. # 8. Troubleshooting If you encounter issues while running the Operator: 1. Verify the database and Redis are running: ``` sudo docker ps | grep postgres sudo docker ps | grep redis ``` 2. Check the `.env` file to make sure environment variables are set correctly. 3. Make sure the operator binary has **execute permissions**: ``` chmod +x fiamma-operator ``` 4. Review the logs for detailed error messages: ``` tail -f .logs/bitvm-operator/bitvm-operator.$(date +%Y-%m-%d).log ``` # How to run a challenger? ### Prerequisite * Anyone can permissionlessly become a challenger to help monitor bridge operators. * You need to have a Bitcoin wallet in order to become the challenger. ### Get started 1. Connect your Bitcoin wallet to get started
2. Stake sBTC (BTC for mainnet) as security deposit to become a challenger. If a challenger is found to act maliciously, the security deposit will be slashed to punish such behavior.
* Wait for several minutes for the staking to be processed.
3. Once the staking completes, click the "Verify" button to start your challenger role. The challenge app will automatically verify proofs from transactions.
### Submit a Challenge If an operator acted maliciously (e.g., tried to steal user's funds by submitting fake proofs), the bridge will send out challenge tasks to challengers. You will see the challenge task pop up in the Total Challenged section:
1. Click the red pop up button to enter Challenge page. Here you will see all challenges listed on the left. Select one to start the challenge process.
2. Click one of the challenges to see the details. Click "Start Analysis" to analyze the fraudulent proof. An analysis will be generated automatically to indicate the error chunk. Click "Submit Challenge" to submit this challenge to the bridge.
Note: Since all challengers will receive the same challenge task, you need to be the first one to submit the task in order to be considered as successful. If another challenger submitted the task earlier, you won't be able to successfully submit the same challenge.
# Fiamma Layer (BitVM-Powered Settlement Layer) Fiamma Layer is the first-ever implementation of BitVM2, enabling ZK use cases to be verified and settled on Bitcoin for the first time, harnessing Bitcoin's unmatched security. By integrating with Babylon and implementing BitVM2, the verification/settlement layer offers both fast and hard finality, leveraging Bitcoin's robust cryptoeconomic and network security. This is a foundational tool for democratizing Bitcoin security, making it accessible to a broader range of applications and users. # Introduction Please learn more about the key highlights, challenges tackled, and core technologies adopted in Fiamma Layer in this section. # Key Highlights ## **Triple Security Model** \ Bitcoin network security: By implementing BitVM2, Fiamma pioneers in verifying ZK proofs with fraud proofs on the Bitcoin network. Our intersubjective nodes invoke optimistic ZKP verification on Bitcoin to settle disputes if any.\ \ Bitcoin cryptoeconomic security: Secured by Babylon, Fiamma chain leverages the immense cryptoeconomic security of Bitcoin network in ZKP verification in all ecosystems.\ \ Decentralized and permissionless security: Our intersubjective nodes running on mobile devices further decentralize our POS chain and help both Fiamma and Babylon identify intersubjectively attributable faults.\\ ## **Cost-Effective and Instant ZK Verification** Built on Cosmos SDK, Fiamma provides fast proof verification, reducing verification time from hours to seconds, and achieves \~99% cost reduction by checking signatures securely. ## **Universal Compatibility** Designed to be blockchain-agnostic, Fiamma serves as a universal verification layer for ZK applications across various blockchain environments, including both programmable and non-programmable chains. ## **Extending the Functionality of Babylon** Our intersubjectivite node module and capability of verifying ZKP on Bitcoin network by fraud proof can help Babylon offer comprehensive and secure POS services. Currently, Babylon chain can only identify objectively attributable faults like double-sign on the blockchains. With us, Babylon can better unlock the cryptoeconomic security of the 21M BTC. # Challenges Tackled **Centralization of Off-Chain State Verification**: * Fiamma consists of both objective POS node module and intersubjective mobile node module. * The discrepancy between the results of intersubjective and objective node modules would be settled by Bitcoin network via BitVM2. * By this approach, Fiamma eliminates the reliance on a single sequencer, thus preventing a single point of failure and promoting a more democratic verification process. **Latency in On-Chain State Verification**: * Fiamma's design mitigates delays arising from proof aggregation and on-chain delay parameters. We will reduce the time required for each proof verification from hours to seconds. **High Costs of On-Chain State Verification**: * With high costs ranging significantly across different ZK proof algorithms (e.g., Groth at 250,000, Halo2-KZG at 400,000, and STARK-FRI at 1,500,000), Fiamma reduces these expenses by over 99%, making ZK proof verification more accessible. **Limited Compatibility with ZK Verification Algorithms**: * Fiamma is designed to be compatible with a variety of ZK proof algorithms, not just those that are Snark-friendly, thus accommodating a broader spectrum of blockchain applications. **Non-Atomic Cross-Chain Operations**: * Fiamma's infrastructure supports atomic transactions across different blockchains by receiving ZKPs from multiple chains. This ensures that operations are executed correctly and consistently on all involved chains, making Fiamma an excellent infrastructure for building cross-chain ZK bridges. **High Threshold for Validator Nodes**: * By lowering barriers to entry with intersubjective verifiers on mobile devices, Fiamma encourages more diverse and inclusive participation in the network's governance and operation. # Core Technologies Beyond solving existing problems, Fiamma is also poised to drive the industry forward through its innovative features.\ \ **Implementation of BitVM2**\ As the first to implement Fflonk and Groth16 in Bitcoin Script, we are leading the R\&D of BitVM2. BitVM2 secures our ZK verification network, Fiamma, and any integrated ZK use cases with the Bitcoin network. Fiamma leverages the Bitcoin network to settle critical disputes among our intersubjective and objective nodes via BitVM2.\ \ **Modular Design**\ Fiamma's architecture is modular, consisting of distinct but interoperable components for execution, data availability (DA), settlement, and storage, allowing for flexibility and specialization within the network.\ \ **Decentralized Node Design with Low Barriers to Entry**\ By designing a system with low thresholds for node participation, Fiamma opens up the network to a wider community, fostering a more decentralized and resilient ecosystem.\ \ **Universal Verification Network**\ For blockchains with limited programmability, such as Bitcoin, Fiamma offers a foundational layer of functionality, enhancing their capabilities and meeting their base requirements.\ \ For highly programmable chains like Ethereum and Solana, Fiamma serves as a layer that improves user experience (UX), decentralization, and security by offering a more efficient and seamless settlement process secured by Bitcoin network. Fiamma is a universal verification network with high security and decentralization, designed to support the growth of ZK use cases across all blockchain platforms. It is a vital infrastructure for the future of blockchain technology and applications.




# Architecture # General Flow (Soft Finality) Fiamma supports zkp verification of programmable and non-programmable chains This flow represents the process to achieve soft finality for our ZKP verification process, only going through the PoS chain (objective nodes) of our verification layer. # For Programmable Blockchains

Fig1. The general flow of applications on Ethereum

### Components Involved: 1. **Fiamma:** The core network handling the verification of ZKPs. 2. **Data Availability (DA) Layer:** Stores proof-related data securely. 3. **Ethereum:** Executes smart contracts to verify data and signatures. 4. **Check Contracts for Various ZKP Systems:** Includes Boojum, Plonky2, Circle Stark, and others. ### Steps: #### Step 1: Proof Generation and Submission * **ZKP Systems (Boojum, Plonky2, Circle Stark, etc.):** * Various ZKPs are generated by different systems and submitted to the Fiamma network. * **Fiamma:** * **Generate BLS Signature:** Fiamma generates a BLS signature which includes `data_hash`, `proof_hash`, `result`, and `new_state`. #### Step 2: Storing Data in DA Layer * **Fiamma to DA Layer:** * **Send Data:** Fiamma sends the transaction data (`txdata`), proof, and result to the DA layer for storage. * **DA Layer:** * **Store Data:** The DA layer securely stores the received data ensuring its availability and integrity. #### Step 3: Retrieving Data from DA Layer * **DA Layer to Ethereum:** * **Send Tuple Data:** The DA layer sends a tuple of data (`tuple_data{data_hash, proof_hash, result, new_state}`) to Ethereum for further verification. * **Ethereum:** * **Check Contract:** Ethereum smart contracts retrieve and verify the data from the DA layer. The contracts perform checks on `DA Check` and `Sig Check`. #### Step 4: Verification on Ethereum * **Ethereum Smart Contracts:** * **Check Contract Execution:** The smart contracts on Ethereum execute the checks (`DA Check` and `Sig Check`) to verify the data and signatures. * **Final State Update:** Once the checks are successful, the final state is updated on the Ethereum network. # For Non-Programmable Blockchains :

Fig2. The general flow of applications on Bitcoin

#### Components Involved: 1. **Fiamma:** The core network handling the verification of ZKPs. 2. **Data Availability (DA) Layer:** Stores proof-related data securely. 3. **Bitcoin:** Executes scripts to verify data and signatures. 4. **Check Contracts for Various ZKP Systems:** Includes Fflonk, Boojum, Stark, and others. #### Steps: #### Step 1: Proof Generation and Submission * **ZKP Systems (Fflonk, Boojum, Stark, etc.):** * Various ZKPs are generated by different systems and submitted to the Fiamma network. * **Fiamma:** * **Generate Schnorr Signature:** Fiamma generates a Schnorr signature which includes `data_hash`, `proof_hash`, `result`, and `new_state`. #### Step 2: Storing Data in DA Layer * **Fiamma to DA Layer:** * **Send Data:** Fiamma sends the transaction data (`txdata`), proof, and result to the DA layer for storage. * **DA Layer:** * **Store Data:** The DA layer securely stores the received data ensuring its availability and integrity. #### Step 3: Retrieving Data from DA Layer * **DA Layer to Bitcoin:** * **Send Tuple Data:** The DA layer sends a tuple of data (`tuple_data{data_hash, proof_hash, result, new_state}`) to Bitcoin for further verification. * **Bitcoin:** * **Check Script:** Bitcoin executes scripts to verify the data and signatures. #### Step 4: Verification on Bitcoin * **Bitcoin Scripts:** * **Check Script Execution:** The scripts on Bitcoin perform checks on `DA Check` and `Sig Check` to verify the data and signatures. * **Final State Update:** Once the checks are successful, the final state is updated on the Bitcoin network. # ZKP Verification Process The following diagram illustrates the comprehensive workflow of the Fiamma verification layer.

Fig4. Sequence diagram for the Fiamma network

## Components * **Public Chains:** These are the major blockchain networks like Bitcoin and Ethereum, where final transactions and state updates are recorded. * **ZK Apps:** Applications that generate and aggregate Zero-Knowledge Proofs, ensuring privacy and integrity of transactions. * **Objective Nodes:** Nodes participating in the Proof-of-Stake consensus mechanism to validate proofs. * **Intersubjective Nodes :** User-operated nodes run on mobile devices involved in fetching, verifying, and submitting proofs. * **Fiamma Chain:** The core network handling the verification of Zero-Knowledge Proofs built with Cosmos SDK. * **DA :** Data Availability layer that stores proof-related data securely. * **Staking:** Mechanism within the Fiamma ecosystem responsible for staking operations and state updates. * **Finalize:** Finalization layer where transactions and state updates are recorded on the Bitcoin blockchain. ## Workflow Steps **Step 1: Proof Submission and Aggregation** * **ZK Apps:** * Submit individual proofs to the Fiamma network. * **Aggregate Proofs (Optional):** Aggregate proofs before submission to save costs. Note that this can increase the processing time from seconds to hours depending on the situation. **Step 2:Objective Finality and Consensus** * **Objective Nodes (PoS):** * **Begin Objective Finality:** The process to reach consensus on the submitted proofs begins. * **Consensus:** Nodes collaborate to validate the proof, ensuring its accuracy. * **Send Hash, Proof Results, and Multi-Signatures:** The validated proof, along with hash and signatures, is sent to the DA module. * **Fiamma Chain:** * **Return Commitment:** The chain returns the commitment to the data. * **Pre-Sign Asset Transaction:** Prepares to sign the asset transaction for further processing. **Step 3:Data Request and Proof Validation** * **ZK Apps:** * **Request Merkle Proof:** Applications request the Merkle proof to construct transactions sent to the L1 chain. * **Access Proofs:** The requested proofs are accessed for validation. * **Objective Nodes (PoS):** * **Provide Merkle Proof Request:** Nodes process the request for Merkle proofs. * **Access Proof Data:** Data required for proof validation is accessed and prepared. * **Fiamma Chain:** * **Begin Intersubjective Finality:** The process for final validation involving intersubjective nodes **begins.** **Step 4: Intersubjective verification and hard Finality** * **Intersubjective Nodes (User):** * **Verify ZKP:** Nodes verify the Zero-Knowledge Proof. * **If Valid (Happy Path):** If the proof is valid, the result is marked as TRUE. * **Collect Intersubjective Results:** The results from various nodes are collected to confirm the proof’s validity. if the number exceeds the threshold, the proof state will be updated to hard finality. **Step 5: Happy Path** * **Intersubjective Nodes (User):** * **Send Results if TRUE:** If the proof is valid, the results are sent as TRUE. * **Achieve Objective and Intersubjective Finality:** Both objective and intersubjective finality are achieved, confirming the proof’s validity. * **Public Chains:** * **Process Transactions (Soft Finality):** Transactions are processed if the network trusts the soft finality of the proof. * **Fiamma Chain:** * **State Updates:** The chain updates its state, confirming the successful verification of proofs. **Step 6: Unhappy Path (Orange)** * **Intersubjective Nodes (User):** * **If Invalid (Unhappy Path):** If the proof is invalid, the unhappy path is triggered. * **Read Commitments:** Nodes read the commitments to identify discrepancies. * **Send Disputed Sub-Script:** A disputed sub-script is sent for further verification. * **Fiamma Chain:** * **Handle Dispute:** The chain processes the dispute, verifying the invalid proof. * **Initiate Slashing:** Penalizes the involved parties for submitting invalid proofs. * **Babylon Chain:** * **Manage Penalties and Slashing:** Manages the penalties and slashing operations for invalid proofs. * **Bitcoin Chain:** * **Record Commitments and Checkpoints:** Records the necessary commitments and checkpoints for validation. * **Public Chains:** * **Process Transactions (Hard Finality):** Transactions are processed if the network trusts the hard finality of the proof. **Step 7: Finalization and Penalties** * **Fiamma Chain:** * **Ensure Finalization:** Ensures that all processes are finalized, managing stakes and penalties appropriately. * **Bitcoin Chain:** * **Record Timestamps and Checkpoints:** Records final timestamps and checkpoints to validate the process. \***Additional Details:** * **Unhappy Path Handling****:** When an invalid proof is detected (Proof\_0), it follows the "Unhappy Path," triggering the Slash mechanism and involving steps like reading commitments, issuing challenge transactions, and validating through consensus. * **Happy Path Processing****:** Valid proofs follow the "Happy Path," ensuring smooth and efficient processing without triggering penalties. **Here's a table comparing the Happy Path and Unhappy Path in Fiamma's ZKP handling:** | **Aspect** | **Unhappy Path** | **Happy Path** | | ---------------------------- | ----------------------------------------------------------- | -------------------------------------------------------------------- | | **Definition** | Error-handling workflow triggered by invalid proofs | Standard, error-free workflow with valid proofs | | **Proof Submission** | Users submit zero-knowledge proofs to the Fiamma chain | Users submit zero-knowledge proofs to the Fiamma chain | | **Proof Reception** | Proofs are received and processed | Proofs are received and processed | | **Objective Finality** | Invalid proof triggers error handling | Consensus is reached, and proof results are sent to the Fiamma chain | | **Proof Validation** | Invalid proof detected, challenge process is initiated | Proofs are validated, multi-signatures are generated | | **Data Request** | Commitments are read to identify discrepancies | Merkle proof is requested and accessed | | **Intersubjective Finality** | Disputed sub-script is sent for verification | Users verify proofs and confirm validity (results marked TRUE) | | **Consensus Process** | Nodes handle disputes and initiate slashing | Nodes achieve both objective and intersubjective finality | | **State Updates** | State update is paused for further verification | State is updated with validated proofs | | **Commitments Handling** | Invalid commitments handled through dispute resolution | Valid commitments sent to Bitcoin chain | | **Penalty Mechanism** | Slashing mechanism is triggered for invalid proofs | Not applicable | | **Transaction Processing** | Transactions processed if hard finality is trusted | Transactions processed if soft finality is trusted | | **User Notification** | Users are informed of invalid proof and penalties | Users are informed of successful validation | | **Finalization** | Ensures disputes are resolved, and penalties managed | Ensures all processes are finalized and recorded | | **Efficiency** | More complex with additional steps for error handling | Smooth, efficient, and straightforward | | **Outcome** | Invalid proofs lead to penalties and potential delays | Valid proofs lead to state updates and rewards | | **User Experience** | More complex due to error handling and validation processes | Positive, with timely processing | # Ecosystem Layout Fiamma is poised to provide a cheap, timely, and secure verification service for any ZK application or scenario, laying the groundwork for mass blockchain adoption. The low barrier to entry for general nodes, coupled with sustainable and multiple rewards from various ZK use cases, is expected to attract a broader user base to the industry.
#### **New Modularity Era Based on Fiamma** Fiamma ushers in a new era of blockchain modularity: * **Execution Modularity**: Rollups and other layer 2 solutions continue to drive execution off-chain. * **DA Modularity**: With various DA solutions catering to data availability needs. * **Verification Modularity**: Fiamma takes on the verification process, allowing L1 to focus on storage and consensus. * **L1 Simplified Consensus**: L1 nodes no longer perform computational tasks, only verifying DA and L2 state transitions, then executing consensus. #### This modular approach offers two key advantages: * **Cost and Security**: By offloading verification to Fiamma, the process becomes faster and less hardware-intensive, reducing costs and facilitating user access. * **Architecture and Scenario Advantages**: While potentially trading off some security for the sake of architectural benefits, Fiamma's network security is not solely dependent on staking amounts. Our security framework is significantly enhanced by the integration of BitVM2 and the highly decentralized intersubjective nodes. These elements provide an additional layer of security, ensuring robustness and resilience across a wide range of applications. BitVM2 acts as a safety net, guaranteeing security, while the decentralized nature of the intersubjective nodes further strengthens the network’s integrity. # User Guides In this tutorial, you will learn how to interact with the fiamma network. # QuickStart This guide will help you get started with Fiamma Network for ZKP verification. We'll cover the complete workflow from installation to sending verification requests. ## 1. Install Fiamma You can refer to the [Installation](/our-product-suite/bitvm-powered-zkp-verification-layer/user-guides/installation) section to install the fiammad binary program ## 2. Generate Fiamma Address You can refer to the [Add Keys](/our-product-suite/bitvm-powered-zkp-verification-layer/user-guides/manage-keys#list-keys) section to generate a fiamma address ## 3. Get Testnet Token You can refer to the [Get $FIA](/our-product-suite/bitvm-powered-zkp-verification-layer/user-guides/wallet-and-tokens/get-fia) section to get some testnet token ## 4. Submit Proof for Verification Before you can use fiammad cli to submit proof , you need to prepare the proof for testing, and a simple way to do this is to use the [fiamma git repository](https://github.com/fiamma-chain/fiamma/tree/main/prover_examples) provides some test proof files. If you have cloned the fiamma repository as instructed earlier, you can navigate to the root directory of the fiamma repository and then use the script and your previously created account to send transactions quickly. You can also manually construct a transaction to send based on the contents of the submit\_proof.sh script, which works either way ```bash cd fiamma/script/cli ./submit_proof.sh alice ``` ## 5. Check Verification Results After you submit the transaction in the manner described in step 4, you can use the scripts in scirpt/cli to query and verify the results. ```bash ./query_verify_result.sh ``` # Installation In this tutorial, you will learn about the dependencies that need to be installed to run Fiamma. ### Step 1: Install Golang {% hint style="info" %} Fiamma requires Golang [version 1.23.3](https://go.dev/doc/install) for Fiamma to be installed on your system. Install it using the instructions on the provided link. {% endhint %} For Linux server installation of Go language, you can refer to the commands below, and for installation tutorials of Go language on other operating systems, you can refer to the official[ Go language documentation.](https://go.dev/doc/install) ``` wget https://golang.org/dl/go1.23.3.linux-amd64.tar.gz sudo rm -rf /usr/local/go && sudo tar -C /usr/local -xzf go1.23.3.linux-amd64.tar.gz echo 'export GOROOT=/usr/local/go' >> ~/.profile echo 'export GOPATH=$HOME/go' >> ~/.profile echo 'export GOBIN=$HOME/go/bin' >> ~/.profile echo 'export PATH=$PATH:$GOROOT/bin:$GOBIN' >> ~/.profile source ~/.profile ``` After executing the above commands, you should check that the version of go is the same as the required version. 
$ go version
go version go1.22.3 linux/amd64
### Step 2: Build and Install Fiamma You need to clone Fiamma’s GitHub repository to install the `fiammad` executable. 1. Install build requirements ```bash sudo apt-get install -y make git bash gcc curl jq pkg-config openssl libssl-dev ``` 2. Retrieve the Fiamma source code either through the [releases page](https://github.com/fiamma-chain/fiamma/releases) or by cloning the [source code](https://github.com/fiamma-chain/fiamma). 3. Navigate to the directory that contains the Fiamma source code. From there build and install the fiammad executable ```bash git checkout make install ``` 4. Check fiammad command ```bash $ fiammad version ``` {% hint style="info" %} Note! he last command first executes `git checkout` in the specific version that you want to install. Ensure that you install the same version of the Fiamma executable as the one that is running on the network you aim to join. {% endhint %} # Wallet and Tokens In this tutorial, you will learn how to create a fiamma account with keplr wallet and get fiamma testnet tokens! # Connect Keplr Wallet Fiamma Testnet has been integrated with the Keplr wallet! To better manage your fiamma address, you can connect your Keplr wallet by following these steps. {% hint style="info" %} **Note**: We are in the Testnet stage, so the API may undergo incompatible changes in the future. If you encounter any issues, please join our [Discord](https://discord.com/invite/8mCBXXjgvA) to get in touch with the Fiamma Team. {% endhint %} [![Logo](https://assets.website-files.com/61e518f84aa2a6645094f0ad/621751811f62db2c7da50744_Keplr_256.png)Keplr Wallet | First and Leading IBC Wallet](https://www.keplr.app/) ## Add Fiamma Testnet Chain Visit search for "**Fiamma Testnet**" and add it to your Keplr wallet. Add "**Fiamma Testnet**" Chain to Keplr:
## Create a Wallet with Fiamma Address Open the Keplr wallet extension, click the user avatar in the top right corner, and select "**Add Wallet**" on the Select Wallet page. Add Wallet in Keplr:
On the new page, choose "**Create a new wallet**". If you want to import an existing wallet from fiamma-node, please refer to [Manage Keys](/our-product-suite/bitvm-powered-zkp-verification-layer/user-guides/manage-keys). Create a new wallet:
Then follow the steps to sign in and set a custom name for your wallet. In the third step, select the chain for your wallet. Search for "**Fiamma Testnet**" and check the box to confirm. Select "**Fiamma Testnet" Chain**:
You will now see your Fiamma address in the Keplr wallet. To get testnet FIA from our faucet, please refer to [Get FIA](/our-product-suite/bitvm-powered-zkp-verification-layer/user-guides/wallet-and-tokens/get-fia). # Get $FIA The token symbol for the Fiamma testnet is $FIA, and the token's denom value is ufia . 1FIA = 1\_000\_000 ufia Get your testnet token FIA for development and testing {% hint style="info" %} **Note**: We are in the Alpha Testnet stage, so the API may undergo incompatible changes in the future. If you encounter any issues, please join our Discord to get in touch with the Fiamma Team. {% endhint %} In Fiamma DA Alpha Testnet, users can receive FIA tokens through two methods: the Discord channel and the web faucet. Each method has its own limits and conditions, and these two methods are not mutually exclusive. * **Discord Faucet**: Each address/Discord ID can receive **1 FIA** per day, but each address can only claim once every 24 hours. * **Web Faucet**: Each address can receive **0.5 FIA** daily, but each device can only claim once every 24 hours. {% hint style="info" %} **Note**: The tokens of the faucet will dynamically adjust based on supply and demand conditions. The provided tokens should be sufficient to cover gas fees under normal circumstances, so please use them wisely. If you need more FIA, please contact the [Fiamma team](mailto:undefined). {% endhint %} ## Web Faucet The web faucet is available at: . Users can claim 0.03 FIA per day, but each device is restricted to one claim every 24 hours. ## Discord Faucet Join Fiamma discord server by this invitation: [Fiamma Discord](https://discord.com/invite/jTXWxKmG). To request tokens from the Fiamma DA Alpha Testnet Faucet, use the following command in the `#[testnet-faucet]` channel on Fiamma’s Discord server: ``` $request ``` Where `` is a generated address starting with Fiamma. Additionally, you can use the `$balance ` command to check the balance of a specified address and the `$transaction ` command to check the status of a specific transaction (faucet transactions only). # Manage Keys In this tutorial, you will learn how to manage your account using the fiammad command line tool. ## Add Keys {% hint style="info" %} Note! Once your account is created, you must keep your mnemonic phrase safe. If you lose it, you will also lose your assets. {% endhint %} ```bash fiammad keys add --keyring-backend=test ``` A fiamma address will be automatically generated such as: ```json - address: fiammaXXX name: test-alice pubkey: '{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"XXX"}' type: local ``` ## Recover keys ``` fiammad keys add --keyring-backend=test --recover ``` After executing the above command, you will be prompted to enter a mnemonic in the bip39 format After bip39 mnemonic inputed, a fiamma address will be automatically generated such as: ```json - address: fiammaXXX name: test-alice pubkey: '{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"XXX"}' type: local ``` ## List Keys You can use the command below to view the account you just created. ```bash fiammad keys list --keyring-backend=test ``` A fiamma address named with test-alice will be automatically show such as: ``` - address: fiammaXXX name: test-alice pubkey: '{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"XXX"}' type: local ``` ## Export Keys You can use the command below to show the account private key. ```bash fiammad keys export --keyring-backend=test --unarmored-hex --unsafe ``` ## Store Keys in Keplr Wallet Fiamma Testnet has been integrated with the Keplr wallet. Please refer to [Connect Keplr Wallet](/our-product-suite/bitvm-powered-zkp-verification-layer/user-guides/wallet-and-tokens#connect-keplr-wallet) for more details. To better manage your Fiamma address, you can import it into your Keplr wallet by following these steps. Visit the Keplr Chains website at , search for "**Fiamma Testnet**" and add it to your Keplr wallet. Open the Keplr wallet extension and click the user avatar in the top right corner. Select "**Add Wallet**," then choose either "**Import an existing wallet**" or "**Create a new wallet**." Opt for the "24 words recovery phrase" and enter your mnemonic phrase, or opt for the "private key" and enter your unarmored hex private key. Use Recovery Phrase or Private Key to Import Keys into Keplr Wallet:

import-private-key

Set a custom name for your wallet, select "**Fiamma Testnet**" Chain and confirm. Your Fiamma address will now appear in the Keplr wallet extension, ready for receive and send transactions. For more faucet details, please refer to [Get FIA](/our-product-suite/bitvm-powered-zkp-verification-layer/user-guides/wallet-and-tokens#get-fia). \\ # Fiamma Testnet Explorer A temporary Fiamma testnet deployment uses ping.pub to deploy a browser; a dedicated browser for zkp verification is coming soon. After sending transactions to Fiamma Testnet, you can query details and view other various types of information such as Addresses, Blocks, Validators at [**Fiamma Testnet Explorer**](https://testnet-explorer.fiammachain.io/fiamma). # Developer Guides In this tutorial, you will learn about more advanced uses of fiamma. # Network Information Obtain the network information for the current Fiamma Testnet. The latest [testnet information](https://github.com/fiamma-chain/networks/tree/main/fiamma-testnet-1) can be obtained here. # Fiamma CLI The Fiammad Command Line Interface(CLI) allows you to quickly interact with the Fiamma local network or test network. # CLI Command Overview In this tutorial, you will learn about the Command Line Interface(CLI) introduction related to fiammad zkpverify and bitvmstaker. {% hint style="info" %} Note! that the CLI here refers to transactions and queries in the fiamma verification network and doesn't include the regular cosmos application chain. {% endhint %} The Fiamma Command Line Interface(CLI) provides essential commands to manage zero-knowledge proofs and staker accounts, streamlining interactions with the blockchain. Use the commands and options as described to perform operations effectively. Use CLI tools `fiammad` you can: * send **zkpverify transactions** with `tx zkpverify [command] [flags]` and queries with `query zkpverify [command] [flags]` * send **bitvmstaker transactions** with `tx bitvmstaker [command] [flags]` and queries with `query bitvmstaker [command] [flags]` Global Flags usually contains: `--from`, `--chain-id`, `--gas`, `--node`, `--keyring-backend`. command currently support: ## Tx Type CLI **Zkpverify transactions** * [`submit-proof`](#submit-proof) * [`submit-community-verification`](#submit-community-verification) **Bitvmstaker transactions** * [`create-staker`](#create-staker) * [`register-vk`](#register-vk) * [`remove-staker`](#remove-staker) * [`remove-vk`](#remove-vk) * [`update-committee-address`](#update-committee-address) ### **submit-proof** A (zkpverify) operation for verifying a proof by namespace, proof\_system, proof, public\_input and vk. request params: ``` { "namespace": "string", "proof_system": "string", "proof": "string", "public_input": "string", "vk": "string" } ``` ### **submit-community-verification** A community (zkpverify) operation for verifying a proof by proof\_id and verify\_result. request params: ``` { "proof_id": "string", "verify_result": "bool" } ``` ### **create-staker** A committee (bitvmstaker) operation for create a new staker account on the Fiamma blockchain by staker address. request params: ``` { "staker_address": "string" } ``` ### **remove-staker** A committee (bitvmstaker) operation for removing a staker account on the Fiamma blockchain by staker address. This action can be necessary for managing the network's staker list, ensuring that only valid stakers participate. request params: ``` { "staker_address": "string" } ``` ### **register-vk** A committee (bitvmstaker) operation for registering a new verification key (VK) for a specific proof system on the blockchain by verification key. This is essential for validating the correctness of proofs submitted to the network. request params: ``` { "vk": "string" } ``` ### **remove-vk** A committee (bitvmstaker) operation for removing a previously registered verification key (VK) for a specific proof system on the blockchain by verification key. This command is essential for maintaining the integrity of the verification processes by allowing the removal of outdated or incorrect VKs. request params: ``` { "vk": "string" } ``` ### **update-committee-address** A committee (bitvmstaker) operation for updating the address of the committee responsible for overseeing the blockchain operations or specific proof systems. This is crucial for ensuring that the governance structure is current and that the correct addresses are in use for administrative tasks. request params: ``` { "new_committee_address": "string" } ``` ## Query Type CLI **Zkpverify queries** * [`get-proof-data`](#get-proof-data) * [`get-bitvm-challenge-data`](#get-bitvm-challenge-data) * [`get-verify-result`](#get-verify-result) * [`get-verify-results-by-namespace`](#get-verify-results-by-namespace) * [`pending-proof`](#pending-proof) * [`pending-proof-by-namespace`](#pending-proof-by-namespace) **Bitvmstaker queries** * [`all-staker-info`](#all-staker-info) * [`committee-address`](#committee-address) * [`registered-vk-list`](#registered-vk-list) ### **get-bitvm-challenge-data** Query bitVM chanllenge data stored in the fiamma by proof\_id. request params: ``` { "proof_id": "string", } ``` response: ``` { "bitvm_challenge_data": { "proposer": "string", "public_input": "string", "verify_result": "bool", "vk": "string", "witness": "string" } } ``` ### **get-proof-data** Query Proof data stored in the fiamma by proof\_id. request params: ``` { "proof_id": "string", } ``` response: ``` { "proof_data": { "proof_system": "integer", "proof": "string", "public_input": "string", "vk": "string", "namespace": "string" } } ``` ### **get-verify-result** Query Proof verify status stored in the fiamma by proof\_id. request params: ``` { "proof_id": "string", } ``` response: ``` { verify_result: { "proof_id": "string", "proof_system": "string", "data_commitment": "string", "data_location": "string", "result": "bool", "status": "integer", "community_verification_count": "integer", "namespace": "string" } } ``` ### **get-verify-results-by-namespace** Query Proof verify status stored in the fiamma by namespace. request params: ``` { "namespace": "string", } ``` response: ``` { verify_result: [ { "proof_id": "string", "proof_system": "string", "data_commitment": "string", "data_location": "string", "result": "bool", "status": "integer", "community_verification_count": "integer", "namespace": "string" }, ... ] } ``` ### **pending-proof** Queries a list of pending proof verification items. There is no request param for this method. response: ``` { "pending_proofs": [ { "proof_id": "string", "proof_system": "string", "data_commitment": "string", "data_location": "string", "result": bool, "status": "string", "community_verification_count": "string", "namespace": "string" }, ... ], "pagination": { "next_key": "string", "total": "integer" } } ``` ### **pending-proof-by-namespace** Queries a list of pending proof verification items by namespace. request params: ``` { "namespace": "string", } ``` response: ``` { "pending_proofs": [ { "proof_id": "string", "proof_system": "string", "data_commitment": "string", "data_location": "string", "result": bool, "status": "string", "community_verification_count": "string", "namespace": "string" }, ... ], "pagination": { "next_key": "string", "total": "integer" } } ``` ### **all-staker-info** Queries a list of holding information about all the stakers. It may include details such as staker\_index and staker\_address. response: ``` { "all_staker_info": [ { "staker_index": "integer", "staker_address": "string" }, ... ], "pagination": { "next_key": "string", "total": "integer" } } ``` ### **committee-address** Queries the address associated with the committee responsible for overseeing certain operations or governance within Fiamma blockchain system. response: ``` { "committeeAddress": "string", } ``` ### **registered-vk-list** Queries a list of registered verification keys (VKs). response: ``` { "registered_vk_list": [ ["string"] , ... ], "pagination": { "next_key": "string", "total": "integer" } } ``` # CLI Tutorial In this tutorial, you will learn how to use the Fiammad Command Line Interface(CLI) to send requests related to zkpverify. ## Preparations Before you can use CLI, you need to prepare the proof for testing, and a simple way to do this is to use the [fiamma git repository](https://github.com/fiamma-chain/fiamma/tree/main/prover_examples) provides some sample prover code for generating test proof files, which can be used to easily generate test **proof** **public\_input** and **vk**. {% hint style="info" %} Note! Fiamma currently supports zkp authentication with a variety of proofs, the list of supported proofs is shown in[ **Support ProofSystem.**](/our-product-suite/bitvm-powered-zkp-verification-layer/developer-guides/supported-proofsystem) For the **bitvm proof system** , there is currently no open source specific prover, we give a sample generated by our test, soon we will open source bitvm proof system {% endhint %} ### 1. Clone Fiamma Git repository ```bash git clone https://github.com/fiamma-chain/fiamma cd fiamma git checkout ``` ## ZKPVerify Module ### 1. Send your proof to Fiamma network **Submit BitVM proof** The BitVM proof need the proof file, public input file and verifying key file. You may set gas and fees. ```bash fiammad tx zkpverify submit-proof \ --from --chain-id \ --gas --fees \ --node \ --keyring-backend test \ \ \ \ \ ``` The current Fiamma network chain-id is `fiamma-testnet-1`, the namespace is `test-namespace`, the data\_location should be **FIAMMA** , the proof system is **`GROTH16_BN254_BITVM`** or **`FFPLONK_BN254_BITVM`** and the node is . **Example** Proof system use **GROTH16\_BN254\_BITVM**. Send BitVM proof: ```bash fiammad tx zkpverify submit-proof \ --from alice --chain-id fiamma-testnet-1 \ --gas 20000000 --fees 2000ufia \ --node https://testnet-rpc.fiammachain.io \ --keyring-backend test \ "test-namespace" \ "GROTH16_BN254_BITVM" \ ./prover_examples/bitvm/proof.bitvm \ ./prover_examples/bitvm/public_input.bitvm \ ./prover_examples/bitvm/vk.bitvm "FIAMMA" ``` ### 2. Get Proof id When you have finished submitting your proof, there are two ways to query the proof id of the proof you have submitted. * **Get Proof Id by tx event** When you submit a proof, you will receive a transaction hash. Typically, if the transaction is successful, by querying the transaction details using the hash, you can retrieve an event list where you can filter out the **proofId**. ```bash fiammad query tx 65C110AE8E0624AC34CC1F7E36E253B3437B28E008433AE499DEF40D770A1915 --node https://testnet-rpc.fiammachain.io ```

SubmitProof event

* **Get Proof Id by Manual/Code Calculation** The proof id can be calculated from `sha256sum` of proof inputs using shell. It Concatenate the proof system, proof, public input,and vk. ```bash # the proof input files directory is fiamma/prover_examples/bitvm : ${PROOF_FILE:=proof.bitvm} : ${PUBLIC_INPUT_FILE:=public_input.bitvm} : ${VK_FILE:=vk.bitvm} : ${PROOF_SYSTEM:="GROTH16_BN254_BITVM"} : ${NAMESPACE:="test-namespace"} : ${PROOF_SYSTEM:="GROTH16_BN254_BITVM"} NEW_NAMESPACE=$(echo -n $NAMESPACE | xxd -p) NEW_PROOF_SYSTEM=$(echo -n $PROOF_SYSTEM | xxd -p) NEW_PROOF=$(xxd -p -c 256 $PROOF_FILE | tr -d '\n') NEW_PUBLIC_INPUT=$(xxd -p -c 256 $PUBLIC_INPUT_FILE | tr -d '\n') NEW_VK=$(xxd -p -c 256 $VK_FILE | tr -d '\n') # Concatenate the namespace, proof system, proof, public input, and vk allDataHex="${NEW_NAMESPACE}${NEW_PROOF_SYSTEM}${NEW_PROOF}${NEW_PUBLIC_INPUT}${NEW_VK}" echo -n "$allDataHex" | xxd -r -p | sha256sum | awk '{print $1}' ``` ### 3. Submit community verification to Fiamma network The community verification need an proof id and verification result. submit community verification: ```bash fiammad tx zkpverify submit-community-verification \ --from --chain-id \ --gas --fees \ --node \ --keyring-backend test \ \ ``` **Example** You may use the above shell to calculate a proof id, and use fiammad command to sumbit community verification with a verification result. ```bash fiammad tx zkpverify submit-community-verification \ --from alice --chain-id fiamma-testnet-1 \ --gas 20000000 --fees 2000ufia \ --node https://testnet-rpc.fiammachain.io \ --keyring-backend test \ 1776686b821785672155f4f34a0cf0d088e721e3ec5ff32709a7cec1b5a3b669 \ true ``` In addition, we provide shell scripts to make it easier to send these commands. The parameter accepted by the script is account. ```bash // Assuming you are currently in the root directory at fiamma ./scripts/cli/submit_community_verification_bitvm.sh alice ``` ### 4. Get proof data by proof id from Fiamma network You can query proof data stored in the fiamma network by proof id. ```bash fiammad query zkpverify get-proof-data \ --chain-id \ --node \ ``` **Example** ```bash fiammad query zkpverify get-proof-data \ --chain-id fiamma-testnet-1 \ --node https://testnet-rpc.fiammachain.io \ 1776686b821785672155f4f34a0cf0d088e721e3ec5ff32709a7cec1b5a3b669 ``` ### 5. Get bitvm chanllenge data by proof id from Fiamma network You can query bitVM chanllenge data stored in the fiamma network by proof id. ```bash fiammad query zkpverify get-bitvm-challenge-data \ --chain-id \ --node \ ``` **Example** ```bash fiammad query zkpverify get-bitvm-challenge-data \ --chain-id fiamma-testnet-1 \ --node https://testnet-rpc.fiammachain.io \ 1776686b821785672155f4f34a0cf0d088e721e3ec5ff32709a7cec1b5a3b669 ``` ### 6. Get verify result from Fiamma network You can query proof verify status stored in the fiamma network by proof id. ```bash fiammad query zkpverify get-verify-result \ --chain-id \ --node \ ``` **Example** ```bash fiammad query zkpverify get-verify-result \ --chain-id fiamma-testnet-1 \ --node https://testnet-rpc.fiammachain.io \ 1776686b821785672155f4f34a0cf0d088e721e3ec5ff32709a7cec1b5a3b669 ``` ### 7. Get verify result by namespace from Fiamma network You can query proof verify status stored in the fiamma network by namespace. ```bash fiammad query zkpverify get-verify-results-by-namespace \ --chain-id \ --node \ ``` **Example** ```bash fiammad query zkpverify get-verify-result \ --chain-id fiamma-testnet-1 \ --node https://testnet-rpc.fiammachain.io \ "test-namespace" ``` ### 8. Get pending proofs from Fiamma network You can queries a list of pending proof verification items in the fiamma network. ```bash fiammad query zkpverify pending-proof \ --chain-id \ --node ``` **Example** ```bash fiammad query zkpverify pending-proof \ --chain-id fiamma-testnet-1 \ --node https://testnet-rpc.fiammachain.io ``` ### 9. Get pending proofs by namespace from Fiamma network You can queries a list of pending proof verification items by namespace in the fiamma network. ```bash fiammad query zkpverify pending-proof-by-namespace \ --chain-id \ --node ``` **Example** ```bash fiammad query zkpverify pending-proof-by-namespace \ --chain-id fiamma-testnet-1 \ --node https://testnet-rpc.fiammachain.io "test-namespace" ``` ## BitVMStaker Module ### 1. Create a new staker account by staker address You can create a new staker account by staker address in the fiamma network. ```bash fiammad tx bitvmstaker create-staker \ \ --from \ --keyring-backend test \ --chain-id \ --node ``` **Example** ```bash fiammad tx bitvmstaker create-staker \ fiammavaloper1f9t28umy70d8flvms23042ydyky7wvfmalf0yz \ --from dev \ --keyring-backend test \ --chain-id fiamma-testnet-1 \ --node https://testnet-rpc.fiammachain.io ``` ### 2. Get a list of holding information about all the stakers You can query a list of holding information about all the stakers in the fiamma network. ```bash fiammad query bitvmstaker all-staker-info \ --chain-id \ --node ``` **Example** ```bash fiammad query bitvmstaker all-staker-info \ --chain-id fiamma-testnet-1 \ --node https://testnet-rpc.fiammachain.io ``` ### 3. Remove a staker account by staker address You can remove a staker account by staker address in the fiamma network. ```bash fiammad tx bitvmstaker remove-staker \ \ --from \ --keyring-backend test \ --chain-id \ --node ``` **Example** ```bash fiammad tx bitvmstaker remove-staker \ fiammavaloper1f9t28umy70d8flvms23042ydyky7wvfmalf0yz \ --from dev \ --keyring-backend test \ --chain-id fiamma-testnet-1 \ --node https://testnet-rpc.fiammachain.io ``` ### 4. Register a new verification key (VK) You can Register a new verification key (VK) for a specific proof system by vk in the fiamma network. ```bash fiammad tx bitvmstaker register-vk \ \ --from \ --keyring-backend test \ --chain-id \ --node ``` **Example** ```bash : ${VK_FILE:=fiamma-network/fiamma/prover_examples/bitvm/vk.bitvm} fiammad tx bitvmstaker register-vk \ $VK_FILE \ --from dev \ --keyring-backend test \ --chain-id fiamma-testnet-1 \ --node https://testnet-rpc.fiammachain.io ``` ### 5. Get a list of registered VKs You can query a list of registered verification keys (VKs) in the fiamma network. ```bash fiammad query bitvmstaker registered-vk-list \ --chain-id \ --node ``` **Example** ```bash fiammad query bitvmstaker registered-vk-list \ --chain-id fiamma-testnet-1 \ --node https://testnet-rpc.fiammachain.io ``` ### 6. Remove a registered verification key(VK) You can remove a previously registered verification key (VK) for a specific proof system in the fiamma network. ```bash fiammad tx bitvmstaker remove-vk \ \ --from \ --keyring-backend test \ --chain-id \ --node ``` **Example** ```bash fiammad tx bitvmstaker remove-staker \ $VK_FILE \ --from dev \ --keyring-backend test \ --chain-id fiamma-testnet-1 \ --node https://testnet-rpc.fiammachain.io ``` ### 7. Update committee addresses You can update the address of the committee responsible for overseeing the blockchain operations or specific proof systems in the fiamma network. ```bash fiammad tx bitvmstaker update-committee-address \ \ --from \ --keyring-backend test \ --chain-id \ --node ``` **Example** ```bash fiammad tx bitvmstaker update-committee-address \ fiamma1f9t28umy70d8flvms23042ydyky7wvfmjpeuh9 \ --from dev \ --keyring-backend test \ --chain-id fiamma-testnet-1 \ --node https://testnet-rpc.fiammachain.io ``` ### 8. Get the committee address You can query the address associated with the committee responsible for overseeing certain operations or governance in the fiamma network. ```bash fiammad query bitvmstaker committee-address \ --chain-id \ --node ``` **Example** ```bash fiammad query bitvmstaker committee-address \ --chain-id fiamma-testnet-1 \ --node https://testnet-rpc.fiammachain.io ``` # Fiamma-Committee CLI Fiamma Committee CLI is a BTC Staking Command Line Tool for Validator Registration and BITVM2 Challenges on the Fiamma Chain. ## Installation ### From GitHub Releases 1. Visit the [GitHub Releases page](https://github.com/fiamma-chain/fiamma-committee-cli/releases). 2. Download the binary file for your operating system: * Linux x86-64: `fcli-linux-x86-64` * macOS Intel: `fcli-mac-intel` * macOS Apple Silicon (M1/M2): `fcli-mac-arm` * Windows: `fcli-windows.exe` 3. Rename the downloaded file: * On Linux and macOS, rename to `fcli` * On Windows, rename to `fcli.exe` 4. Move the renamed file to a directory in your PATH. For example, on Linux or macOS: ```bash mv fcli-linux-x86-64 fcli # or fcli-mac-intel or fcli-mac-arm chmod +x fcli sudo mv fcli /usr/local/bin/ ``` On Windows, move `fcli.exe` to a directory in your PATH, such as `C:\Windows\System32\`. ### Building from Source To build the CLI from source, ensure you have Rust and Cargo installed. Then follow these steps: 1. Clone the repository: ``` git clone https://github.com/fiamma-chain/fiamma-committee-cli.git cd fiamma-committee-cli ``` 2. Build the project: ``` cargo build --release ``` 3. After building, you can find the binary in the `target/release` directory. ## Usage ### Explanation of All Command Parameters * `--network`: Currently only supports `testnet` network. * `--private-key`: The signet BTC private key used to sign the tx. * `--validator-key`: The new validator address for the fiamma chain, you can get the validator address refer to [become a validator](https://docs.fiammachain.io/our-product-suite/bitvm-powered-zkp-verification-layer/developer-guides/run-a-fiamma-node/become-a-validator). * `--proof-id`: The proof ID for the challenge process, we provide a test proof id `1735e881fa5e58408e4710a4e8cbea0a7995f029eefdf85d7e59775b0b6c44c5`. * `--vk-path`: The path to the verification key for the challenge process, you can obtain it from the fiamma committee cli repository [vk.bitvm](https://github.com/fiamma-chain/fiamma-committee-cli/blob/main/vk.bitvm). * `--circuit-type`: The circuit type used for the challenge process. Currently only supports `groth16`. * `--script-index`:The script index for the BitVM2 challenge program. This value is fixed and cannot be modified at present. * `--reward-address`: The reward signet BTC address for the disprove process, if you challenge success, you will get the reward. * `--txid`: The signet BTC transaction ID for the registration process. * `--vout`: The signet BTC output index for the registration process. you can obtain the txid and vout use the following command: ```bash curl -sSL "https://mempool.space/signet/api/address/{signet_btc_address}/utxo" ``` ### Register as a BitVM2 Staker/Validator To run a Fiamma node as a validator, you must first register as a BitVM2 staker using fcli. The registration process requires executing the following two commands: **1.Start the registration process** ``` fcli register --network testnet start --validator-key --txid --vout --private-key ``` after executing the above command, you will get a registration number, the committee will generate some tx and bitvm2 challenge scripts, it will take about 5 minutes. **2.Finish the registration process** ``` fcli register --network testnet finish --validator-key --private-key ``` after executing the above command, the register tx will be broadcasted to the bitcoin network, it will take about 10 minutes for the registration to be complete depending on the bitcoin network. after the registration is complete, you can become a validator. ### Challenge Proofs If you want to challenge a proof , you can use the following command: #### **1.Start the challenge process** ``` fcli challenge --network testnet start --proof-id --vk-path --circuit-type groth16 ``` #### **2.Finish the challenge process** ``` fcli challenge --network testnet finish --proof-id --vk-path --circuit-type groth16 --txid --vout --private-key ``` #### **3. Monitor the challenge process** After executing the challenge finish command, you can monitor the challenge process using: ``` fcli challenge --network testnet info --proof-id --vk-path --circuit-type groth16 ``` The console will display the challenge transaction ID, committee-generated assertion transaction ID, and challenge status. You can use the [signet explorer](https://mempool.space/signet/tx/d81eccdca492ad1c9e9b4e9dd48fb181eb566bed2949d3b8f13d28ff015e489b) to verify if the challenge and assertion transactions have been confirmed. #### **4.Disprove the challenge** After executing the challenge finish command, if you challenge success, you will get the reward, you can use the following command to create the disprove tx and broadcast it to the bitcoin network: ``` fcli disprove --network testnet create_disprove_tx --proof-id --script-index 977 --reward-address ``` You should wait until the disprove tx is confirmed, after the disprove tx is confirmed, you will get the reward to your reward address. # Run a Fiamma Node In this tutorial, you will learn how to run a fiamma node and pledge it as a validator. # Set up a Node In this tutorial you will learn how to set up a fiamma node {% hint style="info" %} NOTE This guide requires having Fiamma installed on a Linux System. The instructions can be found on the Installation page The version to install is specified at the [fiamma-testnet-1 ](https://github.com/fiamma-chain/networks/tree/main/fiamma-testnet-1)network info page. {% endhint %} ## System Requirements The following specifications have been found to work well: * Quad Core or larger AMD or Intel (amd64) CPU * 32GB RAM; * 1TB NVMe SSD Storage (disk i/o is crucial); * 100Mbps bi-directional Internet connection; ## Install Fiammad You can refer to the [installation page](/our-product-suite/bitvm-powered-zkp-verification-layer/user-guides/installation) to install the fiammad binary ## Initialize the Node Directory First, initialize a node configuration directory under `~/.fiamma`. The `$NODENAME` variable specifies the name you aim to give your node. ```shell fiammad init $NODENAME --chain-id fiamma-testnet-1 ``` Then, retrieve the genesis file and place it in the node directory: ```bash wget https://raw.githubusercontent.com/fiamma-chain/networks/main/fiamma-testnet-1/genesis.json -O ~/.fiamma/config/genesis.json ``` ## Add Peers and Modify Configuration Edit the configuration file at `~/.fiamma/config/config.toml` and modify the `seeds` and `persistent_peers` attributes to contain appropriate seeds and peers of your choice. The full list of Fiamma approved seeds and peers can be found under the [fiamma-testnet-1 ](https://github.com/fiamma-chain/networks/tree/main/fiamma-testnet-1)network info page. ```toml # Comma separated list of seed nodes to connect to seeds = "5d6828849a45cf027e035593d8790bc62aca9cef@18.182.20.173:26656,526d13f3ce3e0b56fa3ac26a48f231e559d4d60c@35.73.202.182:26656" # Comma separated list of nodes to keep persistent connections to persistent_peers = "5d6828849a45cf027e035593d8790bc62aca9cef@18.182.20.173:26656,526d13f3ce3e0b56fa3ac26a48f231e559d4d60c@35.73.202.182:26656" ``` Edit the configuration file at `~/.babylond/config/app.toml` and modify the `minimum-gas-prices` attribute and set it to a value of your choosing. For example ```toml minimum-gas-prices = "0.00001ufia" ``` ## Setup Cosmovisor Cosmovisor is a tool for automating the management of Cosmos SDK application binary files. It simplifies the process of upgrading and rolling back chains. To install the latest version of Cosmovisor ```bash go install cosmossdk.io/tools/cosmovisor/cmd/cosmovisor@latest ``` Create the necessary directories 
mkdir -p ~/.fiamma/cosmovisor
mkdir -p ~/.fiamma/cosmovisor/genesis/bin
mkdir -p ~/.fiamma/cosmovisor/upgrades
Copy the `fiamma` binary into the `cosmovisor/genesis` folder ```bash cp $GOPATH/bin/fiammad ~/.fiamma/cosmovisor/genesis/bin/fiammad ``` Setup a cosmovisor service: ```bash sudo tee /etc/systemd/system/fiamma.service > /dev/null < ```bash sudo -S systemctl daemon-reload sudo -S systemctl enable fiamma sudo -S systemctl start fiamma ``` You can check the status of the node by running ```bash systemctl status fiamma ``` You can also check the fiamma's log by running ```bash journalctl -u fiamma -f ``` # Getting Testnet Tokens Before a pledge can become a validator, you need to have some FIA tokens. In this tutorial you will learn how to get fiamma testnet token. ## Create a Keyring One can create a keyring through the `fiammad keys add` command. ``` # Replace the --keyring-backend argument with a backend of your choice fiammad --keyring-backend test keys add my-key ``` This will output an address and a memo. Record the memo as it is the only way to recover your key if it gets lost. For more commands about keys, you can refer to the [Manage Keys](/our-product-suite/bitvm-powered-zkp-verification-layer/user-guides/manage-keys) ## Request Funds from the Fiamma Testnet Faucet You can refer to the[ Get FIA ](/our-product-suite/bitvm-powered-zkp-verification-layer/user-guides/wallet-and-tokens/get-fia)to obtain Fiamma network test tokens. # Become a Bitvm Staker Before becoming a validator on the fiamma network, you should register your validator address with the committee program, so that your validator address is allowed to join the network {% hint style="info" %} On the current testnet, users who need to register as Fiamma validators must be approved before they are allowed to create one. If you wish to become a Fiamma validator, please follow [Fiamma's relevant announcements](https://x.com/Fiamma_Chain) or contact the [Fiamma team](mailto:undefined). {% endhint %} ## Prerequisites This guide assumes you have some familiarity with Bitcoin wallets and general Bitcoin usage. For example, know what UTXO is, Bitcoin RPC service etc, for more information, please see [bitcoin developer reference](https://developer.bitcoin.org/reference/rpc/index.html). Ensure you have Rust installed on your system. You can [**install Rust**](https://www.rust-lang.org/learn/get-started) from the official Rust website[.](https://www.rust-lang.org/learn/get-started) ## Step 1: Installation Fiamma Committee CLI You can refer to this [installation](/our-product-suite/bitvm-powered-zkp-verification-layer/developer-guides/fiamma-committee-cli#installation) step to install the Fiamma Committee CLI. ## Step 2: Register as a Staker You can refer to [Registration Instructions](/our-product-suite/bitvm-powered-zkp-verification-layer/developer-guides/fiamma-committee-cli#register-as-a-bitvm2-staker-validator) to register as a bitvm2 staker. ### Expected Output If everything is correct, you will receive a registration ID: ```bash You have submitted your registration application. The registration number is 6, please wait patiently. ``` wait the Bitcoin transaction is confimed, we have successfully register validator\_key as BitVM staker. # Become a Validator In this tutorial you will learn how to stake fiamma token and become a fiamma validator {% hint style="info" %} On the current testnet, users who need to register as Fiamma validators must be approved before they are allowed to create one. If you wish to become a Fiamma validator, please follow [Fiamma's relevant announcements](https://x.com/Fiamma_Chain) or contact the [Fiamma team](mailto:undefined). {% endhint %} ## Prerequisites[​](https://docs.babylonchain.io/docs/user-guides/btc-staking-testnet/become-validator#prerequisites) Having a full [node setup ](/our-product-suite/bitvm-powered-zkp-verification-layer/developer-guides/run-a-fiamma-node/set-up-a-node)and synced by following this guide You need to [register your validator ](/our-product-suite/bitvm-powered-zkp-verification-layer/developer-guides/run-a-fiamma-node/become-a-bitvm-staker)address as a bitvm staker, so that you can continue with the registration process. ## 1. Create a Keyring and Get Funds The [Getting Testnet Tokens](/our-product-suite/bitvm-powered-zkp-verification-layer/developer-guides/run-a-fiamma-node/getting-testnet-tokens) page contains detailed instructions on how to create a keyring and get funds for it through a faucet. ## 2. Get Validator Pub Key You can get the validator **pubkey** for the current node using the following command. You'll need to write it down. It will be needed next when creating the validator json file 
fiammad tendermint show-validator
## 3. Get Node Moniker You can get the node moniker for the current node using the following command. You'll need to write it down. It will be needed next when creating the validator json file ```bash fiammad config get config moniker ``` ## 4. Create A Validator Config File You can modify the information of your validator as you wish, the following is just an example You can find the **pubkey** by [Get Validator Key](#id-1-create-a-keyring-and-get-funds-1). You can find the **moniker** by [Get Node Moniker](#id-1-create-a-keyring-and-get-funds-2) ```bash cat << EOF > ~/.fiamma/config/validator.json { "pubkey": {"@type":"/cosmos.crypto.ed25519.PubKey","key":"QiZohv1ATkoaiBvH3aKNryXIw5026xHZAWuqOuR0rWQ="}, "amount": "1000000ufia", "moniker": "test-node", "commission-rate": "0.1", "commission-max-rate": "0.2", "commission-max-change-rate": "0.01", "min-self-delegation": "1" } EOF ``` ## 5. Staking And Become A Validator Now you can create a pledge transaction to complete the creation of the validator ```bash fiammad tx staking create-validator ~/.fiamma/config/validator.json --from $KEYNAME --keyring-backend test --chain-id fiamma-testnet-1 --node "https://testnet-rpc.fiammachain.io/" --fees 2000ufia ``` ## 6. Show Your Validator Addr You can get your validator address with the following command 
fiammad keys show $KEYNAME --keyring-backend test -a --bech val
where `$KEYNAME` is the name of the key that you used for the self-delegation (e.g. `my-key` on our example). ## 7. Query Your Validator staking Use the above command to get the validator address, then you can check if your validator is staking successfully ```bash fiammad query staking validator $ADDR ``` If all goes well, you should see a response indicating the parameters that you specified on the create-validator transaction. # Rest API And GRPC The following API's are recommended for development purposes. For maximum control and reliability it's recommended to run your own node. ## Network Quickly connect your app or client to Fiamma public testnets. You can check the [**network**](/our-product-suite/bitvm-powered-zkp-verification-layer/developer-guides/network-information) page for information about the current test network ## GRPC, Rest, and CometBFT Endpoints The Fiamma RPC interface includes basic query interfaces for the Tendermint consensus, and the API includes basic interfaces related to Cosmos, as well as interfaces for the unique **zkpverify module** of the Fiamma network. | Name | Description | Link | | ------------------- | ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | | **Fiamma Rest API** | Query or send Fiamma transactions using an HTTP restful API | | | **Fiamma RPC** | Query transactions, blocks, consensus state, broadcast transactions, etc. | | | **FIamma GRPC** | Using a predefined proto data structure, grpc requests can be sent to the fiamma network for transactions and queries. | [testnet-grpc.fiammachain.io:443](https://testnet-grpc.fiammachain.io) | ## Rest API Info The list of all REST APIs supported by Fiamma can be obtained from the [Swagger documentation](https://testnet-api.fiammachain.io/). ### API-Msg Fiamma's zkverify RPC message modules all start with **/fiamma.zkpverify.Msg/**, followed by the message name. These requests are all **POST** requests ### API-Query Fiamma's zkpverify RPC query modules all start with **/fiamma.zkpverify/**, followed by the query name. These requests are all **GET** requests ## GRPC Info fiamma supports grpc requests, you can build grpc requests using any language sdk that supports grpc clients, a list of fiamma defined proto files can be found in [Proto Buff](#proto-buff) ### Proto Buff All messages and queries of the fiamma network are defined in proto buff files, which can be found in [**buf.build**](https://buf.build/fiamma-chain/fiamma/tree/main:fiamma/zkpverify). {% hint style="info" %} Note! All gRPC requests will correspond to a REST request. For instance, querying pendingProof could be done via the /**fiamma.zkpverify.Query/PendingProof** gRPC endpoint, or alternatively via the gRPC-gateway **/fiamma/zkpverify/pending\_proof** REST endpoint: both will return the same result. {% endhint %} --- [Next Page](/llms-full.txt/1)