nit

mod/node-api/handlers/proof/block_proposer.go

@@ -26,8 +26,9 @@ import (
 	"github.com/berachain/beacon-kit/mod/node-api/handlers/utils"
 )
 
-// GetBlockProposer returns the block proposer pubkey for the given block id
-// along with a merkle proof that can be verified against the beacon block root.
+// GetBlockProposer returns the block proposer pubkey for the given timestamp
+// id along with a merkle proof that can be verified against the beacon block
+// root.
 func (h *Handler[
 	BeaconBlockHeaderT, _, _, ContextT, _, _,
 ]) GetBlockProposer(c ContextT) (any, error) {

mod/node-api/handlers/proof/execution_fee_recipient.go

@@ -27,7 +27,7 @@ import (
 )
 
 // GetExecutionFeeRecipient returns the fee recipient from the latest execution
-// payload header for the given block id, along with the proof that can be
+// payload header for the given timestamp id, along with the proof that can be
 // verified against the beacon block root.
 func (h *Handler[
 	BeaconBlockHeaderT, _, _, ContextT, _, _,

mod/node-api/handlers/proof/execution_number.go

@@ -27,7 +27,7 @@ import (
 )
 
 // GetExecutionNumber returns the block number from the latest execution
-// payload header for the given block id, along with the proof that can be
+// payload header for the given timestamp id, along with the proof that can be
 // verified against the beacon block root.
 func (h *Handler[
 	BeaconBlockHeaderT, _, _, ContextT, _, _,

mod/node-api/handlers/utils/id.go

@@ -70,17 +70,18 @@ func SlotFromBlockID[StorageBackendT interface {
 	return storage.GetSlotByBlockRoot(root)
 }
 
-// ParentSlotFromTimestampID returns the slot from the block timestamp ID.
+// ParentSlotFromTimestampID returns the parent slot corresponding to the
+// timestamp ID.
 //
 // NOTE: `timestampID` shares the same semantics as `stateID`, with the
-// modification of being able to query by next block <timestamp> instead of
-// <stateRoot>.
+// modification of being able to query by next block's <timestamp> instead of
+// the current block's <stateRoot>.
 //
 // The <timestamp> must be prefixed by the 't', followed by the timestamp
-// in decimal notation. For example 't1728681738' corresponds to the slot with
-// next block timestamp of 1728681738. Providing just the string '1728681738'
-// (without the prefix 't') will query for the beacon block with slot
-// 1728681738.
+// in decimal UNIX notation. For example 't1728681738' corresponds to the slot
+// which has the next block with a timestamp of 1728681738. Providing just the
+// string '1728681738' (without the prefix 't') will query for the beacon block
+// for slot 1728681738.
 func ParentSlotFromTimestampID[StorageBackendT interface {
 	GetParentSlotByTimestamp(timestamp math.U64) (math.Slot, error)
 }](timestampID string, storage StorageBackendT) (math.Slot, error) {

mod/storage/pkg/block/store.go

@@ -93,9 +93,7 @@ func (kv *KVStore[BeaconBlockT]) GetParentSlotByTimestamp(
 ) (math.Slot, error) {
 	slot, _ := kv.timestamps.Peek(timestamp)
 	if slot == 0 {
-		return slot, fmt.Errorf(
-			"parent slot not found at timestamp: %d", timestamp,
-		)
+		return slot, fmt.Errorf("slot not found at timestamp: %d", timestamp)
 	}
 
 	return slot - 1, nil

mod/storage/pkg/block/store_test.go

@@ -65,15 +65,15 @@ func TestBlockStore(t *testing.T) {
 		require.NoError(t, err)
 	}
 
-	// Get the slots by roots & execution numbers.
+	// Get the slots by roots & timestamps.
 	for i := math.Slot(3); i <= 7; i++ {
 		slot, err = blockStore.GetSlotByBlockRoot([32]byte{byte(i)})
 		require.NoError(t, err)
 		require.Equal(t, i, slot)
 
 		slot, err = blockStore.GetParentSlotByTimestamp(i)
 		require.NoError(t, err)
-		require.Equal(t, i, slot)
+		require.Equal(t, i-1, slot)
 
 		slot, err = blockStore.GetSlotByStateRoot([32]byte{byte(i)})
 		require.NoError(t, err)