feat: environment-driven snapshot restore with targetHeight selection (#51)

## Summary
- Snapshot restore derives S3 bucket/region/chainID from environment
(SEI_SNAPSHOT_BUCKET, SEI_SNAPSHOT_REGION, SEI_CHAIN_ID)
- Only task param is now `targetHeight`:
  - `> 0`: lists S3 objects, picks highest snapshot <= target
  - `== 0`: reads latest.txt for newest snapshot
- Simplified filename convention: `{height}.tar.gz` (removed
chain/region suffix)
- Added ObjectLister interface for S3 ListObjectsV2 pagination
- serve.go validates snapshot env vars at startup

## Test plan
- [x] All sidecar tests pass
- [x] Target height selection tested (picks correct snapshot, errors on
no match)
- [x] Latest.txt path tested
- [x] Client round-trip tests updated

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: bdchatham

serve.go

@@ -42,11 +42,15 @@ var serveCmd = cli.Command{
 		chainID := os.Getenv("SEI_CHAIN_ID")
 		genesisBucket := os.Getenv("SEI_GENESIS_BUCKET")
 		genesisRegion := os.Getenv("SEI_GENESIS_REGION")
+		snapshotBucket := os.Getenv("SEI_SNAPSHOT_BUCKET")
+		snapshotRegion := os.Getenv("SEI_SNAPSHOT_REGION")
 
 		for _, kv := range []struct{ name, val string }{
 			{"SEI_CHAIN_ID", chainID},
 			{"SEI_GENESIS_BUCKET", genesisBucket},
 			{"SEI_GENESIS_REGION", genesisRegion},
+			{"SEI_SNAPSHOT_BUCKET", snapshotBucket},
+			{"SEI_SNAPSHOT_REGION", snapshotRegion},
 		} {
 			if kv.val == "" {
 				return fmt.Errorf("required environment variable %s is not set", kv.name)
@@ -71,8 +75,13 @@ var serveCmd = cli.Command{
 			return fmt.Errorf("open result store: %w", err)
 		}
 
+		snapshotRestorer, err := tasks.NewSnapshotRestorer(homeDir, snapshotBucket, snapshotRegion, chainID, nil, nil)
+		if err != nil {
+			return fmt.Errorf("creating snapshot restorer: %w", err)
+		}
+
 		handlers := map[engine.TaskType]engine.TaskHandler{
-			engine.TaskSnapshotRestore:          tasks.NewSnapshotRestorer(homeDir, nil).Handler(),
+			engine.TaskSnapshotRestore:          snapshotRestorer.Handler(),
 			engine.TaskDiscoverPeers:            tasks.NewPeerDiscoverer(homeDir, nil, nil).Handler(),
 			engine.TaskConfigPatch:              tasks.NewConfigPatcher(homeDir).Handler(),
 			engine.TaskConfigApply:              tasks.NewConfigApplier(homeDir).Handler(),

sidecar/client/client_test.go

@@ -69,19 +69,16 @@ func TestSubmitTask_HTTP201(t *testing.T) {
 			t.Fatal("Params is nil")
 		}
 		params := *req.Params
-		if params["bucket"] != "my-bucket" {
-			t.Errorf("bucket = %v, want my-bucket", params["bucket"])
+		if params["targetHeight"] != float64(100000000) {
+			t.Errorf("targetHeight = %v, want 100000000", params["targetHeight"])
 		}
 		w.Header().Set("Content-Type", "application/json")
 		w.WriteHeader(http.StatusCreated)
 		_ = json.NewEncoder(w).Encode(TaskSubmitResponse{Id: taskID})
 	}))
 
 	task := SnapshotRestoreTask{
-		Bucket:  "my-bucket",
-		Prefix:  "snapshots",
-		Region:  "us-east-1",
-		ChainID: "sei-chain",
+		TargetHeight: 100000000,
 	}
 	id, err := c.SubmitSnapshotRestoreTask(context.Background(), task)
 	if err != nil {
@@ -206,7 +203,8 @@ func TestSubmitTask_ValidationFailure(t *testing.T) {
 		t.Fatal("server should not be called when validation fails")
 	}))
 
-	_, err := c.SubmitSnapshotRestoreTask(context.Background(), SnapshotRestoreTask{})
+	// SnapshotUploadTask requires Bucket — empty should fail validation.
+	_, err := c.SubmitSnapshotUploadTask(context.Background(), SnapshotUploadTask{})
 	if err == nil {
 		t.Fatal("expected validation error")
 	}

sidecar/client/tasks.go

@@ -61,54 +61,40 @@ const (
 )
 
 // SnapshotRestoreTask downloads and extracts a snapshot archive from S3.
+// S3 coordinates are derived by the sidecar from its environment.
+// TargetHeight selects the highest available snapshot <= that height.
+// When zero, the latest snapshot (from latest.txt) is used.
 type SnapshotRestoreTask struct {
 	TaskMeta
-	Bucket  string
-	Prefix  string
-	Region  string
-	ChainID string
+	TargetHeight int64
 }
 
 func (t SnapshotRestoreTask) TaskType() string { return TaskTypeSnapshotRestore }
 
-func (t SnapshotRestoreTask) Validate() error {
-	if t.Bucket == "" {
-		return fmt.Errorf("snapshot-restore: missing required field Bucket")
-	}
-	if t.Prefix == "" {
-		return fmt.Errorf("snapshot-restore: missing required field Prefix")
-	}
-	if t.Region == "" {
-		return fmt.Errorf("snapshot-restore: missing required field Region")
-	}
-	if t.ChainID == "" {
-		return fmt.Errorf("snapshot-restore: missing required field ChainID")
-	}
-	return nil
-}
+func (t SnapshotRestoreTask) Validate() error { return nil }
 
 func (t SnapshotRestoreTask) ToTaskRequest() TaskRequest {
-	p := map[string]interface{}{
-		"bucket":  t.Bucket,
-		"prefix":  t.Prefix,
-		"region":  t.Region,
-		"chainId": t.ChainID,
+	var p *map[string]interface{}
+	if t.TargetHeight > 0 {
+		m := map[string]interface{}{"targetHeight": t.TargetHeight}
+		p = &m
 	}
-	req := TaskRequest{Type: t.TaskType(), Params: &p}
+	req := TaskRequest{Type: t.TaskType(), Params: p}
 	t.applyMeta(&req)
 	return req
 }
 
 // SnapshotRestoreTaskFromParams reconstructs a SnapshotRestoreTask from
 // a generic params map. Useful for round-trip testing.
 func SnapshotRestoreTaskFromParams(params map[string]interface{}) SnapshotRestoreTask {
-	s := func(k string) string { v, _ := params[k].(string); return v }
-	return SnapshotRestoreTask{
-		Bucket:  s("bucket"),
-		Prefix:  s("prefix"),
-		Region:  s("region"),
-		ChainID: s("chainId"),
-	}
+	var t SnapshotRestoreTask
+	switch h := params["targetHeight"].(type) {
+	case float64:
+		t.TargetHeight = int64(h)
+	case int64:
+		t.TargetHeight = h
+	}
+	return t
 }
 
 // SnapshotUploadTask archives and streams a local snapshot to S3.

sidecar/client/tasks_test.go

@@ -14,18 +14,8 @@ func genNonEmptyString() gopter.Gen {
 }
 
 func genSnapshotRestoreTask() gopter.Gen {
-	return gopter.CombineGens(
-		genNonEmptyString(),
-		genNonEmptyString(),
-		genNonEmptyString(),
-		genNonEmptyString(),
-	).Map(func(v []interface{}) SnapshotRestoreTask {
-		return SnapshotRestoreTask{
-			Bucket:  v[0].(string),
-			Prefix:  v[1].(string),
-			Region:  v[2].(string),
-			ChainID: v[3].(string),
-		}
+	return gen.Int64Range(0, 300000000).Map(func(h int64) SnapshotRestoreTask {
+		return SnapshotRestoreTask{TargetHeight: h}
 	})
 }
 
@@ -111,11 +101,11 @@ func TestSnapshotRestoreRoundTrip(t *testing.T) {
 			if req.Type != TaskTypeSnapshotRestore {
 				return false
 			}
+			if task.TargetHeight == 0 {
+				return req.Params == nil
+			}
 			rebuilt := SnapshotRestoreTaskFromParams(*req.Params)
-			return rebuilt.Bucket == task.Bucket &&
-				rebuilt.Prefix == task.Prefix &&
-				rebuilt.Region == task.Region &&
-				rebuilt.ChainID == task.ChainID
+			return rebuilt.TargetHeight == task.TargetHeight
 		},
 		genSnapshotRestoreTask(),
 	))
@@ -269,21 +259,19 @@ func TestMarkReadyRoundTrip(t *testing.T) {
 	}
 }
 
-func TestSnapshotRestoreValidationRejectsMissingFields(t *testing.T) {
+func TestSnapshotRestoreValidation(t *testing.T) {
+	// SnapshotRestoreTask has no required fields — TargetHeight=0 means "use latest"
 	cases := []struct {
 		name string
 		task SnapshotRestoreTask
 	}{
-		{"missing bucket", SnapshotRestoreTask{Prefix: "p", Region: "r", ChainID: "c"}},
-		{"missing prefix", SnapshotRestoreTask{Bucket: "b", Region: "r", ChainID: "c"}},
-		{"missing region", SnapshotRestoreTask{Bucket: "b", Prefix: "p", ChainID: "c"}},
-		{"missing chainId", SnapshotRestoreTask{Bucket: "b", Prefix: "p", Region: "r"}},
-		{"all empty", SnapshotRestoreTask{}},
+		{"zero height (latest)", SnapshotRestoreTask{}},
+		{"with target height", SnapshotRestoreTask{TargetHeight: 100000000}},
 	}
 	for _, tc := range cases {
 		t.Run(tc.name, func(t *testing.T) {
-			if err := tc.task.Validate(); err == nil {
-				t.Error("expected validation error, got nil")
+			if err := tc.task.Validate(); err != nil {
+				t.Errorf("unexpected validation error: %v", err)
 			}
 		})
 	}

sidecar/s3/client.go

@@ -46,6 +46,23 @@ func DefaultUploaderFactory(ctx context.Context, region string) (Uploader, error
 	return transfermanager.New(s3.NewFromConfig(cfg)), nil
 }
 
+// ObjectLister abstracts S3 ListObjectsV2 for snapshot discovery.
+type ObjectLister interface {
+	ListObjectsV2(ctx context.Context, input *s3.ListObjectsV2Input, opts ...func(*s3.Options)) (*s3.ListObjectsV2Output, error)
+}
+
+// ObjectListerFactory builds an ObjectLister for a given region.
+type ObjectListerFactory func(ctx context.Context, region string) (ObjectLister, error)
+
+// DefaultObjectListerFactory creates a real S3 client for listing objects.
+func DefaultObjectListerFactory(ctx context.Context, region string) (ObjectLister, error) {
+	cfg, err := config.LoadDefaultConfig(ctx, config.WithRegion(region))
+	if err != nil {
+		return nil, fmt.Errorf("loading AWS config: %w", err)
+	}
+	return s3.NewFromConfig(cfg), nil
+}
+
 // WriteAtBuffer is a goroutine-safe in-memory io.WriterAt, used for
 // downloading small S3 objects (e.g. latest.txt) via DownloadObject.
 type WriteAtBuffer struct {