Welcome to the technical documentation for Hemi, a Layer-2 solution for Bitcoin and Ethereum blockchains that offers true scalability and interoperability.
This documentation is designed to guide builders and enthusiasts in understanding and utilizing the Hemi Virtual Machine (hVM). The hVM is Hemi's modular protocol that provides developers with a familiar programming interface.
Navigating the Docs
Our documentation is organized into the following sections to help you find relevant information quickly:
Quickstart: Whether you plan to develop, explore, or mine on Hemi, we have identified some crucial resources to quickstart your journey.
Foundational Topics: Learn about the architecture, sequencer consensus, PoP consensus & Bitcoin finality, tunneling, and more.
How-To Tutorials: Whether you are using or developing on Hemi, these basics will get you started! Set up your MetaMask Wallet, tunnel ETH and BTC to Hemi, start with Remix IDE, deploy an ERC-20 token and run a PoP miner.
Token Contract Details
Official Hemi token contrat
$HEMI Contract Details
Network
Contract Address
Introduction
The Hemi Network is a modular Layer-2 protocol for superior scaling, security, and interoperability, powered by Bitcoin and Ethereum.
Whereas other projects approach Bitcoin and Ethereum as ecosystem silos, Hemi views them as components of a single supernetwork. This unlocks new levels of programmability, portability, and potential.
At Hemi's core: the Hemi Virtual Machine (hVM), which incorporates a full Bitcoin node within an Ethereum Virtual Machine.
Combined with the Hemi Bitcoin Kit (hBK), developers have a familiar yet powerful platform for creating Hemi decentralized applications (hApps).
Overview
The Hemi Network represents a different way of thinking about Layer-2 scaling, by approaching Bitcoin and Ethereum as components of a supernetwork.
This modular protocol aims to scale these networks and maximize their utility, creating a more connected and efficient blockchain ecosystem.
Through features such as the hVM, Hemi equips developers with robust tools for building next-generation dApps with Bitcoin and Ethereum interoperability.
The Benefits of Hemi
Ease of Development
The Hemi Virtual Machine (hVM) integrates a full Bitcoin node within an Ethereum Virtual Machine (EVM), providing developers with a familiar programming interface while harnessing the power of both Bitcoin and Ethereum.
Bitcoin Programmability
Building with the Hemi Bitcoin Kit (hBK) provides smart contracts with highly granular indexed views of Bitcoin state, unlocking Bitcoin DeFi applications were previously impractical or impossible to execute via an EVM.
Network Details
Everything you need to connect to the Hemi network.
Hemi Mainnet
Consensus and Security Protocols
📜 TL;DR:
Tooling: Understand and access the tools required to build on Hemi.
Incentives: Check out our points, grants, retroactive funding, and one-off spends.
Additional Resources: Partners inquiry, FAQ, official links, and our brand kit.
Send Feedback: We'd love to hear from you, good or bad! Found a bug? Got a hackathon coming up? Slide into our DMs.
Bitcoin Superfinality
Hemi's Proof-of-Proof (PoP) consensus mechanism ensures transactions surpass Bitcoin's level of security in just a few hours.
Trustless Cross-chain Portability
The hVM's unique awareness of Bitcoin's and Ethereum's states enables secure, seamless asset transfers between Hemi and other chains through its "Tunnels" feature.
Extensibility
Hemi allows external projects to create their own chains secured by Hemi's technology, facilitating Bitcoin-Security-as-a-Service and enhancing dual-chain interoperability.
Superior Asset Handling
Advanced on-chain functionalities, including routing, time-lock, and password protection, are made possible through Hemi, elevating asset management and security.
Incorporates Bitcoin's security to prevent attacks, with PoP Miners embedding consensus data on the Bitcoin blockchain.
Rewards PoP Miners in native tokens for strengthening consensus.
Utilizes Bitcoin confirmations to ensure network integrity, achieving "Bitcoin Finality" for robust defense against reorganizations.
👀 Sneak Peek WIP
Overview
The Hemi Network's sequencer consensus combines Proof-of-Stake with Proof-of-Proof to address weak subjectivity and censorship attacks inherent in traditional PoS systems.
This hybrid model prevents forged chains through state proofs on the Bitcoin network and allows legitimate sequencers to regain control in adversarial conditions, ensuring the network's resilience and security.
🔒 Network Security and Finality
To inherit Bitcoin security, a new type of miner (a “PoP Miner”) publishes Hemi consensus information to the Bitcoin blockchain.
After a state publication to Bitcoin, the Hemi Network’s consensus layer incorporates cryptographic proofs of these publications, with PoP Miners receiving a reward in the protocol’s native token. The network uses these proofs during fork resolution to prevent reorganizations with the full force of Bitcoin’s security.
As they are produced, the Hemi Network’s chain segments initially receive Bitcoin confirmations, which means an attacker would have to control increasingly large ratios of staking power to successfully affect a reorganization.
During normal operation, each block on the Hemi Network reaches full “Bitcoin Finality”after 90 minutes, or nine Bitcoin blocks, on average.
At this point, it is mathematically impossible for anyone to reorganize the network without 51% attacking Bitcoin itself.
Need to bring assets to Hemi? Visit the Hemi Tunnel.
Hemi Testnet
Testnet is a testing environment for validating new features and deployments before they reach mainnet. Testnet tokens have no monetary value — do not send real assets to testnet addresses. Hemi testnet may undergo maintenance or be reset without notice.
Chain ID
743111
Currency symbol / Gas Token
ETH
RPC URL
Block Explorer URL
Public RPC endpoints are rate-limited to approximately 300 requests per minute and are intended for development and testing. These limits are subject to change. For production applications, use a third-party provider.
Third-Party RPC Providers
We partner with leading node providers to allow dApps to seamlessly integrate with the Hemi network. These providers offer reliable and scalable RPC endpoints, allowing you to concentrate on development while they handle node infrastructure.
dRPC
dRPC provides high-performance RPC access to Hemi, backed by a distributed network of node providers. A free tier is available.
To use hVM directly, you will have to call the appropriate precompile address with the appropriate serialized bytes to pass parameters to the function.
Most dApp developers will use the Hemi Bitcoin Kit (hBK) rather than hVM directly.
🌐 Overview
To use hVM directly, you will have to call the appropriate precompile address with the appropriate serialized bytes to pass parameters to the function.
Each successful precompile call will return serialized bytes according to the precompile’s return data specification.
🟨 Developer Tip
Most dApp developers will use the Hemi Bitcoin Kit (hBK) rather than hVM directly.
If you’re looking for an easy way to get started developing Bitcoin-aware dApps on Hemi, check out the “Hemi Bitcoin Kit (hBK)” section. Understanding how Bitcoin Kit uses hVM under-the-hood may be helpful, and dApp developers looking to maximize gas efficiency may benefit from using hVM directly to avoid paying overhead for unmarshalling data they don’t need for a specific use case.
PoP Mining
Tunnel from Ethereum
General
Decentralized Rollups
📜 TL;DR:
The Hemi Network champions decentralized roles, leverages Bitcoin's security, promotes open participation, fault tolerance, and fee efficiency to enhance Layer 2 solutions.
🌐 Overview
In contrast to other Layer 2 (L2) rollup solutions, the Hemi Network introduces a more decentralized approach to data publication and validation, addressing critical issues present in current L2 setups:
✅ Decentralized Roles: Introduces a decentralized approach with Publishers handling key roles asynchronously, mitigating the risks associated with centralized control found in other L2 networks.
✅ Incentivized Participation: Allows open participation through staking tokens with Ethereum-side validation contracts, fostering consistent and incentivized data sharing even during times of increased fee activity.
Follow along with some of the tutorials to help you get a head start when building your first Hemi project.
Note: You may be eligible to earn Hemi by completing tutorials. Visit our for more information on active quests.
Transactions
📜 TL;DR:
PoS-Only Pitfalls
📜 TL;DR:
Introduction
📜 TL;DR:
Ethereum Virtual Machine (EVM)
📜 TL;DR:
Get Bitcoin Balance with Remix
📜 TL;DR:
Retroactive Funding
Coming Soon (Join to See Updates)
Ethereum Rollups
📜 TL;DR:
One-Off Spends
Coming Soon (Join to See Updates)
Brand Kit
This page features the official Hemi logos, symbols, and colors for media use.
Visit to view the full Hemi Brand Kit.
Visual Style Guide
Hemi's Visual Style Guide provides guidelines and a standard for the visual of the Hemi brand. We recommend using this document as a starting point for the Hemi brand.
✅ Fault Tolerance and Reward System: Implements a system to discourage malicious behavior, slashing stakes of Publishers submitting invalid data while rewarding Challengers who identify faults, thereby promoting network integrity.
✅ Efficient Ethereum Fee Management: Manages rewards via Ethereum-side validation contracts, ensuring consistent incentives for Publishers despite Ethereum fee fluctuations.
This approach addresses key PoS vulnerabilities: weak subjectivity and censorship attacks.
Forged chains would be invalidated by the state proofs on the Bitcoin network.
Integration with the Bitcoin network validates the blockchain and helps maintain integrity even under attack.
👀 Sneak Peek WIP
The Hemi Network uses a hybrid of Proof-of-Stake (PoS) and Proof-of-Proof (PoP) to secure its blockchain.
🌐 Overview
The Hemi Network utilizes the Bitcoin-Secure Sequencer (BSS), a type of Proof-of-Stake (PoS) node, to achieve consensus, or agreement, on the network’s status. By leveraging the Bitcoin blockchain, the Hemi Network decentralizes its security measures, reducing reliance on internal network validators.
👀 Sneak Peek WIP
Enhanced Consensus Mechanism
The network combines traditional PoS with Proof-of-Proof (PoP), creating a more secure and robust consensus mechanism than standard PoS systems.
🛠️ How?
⛓️ It incorporates state proofs from the Bitcoin network to validate the Hemi blockchain, ensuring the network's history cannot be easily altered or falsified.
🛡️ The hybrid model provides a unique defense against majority stake attacks, a common vulnerability in pure PoS networks.
🔐 In the event of an overwhelming attack, the network can offload transactions to the Bitcoin network, ensuring continuous operation and security.
Blocks
in blockchain technology are packets of transactions and data, made secure through links to previous blocks.
Altering past blocks requires modifying all subsequent ones, a security feature. The Hemi Network enhances this by segmenting blocks into five-minute "keystone" intervals, with a security proof sent to the Bitcoin network every second interval.
🌐 Overview
A block is a component of blockchain technology that contains transactions and their associated data.
Its security is enhanced because all subsequent blocks in the chain cryptographically reference it, reinforcing the integrity of the entire blockchain with each new block added. Tampering with an earlier block requires altering not only that block but also every block after it.
🟦 Hemi Blocks
In the Hemi Network, blocks are organized into five-minute intervals known as keystones. To inherit Bitcoin’s security, *one Hemi Network state proof must be published to the Bitcoin network every two keystone intervals. *
The first block of each interval cryptographically references the previous two keystone blocks, ensuring that the network cannot be reorganized without a 51-percent attack against Bitcoin itself, a scenario considered highly unlikely even for powerful entities like nation-states.
In Proof-of-Proof (PoP) consensus, a PoP miner periodically publishes proof of the Hemi Network’s state to the Bitcoin blockchain.
By building on Bitcoin, PoP consensus inherits the security and finality of Bitcoin’s consensus.
After six Bitcoin blocks, PoP consensus reaches a state of superfinality, where the security of the Hemi Network exceeds that of Bitcoin.
🌐 Overview
Proof-of-Proof (PoP) is the Hemi Network’s additive consensus protocol, building on Bitcoin’s consensus for superior security. PoP miners publish cryptographic network-state proofs to the Bitcoin blockchain, protecting Hemi consensus with Bitcoin's proof of work.
Hemi blocks achieve finality typically nine blocks (approximately an hour and a half) after their proofs are published to Bitcoin.
⏱️ Finality Delay in the Hemi Network
The Hemi Network accounts for fluctuations in Bitcoin's transaction fees and block timings, recognizing that network-state proofs might not appear in every block.
To manage this variability, a finality delay of nine Bitcoin blocks is implemented.
If no competing fork publishes proofs to Bitcoin during this period, the network assumes finality, requiring a 51% attack on both the Hemi and Bitcoin networks to alter this.
👀 Sneak Peek WIP
♾️ Superfinality: A New Benchmark in Blockchain Security
Upon reaching this finality, the Hemi Network attains a state of 'superfinality,' where its chain state's security surpasses Bitcoin's.
How?
This is achieved by combining Bitcoin’s Proof-of-Work consensus with Hemi’s Proof-of-Stake. After superfinality, altering the Hemi Network’s state proof would be economically infeasible even for nation-states. An attacker would need so simultaneously 51% attack Bitcoin and Hemi, which is even harder than attacking Bitcoin itself.
Pure Proof-of-Stake networks rely on social consensus to prevent censorship by majority stakers and long-range attacks using old PoS keys (weak-subjectivity attacks).
Staking is the risking of an asset in return for the chance to construct a block.
A user who acts maliciously will have his stake slashed (reduced) as punishment for attacking the network.
The Hemi Network uses a hybrid staking system that incorporates network state proofs published to the Bitcoin network, preventing both censorship attacks and weak-subjectivity attacks.
🌐 Overview
In Proof-of-Stake (PoS) consensus protocols, staking is a form of virtual mining in which users risk some amount of tokens (a “stake”) for the chance to construct a block and earn block rewards. If the staker misbehaves (for example, by trying to cheat the system), the network will remove some or all of the stake (a process called “slashing”). Under normal conditions when stakers act honestly, slashing is a rare occurrence. PoS is a popular alternative to Proof-of-Work (as in Bitcoin) because staking is far less energy intensive than mining.
⚠️ Security Risks in Proof-of-Stake
Conventional PoS networks, however, face two security risks inherent to staking. If a malicious actor were to acquire more than half of the staking power on the network, he could censor transactions, including slashing transactions, which would prevent other honest validators from regaining control of the network. PoS systems also suffer from weak subjectivity.
If a malicious actor acquired enough old PoS keys to have the majority of staking power, he could use the old keys to create a valid alternative chain. Pure PoS chains like Ethereum rely on social consensus to address these issues because the protocols themselves are vulnerable.
👀 Sneak Peek WIP
The Hemi Network's Hybrid Staking Approach
The Hemi Network uses a modified PoS protocol to provide security. Sequencers and publishers on the Hemi Network stake the network’s native token, as part of their normal operations. However, because of the network state proofs which proof-of-proof miners publish to the Bitcoin network, old staking keys cannot be used to construct a valid alternative chain. Constructing a valid alternative chain would require also reorganizing the Bitcoin network to publish corresponding alternative state proofs.
Furthermore, even a staker with an overwhelming majority of staking power on the Hemi Network would not be able to censor transactions. They would still be forced to include Bitcoin block headers in the PoS blocks he produced, and any Hemi Network user could bypass active PoS censorship attacks by offloading transactions to the Bitcoin network. The attacker’s stake would then be slashed and other validators would be allowed to process transactions.
The Hemi Network combines Proof-of-Stake (PoS) with Proof-of-Proof (PoP) for enhanced security which:
Protects against weak subjectivity using Bitcoin's state proofs.
Prevents censorship attacks by offloading transactions to Bitcoin.
🛡️ Against Weak Subjectivity
Even if an attacker gathers old staking keys, they can't alter the state proofs on the Bitcoin blockchain. These state proofs confirm the Hemi Network's transaction history, so any fake blockchain the attacker creates would be recognized as invalid.
🚫 Against Censorship Attacks
In a worst-case scenario where an attacker controls all the sequencers (the nodes that create blocks in the blockchain), the Hemi Network can still function by using the Bitcoin network.
Transactions can be processed (or "offloaded") to Bitcoin, which prevents the attacker from having total control.
🔚 Conclusion
The Hemi Network’s hybrid PoS-PoP consensus model hardens the network protocol against both weak subjectivity and censorship. Even with an overwhelming majority of old staking keys, an attacker would be unable to forge finalized state proofs on the Bitcoin blockchain, and the established state proofs would invalidate the altered Hemi Network chain.
A cryptocurrency transaction updates a network's decentralized ledger.
It requires the sender's cryptographic signature to ensure the transaction is authorized.
To increase the speed and number of transactions, transactions can be offloaded to an L2 network, which bundles transactions before settling them on the main chain.
Transactions on the Hemi Network inherit the programming abilities of Ethereum and the robust security of Bitcoin while still encouraging decentralization and resistance to censorship.
🌐 Overview
A cryptocurrency transaction fundamentally represents an update to the network's decentralized ledger.
Such a transaction mandates a cryptographic signature from the sender's wallet, serving as a verification mechanism to authorize the transaction. Within the Bitcoin ecosystem, scripting capabilities enable the execution of more complex transaction types.
Conversely, Ethereum operates as a distributed virtual machine, allowing for the execution of sophisticated programs known as smart contracts. These contracts, embedded directly on the blockchain, can operate autonomously based on their programming.
⚖️ The Blockchain Trilemma and L1 Challenges
L1 chains like Bitcoin and Ethereum typically have relatively slow transaction times—a problem commonly known as the blockchain trilemma.
The process of improving transaction throughput on a blockchain necessitates an expansion of data storage capacity, as each transaction must be individually recorded on the ledger. This requirement potentially centralizes the operation of full nodes to entities possessing considerable computational and financial resources.
In response, Layer 2 (L2) networks present a strategic solution by aggregating multiple transactions off-chain prior to their collective finalization on the primary Layer 1 (L1) blockchain. This methodology not only preserves the foundational security principles of the L1 blockchain but also contributes to a reduction in transaction fees and an acceleration of transaction processing times, thereby enhancing the efficiency and accessibility of blockchain technology. ⏩
🌉 Tunneling Ethereum & Bitcoin with Hemi
The Hemi Network, as an EVM-compatible Layer 2 network built to bridge Ethereum and Bitcoin, enables rapid transaction settlement and finality. Transactions inherit the complex programming abilities of Ethereum and the robust security of Bitcoin. The Hemi Network’s design also encourages greater decentralization than typical L2 networks, preventing censorship and ensuring open access.
Standard
Proof-of-Stake (PoS)
systems like Ethereum face two primary risks:
Weak Subjectivity, where attackers could potentially gain majority control by accumulating old PoS keys, enabling them to create alternative chains; and
Censorship, where a current majority stakeholder blocks or ignores transactions, akin to a traditional 51% attack.
🚨 Weak Subjectivity
This risk involves an attacker accumulating enough keys of old PoS miners to gain majority control at some point in the past. With this control, they could create a valid, alternative/competing version of the blockchain which would appear equally valid to a bootstrapping node attempting to sync the network for the first time, and could also be used to create seemingly valid zero-knowledge proofs of chain state that differs from the legitimate canonical chain.
While Ethereum relies on community consensus to avoid long-range reorganizations of its chain, its PoS protocol doesn’t technically prevent this type of attack.
🚫 Censorship
An attacker with current majority stake could potentially block or ignore certain transactions, exercising a form of majority control that undermines the network's decentralization and fairness.
❌ Lack of Protocol-Level Defenses
Since PoS operates entirely within its network, it lacks protocol-level defenses against the types of attacks mentioned above.
Among the vulnerabilities, the limitations are:
No External Correction Mechanism: If internal rules fail or are exploited, there's no external system to protect or correct the network.
Self-Contained Security: PoS systems handle all their security internally within the blockchain network.
By using PoP, Hemi prevents against weak subjectivity attacks because the illegitimate chain an attacker produces when attempting a long-range reorg could not be appropriately published to Bitcoin. Hemi's fork resolution algorithm prevents a reorg from occurring if the new proposed fork does not have PoP publications that are in-step with or before the current chain's publications. As a result, Hemi's consensus algorithm has strong subjectivity and reorganizing a segment of Hemi's chain which has reached Bitcoin finality would require the attacker to 51% attack Hemi and Bitcoin simultaneously.
As a dual-chain L2, Hemi can also provide robust censorship resistance against attacks from majority block-consensus power actors. Any valid Hemi transaction can be published to either Bitcoin or Ethereum, and Hemi's block derivation protocol will force the inclusion of these transactions in Hemi blocks.
The Hemi Virtual Machine (hVM) and Hemi Bitcoin Kit (hBK) power Hemi’s Bitcoin interoperability.
hVM is an indexed Bitcoin full node directly accessible inside the EVM.
hBK is a smart contract library running on Hemi that utilizes hVM and makes Hemi’s Bitcoin awareness easier to use.
hVM’s precompile calls and hBK's functions are subject to change in future versions of the Hemi testnet.
The Hemi Virtual Machine (hVM) and Hemi Bitcoin Kit (hBK) power Hemi’s Bitcoin Interoperability, empowering dApp developers to build novel Bitcoin dApps and robust interoperability infrastructure in a trustless, secure, and gas-efficient manner.
hVM: An indexed Bitcoin full node directly accessible inside the EVM, exposing data including transactions, address balances, UTXOs, and chain metadata to smart contracts on Hemi via custom precompiles.
hBK: A smart contract library running on Hemi that utilizes hVM and makes Hemi’s Bitcoin awareness easier to use by exposing higher-level functions that perform the precompile calls and handle the data marshaling, returning simple data structures developers can use in their dApps.
👷♂️ In Development:
hVM and Bitcoin Kit are in development and experimental.
hVM’s precompile calls and Bitcoin Kit’s functions are subject to change in future versions of the Hemi Testnet.
Prior to mainnet launch, the protocols will ossify and future upgrades will only add new hVM precompiles and Bitcoin Kit functions, ensuring full backwards compatibility.
📋 Latest Version
Because new versions of hBK are being developed and tested, this document will always contain the latest “stable” contract available on Hemi’s testnet.
In Mainnet, Bitcoin Kit contracts will be deployed as predeploys with special addresses like 0x8400000000000000000000000000000000000001, with new versions offering additional features being deployed at incremented addresses.
The Ethereum Virtual Machine (EVM) serves as a global, decentralized computer designed to execute smart contracts.
The Hemi Network offers seamless compatibility with the EVM, allowing it to not only execute Ethereum-based smart contracts directly but also facilitate interactions among various smart contracts across networks.
The Hemi Network also extends this compatibility to Bitcoin through a protocol-level awareness of the state of the Bitcoin network.
🌐 Overview
The Ethereum Virtual Machine (EVM) represents a cornerstone of blockchain technology, functioning as a distributed computational engine that executes smart contracts. These contracts are self-executing agreements with the terms directly written into code, enabling a wide array of decentralized applications (DApps). The Ethereum network's primary role is to maintain the operational integrity and accessibility of the EVM, ensuring a trustless environment for executing these contracts.
💡 An EVM-Compatible L2
On the innovative front, the Hemi Network emerges as an EVM-compatible Layer 2 (L2) solution, architecturally designed atop Ethereum's foundation.
This compatibility empowers the Hemi Network to directly execute smart contracts developed for the Ethereum ecosystem and establish communicative bridges with other EVM-compatible smart contracts, fostering an interconnected blockchain environment.
🔗 Integration with Bitcoin
Through a deep, protocol-level insight into Bitcoin's state, the Hemi Network facilitates the creation and execution of EVM-compatible smart contracts that can interact with Bitcoin. This expands the utility and applications of smart contracts and tunnels the capabilities of Ethereum with the robust security and widespread adoption of Bitcoin, marking a significant advancement in blockchain interoperability and functionality. 🤝
🚗 Rollups optimize Ethereum's performance by gathering transactions "off the main Ethereum highway" (Layer 1) and then officially process them on a "side road" (Layer 2).
🌐 Overview
Ethereum Rollups are a Layer-2 scaling solution designed to enhance the throughput and features of the Ethereum network.
They operate by "rolling up," or bundling, multiple transactions off-chain and submitting them in batches to the Ethereum mainnet for data availability. By doing so, they significantly reduce congestion and gas fees while maintaining interoperability with Ethereum.
Rollups can also add new protocol features that would be impossible directly on Ethereum (e.g., PoP security to inherit Bitcoin Finality and Hemi's hVM Bitcoin Interoperability system).
Support for the Web PoP Miner has since been deprecated.
To learn more about how we implemented the application, feel free to view our codebase here: https://github.com/hemilabs/web-pop-miner
Follow our CLI PoP Miner guide to run a PoP Miner.
🌐 Overview
The web PoP miner was designed for ease of use, allowing users of any experience level to test and run their own PoP miner.
Due to its lightweight nature, it required no specific hardware, making it accessible from any standard computer.
While it was not intended for long-term mining operations, it served as an excellent entry point for users interested in transitioning to the more durable CLI version, providing an introduction to Hemi's architecture and its unique integration with the Bitcoin network.
🔐 Security Note
The web miner uses the same secure code as the CLI miner. However, it also relies on your web browser, which introduces additional security risks.
When transitioning to the CLI PoP Miner, it is recommended to generate a new public key. Private key information obtained via the web PoP Miner, although encrypted, is not fully secure and is not meant for extended mining operations.
Overview
📜 TL;DR:
The Hemi Bitcoin Kit (hBK) enables direct interaction with Bitcoin blockchain data within Ethereum’s environment.
hBK utilizes Hemi Virtual Machine (hVM) to embed a fully indexed Bitcoin node inside the Ethereum Virtual Machine (EVM).
hBK allows Ethereum smart contracts to query Bitcoin data using precompiled calls, ensuring efficient, trustless data access.
⚙️ How It Works
Hemi Virtual Machine (hVM)
The hVM is the backbone of the hBK’s interoperability features, embedding a Bitcoin node within the EVM. This setup allows Ethereum smart contracts to directly query Bitcoin data without relying on external bridges or third-party oracles, ensuring trustless, efficient, and secure access to Bitcoin data.
Direct Access: Smart contracts can communicate with Bitcoin data embedded in the EVM, enabling them to make queries and receive data via precompiled calls.
Indexed Data: The fully indexed Bitcoin node maintains transaction history, UTXOs, and meta-protocols like Ordinals and BRC-20 tokens.
Developer Interface: Simplified Interaction with Bitcoin
The hBK abstracts technical complexities, offering developers straightforward methods for accessing Bitcoin data, allowing them to:
Directly Pass Data to Precompiled Calls: Simple data serialization/deserialization processes provide a transparent gateway to precompiled Bitcoin calls.
Enhanced Query Functions (Upcoming): hBK is set to introduce enhanced functions, combining multiple precompile calls and additional processing steps for advanced operations.
This dual approach ensures developers can create Bitcoin-aware applications without managing low-level integration details, focusing instead on innovation and functionality.
🔑 Key Features
Embedded Node Access: hBK integrates a fully indexed Bitcoin node within Hemi’s EVM environment, exposing robust Bitcoin data for smart contract use.
Precompiled Calls for Direct Data Retrieval: Passthrough functions facilitate Bitcoin data queries with direct calls, automatically handling the data structures.
Enhanced Functions for Advanced Queries: Future upgrades will introduce enhanced functions, combining multiple calls and added processing to support more complex queries and data requirements.
In this section, we’ll deploy a small contract in Remix IDE with a single method which calls the Bitcoin Balance precompile and returns the balance as a uint256.
We recommend you use Solidity version 0.8.25 or later, but previous versions are also expected to work.
🏁 Prerequisites
To follow along, you’ll need:
Metamask (or another Remix-supported web wallet) connected to Hemi testnet as a custom network;
A nonzero ETH balance tunneled over to a Hemi address in your wallet you want to deploy the demo contract with to pay deployment gas fees.
📚 Tutorial
1. Create Contract
To start, open Remix, delete any existing contracts in the “contracts” folder,.
Create a new contract file, which for our example we’ll call “BitcoinBalDemo.sol”.
Paste in the following code:
You can now compile and deploy this contract, and try out calling it with a Bitcoin address string to see the address's balance (in satoshis) returned by hVM.
When setting up your UniSat wallet, the browser extension will default to the Bitcoin mainnet network.
If you plan on building on or interacting with Bitcoin testnet, you may need to change the network your UniSat wallet is set to in order to view your testnet assets.
This guide walks you through switching the connected network on your UniSat wallet.
Click the network dropdown in the top-right corner to view all Bitcoin networks.
3. Select Bitcoin Testnet
Select 'Bitcoin Testnet' from the list of networks.
From here, the dropdown should expand and you can click on 'Bitcoin Testnet'.
4. You are ready to interact on Bitcoin Testnet! 🎉
Your wallet is now ready to send, receive, and sign transactions on Bitcoin Testnet!
Certain tokens are not yet supported by Hemi’s native Tunnel.
For these assets, you can use one of several third-party tunnel solutions to move tokens between Ethereum and Hemi.
🔄 Why Use a Third-Party Bridge?
Hemi’s native Tunnel supports a range of popular ERC-20 tokens. However, some assets (e.g., USDC, USDT) are not yet integrated. In these cases, a third-party bridge provides:
• Fast bridging times.
• Established track record of security and reliability.
• Wide token support, including stablecoins like USDC and USDT.
🤝 Supported Third-Party Bridges
Below is a list of third-party bridges you can use to transfer assets to Hemi. Each bridge has its own UI, fees, and specific token support.
Bridge
Link
Stargate
Eigenpie
General
Tutorial
Description
Difficulty
Learn how to develop and deploy a HelloWorld smart contract on Hemi using .
🟢 Easy
Learn how to deploy an ERC-20 token on Hemi using .
🟢 Easy
hVM & hBK
Tutorial
Description
Difficulty
Learn about the and interact with our precompiles.
🟢 Easy
Deploy a small contract in with a single method which calls the Bitcoin Balance precompile and returns the balance.
Hemi’s Bitcoin Tunnel enables the secure transfer of Bitcoin and Bitcoin-native assets (such as Ordinals and BRC-20 tokens) between Bitcoin, Hemi, and eventually, EVM-compatible networks.
The Bitcoin Tunnel contract uses hVM to track Bitcoin addresses and outputs tied to custodianship vaults, ensuring efficient and secure asset management.
Hemi will offer two custodianship models: overcollateralized multisig and BitVM. These ensure decentralized, trust-minimized asset tunneling with high security and performance.
🚊 How Bitcoin Tunnels Work
The Bitcoin Tunnels allow Bitcoin assets to move between Bitcoin and Hemi by locking assets in custodial vaults and minting representative tokens on Hemi. Users can freely use these tokens on Hemi, and eventually, tunnel them to Ethereum or other EVM-compatible networks.
Deposit to Hemi
Users generate a deposit transaction by sending Bitcoin (or Bitcoin-native assets) to the selected custodianship vault’s Bitcoin address, managed by the multisig.
Once sent, the Bitcoin assets are locked in the custodianship vault.
Hemi’s Bitcoin Tunnel verifies the successful deposit on the Bitcoin network by monitoring the UTXO table for the corresponding deposit. If the deposit is successfully verified, the system moves to the next step.
Withdrawal to Bitcoin
The user on Hemi initiates a withdrawal transaction by selecting the amount of representative tokens they want to convert back to Bitcoin.
These representative tokens are burned on the Hemi network, signaling the system that the user intends to withdraw the corresponding amount of Bitcoin from the custodianship vault.
Hemi’s Bitcoin Tunnel updates the rollup state root with the details of the withdrawal transaction. This state root is submitted to Bitcoin by a Publisher to ensure that the withdrawal is accurately recorded.
🔍 Comparison to Other Bitcoin Interoperability Solutions
Hemi’s Bitcoin Tunnels leverage the power of hVM (Hemi Virtual Machine) to monitor and secure Bitcoin-based asset transfers.
The Bitcoin Tunnel contract uses hVM to track Bitcoin addresses and outputs tied to custodianship vaults, ensuring efficient and secure asset management.
In hVM Phase 0, an externally owned account (EOA) is required to notify the contract of any irregular withdrawals. Once flagged, hVM can verify the offending transaction and respond by slashing misbehaving custodians.
Tunnel ERC20s via Native Tunnel
📜 TL;DR:
Tunnel your ERC20s to Hemi by using the native Hemi Tunnel, enabling interactions within the Hemi Network ecosystem.
🏁 Prerequisites
- Set up your EVM wallet and add the Hemi Network before interacting with any Hemi application.
📚 Tutorial
Video
1. Visit the Hemi Portal
Go to to tunnel your ERC20 asset from Ethereum to the Hemi network.
Confirm your network of choice via the network dropdown at the bottom left.
2. Connect wallet
Click 'Connect Wallets' in the top-right corner of the Hemi Portal.
3. Connect your EVM wallet
Currently, MetaMask and Rabby are the only EVM wallets Hemi supports. Our team is working to add support for additional wallets.
4. Connect to the Ethereum Network
Ensure that you are connected to the Ethereum Network. If you are not connected, the Portal will prompt you to connect.
5. Select asset and enter the amount to tunnel
Use the token dropdown to select the asset you wish to tunnel. After selecting the asset, input the amount of the asset you wish to move to Hemi.
After you have confirmed the gas fee and wish to proceed with the deposit, click 'Deposit.'
6. Confirm the deposit
Sign and confirm your deposit transaction in your connected wallet.
7. You have successfully tunneled to Hemi! 🎉
Your transaction should now be complete! You can check the status and view the transaction in the 'Transaction History' tab.
Note: You can also confirm your transaction was successful in the Activity tab of your wallet.
Set Up a Safe Wallet
📜 TL;DR:
Safe is a smart contract wallet that requires a minimum number of people to approve a transaction before it can occur (M-of-N).
Earn and track Hemi for completing this tutorial!
🏁 Prerequisites
📚 Tutorial
Video
1. Visit the Hemi Safe
2. Connect your wallet
To get started, connect your wallet to the Safe site. For this tutorial, we will be using MetaMask.
3. Name your Safe
After connecting your wallet, you will be prompted to name your Safe account.
Doublecheck the wallet and network provided in the right-hand screen. Confirm that the wallet connected is the wallet you would like to use to create your Safe wallet, and that the network is set to Hemi Sepolia.
When you are ready to proceed, click 'Next'.
4. Add signers and assign a threshold
A Safe Wallet can be set up as a multi-sig wallet, whitelisting addresses who may sign transactions on behalf of the wallet. You may assign a name to each address you intend to add to the wallet.
After adding additional signers, you may specify how many signers are required to sign any given transaction. This variable is referred to as the Threshold.
After finalizing the verified signers and threshold requirements, click 'Next' to proceed.
5. Review and verify your Safe account
Review and verify the network, name, signers, threshold, and estimated network fee to create your Safe account.
After confirming all given information, click 'Create' to proceed.
6. Confirm the transaction in your wallet
Confirm the recent transaction via your MetaMask wallet.
7. You have successfully created a Safe Wallet! 🎉
Your Safe Wallet is ready for use! You may add funds to your wallet and explore sending and receiving assets.
Pros & Cons
📜 TL;DR:
Optimistic Rollups: Faster, presumed valid until proven otherwise; has delays, user fraud detection, relies on centralization.
Zero-knowledge Rollups: Prior validation is needed, enhanced privacy; complex vulnerabilities, trusted setup, reliance on centralization.
Centralized Influence: Centralized proposers could disrupt decentralized frameworks.
Verifiers and Challenges: Vulnerabilities demand verifiers, lack of incentives leads to centralization.
Denial-of-Service Risks: Centralized "batchers" in L2 networks risk refusing to publish transactions back to Ethereum, potentially causing service denial.
🌀 Conventional Rollups
💭 Things to Consider
Centralized Influence in a Decentralized Sequencing World
Within frameworks aiming for decentralized sequencing, the presence of a centralized proposer could wield significant influence, potentially disrupting their intended decentralized nature.
Such control might result in the withholding of valid state rollups from Ethereum, leading to coercion of decentralized sequencers into potential censorship or halting communication of specific chain segments back to Ethereum for settlement.
🟩 Verifiers and Challenges
Vulnerabilities in optimistic rollup networks pose risks of asset theft through forged L2 states. To address this, rollups introduce verifiers, but the lack of proper incentives for this role presents challenges.
These lack of incentives can lead to difficulties such as:
🔒 Securing a sufficient number of verifiers to perform the complex and expensive verification process required.
👥 Relying heavily on users or nodes funded by development teams resulting in centralization.
📣 Potential bias or influence.
✋ Denial-of-Service Risks
L2 networks' reliance on centralized "batchers" can expose them to denial-of-service risks if batchers refuse to publish transactions back to Ethereum for data availability.
Tunnel via Stargate
📜 TL;DR:
Tunnel your ERC20s to Hemi by using the Stargate third-party bridge.
Supported assets include USDC, USDT, ETH, and more.
🏁 Prerequisites
- Set up your EVM wallet and add the Hemi Network before interacting with any Hemi application.
📚 Tutorial
1. Visit the Stargate bridge
Navigate to the to tunnel your ERC20 asset from Ethereum to the Hemi network.
2. Connect wallet
Click 'Connect Wallet' in the top-right corner.
3. Select the asset and confirm networks
Using the token dropdown, select the asset you wish to bridge to Hemi.
Before proceeding, confirm Ethereum as the FROM network and Hemi as the TO network.
4. Enter the amount to bridge
Input the amount of asset you wish to bridge to Hemi.
When you are satisfied with your transaction, click 'Transfer'.
5. Approve and sign the transaction
From your connected wallet, approve the asset spend and sign the transaction.
6. You have successfully tunneled to Hemi! 🎉
After signing the transaction, look for the pending transaction bar at the top of the screen. It may take a few minutes to confirm the transaction.
Proof-of-Proof (PoP)
📜 TL;DR:
TheHemi Network utilizes Proof-of-Proof (PoP) to leverage Bitcoin's renowned security.
PoP Miners enhance security by publishing Hemi's network data on Bitcoin's blockchain.
Bitcoin confirmations further bolster Hemi's defenses, ensuring a robust and secure network.
🛡️ Inherits Bitcoin's Security
Hemi's network capitalizes on Bitcoin's formidable security through a mechanism known as Proof-of-Proof (PoP). This approach allows Hemi to inherit the solid Proof-of-Work (PoW) security of Bitcoin.
🔍 How?
To achieve this, Hemi deploys specialized miners, referred to as PoP Miners. These miners are responsible for:
Gathering crucial network details and publishing them on Bitcoin's blockchain, thereby linking Hemi's security directly to Bitcoin's proven system.
Employing sophisticated algorithms to generate proofs that are vital for the network's security.
🏗️ Block Confirmations
New segments in the Hemi chain receive confirmations from Bitcoin, significantly raising the barrier for potential attacks. These confirmations:
Serve as "security bricks," each one strengthening the network's defenses.
Ensure that any attempt to compromise the network requires substantial power, making unnoticed attacks virtually impossible.
🔚 Conclusion
The Proof-of-Proof (PoP) consensus mechanism uniquely positions the Hemi Network by:
Allowing Bitcoin miners to secure Hemi indirectly, without direct involvement in Hemi's consensus processes.
Facilitating scalable transaction throughput in the Hemi ecosystem without expanding its Bitcoin footprint significantly.
(Testnet) Add tHEMI to MetaMask
📜 TL;DR:
tHEMI is the governance token for the Hemi Network's testnet phase.
tHEMI tokens are used for payouts to PoP miners as a means of acknowledging their contribution to the network's security and functionality. In the future, these incentives will expand to individuals running Sequencers, Publishers, and Challengers.
View your tHEMI balance and transactions directly in MetaMask.
The tHEMI token contract address is 0x4200000000000000000000000000000000000042.
🌐Overview
tHEMI is the testnet governance token for the Hemi Network. Initially, tHEMI tokens are used for payouts to PoP miners to acknowledge their contribution to the network's security and functionality.
Looking ahead, tHEMI will play a broader role in rewarding other network participants, including Sequencers, Publishers, and Challengers, who contribute to the network's resilience and growth. tHEMI is set to become the preferred gas token on the network, offering fee discounts and enhancing user transaction efficiency.
📚 Tutorial
Video
1. Open MetaMask
2. Access Token Selection
Navigate to Tokens
Import Tokens
3. Enter the Contract Address
Type in the tHEMI token contract address 0x4200000000000000000000000000000000000042 into the Token Contract Address field.
If the address is recognized, MetaMask will automatically populate the Token Symbol and Decimals of Precision fields.
4. Import
Confirm the accuracy of the provided information, click on Add Custom Token, and then select Import Tokens.
Your tHEMI tokens should now be visible in your MetaMask wallet. You can view your balance and conduct transactions directly within the wallet interface.
Proof-of-Proof vs. Merged Mining
📜 TL;DR:
allows Bitcoin miners to simultaneously mine a Bitcoin sidechain, which can limit decentralization and lead to an attack on the sidechain.
The Proof-of-Proof (PoP) consensus protocol utilized by Hemi enables PoP miners to independently publish data to the Bitcoin blockchain, cutting off this attack vector.
⛔️ The Trouble With Merged Mining
Bitcoin miners must choose to participate by running nodes for the sidechain, which can curtail decentralization.
This makes the sidechain more susceptible to attack, as Bitcoin miners can collude to attack the sidechain at no cost while reaping Bitcoin block rewards.
Merged mining can introduce new security problems and issues with incentives.
🔍 How Proof-of-Proof Works
Hemi uses a consensus protocol called Proof-of-Proof (PoP), which allows Hemi to exceed Bitcoin's security at scale.
Bitcoin miners don’t need to participate in Hemi directly; they confirm blocks that include Hemi transactions and collect transaction fees for doing so.
Users who do want to earn rewards in Hemi’s native token can run a super-lightweight PoP miner to publish Hemi consensus data to Bitcoin.
👉
Each new Hemi block receives a Bitcoin confirmation, making reorganization increasingly unlikely until the block reaches finality.
Bitcoin requires about 60 minutes to reach finality; Hemi takes nine Bitcoin blocks (about 90 minutes) to reach finality and achieves (WIP) in just two hours.
Thus, in the Proof-of-Proof protocol, unlike with merged mining, Bitcoin miners needn’t be active to benefit; they can’t collude to attack the chain, and superfinality comes fast.
Tunnel BTC via 3rd Party
📜 TL;DR:
Certain tokens are not yet supported by Hemi’s native Tunnel.
For these assets, you can use one of several third-party tunnel solutions to move tokens between Bitcoin and Hemi.
🔄 Why Use a Third-Party Bridge?
Hemi’s native Tunnel supports tunneling BTC, however, some assets (e.g., pumpBTC, iBTC) are not yet integrated. In these cases, a third-party bridge provides:
• Fast bridging times.
• Established track record of security and reliability.
• Wide token support.
🤝 Supported Third-Party Bridges
Below is a list of third-party bridges you can use to transfer BTC assets to Hemi. Each bridge has its own UI, fees, and specific token support.
Bridge
Link
Gas
📜 TL;DR:
Gas fees on Hemi is paid using ETH, the network's native token.
This approach is similar to Ethereum Layer 2 rollups like Optimism, where gas fees are in their native bridged tokens.
🌐 Overview
In cryptocurrency networks, gas refers to the tokens used to pay transaction fees. These fees are essential for processing transactions and maintaining network security, compensating network operators for the real-world costs they incur.
🔧 Fee Mechanisms: Other Networks
For example, in the Bitcoin network, transaction fees are paid in BTC. Ethereum, on the other hand, uses ETH as gas. These fees serve the same fundamental purpose across different blockchains but are paid in the respective network's native tokens.
⛽ Gas Fees on Hemi
Hemi adopts a method akin to Ethereum Layer 2 rollups by using ETH as its gas token. This strategy enhances compatibility and user-friendliness, particularly for those accustomed to Ethereum's system.
To interact with the Hemi Network, users can obtain ETH and tunnel to Hemi. This ensures a seamless and efficient means for users to engage with the Hemi Network's services.
🔍
Hemi Virtual Machine (hVM)
📜 TL;DR:
Hemi’s hVM is an EVM upgraded with Bitcoin awareness.
The Hemi network maintains an EVM-visible Bitcoin node using Hemi’s custom “Tiny Bitcoin” (TBC) daemon.
A “Processed Bitcoin View” synchronizes all Hemi nodes as part of the EVM state transition.
🌐 Overview
Hemi’s hVM is an EVM upgraded with Bitcoin awareness via new precompile contracts that smart contracts can call to get data from the Bitcoin node embedded in the EVM.
🔍 Tiny Bitcoin Daemon (TBC)
The Hemi network maintains an EVM-visible Bitcoin node using Hemi’s custom “Tiny Bitcoin” (TBC) daemon. TBC syncs with the regular Bitcoin network over P2P and indexes Bitcoin blocks up to the height specified by the protocol.
When a Hemi Sequencer creates a block, they can optionally include an additional “Bitcoin Attributes Deposited” transaction communicating one or more new Bitcoin headers to the Hemi protocol.
🎚️ Processed Bitcoin View
When these transactions occur, all nodes on the Hemi network process these Bitcoin blocks at the same Hemi block height creating a “Processed Bitcoin View” synchronized across all Hemi nodes as part of the EVM state transition.
This synchronization ensures execution of all Bitcoin-aware smart contracts are deterministic across all nodes.
To expose Bitcoin data to smart contracts, hVM introduces a number of new precompile contracts accessible in the EVM which fetch the latest data from the Processed Bitcoin View maintained by the embedded TBC node at the time the request is made.
Oracles
🌐 Overview
Oracles play a critical role in bridging the gap between blockchain and the external world, enabling smart contracts on Hemi to access trustworthy off-chain data necessary for various use cases.
The most common applications of oracles include:
Providing up-to-date token prices for different pairs, which is essential for DeFi protocols and financial products.
Enabling dynamic NFTs that can change their properties based on real-world events, adding a layer of interactivity and uniqueness.
⎑ Push vs Pull
Oracles operate using two primary models:
Push Model: In this traditional approach, the oracle regularly pushes data to an on-chain contract, which dApps can access as needed.
Pull Model: This newer model involves oracles signing data and keeping it on an external network. When dApps need updated data, users pull the signed data and submit it on-chain with their transaction.
Pyth
Pyth offers push-based price feeds for Hemi.
Supported Networks:
Hemi Mainnet
Hemi Sepolia
Redstone
Redstone offers push-based price feeds for Hemi.
Supported Networks:
Hemi Mainnet
Hemi Sepolia
Stork
Stork offers pull-based price feeds for Hemi.
Supported Networks:
Hemi Mainnet
eOracle
eOracle offers pull-based price feeds for Hemi.
Supported Networks:
Hemi Mainnet
BTC Wallet Setup
📜 TL;DR:
, available as a browser extension and mobile app, is designed to let users easily manage their Bitcoin assets and interact with dApps.
The Architecture
📜 TL;DR:
Feature Summary
📜 TL;DR:
Motivation
📜 TL;DR:
(Mainnet) Add PoPPoints to Metamask
📜 TL;DR:
Prior to TGE, PoP miners on mainnet will receive PoPPoints tokens.
Support and Bug Reports
How to get help, report bugs, and disclose security vulnerabilities to Hemi.
Getting Help
Issue
Where to report
Upon verification, Hemi mints representative tokens equivalent to the deposited Bitcoin assets. These tokens are sent to the user’s Hemi address. Hemi mints the representative tokens after 6 Bitcoin confirmations, or approximately one hour.
Hemi’s Bitcoin Tunnel verifies the correct burning of tokens and prepares the custodianship system for withdrawal.
The custodianship vault is notified of the withdrawal request. In the case of a multisig vault, the required number of signatures is collected to authorize the withdrawal.
Once verified, the custodianship vault releases the corresponding Bitcoin or Bitcoin-native assets to the user’s Bitcoin address. It may take up to 12 hours to verify and release withdrawn BTC.
The hVM system constantly monitors for any unauthorized withdrawals. In Phase 0, this requires an externally owned account (EOA) to flag any potential issues. In later phases, event notifications will allow automatic detection of unauthorized actions. If any misbehavior is detected during the withdrawal process, the responsible custodian is slashed on Hemi, and corrective measures are taken to prevent unauthorized fund transfers.
This contrasts with BTC interoperability solutions like BTC header relay, where users must manually construct cryptographic proofs of misbehavior and relay them to the contract for validation, introducing higher costs and risks of error.
Ensuring Hemi's network integrity by leveraging Bitcoin's security, providing a dual layer of protection.
This integration with the Bitcoin blockchain affords Hemi an additional security layer, utilizing Bitcoin's PoW system as a basis for resolving disputes and ensuring trustworthiness.
As Bitcoin confirmations accumulate, the Hemi Network's "security wall" becomes increasingly formidable, creating an effective deterrent against malicious actors.
Setting a high barrier for network reorganizations, as disrupting Hemi would necessitate a highly improbable 51% attack on Bitcoin itself, a task too daunting even for nation-states.
This approach not only extends Bitcoin's security to the Hemi Network but also introduces a scalable, robust framework for transaction processing and network integrity.
The Hemi Network operates four kinds of specialized nodes: Bitcoin finality governors, Bitcoin-secure sequencers, Proof-of-Proof miners, and a modified Geth node.
The network’s nodes maintain its EVM and ensure decentralized operability across Bitcoin, Ethereum, and other EVM-compatible chains.
🌐 Overview
The Hemi Network connects to both the Bitcoin and Ethereum networks, allowing asset portability across both, enabling a third-party cross-chain ecosystem. To create this highly secure multichain ecosystem, the Hemi Network operates several kinds of decentralized nodes: Bitcoin finality governors, Bitcoin-secure sequencers, Proof-of-Proof miners, and a modified Geth node.
🛡️ Bitcoin Finality Governors (BFGs)
Regulate the network's security status by analyzing Bitcoin blocks for Hemi Network state proofs.
Determine the network's finality status, ensuring security.
Coordinate with Bitcoin-secure sequencers and proof-of-proof miners.
⚙️ Bitcoin-Secure Sequencers (BSS Nodes)
Integrate Hemi Network transactions with Ethereum mainnet transactions.
Maintain the network's consensus layer and manage staking, unstaking, and slashing operations.
Ensure a seamless connection between the Hemi Network and Ethereum for asset transfers.
🛠️Modified Geth Node
Operates as a customized Ethereum node, providing compatibility and connectivity between the Hemi Network and Ethereum.
Ensures data synchronization and transaction processing within the Hemi Network ecosystem.
🔗 Proof-of-Proof Miners (PoP Miners)
Secure the network by embedding state proofs into the Bitcoin blockchain.
Hash network headers to create cryptographic proofs and publish these to Bitcoin.
Receive tokens as rewards for their contributions.
👀 Sneak Peek WIP
Challengers
Monitor the Hemi Network for data accuracy and completeness.
Initiate challenge-response processes for discrepancies, ensuring integrity.
Receive a portion of the penalized stake for successful challenges.
⚡️ Achieving Decentralized Interoperability
This innovative approach ensures secure, decentralized interoperability among Bitcoin, Ethereum, the Hemi Network, and other EVM-compatible chains.
Current Bitcoin interoperability systems like BTC header relays exist, but come with significant limitations.
By embedding a full indexed Bitcoin node directly inside the EVM, hVM allows anyone to access Bitcoin's processed state efficiently and without introducing any trust assumptions.
dApp developers can now build all kinds of Bitcoin-aware dApps and custom Bitcoin interoperability infrastructure directly on hVM.
🚧 Limitations of Existing Approaches
Various Bitcoin header relay systems have been available on Ethereum as a primitive Bitcoin interoperability technology for nearly a decade. This approach has third-party relayers communicate new Bitcoin headers to a smart contract which maintains a lightweight view of Bitcoin consensus. Smart contracts can then verify a Merkle proof to verify that a specific Bitcoin transaction exists in the canonical Bitcoin chain.
However, this approach has significant limitations:
Relies on third-party relayers
Requires large inclusion proofs with expensive validation
Can only prove a transaction exists in Bitcoin (no UTXO set proofs, no balance proofs, etc.)
Recently, other protocols have designed alternate Bitcoin interoperability primitives like 3-way noncustodial escrow systems validated with zk proofs, or smart-contract-controlled wallets run by the network validator set where network Sequencers facilitate UTXO queries.
However, these other approaches are only designed to serve specific use cases, and still don't provide smart contracts with a complete view of Bitcoin's state. Developers building on these primitives are also forced to accept the governance/security models that these one-off primitives provide, such as trusting a Sequencer doesn't withhold data from a UTXO query.
💡 With hVM, we set out to create something much more powerful and flexible that enabled anyone to build custom Bitcoin interoperability infrastructure directly in the EVM with complete access to Bitcoin state.
🔍 How?
By embedding a full indexed Bitcoin node directly inside the EVM, hVM:
Does not involve any relayer system or trust assumption
Does not require validation of any expensive proofs
Supports secure queries for Bitcoin information that requires processing the entire chain like UTXOs, balances, and eventually popular Bitcoin metaprotocols
🏗️ Use Cases
hVM enables dApp developers to build all kinds of Bitcoin-aware dApps and custom Bitcoin interoperability infrastructure which was previously infeasible or outright impossible on other networks.
Some use cases of hVM include:
Non-custodial BTC<->ETH asset exchanges
Bitcoin MEV marketplaces
Bitcoin lending markets
Bitcoin staking systems
Custom smart-wallets with configurable validator sets and signing technology
Custom Bitcoin tunnels (Hemi’s own standard Bitcoin tunnel is being built entirely on hVM)
Presume transactions are valid unless disputed within a specific period.
Reduce congestion on the main chain (L1)
❌ Cons:
Introduce finalization delays due to the challenge period for dispute resolution
Place the responsibility of fraud detection on users
Rely on centralized sequencers and proposers, causing hidden transaction queues (mempools) and centralized chain state communication
Zero-knowledge Rollups
✅ Pros:
Validate transactions before confirming them on the main chain (L1)
Potentially enable privacy features by leveraging zk proofs (although current implementations like ZKsync do not currently incorporate significant privacy features)
Reduce congestion on the main chain (L1).
❌ Cons:
Introduce potential vulnerabilities due to complex cryptographic systems
Often require a trusted setup for implementation.
Rely on centralized sequencers and proposers, causing hidden transaction queues (mempools) and centralized chain state communication
Open the UniSat extension and click 'Create new wallet.'
2. Create a password
3. Copy your secret recovery phrase
Make sure to save your private key. Your private key provides full access to your wallet and funds.
Hemi team members will never ask you for private keys.
Do not share it with anyone.
After you have saved your private key in a secure area, click 'Continue.'
4. Select address type
Hemi currently uses two primary address types:
Legacy (P2PKH): PoP mining currently requires a P2PKH address, although this may change at some point in the future.
Native SegWit (P2WPKH): For everything else on Hemi (i.e., Bitcoin tunneling), any address type can be used but P2WPKH will (generally) be the cheapest fee-wise.
We recommend creating a Native SegWit wallet to jumpstart in the Bitcoin ecosystem. New wallets and other address types can be created in the future.
After you have selected your address type, click 'Continue.'
Smart contracts on Hemi can access Bitcoin data by calling the hVM precompile contract.
Future protocol upgrades will add additional precompile calls to provide additional information.
🌐 Overview
Smart contracts on Hemi can access Bitcoin data by calling the hVM precompile contract addresses, which query the deterministic TBC node running inside the EVM.
Future protocol upgrades will add additional precompile calls to provide additional information like Bitcoin fee levels, Bitcoin block construction information, and popular metaprotocols like Ordinals, BRC-20s, and Runes.
ℹ️ "Phase 0" Precompile Summary
Name
Address
Description
BtcBalAddr
0x40
Gets the balance of an address in satoshis. Supports all address formats: P2PKH, P2SH, P2WPKH, P2WSH, P2TR.
BtcUtxosAddrList
0x41
Gets the list of Unspent Transaction Outputs (UTXOs) for an address. Supports pagination.
These points are entirely separate from the Incentivized Testnet / Mainnet seasons.
View your tHEMI balance and transactions directly in MetaMask.
The tHEMI token contract address is 0xC5D2E164601c59c2cD760669e849BFe498003e21.
🌐Overview
Prior to TGE, users who engage in securing Hemi (mainnet) to Bitcoin will receive PoPPoints tokens, which are distributed based on how many other users are actively PoP Mining.
These PoPPoints tokens are initially non-transferrable. During the initial mainnet release, all miners who get a PoP publication for a keystone into Bitcoin within ~1.6 hours will share 100 PoPPoints for that keystone round.
As mainnet evolves, this payout algorithm will be adjusted.
📚 Tutorial
Video
1. Open MetaMask
2. Access Token Selection
Navigate to Tokens
Click on the three vertical dots on the right of the token menu
Import tokens
3. Enter the Contract Address
Type in the tHEMI token contract address 0xC5D2E164601c59c2cD760669e849BFe498003e21 into the Token Contract Address field.
If the address is recognized, MetaMask will automatically populate the Token Symbol and Token Decimal fields. For PoPPoints, you should see a symbol POPand 18 decimals.
4. Import
Confirm the accuracy of the provided information, and then click on Next.
If successful, you should see your PoPPoints tokens in your wallet's token list:
For now, these tokens are non-transferrable.
Partnership inquiries
— #create-ticket
Email
Bugs in Hemi services (app, explorer, etc.)
— #create-ticket
Bugs or feature requests for open-source software
Open a on the relevant repository
Security vulnerabilities
Security Vulnerabilities
If you've found a security vulnerability in Hemi, we want to hear about it.
Do not test against production systems, disclose vulnerabilities publicly, or report them in GitHub issues. Doing so puts users at risk, may violate applicable law, and will disqualify you from rewards.
Denial-of-service testing, social engineering, and volumetric attacks are explicitly out of scope and prohibited. All security research must be conducted in accordance with the policies outlined in our Bugcrowd program.
How to Report
All vulnerability reports must be submitted through our official Vulnerability Disclosure Program on Bugcrowd. We do not accept vulnerability reports via email, Discord, social media, or any other channel. Reports submitted outside of Bugcrowd will not be reviewed or eligible for rewards.
When reporting, the more information you can provide, the faster we can triage and confirm the vulnerability. Reports with clear reproduction steps and screenshots are highly valued.
Bug Bounty Program
Hemi also operates a private Bug Bounty program on Bugcrowd with paid rewards. Researchers who submit high-quality reports through our Vulnerability Disclosure Program may be invited to participate at Hemi's discretion.
Responsible Disclosure
Please do not discuss any vulnerabilities outside our Bugcrowd program without express consent from Hemi Labs. Follow our program disclosure policy for full details.
Hemi provides Safe Harbor for security research conducted in good faith under our program policy. See the full Safe Harbor terms on our Bugcrowd program page.
For other security-related questions or concerns, please contact [email protected].
Hemi’s Ethereum Tunnels facilitate secure and efficient asset transfers between Ethereum and the Hemi network.
While similar to other “lock-and-mint” cross-chain mechanisms, Hemi’s Tunnels are distinguished by their integration with Bitcoin’s Proof-of-Work finality model and decentralized dispute mechanisms, offering faster settlement times and enhanced security.
By integrating these features, Hemi’s Ethereum Tunnels offer a more efficient and secure mechanism for cross-chain asset transfers, benefiting from both Ethereum’s smart contract capabilities and Bitcoin’s unrivaled security.
🚊 How Ethereum Tunnels Work
The Ethereum Tunnel process involves locking assets on one network while minting corresponding representative tokens on the other network. For Ethereum-native assets, tokens are minted on Hemi once the assets are locked in a Hemi validation contract on Ethereum.
This allows seamless asset transfers across chains, enabling users to leverage the strengths of both networks while minimizing the friction of cross-chain operations.
Deposit to Hemi
The process begins with the user initiating a deposit transaction on Ethereum. This deposit locks up Ethereum-native tokens in a Hemi validation contract on Ethereum. The validation contract plays a critical role by securing the assets and ensuring they remain locked throughout the tunneling process.
Once the deposit is secured in an Ethereum block, Hemi’s block derivation protocol kicks in. The Sequencer, responsible for ordering and generating Hemi blocks, is required to include the deposit in the first Hemi block derived from the Ethereum block that contains the deposit transaction. This ensures that the deposit is acknowledged in Hemi’s L2 environment almost immediately after its validation on Ethereum.
After the deposit is included, Hemi mints a representative token on the Hemi Network, which serves as the equivalent of the locked asset on Ethereum. This token can now be freely used within the Hemi ecosystem, allowing users to engage with dApps or perform any transaction that requires the asset. You should receive your deposit within
Withdrawal to Ethereum
To return the assets back to Ethereum, the user submits a withdrawal transaction on Hemi. When the withdrawal request is submitted, the representative tokens on Hemi are burned, which signals the user’s intent to withdraw their corresponding Ethereum-native assets.
Hemi’s state transition system updates its rollup state root, which is then submitted to Ethereum by a Publisher. The state root acts as a cryptographic proof of the transactions that occurred on Hemi, including the user’s withdrawal request.
The key to finalizing the withdrawal lies in Hemi’s use of Bitcoin finality, which is a significant differentiator from other optimistic rollup bridges. (In traditional optimistic rollups, the finality of cross-chain transactions is delayed by a dispute window, during which fraud proofs can be raised. Hemi accelerates this process by leveraging Bitcoin’s highly secure Proof-of-Work consensus mechanism to finalize the state root on Ethereum.) This process takes roughly 4
🔄 Tunneling Hemi-Native and Bitcoin-Native Assets to Ethereum
Hemi’s tunneling process is not limited to Ethereum-native assets. Phase 2 of Hemi's Ethereum Tunnel will support Hemi-native and Bitcoin-native assets, extending the functionality of the tunnels to a broader range of assets. This capability is crucial for enabling the use of Bitcoin within Ethereum’s extensive decentralized finance (DeFi) ecosystem, which traditionally lacks native Bitcoin interoperability.
Withdrawal to Ethereum
The process for tunneling Hemi-native assets begins with the user submitting a deposit transaction on Hemi, locking their native assets within Hemi’s native asset tunnel contract.
Similar to Ethereum-native asset transfers, the state root containing this deposit transaction is published to Ethereum.
Once the rollup state root is confirmed (following Bitcoin finality and the absence of any disputes), the user submits a deposit proof on Ethereum to claim the corresponding representative tokens. These tokens represent the Hemi-native assets within the Ethereum ecosystem and can be used in Ethereum dApps or traded just like any other Ethereum-based token.
Deposit to Hemi
Moving Hemi-native assets back to Hemi from Ethereum involves a similar process. The user initiates a withdrawal on Ethereum, burning the representative tokens.
This triggers Hemi’s block derivation protocol to include the withdrawal in the next Hemi block derived from the corresponding Ethereum block.
Once the withdrawal is processed, the Hemi-native assets are transferred from Hemi’s native asset tunnel contract back to the user, completing the return to Hemi’s L2 environment.
One of the core advantages of this system is its flexibility. It allows Bitcoin-native assets, which are traditionally siloed on the Bitcoin network, to be tunneled through Hemi and into Ethereum. This enables Bitcoin to participate in Ethereum’s DeFi ecosystem while maintaining the security and decentralization that Bitcoin’s Proof-of-Work consensus provides.
🔍 Comparison to Standard Ethereum Bridges
While Hemi’s Ethereum Tunnels share the foundational principles of traditional bridges like the Standard Bridge, there are several critical distinctions:
The primary distinction between Hemi’s Tunnels and standard bridges lies in the finality model and security architecture. Standard bridges depend on an optimistic model with a delayed dispute window. The withdrawal process on these bridges typically takes a week or longer, as they await the potential for fraud proofs before finalizing the transaction.
Hemi Tunnels enhance this process by incorporating Bitcoin finality. Instead of relying solely on an Ethereum-based dispute window, Hemi uses Bitcoin’s Proof-of-Work consensus as an additional layer of security. This allows Hemi to finalize transactions more quickly, as the Bitcoin network’s finality period is shorter and more secure than the traditional dispute windows of optimistic rollups.
Hemi will decentralize the dispute process by distributing the Challenger role across a wider set of participants. This decentralization mitigates the risk of collusion or centralization of power within the bridging system, offering a more secure alternative to centralized or semi-centralized dispute mechanisms found in standard bridges.
Create a Capsule
📜 TL;DR:
Capsule is an asset transfer protocol that allows anyone to batch and transfer multiple assets in a single package on Hemi.
Additionally, Capsule provides users and developers with advanced functionality like gasless transactions, re-routing/recalling, and configurable security.
Earn and track Hemi for completing this tutorial!
📖 Background
Capsule is an asset transfer protocol that allows anyone to batch and transfer multiple assets in a single package on Hemi.
Additionally, Capsule provides users and developers with advanced functionality like gasless transactions, re-routing/recalling, and configurable security.
Visit to learn more about the Capsule protocol.
🏁 Prerequisites
(or other Hemi assets)
📚 Tutorial
Video
1. Visit the Hemi Capsule
2. Connect your MetaMask wallet
Connect your MetaMask wallet by clicking the button in the top-right corner.
Capsule currently only supports the Hemi testnet network. View our official to add the Hemi testnet network to your wallet and ensure that you are connected to the Hemi network before proceeding.
3. Add assets to your Capsule
Click 'Add Asset' to select the Hemi assets you would like to add to the Capsule. You may add any quantity and any combination of any Hemi assets as desired.
Optional: You may change the name of the Capsule generated in the text box below the 'Add Asset' button.
When finished, click 'Continue'.
4. Add features
Capsule comes with a variety of optional features, including:
Gasless Pickup: The assets can be redeemed without pay gas costs.
Time Locked: The assets cannot be redeemed until a specific time.
Password Protection: A password is required to redeem the assets (a unique and random password is provided by Capsule).
After selecting and adjusting any preferred features, click 'Continue'.
5. Verify the transaction
Once you are satisfied with your Capsule, click the checkmark that says 'I've read and I agree to the terms listed in the Capsule Terms of Service and Privacy Policy.'
When finished, click 'Continue'.
6. Approve the assets included in your Capsule
To finalize your Capsule, you must approve all the assets you included inside your MetaMask wallet.
When finished, click 'Continue'.
7. Confirm the transaction
Confirm your transaction in MetaMask.
8. All done! 🎉
Copy your Capsule transfer link (and if included, your redemption password) and distribute your Capsule as desired!
HelloWorld.sol
🟩 This is a beginner track.
📜 TL;DR:
In this tutorial, we will utilize , a versatile, open-source web-based platform, to develop and deploy our smart contract onto Hemi testnet.
This guide is tested to work with Solidity version 0.8.26. If you experience any issues, try setting this version explicitly in the Solidity Compiler tab on Remix.
Earn and track Hemi for completing this tutorial!
🏁 Prerequisites
📚 Tutorial
1. Go to
Remix IDE is a powerful, open-source web application for developing, compiling, and deploying Ethereum smart contracts with ease.
2. Add the Smart Contract
In Remix IDE, start by creating a new file named HelloWorld.sol.
The following contract is a basic example designed for interaction. Copy the code below and paste it into the file HelloWorld.sol.
3. Compile the Contract
Select Compile HelloWorld.sol button to use the Remix IDE's Solidity compiler. Check for any compilation errors and fix them.
4. Connect Remix To MetaMask
The address you choose to connect MUST have some ETH (recommended at least 0.01 ETH) to pay for contract deployment fees. Refer back to earlier documentation to with ETH.
Choose Injected Provider - MetaMask under "Environment".
5. Confirm the Connection
A pop-up from MetaMask will appear to confirm the connection. Select Next.
Select Connect
6. Link to Hemi Account
Link to the relevant Hemi account in the "Account" drop-down.
7. Deploy
Execute the deployment of your smart contract to the Hemi network directly from Remix IDE.
Uncheck Publish to IPFS.Note: if you get a warning about Gas Limit, you may ignore it and proceed.
Select Deploy
Your MetaMask will pop-up to confirm the deployment of your smart contract. Select Confirm
🥳 Wohoooo! If successful you should see a ✅ in the console.
⚠️ If it fails, double check that the Solidity version in the compiler is the correct version.
Using Hemi
Follow along with some of the tutorials to help you get a head start when building your first Hemi project.
Note: You may be eligible to earn Hemi points by completing tutorials. Visit our dashboard for more information on active quests.
Wallet Setup
Tutorial
Description
Difficulty
Tunneling
Tutorial
Description
Difficulty
Developer Tooling
Tutorial
Description
Difficulty
PoP Miner
Tutorial
Description
Difficulty
EVM Wallet Setup
📜 TL;DR:
Hemi Bitcoin Kit (hBK)
📜 TL;DR:
Grants
🏁 Getting Started
Are you building the next killer Hemi application (hApp) or a service that adds value to Hemi's ecosystem? Fill out the form below to let us know what you're building and apply for a grant!
Want some inspiration? Check out the lists below for some of the projects we're most excited about.
If you don't see your idea on this list, we'd still love to hear what you're interested in building!
Tunnel BTC via Native Tunnel
📜 TL;DR:
Official Links
Links to everything Hemi.
0-2 minutes
.
0 minutes.
Once Bitcoin finality is achieved, and assuming no disputes are raised through the decentralized Challenger role, the state root is confirmed, and the user can submit a withdrawal proof on Ethereum to claim their assets from the Hemi validation contract. A proof may take up to 24 hours.
The withdrawal proof ensures that the burned representative tokens on Hemi correspond to the original locked Ethereum-native tokens. Upon successful validation of the proof, the Ethereum-native assets are unlocked, completing the cross-chain asset transfer.
The Hemi Bitcoin Kit (hBK) is a library of smart contracts for developers to use to build Bitcoin-aware smart contracts.
The hBK abstracts away the complications of interacting directly with the hVM Precompiles; parsing query results into data structures that are easy to understand and use.
The Hemi Bitcoin Kit (hBK) is a set of smart contracts designed to bridge the Ethereum and Bitcoin blockchains, enabling developers to build Bitcoin-aware dApps on an EVM with full access to Ethereum assets and the cross-chain data calls that ETH L2s provide.
The hBK abstracts away the complexities of dealing directly with hVM's low-level precompile contracts.
🧑💻 How is hBK Unique?
The hVM is based on the Ethereum Virtual Machine (EVM) and comes stocked with built-in precompiles to interact with the embedded Bitcoin full node.
Unlike other Bitcoin interoperability solutions, Bitcoin-aware smart contracts built using hBK don't rely on any external relayers, require gas-intensive proof validation, or suffer from limited views of Bitcoin's state.
Performing a query for Bitcoin data is just as easy as reading the state of other contracts in the EVM. No need to design complex smart contracts that register requests to handle after the requested data is relayed.
Pre-validated data directly available in the EVM significantly reduces both the complexity and cost of developing and maintaining Bitcoin-related applications
The Hemi Bitcoin Kit brings five benefits to developers:
Easier development: Access to a wide range of Bitcoin data is just one smart contract call away.
Rich data: Access Bitcoin state like UTXOs and balances that is impractical or outright impossible to get with other solutions.
Security and reliability: dApps get immediate information about any relevant events on the Bitcoin blockchain without having to rely on third-party relayers or trusted oracles.
Composability: Anyone can design new layers of Bitcoin DeFi infrastructure for others on which to build.
Cost-effectiveness: The hVM uses far less gas than other approaches and there's no need to incentivize third-party bots to watch for and relay events.
🏗️ Use Cases
Some examples of unique applications that the Hemi Bitcoin Kit enables:
Custom Bitcoin tunnels: Connect chains to the Bitcoin network using customized security, cost, and speed settings.
Trustless BTC staking and re-staking protocols: 99% of BTC is unbridged and/or unproductive. With Hemi, BTC can be used to secure networks and earn yield.
Bitcoin-authenticated AI-model marketplaces: As an example of an AI use case, model owners can publish Bitcoin-secure hashes of their model weights, timestamping them to the Bitcoin blockchain.
Multichain DAOs: Hemi DAOs operate across both Bitcoin and Ethereum, making decisions based on the collective input of stakeholders from both communities.
🛠️ Bitcoin Kit Demo
The Hemi Bitcoin Kit Demo provides developers with an interactive code editor and execution environment featuring six essential Bitcoin blockchain functions. Users can do the following:
Retrieve address balances,
Access the latest block headers,
Query block headers by specific height,
Get detailed transaction information,
Check transaction confirmations,
List unspent transaction outputs (UTXOs) for any address.
Each function comes with pre-written, well-documented code that demonstrates how to interact with Bitcoin's blockchain through smart contract calls, making it easy for developers to understand and implement Bitcoin functionality in their own applications. The demo serves as both a learning tool and a practical reference for app development, allowing users to execute real Bitcoin queries and see immediate results without needing to set up their own development environment.
BtcTxByTxid
0x42
Gets parts of a Bitcoin transaction by its TxID. The caller can specify which part(s) of the transaction to return using packed bitflags to increase gas efficiency by dropping unnecessary data.
BtxTxConfirmations
0x43
Gets the number of confirmations a specified transaction by TxID has.
BtcLastHeader
0x44
Gets the most recent Bitcoin header known by hVM.
BtcHeaderN
0x45
Gets the canonical Bitcoin header at height N.
BtcAddrToScript
0x46
Converts a Bitcoin address to its corresponding script representation. Supports all address formats: P2PKH, P2SH, P2WPKH, P2WSH, P2TR.
MetaMask Extension Download to execute transactions and smart contract interactions within the Ethereum network.
📚 Tutorial
Video
1. Open the MetaMask Extension
2. Access Network Selection Settings
Click on the network-selection dropdown, which is found at the top left of the MetaMask window.
3. Select "Add Network"
4. Add a Network Manually
5. Enter Network Details
In the "Add a network manually" settings, input the following information for the Hemi testnet network:
Hemi mainnet
Gas Token/Currency Symbol
ETH
ChainID
43111
RPC API endpoint
https://rpc.hemi.network/rpc
Explorer
For Hemi testnet, input the following information instead:
Hemi testnet
Gas Token/Currency Symbol
ETH
ChainID
743111
RPC API endpoint
https://testnet.rpc.hemi.network/rpc
Explorer
6. Your EVM wallet is ready to go! 🎉
Select Save to add the Hemi network to your MetaMask.
🔄 Switch between Ethereum Mainnet and Sepolia
After you have set up your EVM wallet on MetaMask, you may want to explore some of the unique features on Hemi testnet. This requires switching the connected network in your MetaMask wallet.
To ensure visibility of your ETH on the Sepolia testnet, toggle the Show test networksoption in MetaMask:
Select the drop down on the left
Toggle Show Test Networks
Select Sepolia
🤖 Bitcoin-Aware hApps (Using hVM or hBK)
These are hApps that directly take advantage of Hemi's EVM-level Bitcoin awareness.
Non-Custodial BTC / BTC Asset DEXes
A decentralized exchange to trade Bitcoin or Bitcoin-based assets without requiring users to give up custody of their funds.
Non-Custodial Bitcoin Lending
A dApp to enable Bitcoin-based lending (either borrowing Bitcoin itself or using Bitcoin as collateral for other loans) without users giving up custody of their funds.
Bitcoin "smart wallets" with custom key manager sets
Users/smart contracts create Bitcoin wallets controlled by configurable validator sets and managed on Hemi; smart wallet owners can specify transactions that should be performed on Bitcoin from their wallet, and validators work together to sign and propagate on Bitcoin
Bitcoin "transaction forwarding"
A dApp where users/smart contracts can send tunneled BTC on Hemi to a liquidity provider, who then sends tunneled BTC to the sender’s specified destination.
Bitcoin MEV Marketplace / Tx Accelerator
A dApp where users can submit raw Bitcoin transactions or their hashes along with an attached reward (in $HEMI, $ETH, etc.), which will be paid out to the Bitcoin miner that includes their specified Bitcoin transaction in a block
Ordinals/Inscriptions "minting-as-a-service"
A service that facilitates the creation of Ordinals.
Any other novel Bitcoin dApp that benefits from introspection into Bitcoin data
✨ AI hApps
These are hApps that utilize AI directly or provide services that AI developers want to use.
ZK-Verified MLaaS (ML as a Service)
Model owners authenticate their private models to Bitcoin via Hemi by publishing a hash of the model weights. Consumers select a model and send data to perform inference on, and the model owner computes the requested inference and returns the result along with a zero-knowledge proof demonstrating correct execution against the specified model.
Private FHE-based MLaaS
Similar to zk-verified MLaaS, but the model consumers send fully homomorphically encrypted input data, meaning the model owner can't see the consumer's data they are performing inference with.
Training Data Marketplace
Marketplace for users to buy and sell the rights to use different data sets for model training, producing a proof of data licensing authenticated to Bitcoin via Hemi. Optionally, ZK-verified training proofs could be employed to cryptographically prove that a model was only trained on licensed data.
Decentralized Machine Learning
Peer-to-peer marketplaces for buying computing power. Could either be generic compute purchasing, or AI-specific distributed training/inference protocols.
Portfolio Management Agents and DAOs
Autonomous AI agents that trade assets or perform other on-chain actions on Hemi for a user or group of users.
Crowd-Sourced Data Classification
Humans perform data classification/labeling on data so it can be used for machine learning, and are paid a reward if their classification is aligned with the majority of other users.
💡 Other hApp Ideas
DEXes
Lending Markets
Payment Channels
Bridges
Yield Aggregators
Algorithmic Stablecoins
On-chain Games
NFT Projects
NFT Marketplaces
Real World Assets
Other Projects
Custom PoP miners
PoP mining embedded in a widely-used Bitcoin wallet
Hemi metrics/explorers/chain analytics
Improvements to existing services (explorer, portal, demo hApps, etc.)
Bitcoin timestamping services via Hemi
Oracles
Apply Here
Move your BTC to Hemi by using the Bitcoin Tunnel, enabling interactions within the Hemi Network ecosystem with Bitcoin assets.
An EVM and BTC wallet are required to move BTC assets via the Bitcoin Tunnel.
A minimum of 0.0001 BTC is required to deposit and withdrawal using the Native Tunnel.
🏁 Prerequisites
Acquire BTC - BTC can be purchased on any number of exchanges and on-ramps.
TESTNET ONLY
If you plan on developing on or interacting with Hemi testnet, alternative prerequisites may apply. To test out the Bitcoin Tunnel on testnet, you can obtain tBTC (Testnet Bitcoin) via the Direct Faucet Access.
Select your network of choice using the network dropdown located at the bottom left.
2. Connect wallet
Click 'Connect Wallets' in the top-right corner of the Hemi Portal.
3. Connect your EVM wallet
Currently, MetaMask and Rabby are the only EVM wallets Hemi supports. Our team is working to add support for additional wallets.
Connecting an EVM wallet is required for the initial version of the Bitcoin Tunnel. The address connected will receive the tunneled Bitcoin assets.
4. Connect your BTC wallet
Connect your BTC wallet (currently only UniSat supported). If you do not have a UniSat wallet, you can view our tutorial to create and set one up.
5. Select 'Bitcoin' as the 'From Network'
Ensure that you are connected to the Bitcoin network.
Tunneled BTC will be sent to the EVM address connected (denoted by the 'Receiving Hemi Address' at the bottom of the screen). In future versions, you will be able to manually input the preferred receiving address.
6. Enter the amount of BTC to tunnel
Input the amount of BTC you wish to tunnel to Hemi. There is a minimum amount of 0.0001 BTC to deposit and withdrawal.
After you have confirmed the gas fee and wish to proceed with the deposit, click 'Deposit.'
7. Confirm the deposit in UniSat
Confirm your BTC deposit in the UniSat browser extension.
8. You have successfully tunneled BTC to Hemi! 🎉
Your transaction has been initiated and must go through two confirmation periods to confirm your deposit:
Withdrawal from BTC address (~1hr) - When you initiate a deposit request, a transaction is signed from your BTC address to transfer the specified amount into a secure vault on the Bitcoin network. This deposit requires six block confirmations, which generally takes about one hour to complete.
Deposit into EVM Hemi address - Once the deposit is fully confirmed on the Bitcoin network, the Hemi Network validates the transaction and mints a corresponding token receipt (hemiBTC) on the Hemi blockchain, ensuring a seamless transition of assets.
You can check the status and view the transaction in the 'Transaction History' tab.
hemiBTC can be tracked and added to your wallet at the following contract address: 0xAA40c0c7644e0b2B224509571e10ad20d9C4ef28
Manual confirmation of deposit
After six confirmations, Hemi can confirm a successful deposit from the Bitcoin network and deposit the funds to your address. Occasionally, the vault operator will require a manual confirmation in order to complete the deposit.
Store
Status
Apps
Hemi Portal
Hemi Tunnel
Hemi Staking
Mainnet Block Explorer
Testnet Block Explorer
Social Media
Discord
Farcaster
GitHub
LinkedIn
Luma
Official Domains
Below is a list of our official domains. Any domains not listed here are third-party and are not operated, owned, or affiliated with Hemi Labs.Beware of malicious sites claiming to represent Hemi.
Deposit BTC, ETH, or stablecoins into reward contracts and earn passive income from ecosystem incentives.
Earn rewards from Hemi and its partners, with bonuses for early adopters and high-value deposits.
🌐 Overview
provides a seamless way for users to earn rewards by locking up assets within the Hemi ecosystem. Unlike traditional Proof-of-Stake (PoS) mechanisms, staking on Hemi does not involve securing the network or slashing risks. Instead, it enables users to deposit assets into specialized reward contracts to participate in yield opportunities across partner protocols.
Key Benefits:
No Slashing Risk – Assets are never used for network validation.
Flexible Deposits & Withdrawals – No bonding periods; stake and unstake anytime.
Multi-Asset Support – Stake Bitcoin, Ethereum, and stablecoins assets.
🔍 How It Works
Hemi’s staking contracts function differently from PoS staking by offering a reward-based deposit model:
Users deposit assets into smart contracts designed for staking rewards.
Rewards accumulate over time, distributed by Hemi and integrated partners.
No lock-up requirements – Users can unstake at any time.
✅ Supported Assets
Hemi’s staking program supports a variety of assets across Bitcoin, Ethereum, and stablecoin categories.
Bitcoin Assets:
Asset
Provider
Description
Ethereum Assets:
Asset
Provider
Description
🎁 Rewards
Hemi’s staking program offers rewards based on asset deposits and participation within the ecosystem:
Earn ecosystem rewards across Hemi and partnered protocols.
Points-based incentives may apply for early participants and high-value deposits.
Earn additional benefits on highly-incentivized asset groups.
FAQ
General
Where can I learn more about Hemi?
You can learn more about Hemi by reading our documentation, visiting our website, reading the whitepaper, or joining the community on Discord.
How do I earn points, and how does incentivized testnet work?
Check out for the most recent info.
Smart Contract Deployments
Why is my smart contract deployment failing on the testnet even though the contract seems to be created?
🌐 Overview
Deployment issues on testnet can stem from using features or opcodes not yet supported by the testnet's version of the EVM.
Gas Usage (e.g. are you at 100%?)
🌐 Overview
Deployment failures can often be traced back to insufficient gas allocation.
When a transaction consumes all allocated gas without completing, the network rejects it to avoid executing transactions that could run indefinitely.
Did you verify your Smart Contract?
🌐 Overview
Preparing your smart contract for deployment involves a critical step: verification. This process not only helps in catching potential issues early but also enhances the contract's integrity before it goes live.
🔍 Verification is Key
Verifying your smart contract is paramount to ensure its readiness for deployment. This crucial step provides valuable insights into any potential errors or vulnerabilities that could compromise its performance or security.
Navigating the Hemi Portal
What tokens are currently supported?
You can use our platform to access a variety of tokens, including ETH, USDT, USDC, and DAI.
What is tunneling? What is a tunnel?
The Hemi Tunnel is designed for seamless cross-chain transactions.
Hemi’s Bitcoin and Ethereum Tunnels improve security while decentralizing asset portability. They do this by leveraging the Hemi Virtual Machine, which gives the network direct awareness of Bitcoin’s and Ethereum’s states.
Capsules
What is Capsule?
Capsule is an asset transfer protocol that allows anyone to batch and transfer multiple assets in a single package on Hemi. Additionally, it provides users and developers with advanced functionality like gasless transactions, re-routing/recalling, and configurable security. Learn more about Capsule Labs by visiting the Capsule .
This guide explains how to verify smart contracts deployed on the Hemi blockchain using two methods:
Manual UI-based verification via Blockscout.
API-based verification using Hardhat.
🏁 Prerequisites
Hemi RPC URL and deployed contract address.
Contract source code available (flattened only if verifying manually via the Hemi Blockscout UI).
🖥️ Blockscout UI Verification
Manual verification is performed directly through the Blockscout UI. This method requires flattening the contract source code and uploading it manually.
1. Flatten the contract
Flattening a contract is necessary when verifying through the UI.
For Hardhat:
For Foundry:
2. Access Hemi Blockscout
Go to Hemi Blockscout Explorer and navigate to the page.
3. Input contract information
Smart contract / Address: Paste the address that your smart contract was deployed to.
Copy and paste the entire flattened contract code into the Contract code field and click 'Verify & publish'.
4. Submit for verification 🎉
Once all required details are entered, submit the form. BlockScout will compare the uploaded source code with the deployed bytecode. If they match, your contract will be verified.
To confirm verification, search for your contract address on BlockScout. A green check mark next to your contract indicates successful verification.
🚧 Hardhat Verification
1. Install dependencies
If you haven't already installed Hardhat and the verification plugin (adapted for Blockscout), run the following:
2. Configure Hardhat for Hemi
In your `hardhat.config.js`, set up the Hemi network and include Blockscout API information for contract verification:
3. Verify the contract
Once deployed, you can verify the contract using Hardhat’s `verify` command. Make sure to include any constructor arguments if necessary:
4. Verification successful! 🎉
If you encounter the following error, visit the and search your contract address to confirm verification:
Tunnels
📜 TL;DR:
Bridging i.e. Tunneling allows the transfer of assets between disparate blockchains (such as between distinct L1s or between an L1 and an L2).
While bridging addresses the siloed nature common to most blockchains, it typically suffers from centralization because most blockchains do not maintain state awareness of other networks.
Hemi Network enables sophisticated asset transfer and decentralization by maintaining protocol-level state awareness of both Bitcoin and Ethereum.
🌐 Overview
Blockchain networks typically operate as independent systems with no knowledge of other networks, creating a siloed environment. This isolation makes it impossible to transfer assets directly from one chain to another.
Bridges are developed to address this issue, enabling asset transfers between different blockchains. They function by accepting a token from one blockchain (chain A) and issuing a corresponding placeholder or wrapped token on another blockchain (chain B). This wrapped token represents the original token and can be redeemed for it.
🖼️ Example
To illustrate, consider the process of transferring bitcoin to Ethereum. A user sends bitcoin to a bridge connecting to the Ethereum network. This bridge then issues a wrapped Ethereum token representing the bitcoin.
The user can utilize this wrapped bitcoin within the Ethereum network or return it to the bridge to reclaim the original bitcoin on the Bitcoin network.
🔍 Broader Applications & Limitations of Bridges
Bridges are not limited to transferring assets between distinct blockchains. They can also facilitate transfers between different network layers, like connecting a Layer 1 (L1) blockchain like Ethereum to a Layer 2 (L2) rollup chain. This connection allows assets to benefit from the L2's lower fees and other features.
However, bridges often rely on centralized infrastructure due to the lack of protocol-level awareness between the connected chains. For example, while an L2 might maintain the state of its corresponding L1, the L1 lacks inherent knowledge of the L2. This disconnect necessitates a centralized third party to maintain awareness of both chains.
🔒 Security and Efficiency
The security model behind Hemi’s Ethereum Tunnels leverages the strengths of both Ethereum and Bitcoin. By integrating Bitcoin finality, Hemi ensures that cross-chain transactions achieve a level of finality backed by Bitcoin’s Proof-of-Work consensus, widely considered the most secure consensus mechanism in blockchain technology.
This significantly reduces the time it takes to finalize cross-chain transactions and provides strong protection against censorship or fraud attempts during the tunneling process.
The decentralized Challenger role also strengthens Hemi’s security. Rather than relying on a centralized entity to raise disputes, any participant in the Hemi ecosystem can act as a Challenger, further decentralizing the network and increasing its resistance to fraud.
🏗️ A Phased Approach
The phased approach to Hemi’s Ethereum and Bitcoin Tunnels aims to progressively enhance the security, decentralization, and asset support for cross-chain transfers. Each phase introduces key improvements to the settlement mechanisms and expands the range of assets that can be tunneled across Ethereum, Bitcoin, and Hemi, all while focusing on increasing trust minimization and reducing reliance on centralized actors.
👀 Sneak Peek WIP
Introducing Tunnels for Decentralized Asset Transfers
hBK Smart Contract
🌐 Overview
The Hemi Bitcoin Kit smart contract provides utilities for interacting with Bitcoin data on the Hemi blockchain.
hardhat-verify found one or more errors during the verification process:
Etherscan:
The block explorer's API responded that the contract contracts/MyToken.sol:MyToken at <CONTRACT ADDRESS> is already verified.
This can happen if you used the '--force' flag. However, re-verification of contracts might not be supported
by the explorer (e.g., Etherscan), or the contract may have already been verified with a full match.
struct UTXO {
bytes32 txId; // Transaction ID
uint256 index; // Index of the UTXO
uint256 value; // Value in satoshis
bytes scriptPubKey; // Script public key
}
struct Transaction {
bytes32 containingBlockHash; // Hash of the containing block
uint256 transactionVersion; // Transaction version
uint256 size; // Transaction size
uint256 vSize; // Virtual size of the transaction
uint256 lockTime; // Lock time
Input[] inputs; // Array of inputs
Output[] outputs; // Array of outputs
uint256 totalInputs; // Total number of inputs in the original transaction
uint256 totalOutputs; // Total number of outputs in the original transaction
bool containsAllInputs; // Indicates if all inputs are contained
bool containsAllOutputs; // Indicates if all outputs are contained
}
struct Input {
uint256 inValue; // Value spent by the input in satoshis
bytes32 inputTxId; // Transaction ID of the input source
uint256 sourceIndex; // Index of the input in its transaction
bytes scriptSig; // Script signature
uint256 sequence; // Sequence number
uint256 fullScriptSigLength; // Full length of the script signature
bool containsFullScriptSig; // Indicates if the full script signature is contained
}
struct Output {
uint256 outValue; // Value of the output in satoshis
bytes script; // Output script
string outputAddress; // Output address
bool isOpReturn; // Indicates if the output is an OP_RETURN output
bytes opReturnData; // Data contained in the OP_RETURN output
bool isSpent; // Indicates if the output is spent
uint256 fullScriptLength; // Full length of the output script
bool containsFullScript; // Indicates if the full output script is contained
SpentDetail spentDetail; // Details of the spent output
}
struct SpentDetail {
bytes32 spendingTxId; // Transaction ID of the spending transaction
uint256 inputIndex; // Index of the input in the spending transaction
}
interface IBitcoinKit {
function getUTXOsForBitcoinAddress(string calldata btcAddress, uint256 pageNumber, uint256 pageSize) external view returns (UTXO[] memory);
function getTxConfirmations(bytes32 txId) external view returns (uint32 confirmations);
function getBitcoinAddressBalance(string calldata btcAddress) external view returns (uint256 balance);
function getTransactionByTxId(bytes32 txId) external view returns (Transaction memory);
function getTransactionInputsByTxId(bytes32 txId) external view returns (Input[] memory);
function getTransactionOutputsByTxId(bytes32 txId) external view returns (Output[] memory);
function getLastHeader() external view returns (BitcoinHeader memory);
function getHeaderN(uint32 height) external view returns (BitcoinHeader memory);
}
function getBitcoinAddressBalance(string calldata btcAddress) public view returns (uint256 balance)
function getUTXOsForBitcoinAddress(string calldata btcAddress, uint256 pageNumber, uint256 pageSize) public view returns (UTXO[] memory)
function getTransactionByTxId(bytes32 txId) external view returns (Transaction memory);
function getTxConfirmations(bytes32 txId) public view returns (uint32 confirmations)
function getLastHeader() public view returns (BitcoinHeader memory)
function getHeaderN(uint32 height) public view returns (BitcoinHeader memory)
Check the Raw trace tab
👀 Common Culprits
One frequent cause is the use of thePUSH0opcode, which was introduced inEIP-3855with theShanghai upgrade.
✅ Solutions
To avoid such issues, it's best to wait until testnet officially supports these new features before attempting to deploy contracts that rely on them.
📜 We will make an announcement when we update this soon!
👀 Common Culprits
100% Gas Consumption: If a transaction fails and the gas usage is 100%, it suggests the gas limit set for the contract's deployment was too low to cover the computation required.
Check Gas usage & limit by txn
✅ Solutions
Increase Gas Limit: Adjust the gas limit upwards based on the complexity of your contract and the estimations provided by gas estimation tools.
Optimize Contract Code: Review and optimize your smart contract code to reduce gas consumption. This can involve simplifying functions, removing unnecessary operations, or leveraging patterns that consume less gas.
Test Thoroughly
🛠 Steps to Verify:
Navigate to Contract Details: Access your contract's details within your development environment or via a testnet blockchain explorer where your contract will be deployed.
Look for the Verify and Publish option. Selecting this begins the verification process, which is essential for assessing whether your contract operates as intended and is ready for interaction with users.
Read more about verifying smart contracts deployed on Hemi.
This approach contrasts with centralized bridges, which can be vulnerable to manipulation or collusion by a single entity overseeing the dispute process.
To promote greater decentralization and address the limitations of bridges, the Hemi Network introduces
tunnels
.
Tunnels allow for sophisticated, noncustodial bidirectional asset transfers between networks, such as Bitcoin and Ethereum. Unlike traditional bridges, tunnels within the Hemi Network maintain state awareness of both networks at the protocol level.
This enables a variety of custodianship approaches, both centralized and decentralized. For instance, BRC-20 tokens can be tunneled from Bitcoin to the Hemi Network or Ethereum, facilitating trading on Ethereum-based decentralized exchanges (DEXes). Additionally, tunnels benefit from the security features of the Hemi Network’s Bitcoin-based superfinality
Phase 0 (Current State)
Ethereum Tunnels:
Optimistic (fault-dispute) model, where disputes are raised within a dispute window.
Phase 1 (Expansion)
Ethereum Tunnels:
ZK proof-based settlement with an optimistic fallback if the ZK system fails.
Phase 2 (Maturity)
Ethereum Tunnels:
Redundant ZK proof system (2-of-3), providing higher security with multiple ZK proofs.
This tutorial guides you through deploying an ERC-20 token using , a comprehensive Ethereum development environment. Hardhat is recommended for its powerful features, but you can also use other Ethereum development tools like .
Ensure Node.js, Hardhat, and Solidity are set up correctly for effective ERC-20 token development and deployment.
Earn and track Hemi for completing this tutorial!
🏁 Prerequisites
Download (or any other IDE)
Install or update it to
📚 Tutorial
Video
1. Create A Project Directory
Create a folder on your computer and name it TestToken.
This folder will serve as your project directory, containing all the elements and code needed to deploy your ERC-20 token.
2. Initialize Your NPM Project
In your TestToken project directory, open a terminal window and initialize a Node.js project
3. Install Hardhat & Ethers.js Plugin
Install Hardhat along with the Ether.js plugin, and the OpenZeppelin contracts library.
4. Create a HardHat Project
a) Inside your Node.js project, start a Hardhat project
b) Select Create an empty hardhat.config.js
5. Add Folder
In the root directory of your project, create contracts and scripts folders:
6. Write Your Contract
In the contracts folder, create a file named MyToken.sol . This will be your ERC-20 token contract. Here's a basic example:
This code defines a simple ERC-20 token with an initial supply and basic ERC-20 functionalities.
7. Compile Your Contract
8. Secure Your Private Key for Deployment
Your private key provides access to your wallet and your funds. Never share your private key with anyone. Ensure this file is never shared or committed to version control.
a) Export your private key from MetaMask:
Open MetaMask, select your account icon, and go to Account Details
Select Show private key
Enter your password.
Select Confirm
b) Install dotenv package
c) Run the command touch .env to create an .env file in the root directory of your project.
d) Run the command nano .env to open the CLI editor
e) Add your private key to the .env file.
9. Configure Hardhat for the Testnet
a) Open hardhat.config.js in your project.
b) Configure Hemi Network
Add the required modules at the top of the config file
Add the Hemi Network settings inmodule.exports. Ensure you include the network's URL, Chain ID, and the accounts array with your private key (stored in an environment variable for security).
Here's an example configuration:
10. Write a Deployment Script
In the scripts folder, create a file named deploy.js to write a script for deploying your contract.
This script is deploying MyToken with an initial supply (customize the supply as needed).
11. Deploy the Contract
If the deployment is successful, you will see messages indicating the token was deployed to
Token deployed to: 0x5fc5c2265E4f77E63e82f7F10FE803d04Cc53D82
To view the details of your deployed contract, enter the contract address from your success message into the . This will provide you with information about the contract's transactions and state.
Contract details we just deployed:
Data Indexing
Getting historical data on a smart contract can be frustrating when you’re building a dapp. The Graph provides a decentralized option to query smart contract data through APIs known as subgraphs, which utilize GraphQL. The Graph’s infrastructure relies on a decentralized network of indexers, enabling your dapp to become truly decentralized.
Quick Start
These subgraphs only take a few minutes to set up and get running. To get started, follow these three steps:
Initialize your subgraph project
Deploy & Publish
Query from your dapp
Pricing: All developers receive 100K free queries per month on the decentralized network. After these free queries, you only pay based on usage at $2 for every 100K queries.
Here’s a step by step walk through:
1. Initialize your subgraph project
Create a subgraph on Subgraph Studio
Go to the and connect your wallet. Once your wallet is connected, you can begin by clicking “Create a Subgraph”. It is recommended to use Title Case: “Subgraph Name Chain Name.”
You will then land on your subgraph’s page. All the CLI commands you need will be visible on the right side of the page:
Install the Graph CLI
On your local machine run the following:
Initialize your Subgraph
You can copy this directly from your subgraph page to include your specific subgraph slug:
You’ll be prompted to provide some info on your subgraph like this:
Simply have your contract verified on the block explorer and the CLI will automatically obtain the ABI and set up your subgraph. The default settings will generate an entity for each event.
2. Deploy & Publish
Deploy to Subgraph Studio
First run these commands:
Then run these to authenticate and deploy your subgraph. You can copy these commands directly from your subgraph’s page in Studio to include your specific deploy key and subgraph slug:
You will be asked for a version label. You can enter something like v0.0.1, but you’re free to choose the format.
Test your subgraph
You can test your subgraph by making a sample query in the playground section. The Details tab will show you an API endpoint. You can use that endpoint to test from your dapp.
Publish Your Subgraph to The Graph’s Decentralized Network
Once your subgraph is ready to be put into production, you can publish it to the decentralized network. On your subgraph’s page in Subgraph Studio, click on the Publish button:
Before you can query your subgraph, Indexers need to begin serving queries on it. In order to streamline this process, you can curate your own subgraph using GRT.
When publishing, you’ll see the option to curate your subgraph. As of May 2024, it is recommended that you curate your own subgraph with at least 3,000 GRT to ensure that it is indexed and available for querying as soon as possible.
3. Query your Subgraph
Congratulations! You can now query your subgraph on the decentralized network!
For any subgraph on the decentralized network, you can start querying it by passing a GraphQL query into the subgraph’s query URL which can be found at the top of its Explorer page.
Now, you simply need to fill in your own API Key to start sending GraphQL queries to this endpoint.
Getting your own API Key
In Subgraph Studio, you’ll see the “API Keys” menu at the top of the page. Here you can create API Keys.
Appendix
Sample Query
This query shows the most expensive CryptoPunks sold.
Passing this into the query URL returns this result:
💡 Trivia: Looking at the top sales on [CryptoPunks website](https://cryptopunks.app/cryptopunks/topsales) it looks like the top sale is Punk #5822, not #9998. Why? Because they censor the flash-loan sale that happened.
Sample code
Additional resources:
To explore all the ways you can optimize & customize your subgraph for a better performance, read more about .
For more information about querying data from your subgraph, read more .
Using the hBK Demo App
📜 TL;DR:
The enables seamless interaction with Bitcoin data in an Ethereum-compatible environment.
Key features include:
Query .
Retrieve the or specific .
Developers can easily integrate Bitcoin data into dApps without external services, simplifying Bitcoin-aware application development.
🌐 Overview
The is a tool designed for developers to interact with Bitcoin blockchain data directly from an Ethereum-compatible environment.
This demo app provides a user-friendly interface for querying Bitcoin information.
By abstracting the complexities of interacting with Bitcoin data, the app allows developers to seamlessly retrieve and use Bitcoin blockchain data in their dApps without needing external services.
🏁 Prerequisites
To follow along, you’ll need:
Nothing!
1. Get Address Balance
Retrieves the current balance (in satoshis) of a specified Bitcoin address.
Verifying our Output
Navigate to and input the Bitcoin address to confirm the above output.
2. Get Latest Block Header
Returns the latest Bitcoin block header containing metadata like hash, height, and timestamp.
Verifying our Output
Navigate to and input the Block header to confirm the above output.
3. Get Block Header by Height
Fetches the block header for a specific block height.
Verifying our Output
Navigate to and input the Block header height to confirm the above output.
4. Get Transaction Details
Fetches the details of a Bitcoin transaction using its transaction ID, including all of its inputs and outputs.
Verifying our Output
Navigate to and input the transaction ID to confirm the above output.
5. Get Transaction Confirmations
Retrieves the number of confirmations for a specific transaction based on its transaction ID.
Verifying our Output
Navigate to and input the transaction ID to confirm the above output.
6. List Address UTXOs
Returns the UTXOs (Unspent Transaction Outputs) of a Bitcoin address, with pagination support.
Verifying our Output
Navigate to and input the Bitcoin address to confirm the above output.
This guide provides straightforward steps to download, set up, and run your PoP Miner, either by downloading pre-built binaries or by building from source.
Ensure you have your development environment ready and follow the steps below to start PoP mining.
Basic CLI skills are required.
🏁 Prerequisites
Basic CLI Knowledge
BTC (See Bitcoin fee/vB to understand how much BTC is required to PoP mine)
The package you will need to download depends on your OS and architecture:
Windows (Intel/AMD CPU): heminetwork_v1.0.0_windows_amd64.zip
Mac (Intel CPU): heminetwork_v1.0.0_darwin_amd64.tar.gz
Mac (Apple Silicon "M" CPU): heminetwork_v1.0.0_darwin_arm64.tar.gz
Linux (Intel/AMD CPU): heminetwork_v1.0.0_linux_amd64.tar.gz
Linux (ARM CPU): heminetwork_v1.0.0_linux_arm64.tar.gz
2. Extract the files
After downloading the necessary files, you must extract them from their compressed format before you can use or access the software. On most operating systems, you can right-click on the downloaded archive and choose "Extract" or similar.
Linux/macOS tip:
You can also use the command tar xvf heminetwork_v1.0.0_linux_amd64.tar.gz
Run the uname -a command in the Terminal to view all system information, ensuring compatibility with the correct asset on GitHub.
Depending on the output:
"x86_64" => Choose the "amd64" package corresponding to your OS
"arm64" => Choose the "arm64" package corresponding to your OS
3. Open your CLI and navigate to the extracted folder
Launch your CLI:
For Windows:
Press ⊞ Win + R together to open the "Run Program Or File" Window
Type "cmd" and press Enter
For macOS:
Press ⌘ + Space together to open Spotlight Search
Type "terminal" and press Enter
For Linux:
Depends on OS. On Ubuntu (Gnome): Ctrl + Alt + T
For most other distros, you can press Super (Windows Key) and search for Terminal.
Navigate to the folder you extracted by typing cd (don't press Enter yet) and then drag the path of the extracted folder into your CLI, or type the path in manually and then press Enter.
For example on Linux if you downloaded the package to your Downloads folder and extracted it through the GUI, you might run a command like:
cd '/home/<user>/Downloads/heminetwork_v1.0.0_linux_amd64'
4. Confirm folder contents
List the files:
For Windows:
dir (and press Enter) Type "cmd" and press Enter
For macOS:
ls (and press Enter)
Your output should be:
Linux & macOS
For Windows
5. Verify configuration success
To ensure you downloaded the correct binaries and are able to run them, execute the command below:
This will display the help menu for popmd, indicating that it's installed and operational.
Note: Starting with v1.0.0, the PoP miner defaults to mainnet. If you want to PoP mine on testnet, you must specify "testnet" in the POPM_BTC_CHAIN_NAME.
6a. Generate public key
If you prefer to PoP mine using a preexisting private key, you may skip step 6a and 6b. You may import a private key from either an EVM or BTC address. For your BTC wallet (Unisat for example), use the HEX private key and not the WIF private key.
Note: The net flag in the ./keygen command will default to "mainnet". If you are running a PoP miner in testnet, you must also add the flag -net="testnet".
6b. Open the JSON
If you chose to generate a new private key in Step 6a, open your JSON to view your file contents.
On Windows: See the above instructions for how to open the file in Notepad.
On Linux/macOS: Run the following command to print the contents of your key file to the Terminal:
cat ~/popm-address.json
You should see a result like:
7. Fund your address
Find your wallet address:
New Address: If you generated a new public key in Step 6a, check the JSON file from Step 6b for your pubkey_hash.
Existing BTC Address: If you are importing a private key from an existing BTC address, change your wallet type to P2PKH (Legacy) and locate the pubkey hash.
Existing EVM Address: If you are importing a private key from an existing EVM address, import your private key into UniSat and select P2PKH (Legacy) as your wallet type.
Best Practices for BTC Allocation
We advise against sending large amounts of Bitcoin to the private key connected to your PoP miner. To run the miner, ~0.002 BTC is required per day assuming a Bitcoin fee rate of 2-3 sat/vB. As a safety practice, consider sending only enough BTC for a week or a month at a time and refilling periodically.
To determine how much BTC to send to your wallet, review Bitcoin fee/vB.
Testnet Mining
If you want to test out PoP mining on testnet, you can get tBTC from faucets like this one.
8. Run the Miner
In your console, execute the following commands while:
replacing <private_key> with either the value from your JSON file in Step 5 OR your preexisting EVM/BTC private key,
replacing <fee_per_vB_integer> with the fee in sat/vB you want to pay.
Read the "Bitcoin fee/vB" section below if you need help determining what value to set here.
Note: The following commands connect to a Hemi Labs-owned BFG. This BFG can get busy and requests will often time out due to a high load and serving the large number of connected users. If you'd like to run your own, you can do so by following the instructions then you may connect to that with by changing the POPM_BFG_URL value to be your own BFG.
To run a PoP miner connected to a custom BFG endpoint, provide the additional line of code to the run commands listed below:Linux & macOS:
Let us know how this process was for you via Discord. We are constantly looking for ways to improve our documentation.
Bitcoin fee/vB
The Bitcoin transaction (normally represented in satoshis per virtual byte or sats/vB) is a fee paid to the Bitcoin miners to include a transaction in a Bitcoin block. It varies with network congestion, typically rising during periods of high transaction volume and decreasing when there is less activity.
The PoP Miner consumes BTC to pay the Bitcoin miners to include PoP transactions in Bitcoin blocks.
In order to ensure PoP transactions from your PoP miner are included in Bitcoin blocks, ensure the configured fee is set to an appropriate value. The PoP miner can be configured to use a certain fee in sats/vB by changing the POPM_STATIC_FEE environment variable when running the PoP miner. In a future version, the PoP miner will automatically calculate the current network fee to guarantee PoP transactions are included in Bitcoin blocks.
The lower you set the fee, the less BTC you will pay per PoP transaction. If your fees are too low, Bitcoin miners may not include your transaction quickly enough for you to successfully PoP mine.
Bitcoin fee determination:
Check Current Fee Levels: Visit mempool.space to see the current fee levels. Look at the "sat/vB" numbers for the different transaction fee priorities. It is recommended to set the value to the "High Priority" value or slightly higher.
Set the Static Fee: Re-run the command to set the POPM_STATIC_FEE environment variable from above (export on Linux/macOS, set on Windows) each time you want to change the fee, and restart the PoP Miner afterwards.
Hemi Proof-of-Proof Miner v1.0.0+20630a55c (Hemi Labs, popmd, go1.23.7 linux/amd64)
Usage:
help (this help)
Environment:
POPM_BFG_REQUEST_TIMEOUT: request timeout for BFG (Bitcoin Finality Governor) (default: 15s)
POPM_BFG_URL : url for BFG (Bitcoin Finality Governor) (default: http://localhost:8383/v1/ws/public)
POPM_BTC_CHAIN_NAME : the name of the bitcoin chain to connect to (ex. "mainnet", "testnet3") (default: mainnet)
POPM_BTC_PRIVKEY : bitcoin private key (required)
POPM_LOG_LEVEL : loglevel for various packages; INFO, DEBUG and TRACE (default: popmd=INFO;popm=INFO)
POPM_PPROF_ADDRESS : address and port popm pprof listens on (open <address>/debug/pprof to see available profiles)
POPM_PROMETHEUS_ADDRESS : address and port popm prometheus listens on
POPM_REMINE_THRESHOLD : the number of L2 Keystones behind the latest seen that we are willing to remine, this is handy for re-orgs (default: 0)
POPM_STATIC_FEE : specify the number of sats/vB the PoP Miner will pay for fees (default: 1)
set POPM_BTC_PRIVKEY=<private_key>
set POPM_STATIC_FEE=<fee_per_vB_integer>
set POPM_BFG_URL=wss://pop.hemi.network/v1/ws/public
set POPM_BTC_CHAIN_NAME=mainnet
popmd.exe
2025-03-12 14:24:21 INFO popmd popmd.go:123 Hemi Proof-of-Proof Miner v1.0.0+20630a55c (Hemi Labs, popmd, go1.23.7 linux/amd64)
2025-03-12 14:24:21 INFO popmd popmd.go:127 POPM_BFG_REQUEST_TIMEOUT: 15s
2025-03-12 14:24:21 INFO popmd popmd.go:127 POPM_BFG_URL : wss://pop.hemi.network/v1/ws/public
2025-03-12 14:24:21 INFO popmd popmd.go:127 POPM_BTC_CHAIN_NAME : mainnet
2025-03-12 14:24:21 INFO popmd popmd.go:127 POPM_BTC_PRIVKEY : ********
2025-03-12 14:24:21 INFO popmd popmd.go:127 POPM_LOG_LEVEL : DEBUG
2025-03-12 14:24:21 INFO popmd popmd.go:127 POPM_PPROF_ADDRESS :
2025-03-12 14:24:21 INFO popmd popmd.go:127 POPM_PROMETHEUS_ADDRESS :
2025-03-12 14:24:21 INFO popmd popmd.go:127 POPM_REMINE_THRESHOLD : 0
2025-03-12 14:24:21 INFO popmd popmd.go:127 POPM_STATIC_FEE : 5
2025-03-12 14:24:21 INFO popm popm.go:933 Starting PoP miner with BTC address 1Gz6cq1pR777GoVeDBcA7UbpnwTygGdknc (public key 02df4b526c0a81c90308cd88af993022782e167e7b25d69006b4649f8a47d545e1)
2025-03-12 14:24:22 DEBUG popm popm.go:855 Connected to BFG: wss://pop.hemi.network/v1/ws/public
2025-03-12 14:24:34 DEBUG popm popm.go:609 Received new keystone with block height 1326775
2025-03-12 14:24:34 DEBUG popm popm.go:602 Checking keystone received with height 1326800 against last keystone 1326775
2025-03-12 14:24:34 DEBUG popm popm.go:609 Received new keystone with block height 1326800
2025-03-12 14:24:34 DEBUG popm popm.go:602 Checking keystone received with height 1326825 against last keystone 1326800
2025-03-12 14:24:34 DEBUG popm popm.go:609 Received new keystone with block height 1326825
2025-03-12 14:24:34 DEBUG popm popm.go:543 Received keystone for mining with height 1326825...
⚠️ On Mac you will need to first remove the quarantine by running the following command in your Terminal:
xattr -d com.apple.quarantine ./popmdRun
./popmd --help
Windows
⚠️ Important Note for Windows Users: To successfully execute this command, you must use the Command Prompt (CMD), not PowerShell (which is the default terminal in environments like Visual Studio Code).
Run
popmd.exe --help
Linux & macOS
⚠️ On Mac you will need to remove the quarantine by running:
xattr -d com.apple.quarantine ./keygen
Run the following command:
Windows
⚠️ Important Note for Windows Users: To successfully execute this command, you must use the Command Prompt, not PowerShell (which is the default terminal in environments like Visual Studio Code). Follow these steps to open Command Prompt:
Click on the Start Menu button or press the Windows key on your keyboard.
Type cmdinto the search bar and open it.
Type the following command and press Enter:
Note: After running the command, you might not see any immediate feedback in the Command Prompt. This is expected behavior.
Open the generated key file
After generating the key file, you'll want to check its contents. To do this, use the following command in Command Prompt:
This command opens the popm-address.json file in Notepad, allowing you to view or edit the generated key.
