cmd/statesync: Add command calculating recommended trust

Author: martintomazic

cmd/root.go

@@ -14,6 +14,7 @@ import (
 	"github.com/oasisprotocol/cli/cmd/network"
 	"github.com/oasisprotocol/cli/cmd/paratime"
 	"github.com/oasisprotocol/cli/cmd/rofl"
+	"github.com/oasisprotocol/cli/cmd/statesync"
 	"github.com/oasisprotocol/cli/cmd/wallet"
 	"github.com/oasisprotocol/cli/config"
 	"github.com/oasisprotocol/cli/version"
@@ -101,6 +102,7 @@ func init() {
 	rootCmd.AddCommand(network.Cmd)
 	rootCmd.AddCommand(paratime.Cmd)
 	rootCmd.AddCommand(wallet.Cmd)
+	rootCmd.AddCommand(statesync.Cmd)
 	rootCmd.AddCommand(account.Cmd)
 	rootCmd.AddCommand(addressBookCmd)
 	rootCmd.AddCommand(contractCmd)

cmd/statesync/statesync.go

@@ -0,0 +1,16 @@
+// Package statesync defines utility comands for the consensus state sync.
+package statesync
+
+import (
+	"github.com/spf13/cobra"
+)
+
+// Cmd is the statesync sub-command.
+var Cmd = &cobra.Command{
+	Use:   "state-sync",
+	Short: "State sync utilities for the consensus layer",
+}
+
+func init() {
+	Cmd.AddCommand(trustCmd)
+}

cmd/statesync/trust.go

@@ -0,0 +1,157 @@
+package statesync
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	"github.com/oasisprotocol/oasis-core/go/consensus/api"
+	"github.com/oasisprotocol/oasis-core/go/consensus/cometbft/config"
+
+	"github.com/oasisprotocol/cli/cmd/common"
+	cliConfig "github.com/oasisprotocol/cli/config"
+	"github.com/oasisprotocol/oasis-sdk/client-sdk/go/connection"
+	"github.com/spf13/cobra"
+)
+
+const (
+	// maxVerificationTime significantly overestimates the time needed for the
+	// light client to fetch and verify light headers and possibly detect and penalize
+	// misbehavior of byzantine node.
+	maxVerificationTime = 24 * time.Hour
+	// trustPeriodFraction defines the fraction of the debonding period that determines
+	// a valid trust period.
+	//
+	// According to the CometBFT documentation, the sum of the trust period, the time
+	// required to verify headers, and the time needed to detect and penalize misbehavior
+	// should be significantly smaller than the total debonding period.
+	trustPeriodFraction = 3.0 / 4.0
+)
+
+var trustCmd = &cobra.Command{
+	Use:   "trust",
+	Short: "Show the recommended light client trust for consensus state sync",
+	Args:  cobra.NoArgs,
+	RunE: func(_ *cobra.Command, _ []string) error {
+		ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+		defer cancel()
+
+		// Establish connection with the target network.
+		cfg := cliConfig.Global()
+		npa := common.GetNPASelection(cfg)
+		conn, err := connection.Connect(ctx, npa.Network)
+		if err != nil {
+			return fmt.Errorf("failed to establish connection with the target network: %w", err)
+		}
+
+		trustCfg, err := calcTrustCfg(ctx, conn)
+		if err != nil {
+			return fmt.Errorf("failed to calculate consensus state sync trust root: %w", err)
+		}
+
+		switch common.OutputFormat() {
+		case common.FormatJSON:
+			str, err := common.PrettyJSONMarshal(trustCfg)
+			if err != nil {
+				return fmt.Errorf("failed to pretty json marshal: %w", err)
+			}
+			fmt.Println(string(str))
+		default:
+			fmt.Println("Trust period: ", trustCfg.Period)
+			fmt.Println("Trust height: ", trustCfg.Height)
+			fmt.Println("Trust hash: ", trustCfg.Hash)
+		}
+
+		return nil
+	},
+}
+
+// calculateTrustCfg calculates and verifies the recommended trust config.
+func calcTrustCfg(ctx context.Context, conn connection.Connection) (config.TrustConfig, error) {
+	var trust config.TrustConfig
+
+	latestBlk, err := conn.Consensus().Core().GetBlock(ctx, api.HeightLatest)
+	if err != nil {
+		return trust, fmt.Errorf("failed to get latest block: %w", err)
+	}
+	latestHeight := latestBlk.Height
+
+	cpInterval, err := fetchCheckpointInterval(ctx, conn, latestHeight)
+	if err != nil {
+		return trust, fmt.Errorf("failed to fetch checkpoint interval: %w", err)
+	}
+
+	blkTime, err := calcAvgBlkTime(ctx, conn, latestBlk)
+	if err != nil {
+		return trust, fmt.Errorf("failed to calculate average block time: %w", err)
+	}
+
+	debondingPeriod, err := calcDebondingPeriod(ctx, conn, latestHeight, blkTime)
+	if err != nil {
+		return trust, fmt.Errorf("failed to calculate debonding period (height: %d): %w", latestHeight, err)
+	}
+	trustPeriod := calcTrustPeriod(debondingPeriod)
+
+	// Going back the whole checkpoint interval guarantees there will be at least
+	// one checkpoint available.
+	if cpInterval > latestHeight {
+		return trust, fmt.Errorf("checkpoint interval exceeds latest height")
+	}
+	candHeight := latestHeight - cpInterval
+	candBlk, err := conn.Consensus().Core().GetBlock(ctx, candHeight)
+	if err != nil {
+		return trust, fmt.Errorf("failed to get candidate trust (height: %d): %w", candHeight, err)
+	}
+
+	// Sanity check: the trusted root must not be older than the sum of the trust
+	// period and the maximum verification time. If it is, the light client will
+	// not be able to safely use this block as a trusted root for the state sync.
+	if candBlk.Time.Add(trustPeriod).Add(maxVerificationTime).Before(time.Now()) {
+		return trust, fmt.Errorf("failed to verify candidate trust root")
+	}
+
+	trust.Period = trustPeriod
+	trust.Height = uint64(candHeight) // #nosec G115
+	trust.Hash = candBlk.Hash.Hex()
+	return trust, nil
+}
+
+func fetchCheckpointInterval(ctx context.Context, conn connection.Connection, height int64) (int64, error) {
+	params, err := conn.Consensus().Core().GetParameters(ctx, height)
+	if err != nil {
+		return 0, fmt.Errorf("failed to get consensus parameters (height: %d): %w", height, err)
+	}
+	return int64(params.Parameters.StateCheckpointInterval), nil // #nosec G115
+}
+
+func calcAvgBlkTime(ctx context.Context, conn connection.Connection, latest *api.Block) (time.Duration, error) {
+	var deltaBlocks int64 = 1000
+	blk, err := conn.Consensus().Core().GetBlock(ctx, latest.Height-deltaBlocks)
+	if err != nil {
+		return 0, fmt.Errorf("failed to get latest block: %w", err)
+	}
+
+	return latest.Time.Sub(blk.Time) / time.Duration(deltaBlocks), nil
+}
+
+func calcDebondingPeriod(ctx context.Context, conn connection.Connection, height int64, blkTime time.Duration) (time.Duration, error) {
+	stakingParams, err := conn.Consensus().Staking().ConsensusParameters(ctx, height)
+	if err != nil {
+		return 0, fmt.Errorf("failed to get staking parameters: %w", err)
+	}
+	beaconParams, err := conn.Consensus().Beacon().ConsensusParameters(ctx, height)
+	if err != nil {
+		return 0, fmt.Errorf("failed to get beacon parameters: %w", err)
+	}
+	debondingBlks := int64(stakingParams.DebondingInterval) * beaconParams.Interval() // #nosec G115
+	return time.Duration(debondingBlks) * blkTime, nil
+}
+
+func calcTrustPeriod(debondingPeriod time.Duration) time.Duration {
+	return time.Duration(float64(debondingPeriod) * trustPeriodFraction)
+}
+
+func init() {
+	trustCmd.Flags().AddFlagSet(common.FormatFlag)
+	trustCmd.Flags().AddFlagSet(common.SelectorNFlags)
+}

examples/setup/first-run.out

@@ -12,6 +12,7 @@ Available Commands:
   network     Consensus layer operations
   paratime    ParaTime layer operations
   rofl        ROFL app management
+  state-sync  State sync utilities for the consensus layer
   transaction Raw transaction operations
   update      Download and install the newest Oasis CLI release
   wallet      Manage accounts in the local wallet

examples/state-sync/trust.in.static

@@ -0,0 +1 @@
+./oasis state-sync trust  --network testnet

examples/state-sync/trust.out.static

@@ -0,0 +1,3 @@
+Trust period:  239h31m33.6s
+Trust height:  29073305
+Trust hash:  846151e51599876c91427b2239775994fafa48d3cc5172b7b3d16be105249041