How Accounts Work
On the L1 Ledger, like with any DLT, we have trustless and atomic transfers of assets between addresses on the ledger.
Tokens controlled by an address can be moved to another address by providing a valid signature using the private key that controls the source address.
In IOTA Smart Contracts, each chain has a L1 address (also known as the Chain ID) which enables it to control L1 assets (base tokens, native tokens and NFTs). The chain acts as a custodian of the L1 assets on behalf of different entities, thus providing a L2 Ledger.
The L2 ledger is a collection of on-chain accounts (sometimes called just accounts). L2 accounts can be owned by different entities, identified by a unique Agent ID. The L2 ledger is a mapping of Agent ID => balances of L2 assets.
Types of Accounts
Any L1 address can be the owner of a L2 account. The Agent ID of an L1 address is just the address,
Tokens in an address account can only be moved through a request signed by the private key of the L1 address.
Any smart contractSmart contracts are programs that execute contracts automatically. can be the owner of a L2 account. Recall that a smart contract is uniquely identified in a chain by a hname. However, the hname is not enough to identify the account since a smart contract on another chain could own it.
Thus, the Agent ID of a smart contract is composed as the contract hname plus the chain
ID, with syntax
Note that this allows trustless transfers of assets between smart contracts on the same or different chains.
Tokens in a smart contract account can only be moved by that smart contract.
The Common Account
The chain owns a unique L2 account, called the common account. The common account is controlled by the chain owner (defined in the chain root contract) and is used to store funds collected by fees or sent to the chain L1 address.
The Agent ID of the common account is
<hname=0>@<address zero (0x00000...)>.
An L2 account can also be owned by an Ethereum address. See EVM for more information.
The Agent ID of an Ethereum address is just the address prefixed with
Tokens in an Ethereum account can only be moved by sending an Ethereum transaction signed by the same address.
The Accounts Contract
accounts core contract is responsible for managing the L2 ledger.
By calling this contract, it is possible to:
The following diagram illustrates an example situation. The the IDs and hnames are shortened for simplicity.
Two chains are deployed, with IDs
chainA has two smart contracts on it (with hnames
chainB has one smart contract (
There is also an address on the L1 Ledger:
This address controls 1337 base tokens and 42
Red native tokens on the L1 Ledger.
The same address also controls 42 base tokens on
chainA and 8
Green native tokens on
So, the owner of the private key behind the address controls three different accounts: the L1 account and one L2 account on each chain.
7003@chainB has five base tokens on its native chain and controls eleven base tokens on chain A.