State persistence, snapshots and recovery
Development status: Experimental implementation exists — An experimental implementation exists; this page describes the intended public developer capability. In an internal prototype, an experimental state database holds node state, and the implementation saves node state to disk and restores it when the node restarts; its crash safety has not been established, and which state is kept and restored is not documented. No durability, backup or disaster-recovery capability is offered, and nothing is publicly available for live use.
Before you read: Data and state: how information is recorded and retrieved.
Is node state kept across restarts, and how far can that be relied on? The short answer: in an internal prototype, node state is saved and restored on a normal restart, but this cannot be relied on. Crash safety has not been established, and which state is kept and restored is not documented. This page explains the concepts involved — persistence, snapshots, restarts compared with crashes, and restoring a node’s own state compared with backup — and states what operators and developers should and should not assume.
Why persistence matters
A node needs its recorded state after a restart so that it can continue from where it stopped, rather than starting again from nothing. Persistence is the property of keeping that state across restarts.
Persistence matters differently to different readers:
- For developers, it decides whether recorded data survives a node restarting, and therefore whether an application can expect to find again what was recorded before.
- For operators, it decides what must be stored, protected and restored when running a node.
Persistence is a different question from two others that are easy to confuse with it:
- Finality asks whether a recorded result can still change. A result that survives a restart is not thereby final; see Agreement and finality status.
- Data availability asks whether stored data can actually be retrieved when it is needed. Keeping encrypted data retrievable is a separate goal being explored; see Keeping encrypted data available.
What exists today
Status of this section: Experimental implementation exists — internal prototype only; not publicly available.
- An experimental state database is used by the internal prototype to hold node state.
- An experimental implementation saves node state to disk and restores it when the node restarts. Its crash safety has not been established: behaviour after an unplanned stop, such as a process crash or a power loss, is not established.
- Which state is kept and restored, and under which conditions, is not documented. No durability or integrity property is claimed.
- This exists for internal development only. There is no public node software and no public network.
Snapshots, restarts and crashes
In this documentation, a snapshot is a node’s own saved copy of its state at a point in time, used when resuming after a restart. Snapshots are part of how the experimental implementation saves state; as with its persistence generally, crash safety has not been established. Snapshot contents, format, frequency and size are not described.
Two kinds of stop need to be kept apart:
- A restart is a planned stop and start: the node is shut down in an orderly way and started again. This is the case in which the experimental implementation restores saved state — and even then, which state is restored is not documented.
- A crash is an unplanned stop, such as a process failure or a loss of power. The experimental implementation’s behaviour after a crash is not established, so nothing should be assumed about what state would remain usable afterwards.
Crash safety — whether saved state survives an unplanned stop intact — is therefore the property that is missing today, and it is the one that matters most for anything that would need to be relied on.
Restoring a node’s own state compared with backup and recovery
Restoring a node’s own saved state after a restart is a different capability from backup and disaster recovery. Restoring after a restart brings back what the node saved for itself. Backup and disaster recovery would protect against that saved state itself being lost or damaged, for example by keeping copies elsewhere and having a way to restore from them.
- Production deployment, backup and recovery procedures are not yet specified or published.
- An experimental local multi-node test setup exists for internal development. It is not a deployment, backup or recovery procedure, and it does not make any network available.
- What operators would plan for is described on Deployment, backup and recovery: what operators would plan for.
What operators and developers should assume
Operators
Status: Planned — described conditionally; no node software is released.
Once node software is released, operators would be expected to plan for storing node state, shutting down and restarting nodes cleanly, and making backups. Supported requirements and procedures would accompany a release. No storage sizes, retention periods, recovery times or hardware requirements are published, and none should be inferred from the experimental implementation. What running a node would involve more broadly is described on Operating a node: intended roles and what exists today.
Developers
- Do not rely on any experimental state persisting, being recoverable or being final.
- Re-check recorded state when your application needs it, rather than assuming that it survived a restart.
- Treat recorded results as not final: nothing is reported as final, because the finality component is not yet connected.
Assumptions, trust and limitations
- Crash safety has not been established, and no durability, integrity, backup or disaster-recovery property is claimed.
- Which state is kept and restored, and under which conditions, is not documented.
- The experimental implementation is internal and has not been independently reviewed. It is an early prototype and must not be relied on for security or production use.
- State kept by the experimental implementation is not confidential: confidentiality features are simulated or switched off. Crash safety is also listed among the prototype’s limitations on Known limitations of the experimental prototype.
Not yet available, and how this page will grow
Storage requirements, snapshot behaviour and recovery procedures are not yet available. Further technical reference is not yet available. Once node software is released, this page would describe the supported persistence behaviour and link to operator procedures. The status label would change only with release evidence, and the Documentation change log would record the change.
What this page does not claim
This page does not describe any storage engine, file layout, snapshot format or snapshot frequency, and it states no retention period, recovery time or recovery procedure. It does not claim crash safety, durability or integrity for any saved state. Anything not stated here as available should be treated as unavailable.
Related pages
- Committed state and inclusion proofs — the committed state that persistence keeps across restarts.
- Deployment, backup and recovery: what operators would plan for — backup and recovery concerns, with procedures not yet specified.
- Known limitations of the experimental prototype — crash safety among the prototype’s limitations.
- Operating a node: intended roles and what exists today — what running a node would involve and what exists today.
- Keeping encrypted data available — data availability, a different concern from persistence.
Glossary
References
No approved public references yet.
