zoneconcierge: API for querying headers in a given epoch

proto/babylon/zoneconcierge/query.proto

@@ -30,10 +30,18 @@ service Query {
   rpc ChainInfo(QueryChainInfoRequest) returns (QueryChainInfoResponse) {
     option (google.api.http).get = "/babylon/zoneconcierge/v1/chain_info/{chain_id}";
   }
+  // EpochChainInfo queries the latest info of a chain in a given epoch of Babylon's view
+  rpc EpochChainInfo(QueryEpochChainInfoRequest) returns (QueryEpochChainInfoResponse) {
+    option (google.api.http).get = "/babylon/zoneconcierge/v1/epochs/{epoch_num}/chain_info/{chain_id}";
+  }
   // ListHeaders queries the headers of a chain in Babylon's view, with pagination support
   rpc ListHeaders(QueryListHeadersRequest) returns (QueryListHeadersResponse) {
     option (google.api.http).get = "/babylon/zoneconcierge/v1/headers/{chain_id}";
   }
+  // ListEpochHeaders queries the headers of a chain timestamped in a given epoch of Babylon, with pagination support
+  rpc ListEpochHeaders(QueryListEpochHeadersRequest) returns (QueryListEpochHeadersResponse) {
+    option (google.api.http).get = "/babylon/zoneconcierge/v1/epochs/{epoch_num}/headers/{chain_id}";
+  }
   // FinalizedChainInfo queries the BTC-finalised info of a chain, with proofs
   rpc FinalizedChainInfo(QueryFinalizedChainInfoRequest) returns (QueryFinalizedChainInfoResponse) {
     option (google.api.http).get = "/babylon/zoneconcierge/v1/finalized_chain_info/{chain_id}";
@@ -68,6 +76,18 @@ message QueryChainInfoResponse {
   babylon.zoneconcierge.v1.ChainInfo chain_info = 1;
 }
 
+// QueryEpochChainInfoRequest is request type for the Query/EpochChainInfo RPC method.
+message QueryEpochChainInfoRequest {
+  uint64 epoch_num = 1;
+  string chain_id = 2;
+}
+
+// QueryEpochChainInfoResponse is response type for the Query/EpochChainInfo RPC method.
+message QueryEpochChainInfoResponse {
+  // chain_info is the info of the CZ
+  babylon.zoneconcierge.v1.ChainInfo chain_info = 1;
+}
+
 // QueryListHeadersRequest is request type for the Query/ListHeaders RPC method.
 message QueryListHeadersRequest {
   string chain_id = 1;
@@ -83,6 +103,18 @@ message QueryListHeadersResponse {
   cosmos.base.query.v1beta1.PageResponse pagination = 2;
 }
 
+// QueryListEpochHeadersRequest is request type for the Query/ListEpochHeaders RPC method.
+message QueryListEpochHeadersRequest {
+  uint64 epoch_num = 1;
+  string chain_id = 2;
+}
+
+// QueryListEpochHeadersResponse is response type for the Query/ListEpochHeaders RPC method.
+message QueryListEpochHeadersResponse {
+  // headers is the list of headers
+  repeated babylon.zoneconcierge.v1.IndexedHeader headers = 1;
+}
+
 // QueryFinalizedChainInfoRequest is request type for the Query/FinalizedChainInfo RPC method.
 message QueryFinalizedChainInfoRequest {
   // chain_id is the ID of the CZ

x/zoneconcierge/keeper/canonical_chain_indexer_test.go

@@ -14,7 +14,8 @@ func FuzzCanonicalChainIndexer(f *testing.F) {
 	f.Fuzz(func(t *testing.T, seed int64) {
 		rand.Seed(seed)
 
-		_, babylonChain, czChain, zcKeeper := SetupTest(t)
+		_, babylonChain, czChain, babylonApp := SetupTest(t)
+		zcKeeper := babylonApp.ZoneConciergeKeeper
 
 		ctx := babylonChain.GetContext()
 		hooks := zcKeeper.Hooks()

x/zoneconcierge/keeper/epoch_chain_info_indexer.go

@@ -1,6 +1,7 @@
 package keeper
 
 import (
+	bbn "github.com/babylonchain/babylon/types"
 	"github.com/babylonchain/babylon/x/zoneconcierge/types"
 	"github.com/cosmos/cosmos-sdk/store/prefix"
 	sdk "github.com/cosmos/cosmos-sdk/types"
@@ -19,6 +20,46 @@ func (k Keeper) GetEpochChainInfo(ctx sdk.Context, chainID string, epochNumber u
 	return &chainInfo, nil
 }
 
+// GetEpochHeaders gets the headers timestamped in a given epoch, in the ascending order
+func (k Keeper) GetEpochHeaders(ctx sdk.Context, chainID string, epochNumber uint64) ([]*types.IndexedHeader, error) {
+	headers := []*types.IndexedHeader{}
+
+	// find the last timestamped header of this chain in the epoch
+	epochChainInfo, err := k.GetEpochChainInfo(ctx, chainID, epochNumber)
+	if err != nil {
+		return nil, err
+	}
+	// it's possible that this epoch's snapshot is not updated for many epochs
+	// this implies that this epoch does not timestamp any header for this chain at all
+	// and the query should return empty
+	if epochChainInfo.LatestHeader.BabylonEpoch < epochNumber {
+		return nil, types.ErrEpochHeadersNotFound
+	}
+	// now we have the last header in this epoch
+	headers = append(headers, epochChainInfo.LatestHeader)
+
+	// append all previous headers until reaching the previous epoch
+	canonicalChainStore := k.canonicalChainStore(ctx, chainID)
+	lastHeaderKey := sdk.Uint64ToBigEndian(epochChainInfo.LatestHeader.Height)
+	// NOTE: even in ReverseIterator, start and end should still be specified in ascending order
+	canonicalChainIter := canonicalChainStore.ReverseIterator(nil, lastHeaderKey)
+	defer canonicalChainIter.Close()
+	for ; canonicalChainIter.Valid(); canonicalChainIter.Next() {
+		var prevHeader types.IndexedHeader
+		k.cdc.MustUnmarshal(canonicalChainIter.Value(), &prevHeader)
+		if prevHeader.BabylonEpoch < epochNumber {
+			// we have reached the previous epoch, break the loop
+			break
+		}
+		headers = append(headers, &prevHeader)
+	}
+
+	// reverse the list so that it remains ascending order
+	bbn.Reverse(headers)
+
+	return headers, nil
+}
+
 // recordEpochChainInfo records the chain info for a given epoch number of given chain ID
 // where the latest chain info is retrieved from the chain info indexer
 func (k Keeper) recordEpochChainInfo(ctx sdk.Context, chainID string, epochNumber uint64) {

x/zoneconcierge/keeper/epoch_chain_info_indexer_test.go

@@ -14,7 +14,8 @@ func FuzzEpochChainInfoIndexer(f *testing.F) {
 	f.Fuzz(func(t *testing.T, seed int64) {
 		rand.Seed(seed)
 
-		_, babylonChain, czChain, zcKeeper := SetupTest(t)
+		_, babylonChain, czChain, babylonApp := SetupTest(t)
+		zcKeeper := babylonApp.ZoneConciergeKeeper
 
 		ctx := babylonChain.GetContext()
 		hooks := zcKeeper.Hooks()
@@ -35,3 +36,40 @@ func FuzzEpochChainInfoIndexer(f *testing.F) {
 		require.Equal(t, numForkHeaders, uint64(len(chainInfo.LatestForks.Headers)))
 	})
 }
+
+func FuzzGetEpochHeaders(f *testing.F) {
+	datagen.AddRandomSeedsToFuzzer(f, 10)
+
+	f.Fuzz(func(t *testing.T, seed int64) {
+		rand.Seed(seed)
+
+		_, babylonChain, czChain, babylonApp := SetupTest(t)
+		zcKeeper := babylonApp.ZoneConciergeKeeper
+		epochingKeeper := babylonApp.EpochingKeeper
+
+		ctx := babylonChain.GetContext()
+		hooks := zcKeeper.Hooks()
+
+		// enter a random epoch
+		epochNum := datagen.RandomInt(10) + 1
+		for i := uint64(0); i < epochNum; i++ {
+			epochingKeeper.IncEpoch(ctx)
+		}
+
+		// invoke the hook a random number of times to simulate a random number of blocks
+		numHeaders := datagen.RandomInt(100) + 1
+		numForkHeaders := datagen.RandomInt(10) + 1
+		expectedHeaders, _ := SimulateHeadersAndForksViaHook(ctx, hooks, czChain.ChainID, numHeaders, numForkHeaders)
+
+		// end this epoch so that the chain info is recorded
+		hooks.AfterEpochEnds(ctx, epochNum)
+
+		// check if the headers are same as expected
+		headers, err := zcKeeper.GetEpochHeaders(ctx, czChain.ChainID, epochNum)
+		require.NoError(t, err)
+		require.Equal(t, len(expectedHeaders), len(headers))
+		for i := 0; i < len(expectedHeaders); i++ {
+			require.Equal(t, expectedHeaders[i].Header.LastCommitHash, headers[i].Hash)
+		}
+	})
+}

x/zoneconcierge/keeper/fork_indexer_test.go

@@ -14,7 +14,8 @@ func FuzzForkIndexer(f *testing.F) {
 	f.Fuzz(func(t *testing.T, seed int64) {
 		rand.Seed(seed)
 
-		_, babylonChain, czChain, zcKeeper := SetupTest(t)
+		_, babylonChain, czChain, babylonApp := SetupTest(t)
+		zcKeeper := babylonApp.ZoneConciergeKeeper
 
 		ctx := babylonChain.GetContext()
 		hooks := zcKeeper.Hooks()

x/zoneconcierge/keeper/grpc_query.go

@@ -45,6 +45,27 @@ func (k Keeper) ChainInfo(c context.Context, req *types.QueryChainInfoRequest) (
 	return resp, nil
 }
 
+// EpochChainInfo returns the info of a chain with given ID in a given epoch
+func (k Keeper) EpochChainInfo(c context.Context, req *types.QueryEpochChainInfoRequest) (*types.QueryEpochChainInfoResponse, error) {
+	if req == nil {
+		return nil, status.Error(codes.InvalidArgument, "invalid request")
+	}
+
+	if len(req.ChainId) == 0 {
+		return nil, status.Error(codes.InvalidArgument, "chain ID cannot be empty")
+	}
+
+	ctx := sdk.UnwrapSDKContext(c)
+
+	// find the chain info of the given epoch
+	chainInfo, err := k.GetEpochChainInfo(ctx, req.ChainId, req.EpochNum)
+	if err != nil {
+		return nil, err
+	}
+	resp := &types.QueryEpochChainInfoResponse{ChainInfo: chainInfo}
+	return resp, nil
+}
+
 // ListHeaders returns all headers of a chain with given ID, with pagination support
 func (k Keeper) ListHeaders(c context.Context, req *types.QueryListHeadersRequest) (*types.QueryListHeadersResponse, error) {
 	if req == nil {
@@ -76,6 +97,29 @@ func (k Keeper) ListHeaders(c context.Context, req *types.QueryListHeadersReques
 	return resp, nil
 }
 
+// ListEpochHeaders returns all headers of a chain with given ID, with pagination support
+func (k Keeper) ListEpochHeaders(c context.Context, req *types.QueryListEpochHeadersRequest) (*types.QueryListEpochHeadersResponse, error) {
+	if req == nil {
+		return nil, status.Error(codes.InvalidArgument, "invalid request")
+	}
+
+	if len(req.ChainId) == 0 {
+		return nil, status.Error(codes.InvalidArgument, "chain ID cannot be empty")
+	}
+
+	ctx := sdk.UnwrapSDKContext(c)
+
+	headers, err := k.GetEpochHeaders(ctx, req.ChainId, req.EpochNum)
+	if err != nil {
+		return nil, err
+	}
+
+	resp := &types.QueryListEpochHeadersResponse{
+		Headers: headers,
+	}
+	return resp, nil
+}
+
 func (k Keeper) FinalizedChainInfo(c context.Context, req *types.QueryFinalizedChainInfoRequest) (*types.QueryFinalizedChainInfoResponse, error) {
 	if req == nil {
 		return nil, status.Error(codes.InvalidArgument, "invalid request")
@@ -101,7 +145,7 @@ func (k Keeper) FinalizedChainInfo(c context.Context, req *types.QueryFinalizedC
 
 	// It's possible that the chain info's epoch is way before the last finalised epoch
 	// e.g., when there is no relayer for many epochs
-	// NOTE: if an epoch is finalisedm then all of its previous epochs are also finalised
+	// NOTE: if an epoch is finalised then all of its previous epochs are also finalised
 	if chainInfo.LatestHeader.BabylonEpoch < finalizedEpoch {
 		finalizedEpoch = chainInfo.LatestHeader.BabylonEpoch
 	}

x/zoneconcierge/keeper/grpc_query_test.go

@@ -24,7 +24,8 @@ func FuzzChainList(f *testing.F) {
 	f.Fuzz(func(t *testing.T, seed int64) {
 		rand.Seed(seed)
 
-		_, babylonChain, _, zcKeeper := SetupTest(t)
+		_, babylonChain, _, babylonApp := SetupTest(t)
+		zcKeeper := babylonApp.ZoneConciergeKeeper
 
 		ctx := babylonChain.GetContext()
 		hooks := zcKeeper.Hooks()
@@ -66,7 +67,8 @@ func FuzzChainInfo(f *testing.F) {
 	f.Fuzz(func(t *testing.T, seed int64) {
 		rand.Seed(seed)
 
-		_, babylonChain, czChain, zcKeeper := SetupTest(t)
+		_, babylonChain, czChain, babylonApp := SetupTest(t)
+		zcKeeper := babylonApp.ZoneConciergeKeeper
 
 		ctx := babylonChain.GetContext()
 		hooks := zcKeeper.Hooks()
@@ -85,13 +87,44 @@ func FuzzChainInfo(f *testing.F) {
 	})
 }
 
+func FuzzEpochChainInfo(f *testing.F) {
+	datagen.AddRandomSeedsToFuzzer(f, 10)
+
+	f.Fuzz(func(t *testing.T, seed int64) {
+		rand.Seed(seed)
+
+		_, babylonChain, czChain, babylonApp := SetupTest(t)
+		zcKeeper := babylonApp.ZoneConciergeKeeper
+
+		ctx := babylonChain.GetContext()
+		hooks := zcKeeper.Hooks()
+
+		// invoke the hook a random number of times to simulate a random number of blocks
+		numHeaders := datagen.RandomInt(100) + 1
+		numForkHeaders := datagen.RandomInt(10) + 1
+		SimulateHeadersAndForksViaHook(ctx, hooks, czChain.ChainID, numHeaders, numForkHeaders)
+
+		// simulate the scenario that a random epoch has ended
+		epochNum := datagen.RandomInt(10)
+		hooks.AfterEpochEnds(ctx, epochNum)
+
+		// check if the chain info of is recorded or not
+		resp, err := zcKeeper.EpochChainInfo(ctx, &zctypes.QueryEpochChainInfoRequest{EpochNum: epochNum, ChainId: czChain.ChainID})
+		require.NoError(t, err)
+		chainInfo := resp.ChainInfo
+		require.Equal(t, numHeaders-1, chainInfo.LatestHeader.Height)
+		require.Equal(t, numForkHeaders, uint64(len(chainInfo.LatestForks.Headers)))
+	})
+}
+
 func FuzzListHeaders(f *testing.F) {
 	datagen.AddRandomSeedsToFuzzer(f, 10)
 
 	f.Fuzz(func(t *testing.T, seed int64) {
 		rand.Seed(seed)
 
-		_, babylonChain, czChain, zcKeeper := SetupTest(t)
+		_, babylonChain, czChain, babylonApp := SetupTest(t)
+		zcKeeper := babylonApp.ZoneConciergeKeeper
 
 		ctx := babylonChain.GetContext()
 		hooks := zcKeeper.Hooks()
@@ -118,6 +151,47 @@ func FuzzListHeaders(f *testing.F) {
 	})
 }
 
+func FuzzListEpochHeaders(f *testing.F) {
+	datagen.AddRandomSeedsToFuzzer(f, 10)
+
+	f.Fuzz(func(t *testing.T, seed int64) {
+		rand.Seed(seed)
+
+		_, babylonChain, czChain, babylonApp := SetupTest(t)
+		zcKeeper := babylonApp.ZoneConciergeKeeper
+		epochingKeeper := babylonApp.EpochingKeeper
+
+		ctx := babylonChain.GetContext()
+		hooks := zcKeeper.Hooks()
+
+		// enter a random epoch
+		epochNum := datagen.RandomInt(10) + 1
+		for i := uint64(0); i < epochNum; i++ {
+			epochingKeeper.IncEpoch(ctx)
+		}
+
+		// invoke the hook a random number of times to simulate a random number of blocks
+		numHeaders := datagen.RandomInt(100) + 1
+		numForkHeaders := datagen.RandomInt(10) + 1
+		expectedHeaders, _ := SimulateHeadersAndForksViaHook(ctx, hooks, czChain.ChainID, numHeaders, numForkHeaders)
+
+		// end this epoch so that the chain info is recorded
+		hooks.AfterEpochEnds(ctx, epochNum)
+
+		req := &zctypes.QueryListEpochHeadersRequest{
+			ChainId:  czChain.ChainID,
+			EpochNum: epochNum,
+		}
+		resp, err := zcKeeper.ListEpochHeaders(ctx, req)
+		require.NoError(t, err)
+
+		require.Equal(t, len(expectedHeaders), len(resp.Headers))
+		for i := 0; i < len(expectedHeaders); i++ {
+			require.Equal(t, expectedHeaders[i].Header.LastCommitHash, resp.Headers[i].Hash)
+		}
+	})
+}
+
 func FuzzFinalizedChainInfo(f *testing.F) {
 	datagen.AddRandomSeedsToFuzzer(f, 10)
 

x/zoneconcierge/keeper/keeper_test.go

@@ -13,13 +13,13 @@ import (
 )
 
 // SetupTest creates a coordinator with 2 test chains, and a ZoneConcierge keeper.
-func SetupTest(t *testing.T) (*ibctesting.Coordinator, *ibctesting.TestChain, *ibctesting.TestChain, zckeeper.Keeper) {
-	var zcKeeper zckeeper.Keeper
+func SetupTest(t *testing.T) (*ibctesting.Coordinator, *ibctesting.TestChain, *ibctesting.TestChain, *app.BabylonApp) {
+	var bbnApp *app.BabylonApp
 	coordinator := ibctesting.NewCoordinator(t, 2)
 	// replace the first test chain with a Babylon chain
 	ibctesting.DefaultTestingAppInit = func() (ibctesting.TestingApp, map[string]json.RawMessage) {
 		babylonApp := app.Setup(t, false)
-		zcKeeper = babylonApp.ZoneConciergeKeeper
+		bbnApp = babylonApp
 		encCdc := app.MakeTestEncodingConfig()
 		genesis := app.NewDefaultGenesisState(encCdc.Marshaler)
 		return babylonApp, genesis
@@ -30,7 +30,7 @@ func SetupTest(t *testing.T) (*ibctesting.Coordinator, *ibctesting.TestChain, *i
 	babylonChain := coordinator.GetChain(ibctesting.GetChainID(1))
 	czChain := coordinator.GetChain(ibctesting.GetChainID(2))
 
-	return coordinator, babylonChain, czChain, zcKeeper
+	return coordinator, babylonChain, czChain, bbnApp
 }
 
 // SimulateHeadersViaHook generates a non-zero number of canonical headers via the hook