-
Notifications
You must be signed in to change notification settings - Fork 19
/
doc.go
81 lines (79 loc) · 3.68 KB
/
doc.go
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
// Copyright (C) 2023 Gobalsky Labs Limited
//
// This program is free software: you can redistribute it and/or modify
// it under the terms of the GNU Affero General Public License as
// published by the Free Software Foundation, either version 3 of the
// License, or (at your option) any later version.
//
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU Affero General Public License for more details.
//
// You should have received a copy of the GNU Affero General Public License
// along with this program. If not, see <http://www.gnu.org/licenses/>.
package snapshot
// Package snapshot implements the snapshot engine responsible of taking a
// snapshot of the node state, that will allow a node to restore the state later
// on without replaying the entire chain.
//
// # Taking a snapshot
//
// The engine gathers the state from the state providers that subscribed to it.
// A state provider can be any component that needs to have its state snapshotted
// and restored to work.
//
// A snapshot is taken at defined interval counted in "block". For example,
// every 10 blocks. It happens when Tendermint calls `Commit()` on the node.
//
// The snapshot is taken asynchronously on the providers.
//
// # Restoration modes
//
// There are 2 ways to load a snapshot:
// - Loading from a local snapshot, stored on disk,
// - Loading from the network via Tendermint state-sync.
//
// Once a snapshot is loaded by it engine, the engine distributes the deserialized
// state to the state providers. Once the state is restored, the engine will
// reject any new attempt to restore another state. The node will have to be
// shutdown and reset to apply another state.
//
// ## Restore from local snapshots
//
// Local snapshots are stored locally in a LevelDB database. Snapshots metadata
// are stored in a separate database to go easy on machine resources when looking
// for high-level information, that avoid loading the entire snapshot in memory.
//
// If there is any snapshot stored locally, the snapshot engine will load from
// the last one (or the one matching the configured block height), regardless of
// whether Tendermint's state-sync is enabled or not.
//
// To prevent this loading from this mode, the local snapshots must be entirely
// removed. This can be achieved using the command-line `vega unsafe-reset-all`.
//
// ## Restore from state-sync
//
// Restoring from this mode requires that no snapshot is stored locally.
//
// If there is no local snapshot, the snapshot engine will wait for Tendermint to
// offer a snapshot, through the method (*Engine).ReceiveSnapshot(). The snapshot
// will have to match the expectation of the engine, and if it does, it listens
// for incoming snapshot chunks distributed by network peers, through the
// method (*Engine).ReceiveSnapshotChunk().
//
// If Tendermint fails to retrieve all the chunks, it will automatically abort the
// on-going state-sync, and offer another snapshot to the engine, and go all over
// the chunk distribution process, again. The engine reacts to that change accordingly
// by resetting the process.
//
// When the snapshot is completed, the engine restores the state, and save the
// received snapshot locally.
//
// # Sharing snapshots with peers
//
// To share snapshots with peers, the node must have a snapshot saved locally.
// Tendermint asks which snapshots the node currently have via the method
// (*Engine).ListSnapshots(). If the snapshot Tendermint is looking for is present,
// it then asks for chunks of that snapshot. The node have to load the snapshot in
// memory, and look for the asked chunk.