Skip to content

Commit

Permalink
chore: small snapshot commands & docs improvement (backport #16404) (#…
Browse files Browse the repository at this point in the history
…16408)

Co-authored-by: Julien Robert <julien@rbrt.fr>
  • Loading branch information
mergify[bot] and julienrbrt committed Jun 2, 2023
1 parent 2cd72b7 commit 616841b
Show file tree
Hide file tree
Showing 9 changed files with 51 additions and 26 deletions.
1 change: 0 additions & 1 deletion client/snapshot/cmd.go
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,6 @@ func Cmd(appCreator servertypes.AppCreator) *cobra.Command {
cmd := &cobra.Command{
Use: "snapshots",
Short: "Manage local snapshots",
Long: "Manage local snapshots",
}
cmd.AddCommand(
ListSnapshotsCmd,
Expand Down
6 changes: 2 additions & 4 deletions client/snapshot/export.go
Original file line number Diff line number Diff line change
@@ -1,8 +1,6 @@
package snapshot

import (
"fmt"

"github.com/cosmos/cosmos-sdk/server"
servertypes "github.com/cosmos/cosmos-sdk/server/types"
"github.com/spf13/cobra"
Expand Down Expand Up @@ -33,15 +31,15 @@ func ExportSnapshotCmd(appCreator servertypes.AppCreator) *cobra.Command {
height = app.CommitMultiStore().LastCommitID().Version
}

fmt.Printf("Exporting snapshot for height %d\n", height)
cmd.Printf("Exporting snapshot for height %d\n", height)

sm := app.SnapshotManager()
snapshot, err := sm.Create(uint64(height))
if err != nil {
return err
}

fmt.Printf("Snapshot created at height %d, format %d, chunks %d\n", snapshot.Height, snapshot.Format, snapshot.Chunks)
cmd.Printf("Snapshot created at height %d, format %d, chunks %d\n", snapshot.Height, snapshot.Format, snapshot.Chunks)
return nil
},
}
Expand Down
2 changes: 1 addition & 1 deletion client/snapshot/list.go
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ var ListSnapshotsCmd = &cobra.Command{
return fmt.Errorf("failed to list snapshots: %w", err)
}
for _, snapshot := range snapshots {
fmt.Println("height:", snapshot.Height, "format:", snapshot.Format, "chunks:", snapshot.Chunks)
cmd.Println("height:", snapshot.Height, "format:", snapshot.Format, "chunks:", snapshot.Chunks)
}

return nil
Expand Down
4 changes: 2 additions & 2 deletions client/snapshot/load.go
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ const SnapshotFileName = "_snapshot"
func LoadArchiveCmd() *cobra.Command {
return &cobra.Command{
Use: "load <archive-file>",
Short: "Load a snapshot archive file into snapshot store",
Short: "Load a snapshot archive file (.tar.gz) into snapshot store",
Args: cobra.ExactArgs(1),
RunE: func(cmd *cobra.Command, args []string) error {
ctx := server.GetServerContextFromCmd(cmd)
Expand Down Expand Up @@ -70,7 +70,7 @@ func LoadArchiveCmd() *cobra.Command {

savedSnapshot, err := snapshotStore.Save(snapshot.Height, snapshot.Format, chunks)
if err != nil {
fmt.Println("failed to save snapshot", err)
cmd.Println("failed to save snapshot", err)
return
}
quitChan <- savedSnapshot
Expand Down
35 changes: 32 additions & 3 deletions docs/docs/run-node/01-run-node.md
Original file line number Diff line number Diff line change
Expand Up @@ -152,12 +152,41 @@ log_level: "state:info,p2p:info,consensus:info,x/staking:info,x/ibc:info,*error"

## State Sync

State sync is the act in which a node syncs the latest or close to the latest state of a blockchain. This is useful for users who don't want to sync all the blocks in history. You can read more here: https://docs.cometbft.com/v0.37/core/state-sync
State sync is the act in which a node syncs the latest or close to the latest state of a blockchain. This is useful for users who don't want to sync all the blocks in history. Read more in [CometBFT documentation](https://docs.cometbft.com/v0.37/core/state-sync).

State sync works thanks to snapshots. Read how the SDK handles snapshots [here](https://github.com/cosmos/cosmos-sdk/blob/825245d/store/snapshots/README.md).

### Local State Sync

Local state sync work similar to normal state sync except that it works off a local snapshot of state instead of one provided via the p2p network. The steps to start local state sync are similar to normal state sync with a few different designs.

1. As mentioned in https://docs.cometbft.com/v0.37/core/state-sync, one must set a height and hash in the config.toml along with a few rpc servers (the afromentioned link has instructions on how to do this).
2. Bootsrapping Comet state in order to start the node after the snapshot has been ingested. This can be done with the bootstrap command `<app> comet bootstrap-state`
<!-- 3. TODO after https://github.com/cosmos/cosmos-sdk/pull/16060 is merged -->
2. Run `<appd snapshot restore <height> <format>` to restore a local snapshot (note: first load it from a file with the *load* command).
3. Bootsrapping Comet state in order to start the node after the snapshot has been ingested. This can be done with the bootstrap command `<app> comet bootstrap-state`

### Snapshots Commands

The Cosmos SDK provides commands for managing snapshots.
These commands can be added in an app with the following snippet in `cmd/<app>/root.go`:

```go
import (
"github.com/cosmos/cosmos-sdk/client/snapshot"
)

func initRootCmd(/* ... */) {
// ...
rootCmd.AddCommand(
snapshot.Cmd(appCreator),
)
}
```

Then following commands are available at `<appd> snapshots [command]`:

* **list**: list local snapshots
* **load**: Load a snapshot archive file into snapshot store
* **restore**: Restore app state from local snapshot
* **export**: Export app state to snapshot store
* **dump**: Dump the snapshot as portable archive format
* **delete**: Delete a local snapshot
2 changes: 1 addition & 1 deletion go.mod
Original file line number Diff line number Diff line change
Expand Up @@ -177,7 +177,7 @@ replace (
// Fix upstream GHSA-h395-qcrw-5vmq and GHSA-3vp4-m3rf-835h vulnerabilities.
// TODO Remove it: https://github.com/cosmos/cosmos-sdk/issues/10409
github.com/gin-gonic/gin => github.com/gin-gonic/gin v1.9.0
// Downgraded to avoid bugs in following commits which caused simulations to fail.
// replace broken goleveldb
github.com/syndtr/goleveldb => github.com/syndtr/goleveldb v1.0.1-0.20210819022825-2ae1ddf74ef7
)

Expand Down
2 changes: 1 addition & 1 deletion server/tm_cmds.go
Original file line number Diff line number Diff line change
Expand Up @@ -209,7 +209,7 @@ func BootstrapStateCmd(appCreator types.AppCreator) *cobra.Command {
},
}

cmd.Flags().Int64("height", 0, "Block height to bootstrap state at, if not provided will use the latest block height in app state")
cmd.Flags().Int64("height", 0, "Block height to bootstrap state at, if not provided it uses the latest block height in app state")

return cmd
}
2 changes: 1 addition & 1 deletion simapp/go.mod
Original file line number Diff line number Diff line change
Expand Up @@ -170,6 +170,6 @@ replace (
// Fix upstream GHSA-h395-qcrw-5vmq and GHSA-3vp4-m3rf-835h vulnerabilities.
// TODO Remove it: https://github.com/cosmos/cosmos-sdk/issues/10409
github.com/gin-gonic/gin => github.com/gin-gonic/gin v1.9.0
// Downgraded to avoid bugs in following commits which caused simulations to fail.
// replace broken goleveldb
github.com/syndtr/goleveldb => github.com/syndtr/goleveldb v1.0.1-0.20210819022825-2ae1ddf74ef7
)
23 changes: 11 additions & 12 deletions snapshots/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,16 +55,16 @@ Snapshot settings are optional. However, if set, they have an effect on how prun
persisting the heights that are multiples of `state-sync.snapshot-interval` until after the snapshot is complete.

If pruning is enabled (not `pruning = "nothing"`), we avoid pruning heights that are multiples of
`state-sync.snapshot-interval` in the regular logic determined by the
pruning settings and applied after every `Commit()`. This is done to prevent a
height from being removed before a snapshot is complete. Therefore, we keep
such heights until after a snapshot is done. At this point, the height is sent to
`state-sync.snapshot-interval` in the regular logic determined by the
pruning settings and applied after every `Commit()`. This is done to prevent a
height from being removed before a snapshot is complete. Therefore, we keep
such heights until after a snapshot is done. At this point, the height is sent to
the `pruning.Manager` to be pruned according to the pruning settings after the next `Commit()`.

To illustrate, assume that we are currently at height 960 with `pruning-keep-recent = 50`,
`pruning-interval = 10`, and `state-sync.snapshot-interval = 100`. Let's assume that
the snapshot that was triggered at height `900` **just finishes**. Then, we can prune height
`900` right away (that is, when we call `Commit()` at height 960 because 900 is less than `960 - 50 = 910`.
`900` right away (that is, when we call `Commit()` at height 960 because 900 is less than `960 - 50 = 910`).

Let's now assume that all conditions stay the same but the snapshot at height 900 is **not complete yet**.
Then, we cannot prune it to avoid deleting a height that is still being snapshotted. Therefore, we keep track
Expand All @@ -78,23 +78,22 @@ Note that in both examples, if we let current height = C, and previous height P

P - `pruning-keep-recent` - `pruning-interval` <= h <= P - `pruning-keep-recent`

we can prune height h. In our first example, all heights 899 - 909 fall in this range and are pruned at height 960 as long as
we can prune height h. In our first example, all heights 899 - 909 fall in this range and are pruned at height 960 as long as
h is not a snapshot height (E.g. 900).

That is, we always use current height to determine at which height to prune (960) while we use previous
to determine which heights are to be pruned (959 - 50 - 10 = 899-909 = 959 - 50).


## Configuration

* `state-sync.snapshot-interval`
* the interval at which to take snapshots.
* the value of 0 disables snapshots.
* if pruning is enabled, it is done after a snapshot is complete for the heights that are multiples of this interval.
* the interval at which to take snapshots.
* the value of 0 disables snapshots.
* if pruning is enabled, it is done after a snapshot is complete for the heights that are multiples of this interval.

* `state-sync.snapshot-keep-recent`:
* the number of recent snapshots to keep.
* 0 means keep all.
* the number of recent snapshots to keep.
* 0 means keep all.

## Snapshot Metadata

Expand Down

0 comments on commit 616841b

Please sign in to comment.