Name of a disk snapshot.

The snapshot itself might not yet exist on disk.

Number of snapshots to be stored on disk. See the SnapshotPolicy documentation for more information.

Default snapshot policy args are Mithril snapshot policy args

Snapshot Policy arguments to be used by Mithril

The snapshot interval is derived as follows: * The epoch in Shelley is 432,000 (10k/f) slots long, which corresponds to 5 days. * We want to take a snapshot a day, so that is 40*k.

Note that we will take a snapshot at the beginning of each epoch too, but we won't write it immediately, instead we will write it 5 - 10 minutes later, so we don't risk imposing more work on the epoch boundary.

Read an extended ledger state from disk

Write an extended ledger state to disk

The snapshots that are periodically created are temporary, they will be deleted when trimming or if they fail to deserialize.

The path within the LedgerDB's filesystem to the file that contains the snapshot's serialized ledger state

The path within the LedgerDB's filesystem to the snapshot's directory

Management of snapshots for the different LedgerDB backends.

Delete snapshot from disk

List on-disk snapshots, highest number first.

Trim the number of on disk snapshots so that at most onDiskNumSnapshots snapshots are stored on disk. The oldest snapshots are deleted.

The deleted snapshots are returned.

Load a snapshot metadata JSON file.

• Fails with MetadataFileDoesNotExist when the file doesn't exist;
• Fails with MetadataInvalid when the contents of the file cannot be deserialised correctly

Write a snapshot metadata JSON file.

Snapshots policy

We only write ledger states that are older than k blocks to disk (that is, snapshots that are guaranteed valid). The on-disk policy determines how often we write to disk and how many checkpoints we keep.

Range from which the randomised snapshot delay will be taken. The randomly chosen duration will be at least minimumDelay and at most maximumDelay.

Determines when/how often we take ledger snapshots.

We only write snapshots for ledger states that are immutable. Concretely, for every slot s out of

sfaOffset, sfaOffset + sfaInterval, sfaOffset + 2 * sfaInterval, sfaOffset + 3 * sfaInterval, ...

we write a snapshot for the most recent immutable ledger state before s. This way, nodes with the same sfaInterval/sfaOffset configuration create snapshots for precisely the same slots.

For example, on Cardano mainnet, where k=2160 and f=1/20, setting sfaInterval = 10*k/f = 432000 (one epoch) and sfaOffset = 0 will cause the node to create snapshots for the last block in every Shelley epoch. By setting sfaOffset to eg 5*k/f (half an epoch), snapshots are created just before the midway point in each epoch.

Additionally, there is an (optional, opt-out) rate limit (useful while bulk-syncing). When set to a given duration, we will skip writing a snapshot if less time than the given duration has passed since we finished writing the previous snapshot (if any).

To avoid skipping a snapshot write when caught-up, it is advisable to set sfaRateLimit to something significantly smaller than the wall-clock duration of sfaInterval.

How many slots to leave between snapshots, see SnapshotFrequencyArgs.

The interval is only resolved into a concrete number of slots once the SecurityParam is known, see resolveSnapshotInterval.

Resolve a SnapshotInterval into a concrete number of slots.

Default on-disk policy suitable to use with cardano-node

The Cardano mainnet epoch length in slots, used as the reference for the Mithril snapshot compatibility check in sanityCheckSnapshotPolicyArgs. Mithril requires a ledger snapshot at each epoch boundary; for snapshots to land on every epoch boundary, sfaInterval must divide this value evenly.

Check a SnapshotPolicyArgs for suspicious configurations and return a (possibly empty) list of SanityCheckIssues describing any problems found.

Only Override values are checked — UseDefault values are known-good and are never flagged. Checks that are specific to SnapshotFrequency are skipped entirely when spaFrequency is DisableSnapshots.

Type-safe flag to regulate the checksum policy of the ledger state snapshots.

These patterns are exposed to cardano-node and will be passed as part of SnapshotPolicy.

Type-safe flag to regulate the checksum policy of the ledger state snapshots.

These patterns are exposed to cardano-node and will be passed as part of SnapshotPolicy.

A pending request to write ledger snapshots to disk.

The ledger states to snapshot have already been selected and pinned down (the request holds on to duplicated ledger tables handles), but nothing has been written yet. Serving the request via writeSnapshots is what writes the snapshots and releases those handles again.

A queue holding at most one SnapshotRequest.

It is shared between the thread deciding that a snapshot must be taken and the background thread taking it. The former never blocks (tryEnqueueSnapshotRequest drops the request when the queue is occupied), the latter is parked on the queue until there is work to do (withSnapshotRequest).

The queue stays occupied for as long as a request is being served, not merely while it is waiting to be picked up. Hence at most one snapshot request is alive at any point in time.

Bounding it this way is not something the SnapshotPolicy rate limit can do on its own: sscTimeSinceLast is derived from the last completed request, so it stays satisfied for the whole of a request's delay, and it can be disabled altogether (SnapshotRateLimitDisabled). Without this bound, every advance of the immutable tip during one delay would start another request, each pinning a ledger state and each writing a snapshot that trimSnapshots then discards.

The range to draw the randomised delay before writing the snapshots from, see onDiskSnapshotDelayRange.

It lives on the queue, and not in every SnapshotRequest, because it is a property of the SnapshotPolicy the LedgerDB was opened with, hence the same for every request.

Whether a request is currently queued or being served.

Merely a hint: by the time the caller acts on it, the answer might have changed. It is meant to let a would-be producer skip the (not entirely cheap) work of assembling a request that tryEnqueueSnapshotRequest would then drop anyway.

Enqueue a request, unless one is already queued or being served.

Never blocks. Returns False when the request was dropped, in which case the caller is responsible for releasing the resources it holds on to.

Like withSnapshotRequest, but do nothing when no request is queued instead of waiting for one.

Block until a request is enqueued, then serve it.

The queue is only freed once the given action has returned or thrown, so that no further request is accepted while this one is being served.

Type-safe boolean flags with type level tags

It is recommended to create pattern synonyms for the true and false values.

See DiskSnapshotChecksum for an example.

To remain backwards compatible with existing snapshots stored on disk, we must accept the old format as well as the new format.

The old format:

• The tip: WithOrigin (RealPoint blk)
• The chain length: Word64
• The ledger state: l

The new format is described by snapshotEncodingVersion1.

This decoder will accept and ignore them. The encoder (encodeSnapshot) will no longer encode them.

Testing only! Destroy all snapshots in the DB.

Encoder to be used in combination with decodeSnapshotBackwardsCompatible.