BitGuardian

BitGuardian - Bitcoin Inheritance triggered Posthumously

Comment

Inspiration

BitGuardian was inspired by the desire to address a critical, yet often overlooked, aspect of the Bitcoin ecosystem: secure and reliable wealth transfer across generations. As Bitcoin matures as an asset class, the need for robust inheritance solutions becomes paramount. We envisioned a platform that would empower individuals to seamlessly pass on their Bitcoin holdings to their chosen heirs, leveraging the inherent security and programmability of the Bitcoin network itself. The challenge of making this complex process user-friendly and integrating potentially cutting-edge Bitcoin Layer 2 and ancillary services like exSat and Rebar Shield provided a compelling technical motivation.

What it does

BitGuardian is a platform designed to facilitate the creation and execution of Bitcoin inheritance plans. In its current iteration, it operates within a local Polar Bitcoin testnet environment featuring three core nodes:

  • Alice: The owner of the Bitcoin, setting up the inheritance plan.
  • Bob: Heir 1.
  • Carol: Heir 2.

The platform allows Alice to define an inheritance plan, specifying how her Bitcoin should be distributed to Bob and Carol. While the demo focuses on manual execution, the underlying concept includes configurable inactivity periods and verification methods to trigger the inheritance process. The system handles the backend logic for managing these plans and interacting with the Bitcoin and Lightning Network nodes to eventually distribute the funds according to Alice's wishes. The new bitguardian-next-chakra frontend aims to provide a user-friendly interface for these operations.

How we built it

Vibecoding AND BitGuardian is a full-stack application built with the following components and a phased approach:

  1. Foundation & Test Environment:

    • A Polar Bitcoin testnet was set up with three bitcoind nodes and their corresponding LND (Lightning Network Daemon) nodes for Alice, Bob, and Carol. This provided a controlled environment for development and testing.

  2. Backend Development (Node.js & Express):

    • The backend is built using Node.js and the Express framework.
    • bitcoinClient.js: A dedicated service to interact with the bitcoind RPC interface using the bitcoin-core library for on-chain operations like getting addresses and mining blocks (for testnet transaction confirmation).
    • lndClient.js: A service to communicate with LND nodes via gRPC. This involved using @grpc/grpc-js, @grpc/proto-loader, and a lightning.proto file to make calls for actions like opening channels and sending payments. Secure communication was established using TLS certificates and macaroons specific to each LND node.
    • inheritanceService.js: Core logic for creating, managing, and executing inheritance plans.
    • Simulated Sponsor Integrations:
      • exSatService.js: Simulates interaction with exSat Data Consensus Extension Protocol for storing inheritance plan metadata.
      • rebarShieldService.js: Simulates interaction with Rebar Shield for private Bitcoin transactions. Both were kept in simulation mode for the demo, with rebarShieldService attempting to use the local BitcoinClient as a preferred fallback.
    • Configuration for backend services (RPC details, LND paths, server ports) is managed via config/default.json.

  3. Frontend Development (Next.js & Chakra UI):

    • A new frontend, bitguardian-next-chakra, was initiated using Next.js for a modern, server-rendered React application.
    • Chakra UI was chosen for its component library and theming capabilities to build a more customizable and visually appealing user interface.
    • Key frontend components include a Navbar, pages for displaying inheritance plans (/dashboard), creating new plans (/create), and an InfoModal.
    • Axios is used for making API calls from the frontend to the backend.

  4. Iterative Refinement & Debugging:

    • Significant effort went into troubleshooting connectivity and operational issues with both bitcoind (e.g., "Invalid URI" errors with bitcoin-core) and LND (e.g., "expected 1 macaroon, got 2" gRPC error). This involved meticulous logging, configuration adjustments, and understanding library-specific behaviors.

Challenges we ran into

The development journey was not without its hurdles:

  • Bitcoin/LND Node Configuration: Initial setup and connection to Polar nodes proved challenging due to incorrect LND configuration paths for TLS certificates and macaroons (especially issues with ${HOME} variable expansion).
  • bitcoin-core Library Integration: Resolving "Invalid URI" errors when the bitcoinClient.js tried to communicate with bitcoind was a major roadblock. This required extensive debugging, trying different connection parameter formats, and eventually understanding the specific initialization requirements for the version of the bitcoin-core library being used (v2.x.x).
  • LND gRPC Authentication: Correctly handling macaroons for LND gRPC calls was tricky, leading to an "expected 1 macaroon, got 2" error, which was resolved by adjusting how macaroons were passed in the metadata.
  • Testnet Fund Management: Ensuring Alice had sufficient funds to cover multiple transactions (e.g., to both Bob and Carol) became apparent once LND transactions were working, leading to "insufficient funds" errors.
  • Conceptual Shift (Coming from Ethereum): Adapting to Bitcoin's UTXO model, transaction construction (PSBTs), and different scripting capabilities required a learning curve compared to Ethereum's account-based model and smart contract environment.
  • Frontend Setup & Integration: Building a new Next.js/Chakra UI frontend from scratch involved setting up the toolchain, managing dependencies, and ensuring smooth API communication with the backend.
  • Automated Tooling Issues: An attempt to automatically patch node_modules/bitcoin-core/src/index.js resulted in a corrupted file, highlighting the need for caution with such tools.

Sponsor Prizes

BitGuardian's Bitcoin inheritance platform has integrated technologies from two major Bitcoin 2025 Hackathon sponsors:

  1. exSat - Data Consensus Extension Protocol
  2. Rebar Shield - Private Transaction Service

This document explains how these technologies are integrated into BitGuardian and how they enhance the platform's security, privacy, and reliability.

exSat Integration: Decentralized Metadata Storage

What is exSat?

exSat is a cutting-edge Data Consensus Extension Protocol for Bitcoin that provides a secure way to store and retrieve metadata. It uses a hybrid consensus mechanism (PoW + PoS) to enable decentralized data storage without bloating the Bitcoin blockchain.

How BitGuardian Uses exSat

BitGuardian uses exSat to store critical metadata related to inheritance plans:

  1. Plan Verification Data: Each inheritance plan's verification parameters (inactivity period, verification methods) are stored on exSat for immutable reference.

  2. Execution Conditions: The conditions that trigger an inheritance plan's execution are stored as metadata.

  3. Proof of Auditing: When a plan executes, proof of the verification steps completed is stored on exSat to provide an immutable audit trail.

Benefits for BitGuardian Users

  • Decentralized Verification: Plan verification doesn't rely solely on BitGuardian's servers
  • Tamper-Proof Records: Metadata about plans cannot be altered once committed
  • Enhanced Trust: Beneficiaries can verify inheritance conditions were met through blockchain-based proof

Implementation Details

  • The ExSatService class in backend/services/exSatService.js handles all interactions with the exSat network
  • Inheritance plans store their metadata on exSat during creation and update
  • Plan execution verifies conditions using both locally stored data and exSat metadata

Rebar Shield Integration: Private Transaction Submission

What is Rebar Shield?

Rebar Shield is an innovative service that allows Bitcoin transactions to be submitted directly to mining pools, bypassing the public mempool entirely. This provides enhanced privacy and faster settlement times.

How BitGuardian Uses Rebar Shield

BitGuardian uses Rebar Shield for critical inheritance transactions:

  1. Private Execution: When an inheritance plan executes, the Bitcoin transfers to heirs are sent via Rebar Shield to protect privacy.

  2. Frontrunning Protection: By bypassing the public mempool, inheritance transactions cannot be front-run or delayed by other actors.

  3. Faster Settlement: Direct mining pool access can result in quicker inclusion in blocks, reducing waiting time for heirs.

Benefits for BitGuardian Users

  • Enhanced Privacy: Inheritance transactions don't appear in the public mempool before confirmation
  • Execution Reliability: Reduced risk of transaction delays or mempool congestion affecting execution
  • Settlement Speed: Potentially faster confirmation times for inheritance distributions

Implementation Details

  • The RebarShieldService class in backend/services/rebarShieldService.js manages the Rebar Shield integration
  • When executing a plan, the inheritanceService.js uses Rebar Shield to send transactions when available
  • A fallback mechanism ensures transactions still complete even if Rebar Shield is unavailable

Accomplishments that we're proud of

Despite the challenges, we achieved several key milestones:

  • Successful Multi-Node Testnet Operation: Setting up and reliably interacting with a local Polar testnet consisting of three Bitcoin and LND nodes.
  • Overcoming Complex Client Integrations: Resolving persistent and nuanced issues with both the bitcoin-core library for bitcoind and the gRPC interface for LND. This demonstrated a deep dive into the technical intricacies of these systems.
  • Functional Backend API: Developing a backend capable of creating, storing, and triggering the execution of inheritance plans.
  • End-to-End Transaction Flow: Successfully demonstrating the transfer of funds from Alice to Bob and Carol on the testnet via LND, confirming the core inheritance distribution mechanism.
  • Modern Frontend Initiation: Launching a new Next.js and Chakra UI frontend (bitguardian-next-chakra) to provide a better user experience and a solid foundation for future UI enhancements.
  • Vision for Advanced Features: Designing and simulating integrations with services like exSat and Rebar Shield, showcasing a forward-thinking approach to metadata management and transaction privacy.

What we learned

This project was a significant learning experience across multiple domains:

  • Deep Dive into Bitcoin & LND: Gained a much more profound understanding of bitcoind and LND node operation, configuration (TLS, macaroons, RPC/gRPC settings), and on-chain vs. Lightning Network transactions.
  • RPC/gRPC Client Libraries: Learned the intricacies of using client libraries like bitcoin-core and @grpc/grpc-js, including version-specific behaviors and proper authentication mechanisms.
  • Full-Stack Development: Honed skills in building a full-stack application, from a Node.js/Express backend with service-oriented architecture to a modern React-based frontend using Next.js and Chakra UI.
  • Debugging Distributed Systems: Developed better strategies for debugging issues that span multiple services and processes (backend, Bitcoin nodes, LND nodes, frontend).
  • Bitcoin vs. Ethereum Paradigms: Solidified understanding of the fundamental differences between Bitcoin's UTXO model and Ethereum's account model, and their implications for application development.
  • Importance of Precise Configuration: Reinforced the lesson that meticulous attention to configuration details is critical in blockchain development.

What's next for BitGuardian

BitGuardian has a promising future with several avenues for expansion and improvement:

  • Full Sponsor Integration: Move beyond simulation and implement real integrations with exSat for decentralized metadata storage and Rebar Shield for enhanced transaction privacy.
  • Enhanced UI/UX: Continue developing the bitguardian-next-chakra frontend, focusing on:
    • More intuitive and customizable plan creation (e.g., allocation of funds beyond fixed heirs).
    • A visually appealing "web3" aesthetic.
    • Dark/light theme switcher.
    • Improved dashboard for managing and monitoring plans.
  • Automated Inactivity Tracking: Implement robust mechanisms for tracking the inactivity period specified in inheritance plans, potentially integrating with oracles or other on-chain/off-chain verification methods.
  • Advanced Verification Methods: Expand beyond manual execution to include options like email verification, trusted contact confirmation, or blockchain activity monitoring.
  • Sophisticated Inheritance Logic: Introduce more complex inheritance rules, conditional distributions, and potentially multi-signature requirements.
  • Security Audits & Hardening: Conduct thorough security audits of both the smart contract logic (if applicable in future iterations) and the backend/frontend code.
  • Mainnet Deployment Considerations: Explore the pathways and requirements for deploying BitGuardian on the Bitcoin mainnet, once the platform is sufficiently mature and secure.
  • Legal and Regulatory Research: Investigate the legal and regulatory landscape surrounding cryptocurrency inheritance to ensure compliance and provide users with appropriate guidance.

Built With

Share this project:

Updates