Box Model

Understanding Ergo's extended UTXO model and box-based architecture

What is a Box?

In Ergo, a box is the fundamental unit of the blockchain state. It's an extended version of Bitcoin's UTXO (Unspent Transaction Output) that can hold not just ERG tokens, but also other tokens, data, and smart contract code.

Each box is immutable once created and can only be spent (destroyed) once. When a transaction spends boxes, it creates new boxes as outputs, maintaining the blockchain's state transition.

Box Structure

Mandatory Fields

  • Value: Amount of nanoERG (1 ERG = 10^9 nanoERG)
  • ErgoTree: Smart contract guarding the box
  • Creation Height: Block height when created

Optional Components

  • Tokens: Up to 255 different tokens
  • Registers (R4-R9): Additional data storage
  • Extension: Key-value data dictionary

Box Registers

Each box has 10 registers (R0-R9) for storing data. The first 4 are mandatory and predefined:

R0 - Value

Amount of nanoERG in the box

R1 - Script

ErgoTree script (guard condition)

R2 - Tokens

Array of token IDs and amounts

R3 - Creation Info

Creation height and transaction ID/index

R4-R9 - User Defined

Available for storing arbitrary data like addresses, numbers, byte arrays, or complex data structures

Box Lifecycle

Learn how boxes are created, spent, and managed in transactions

Learn more

Assets & Tokens

Working with native tokens and custom assets in boxes

Learn more

Data Modelling

Best practices for structuring data in box registers

Learn more

Example: Creating a Box

// Using Fleet SDK (JavaScript)
const box = new OutputBuilder(
  1000000000n, // 1 ERG in nanoERG
  "9hY16vzHmmfyVBwKeFGHvb2bMFsG94A1u7To1QWtUokACyFVENQ" // Recipient address
)
  .addTokens({
    tokenId: "token_id_here",
    amount: 100n
  })
  .setAdditionalRegisters({
    R4: "0x0580dac409", // Store integer 1234567890
    R5: "0e0568656c6c6f", // Store string "hello"
    R6: "1a0201020304" // Store byte array
  })
  .build();

Important Considerations

  • • Minimum box value is 0.001 ERG (1,000,000 nanoERG)
  • • Boxes are subject to storage rent after 4 years of inactivity
  • • Token emission must happen in the first transaction output
  • • Box size is limited to 4KB
  • • Registers can store various data types but have size limits

Resources