Get a snapshot of states, smart contracts, and transactions on the blockchain.


The latest states and transactions of all accounts and smart contracts of the application need to be migrated to the target blockchain. Source blockchain is currently active; hence, the global state continues to change as new transactions arrive. The state to be migrated is already aggregated on the source blockchain.


How to get a complete account of states, smart contracts, and transactions on the source blockchain before migration?


  • Anonymity – A blockchain does not track the ownership of accounts, states, smart contracts, and transactions of an application to enhance the anonymity.
  • Consistency – Must capture the latest states and transactions of all accounts and smart contracts on the source blockchain. However, getting a globally consistent view of a distributed system is hard, e.g., it is difficult to freeze all transactions precisely at the same time on a distributed set of nodes.
  • Finality – A state change may not be confirmed immediately after a transaction is included in a block.
  • Latency – Time to collect states, smart contracts, and transactions are proportional to the number of accounts and smart contracts, as well as their states and transactions.


Get a snapshot of relevant states, smart contracts, and transactions on the source blockchain at a given time. The following figure shows the process of making a snapshot. First, select a block number to initiate the snapshotting process and number of blocks to wait for finality (aka., x-confirmation). Second, update all instances of the Blockchain Access/API Layer (BAL). Third, the BAL should wait until the chosen block number is reached. Once reached, it should freeze processing further transactions to prevent any state changes. BAL should further wait for x-confirmation to ensure the finality of transactions already included in a block. Once it is reached, the migration tool can extract all required states, smart contracts, and transactions by querying the source blockchain via the BAL. Finally, all extracted data are saved as a snapshot file.

Process of taking a snapshot
Process of taking a snapshot of blockchain state

Process of taking a snapshot

Time is not reliable in blockchains due to clock skew. Therefore, time to freeze transactions and x-confirmation should be specified as block numbers because they are consistent across all blockchain nodes. If the entire blockchain is being migrated, all blockchain nodes need to freeze transaction processing at the set block number. In case the BAL or nodes are not designed to freeze transactions at a set number, they need to be patched (aka., soft fork). Such changes usually require approval from the blockchain governance body. Further considerations include the time needed to develop and patch all the BAL instances or nodes, and to notify cryptocurrency exchanges and users about the potential downtime. Given such technical, operational, and governance considerations, the governance body should decide on the block number to freeze transactions well-ahead. For example, the typical time frame for a public blockchain migration range from weeks to months.

x-confirmation is essential in Nakamoto consensus based blockchains, as the finality is probabilistic. A relatively higher value of x-confirmation is used to minimize the probability of state change after the migration. For example, while Bitcoin and Ethereum typically use x-confirmations of 6 and 12, respectively, they are almost doubled during migration. The time that the BAL or blockchain nodes remain frozen can be minimized by first taking a snapshot of the relevant data after the set block number and x-confirmation, then iteratively going through the new blocks that were generated since then to find only the updated state. If only the application-specific data are migrated, corresponding accounts can be found from the application-level reference to
blockchain identifier mapping
database (i.e., ID database).

States represented as native assets of a blockchain platform, transactions, and smart contract code can be queried using the API exposed by the blockchain client nodes. If a smart contract exposes getter functions, its embedded state can be easily extracted. Otherwise, states have to be extracted by going through the global state data structure of a blockchain node. If the entire blockchain is to be migrated, the migration tool needs to go through the global state and entire block history to extract relevant accounts, states, smart contracts, and transactions. While a blockchain explorer can simplify this process, it is essential to validate that the explorer is in sync with the source blockchain. All data extractions can be parallelized as they are read-only.


  • Consistency – is preserved as all blockchain activities are frozen on distributed instances of the BAL or blockchain nodes, and the snapshot is created after reaching time to finality.
  • Latency – Transactions could be made to freeze only when the snapshot of states, smart contracts, and transactions that were updated after initiating the snapshotting process is being taken. Thus, a snapshot on a blockchain can be made relatively faster than in a database, which needs to freeze all transactions due to the difficulty in determining the data that got changed once the migration process begins.
  • Availability – of an application-level ID database simplifies the identification of application-specific data overcoming anonymity.
  • This pattern can be applied to states, smart contracts, and transactions, and any combination thereof.


  • Latency – depends on the time to finality and freeze time. Freeze time depends on the parallelization of state, smart contract, and transaction extraction. Hence, this pattern is more desirable when the source blockchain is private, or the application does not interact with any external state.

Related patterns

Known uses

  • Snapshotting is commonly used to bootstrap blockchains, sidechains, and new nodes. For example, a snapshot file format and bootstrap procedure for Bitcoin alt-coins is presented in Bitcoin Forum.
  • EOS, Telos, TOMO, Tron, and Vechain alt-coins took a snapshot while freezing all the transactions when they moved away from the Ethereum.
  • Bithereum took a snapshot of the Ethereum global state to spin up a duplicate blockchain (aka., hard spoon).
  • Both Bitcoin and Ethereum support dumping the history at different granularities and bootstrapping a new node using the dumped snapshot. Such daily snapshots are available on the web, e.g., Blockchair.
  • Snapshots are also used while migrating a DApp to a different smart contract or blockchain instance. For example, Tronbet took a snapshot of all ANTE tokens before exchanging them to the upgraded WIN tokens managed by a new smart contract.