---
id: core-accounts
title: Account Management
keywords:
- core
- account
description: Core protocol design - account management.
---
---
## Overview
The Zilliqa blockchain supports two types of accounts:
- **Non-contract** - for balance transfers
- **Contract** - for both balance transfers and smart contract execution
While non-contract accounts simply need to record base data like **balance** and
**nonce**, contract accounts also have to store smart contract **code**, as well
as **immutable and mutable states**.
The diagram here shows that account data is organized according to those common
to all accounts (`AccountBase`) and those that only contract accounts would have
(`Account`).
!!! note
We can distinguish a contract from non-contract account by checking if
`m_codeHash` is NULL. We can also choose to serialize only the base fields or
both the base and the contract-related fields.
## Contract Account States
A transaction that requests a contract **deployment** triggers the generation of
a new contract account and the setting up of that account's immutable and
mutable states. Then, transactions that invoke **transition calls** on that
contract account trigger the updating of the mutable states.
Immutable states are more commonly referred to as the **init data**, and
examples of this include `_scilla_version`, `_library`, and `_extlibs`.
Init data is supplied to the node within the transaction body (please refer to
the
[CreateTransaction](../../../api/transaction-related-methods/api-transaction-create-tx.md)
API documentation), although the node will also eventually add more fields into
init data (such as `_creation_block` and `_this_address`) during transaction
processing.
Mutable states, on the other hand, are the variables that are manipulated by the
Scilla interpreter as it executes a transition on the contract. The Zilliqa node
provides the Scilla interpreter access to these states through the Scilla IPC
server.
## Account Data Storage
Storage of accounts in the Zilliqa blockchain can be quite complex to understand
due to the fact that account data is spread out across several leveldb
databases:
| leveldb Name | Managed By | Key | Value |
| ------------------ | ---------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
| state | AccountStoreTrie | Address | AccountBase |
| contractCode | ContractStorage | Address | Code |
| contractInitState2 | ContractStorage | Address | Tx data field + \_creation_block + \_this_address |
| contractStateData2 | ContractStorage | Address.vname
Address.\_depth.vname
Address.\_type.vname
Address.vname.index1.index2... | State value |
| contractTrie | ContractStorage | Hash of contractStateData2 key | State value |
| stateRoot | BlockStorage | LATEST_EPOCH_STATES_UPDATED
STATEROOT | Epoch number
Trie root value |
| stateDelta | BlockStorage | Tx block number | List of Account |
## State Tries
The **state** and **contractTrie** databases are implementations of Ethereum's
Merkle Patricia Trie data structure.
A trie is a key-value data structure with a root hash and hashes along each
key-value pair. The root hash is updated every time the structure is updated
(e.g., by adding another key-value pair).
Please see this
[Medium article](https://medium.com/@chiqing/merkle-patricia-trie-explained-ae3ac6a7e123)
for how the trie structure evolves (specifically, where the root node is) as you
add transactions one-by-one.
The trie provides the ability to prove that a specific key-value pair exists
within the structure without the requesting party needing to know the rest of
the structure. All the requesting party needs is the hash of the key-value pair
at the particular time that the structure is being evaluated. For example, the
**contractTrie** database supports requests from the
[GetStateProof](../../../api/contract-related-methods/api-contract-get-state-proof.md)
API, which requests for proof of a particular state for an account at a specific
Tx block.
The **contractTrie** database was implemented in order to support bridging
between the Zilliqa and Ethereum blockchains. While the contract state trie is
useful for the blockchain bridging aspect, it is _not_ vital to the normal
operation of the Zilliqa protocol, i.e., it has no impact on the normal
transaction processing, consensus execution, and account state updating.
Therefore, it does not need to be discussed further at present.
The **state** database, on the other hand, is used to store the `AccountBase`
portion of the account data.
## State Trie Library
Zilliqa uses Ethereum's `GenericTrieDB` library for the trie structure. The
`GenericTrieDB` class contains a `TraceableDB` member, which manages the loading
from or saving to disk (i.e., to the levelDB database) of the trie structure.
The basic usage will involve:
1. Calling `init()` to reset the root to NULL
1. Calling `insert()` to add nodes to the trie
1. Calling `at()` to access any of the added nodes
1. Calling `db()` to access the underlying `TraceableDB` member, and then
either
1. Calling `commit()` to save the changes to disk
1. Calling `rollback()` to discard changes
This basic usage applies to the **state** database. In this context, a node
basically refers to the `Address` (key) and the `AccountBase` (value) pair.
For the **contractTrie** database, the usage is slightly more complex due to the
fact that separate tries are maintained for a maximum of
`NUM_DS_EPOCHS_STATE_HISTORY` DS epochs. As mentioned in the previous section,
we won't be going deeper into **contractTrie** for now.
## AccountStore Class Hierarchy
The diagram below highlights the Zilliqa architecture around account and account
state storage.
There are essentially _three_ account store objects in a Zilliqa node:
- `AccountStore` holds the accounts that have been committed to disk (i.e., the
blockchain).
- `AccountStoreTemp` holds the account data that resides in transient memory and
that has yet to be validated by the nodes during consensus.
- `AccountStoreAtomic` also holds account data in transient memory, but only for
the current transaction being executed. More precisely, it is used for
**contract call** transactions, where multiple accounts may be updated (e.g.,
a chain call). After the transaction is completely processed, the contents are
moved to the `AccountStoreTemp` object.
The rest of the account store hierarchy is composed of abstract classes:
- `AccountStoreBase` contains the map of accounts in transient memory. It also
provides an `UpdateAccount()` function for use on non-contract (i.e., payment)
transactions.
- `AccountStoreSC` contains most of the smart contract-related functionality,
including an `UpdateAccount()` function for use on contract (deployment and
call) transactions.
- `AccountStoreTrie` contains trie management functions and the `GenericTrieDB`
instance for the base account data and its storage in the **state** leveldb
database.
Apart from the **state** leveldb database, the other account-related databases
listed in the previous section are managed by the `ContractStorage` and
`BlockStorage` classes.
Finally, the diagram also shows that aside from the account store classes, the
`ScillaIPCServer` also interacts with `ContractStorage` whenever the Scilla
Interpreter requests for state access during the execution of a contract.
## State Deltas
State deltas are the differences between what's stored in disk (i.e., the
blockchain) and what's changed after transaction execution for a particular
account (whether non-contract or otherwise).
Transaction processing by a node does not immediately result in committing any
such differences to disk. As with any distributed ledger system, all nodes in
the network must first reach consensus before they update their storage in a
uniform manner. Until the consensus is completed (i.e., the proposed Tx Block is
accepted by all nodes), state deltas must first be managed by a node separately
within its transient memory.
It should also be noted that _multiple_ transactions could be called on the
_same_ contract (for example, several users withdrawing rewards from the Staking
contract), and thus the complete set of state deltas cannot be known immediately
after one transaction, but rather only after all transactions for the current Tx
epoch have been processed.
Another consideration unique to Zilliqa's architecture is that shards manage
their own set of transactions that are different from those of other shards.
This means nodes belonging to different shards will be holding different state
deltas in their transient memory during the consensus period. Therefore, in
order for all nodes to arrive at the same final states, these state deltas will
eventually have to be shared across shards.
As can be inferred from the previous section, state deltas are generated by
getting the differences for an account between `AccountStore` and
`AccountStoreTemp`.
## Account and State Management During Tx Epoch
## Account and State Management During Node Launch
