Skip to content

Ergo Headless dApp Framework (HDF)#

The Ergo Headless dApp Framework (HDF) is a powerful Rust framework designed for developing portable and reusable off-chain logic for Ergo dApps, often referred to as "Headless dApps". It provides developers with the first portable UTXO-based headless dApp development framework on any blockchain.

Testnet Address Limitation

Please be aware that the current version of the Headless dApp Framework does not support testnet addresses. Development and testing should target mainnet address formats.

What Are Headless dApps?#

Headless dApps represent a novel approach to dApp development, focusing on creating pure, portable, self-contained logic for interacting with on-chain smart contract protocols.

Key characteristics and benefits include:

  • Separation of Concerns: They separate the core dApp logic (reading blockchain state, constructing transactions) from the user interface (frontend). The HDF is the "backend" logic, but without a built-in frontend (hence "headless").
  • Portability: Because they are self-contained logic (often compiled to WebAssembly or native libraries), headless dApps built with the HDF can run anywhere – desktop OS, mobile OS, browsers, servers, bots, etc.
  • Reusability & Composability: They expose a streamlined interface, allowing various frontends (websites, mobile apps, CLI tools) and automated systems (scripts, arbitrage bots) to easily integrate and interact with the underlying protocol without needing deep knowledge of its internal workings. Multiple headless dApps can be composed together within a single application.
  • Decentralized Ecosystem: This model encourages a diverse ecosystem of frontends built by different developers or companies, all leveraging the same core headless dApp logic. This contrasts with the traditional model where the protocol creators often also control the single, primary frontend.
  • New Business Models: It creates opportunities for frontend developers to build value and potentially generate revenue by creating user interfaces for existing headless dApps.

In essence, headless dApps provide the standardized "engine" for interacting with a smart contract protocol, allowing anyone to build the "car" (the user interface or application) around it.

The Ergo HDF: Goals & Concepts#

The Ergo HDF aims to:

  1. Write Once, Run Anywhere: Enable developers to write off-chain logic once in Rust and target all platforms.
  2. Simplified Development: Provide a clearer path from Ergo dApp Specifications (like EIP-6) to a working implementation.
  3. Standardized Interface: Offer easy-to-use methods for frontend implementors to access dApp state and perform actions.
  4. Input Abstraction: Abstract the complexity of finding and selecting input UTXOs using BoxSpec definitions.
  5. Composability: Facilitate building scripts, bots, and complex applications on top of multiple HDF-based dApps.

Core Concepts (Based on EIP-6)#

The HDF's design aligns with EIP-6: Ergo Smart Contract Protocol Specification Format:

  • Protocol: Your dApp is defined as a smart contract protocol.
  • Stage: Represents a specific state within the protocol where a UTXO (box) resides at a point in time. Protocols can be single-stage or multi-stage.
  • Action: Defines the logic for state transitions – how UTXOs move between stages, enter the protocol, or exit the protocol. Actions involve:
    1. Acquiring Inputs: Gathering necessary UTXOs, user inputs, or external data.
    2. Creating Outputs: Constructing the output UTXOs that represent the new state after the action, embedded within an UnsignedTx.

The HDF provides Rust structs, traits, and utilities to define these stages, actions, input specifications (BoxSpec), and transaction-building logic.

Getting Started with the HDF#

  1. Prerequisites:
  2. Clone the Repository: 
    git clone https://github.com/ergoplatform/ergo-headless-dapp-framework.git
cd ergo-headless-dapp-framework
  3. Explore Examples: Review the example projects within the repository to understand usage patterns.
  4. Follow Tutorials: Work through the official tutorials (linked below) to build your first headless dApp.
  5. Consult Documentation: Refer to the framework's Rust documentation (often generated via cargo doc --open) and the EIP-6 specification.

Resources#

Tutorials (Located in HDF GitHub Repo)#

References#