On-Chain Storage

In Algorand, when developing an application, data and values can be persistently saved on the decentralized ledger itself. This storage mechanism is known as on-chain storage.

This storage can be global, local, or box storage.

• Global storage is data stored explicitly on the blockchain for the contract globally.
• Local storage refers to storing values related to a smart contract in the account balance record only if the account participates in the contract (this participation relationship is known as opt-in).
• Box storage allows contracts to use larger segments of storage.

The following section describes the main properties of each storage type.

Global Storage

Global Storage allows storing values on an application. This data will be linked to the application, and any user or client will be able to access the data only by interacting with the application.

Usage example

For example, in a voting application, the total votes for each candidate could be stored in Global Storage. Since these values represent aggregate data for the entire application, they should be accessible to all users and clients.

Storage characteristics

• Global Storage is composed of key/value pairs that are limited to 128 bytes in total per pair.
• It can store up to 64 key/value pairs.
• A total of 8Kb of memory can be used among the key/value pairs.

Considerations

When storing data in Global Storage, keep in mind that depending on the type and number of values you want to store, the Minimum Balance Requirement (MBR) of the application creator will be increased according to the following formula:

  100,000*(1+ExtraProgramPages) + (25,000+3,500)*schema.NumUint + (25,000+25,000)*schema.NumByteSlice

• 100,000 microAlgo base fee for each page requested.
• 25,000 + 3,500 = 28,500 microAlgo for each UInt in the Global State schema.
• 25,000 + 25,000 = 50,000 microAlgo for each byte slice in the Global State schema.

Local Storage

Local Storage stores data associated directly with an account that has opted-in to the application. This opt-in mechanism is activated through an opt-in transaction and allows any account to create a relationship and a storage space with the application for storing data for this specific account.

Usage example

When programming a voting application, storing each account’s vote may be necessary, so every user can check the candidate they voted for. This can be achieved by storing a key/value pair in each account’s local storage. This data will only be linked to the specific account that interacted with the smart contract.

Storage characteristics

• Local Storage is composed of key/value pairs that are limited to 128 bytes in total per pair.
• It can store up to 16 key/values pairs.
• A total of 2Kb of memory can be shared among the key/value pairs.
• Remember this storage space is created per account.

Considerations

For this storage type, the account must perform an opt-in transaction. When storing data in Local Storage, keep in mind that depending on the type and number of values you want to store, the Minimum Balance Requirement (MBR) of the account that opts-in to the application will increase according to the following formula:

100,000 + (25,000+3,500)*schema.NumUint + (25,000+25,000)*schema.NumByteSlice

• 100,000 microAlgo base fee of opt-in.
• 25,000 + 3,500 = 28,500 for each UInt in the Local State schema.
• 25,000 + 25,000 = 50,000 for each byte-slice in the Local State schema.

Boxes

Box Storage will allow you to store larger amounts of data, associated with the application you’re creating. Every box can store up to 32KB and an application is capable of create as many boxes as it needs.

Usage example

Let’s revisit our voting application example using Box Storage instead of Global and Local Storage. We can store:

• The total vote counts in a single box as a structured data type.
• Each voter’s choice in a separate box, using the voter’s address as the box name.

This approach eliminates the need for opt-in transactions since we’re not using Local Storage.

Storage characteristics

• Each Box can store up to 32KB, split between the box name and its byte array content.
• Applications can create any number of boxes they need.

Considerations

• Boxes can be created by an application and only accessed by the application that created it. Keep in mind that the Minimum Balance Requirement (MBR) of the application will be increased depending on its size. This means that a contract that intends to use boxes, must be funded beforehand.
• The MBR of the application will increase according to the following formula:

(2500 per box) + (400 * (box size + key size))

• For example, if a box is created with the name “BoxA”, a 4 byte long key, and with a size of 1024 bytes, the MBR for the app account increases by 413,700 microAlgo:

(2500) + (400 * (1024+4)) = 413,700 microAlgos