Skip to content
Algorand Developer Portal Algorand Developer Portal Algorand Developer Portal
This new developer portal is under construction. For complete documentation, please refer to the old developer portal.

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-chain through 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

When creating a voting application, the total number of votes for candidate A and candidate B could be stored in the Global Storage since these values are the total number of votes and are only related to the application, allowing any user or client access.

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 shared 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 micro Algo base fee for each page requested.
  • 25,000 + 3,500 = 28,500 for each UInt in the Global State schema
  • 25,000 + 25,000 = 50,000 for each byte slice in the Global State schema

For further details about Global Storage, read the following section: Global Storage

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

Again, 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

For further details about Local Storage, read the following section: Local Storage

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

For the previous example of the voting dapp, refactoring the application and moving from Global and Local Storage to Boxes is possible. This can be done by creating one Box for storing a struct containing the data stored in the Global State, the total votes per candidate. Also, one box per voter can be created, storing the candidate they voted for and identifying the box using the public address of the account, by doing this, there’s no need for the user to opt-in to the application since Local Storage is not used anymore.

Storage characteristics

  • Every Box can store up to 32KB among the key(name) of the box and its content (a byte array)
  • An application can create as many boxes as it needs.

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

For further details about Local Storage, read the following section: Box Storage