Skip to content

Ergo Box Design: A Comprehensive Guide#

The UTXO system is the backbone of many blockchain networks, and at its core are boxes. These boxes are not just containers for the value of a currency within a blockchain, but they are also equipped with registers that are protected by a contract, enhancing their functionality on the Ergo blockchain.

Registers are essentially storage units for data and information at specific addresses in the blockchain. To visualize this, think of these boxes as remote controls, piggy banks on steroids, or cups that only allow liquid to be poured in. For instance, consider a cup:

A Cup:

  • Holds liquid primarily
  • Can contain a certain quantity of liquid

Now, let's translate this into a blockchain context:

A Cup Box:

  • Stores only Ergs or a specific token
  • Has a storage limit enforced by a guard script

A guard script or contract sets restrictions on the box. Without it, a box is just a storage unit for information or a certain amount of currency. The introduction of guard scripts, which establish specific rules for the boxes, adds a level of control and functionality to the boxes, much like a remote control. The focus here is not on the internal workings of a remote control (guard script) or the data it transmits (registers and storage), but on its functionality - pressing a button changes the TV channel.

Understanding Box Modeling#

Box modeling is a framework that aids developers or box designers in creating a box to perform specific tasks. This structure promotes a clear and systematic understanding of a box's roles and operational mechanics.

Key Principles in Box Design#

A blockchain serves as a financial canvas, allowing developers, engineers, and designers to build financial systems on top of it. However, design flaws can lead to security vulnerabilities, unscalable designs, and inefficient processes. Therefore, it's crucial to prioritize security, scalability, and efficiency in design.

The three pillars of box design are:


The box should be designed to prevent exploitation by unauthorized users.


The system should be designed to handle multiple concurrent requests smoothly.


A straightforward design makes it easier for engineers to understand and improve the design.

Box Modeling: A Step-by-Step Guide#

Before diving into the principles mentioned above, it's essential to understand the basics of box modeling.

When modeling a box, consider the following:

What is the box's purpose?#

For instance, a lending box is designed to simplify the loan process.

What data should the box store?#

The box's function determines the data stored in it. A lending box, for example, would store lending-related information in its registers.

How will the box perform its function?#

This step involves thinking about the overall transaction, not just the box. It requires scripting the guard script (or smart contract) to perform its intended function using the data stored in the registers.

Register Data Types#

Registers can store data in various formats, which can be single or multiple entries.

Single data entries include:

  • Long
  • Coll[Byte] also known as String
  • Bool

Multiple data entries include:

  • Coll[Long]
  • Coll[Coll[Byte]]
  • Coll[Bool]

This guide is based on the article by Keith Lim