Add getLedgers implementation

cmd/soroban-rpc/internal/config/main.go

@@ -26,6 +26,7 @@ type Config struct {
 	CoreRequestTimeout                             time.Duration
 	DefaultEventsLimit                             uint
 	DefaultTransactionsLimit                       uint
+	DefaultLedgersLimit                            uint
 	EventLedgerRetentionWindow                     uint32
 	FriendbotURL                                   string
 	HistoryArchiveURLs                             []string
@@ -35,6 +36,7 @@ type Config struct {
 	LogLevel                                       logrus.Level
 	MaxEventsLimit                                 uint
 	MaxTransactionsLimit                           uint
+	MaxLedgersLimit                                uint
 	MaxHealthyLedgerLatency                        time.Duration
 	NetworkPassphrase                              string
 	PreflightWorkerCount                           uint
@@ -54,6 +56,7 @@ type Config struct {
 	RequestBacklogGetLedgerEntriesQueueLimit       uint
 	RequestBacklogGetTransactionQueueLimit         uint
 	RequestBacklogGetTransactionsQueueLimit        uint
+	RequestBacklogGetLedgersQueueLimit             uint
 	RequestBacklogSendTransactionQueueLimit        uint
 	RequestBacklogSimulateTransactionQueueLimit    uint
 	RequestBacklogGetFeeStatsTransactionQueueLimit uint
@@ -67,6 +70,7 @@ type Config struct {
 	MaxGetLedgerEntriesExecutionDuration           time.Duration
 	MaxGetTransactionExecutionDuration             time.Duration
 	MaxGetTransactionsExecutionDuration            time.Duration
+	MaxGetLedgersExecutionDuration                 time.Duration
 	MaxSendTransactionExecutionDuration            time.Duration
 	MaxSimulateTransactionExecutionDuration        time.Duration
 	MaxGetFeeStatsExecutionDuration                time.Duration

cmd/soroban-rpc/internal/config/options.go

@@ -304,6 +304,28 @@ func (cfg *Config) options() Options {
 				return nil
 			},
 		},
+		{
+			Name:         "max-ledgers-limit",
+			Usage:        "Maximum amount of ledgers allowed in a single getLedgers response",
+			ConfigKey:    &cfg.MaxLedgersLimit,
+			DefaultValue: uint(200),
+		},
+		{
+			Name:         "default-ledgers-limit",
+			Usage:        "Default cap on the amount of ledgers included in a single getLedgers response",
+			ConfigKey:    &cfg.DefaultLedgersLimit,
+			DefaultValue: uint(50),
+			Validate: func(_ *Option) error {
+				if cfg.DefaultLedgersLimit > cfg.MaxLedgersLimit {
+					return fmt.Errorf(
+						"default-ledgers-limit (%v) cannot exceed max-ledgers-limit (%v)",
+						cfg.DefaultLedgersLimit,
+						cfg.MaxLedgersLimit,
+					)
+				}
+				return nil
+			},
+		},
 		{
 			Name: "max-healthy-ledger-latency",
 			Usage: "maximum ledger latency (i.e. time elapsed since the last known ledger closing time) considered to be healthy" +
@@ -394,6 +416,13 @@ func (cfg *Config) options() Options {
 			DefaultValue: uint(1000),
 			Validate:     positive,
 		},
+		{
+			TomlKey:      strutils.KebabToConstantCase("request-backlog-get-ledgers-queue-limit"),
+			Usage:        "Maximum number of outstanding getLedgers requests",
+			ConfigKey:    &cfg.RequestBacklogGetLedgersQueueLimit,
+			DefaultValue: uint(1000),
+			Validate:     positive,
+		},
 		{
 			TomlKey:      strutils.KebabToConstantCase("request-backlog-send-transaction-queue-limit"),
 			Usage:        "Maximum number of outstanding SendTransaction requests",
@@ -475,6 +504,12 @@ func (cfg *Config) options() Options {
 			ConfigKey:    &cfg.MaxGetTransactionsExecutionDuration,
 			DefaultValue: 5 * time.Second,
 		},
+		{
+			TomlKey:      strutils.KebabToConstantCase("max-get-ledgers-execution-duration"),
+			Usage:        "The maximum duration of time allowed for processing a getLedgers request. When that time elapses, the rpc server would return -32001 and abort the request's execution",
+			ConfigKey:    &cfg.MaxGetLedgersExecutionDuration,
+			DefaultValue: 5 * time.Second,
+		},
 		{
 			TomlKey:      strutils.KebabToConstantCase("max-send-transaction-execution-duration"),
 			Usage:        "The maximum duration of time allowed for processing a sendTransaction request. When that time elapses, the rpc server would return -32001 and abort the request's execution",

cmd/soroban-rpc/internal/db/ledger.go

@@ -19,6 +19,7 @@ type StreamLedgerFn func(xdr.LedgerCloseMeta) error
 
 type LedgerReader interface {
 	GetLedger(ctx context.Context, sequence uint32) (xdr.LedgerCloseMeta, bool, error)
+	BatchGetLedgers(ctx context.Context, sequence uint32, batchSize uint) ([]xdr.LedgerCloseMeta, error)
 	StreamAllLedgers(ctx context.Context, f StreamLedgerFn) error
 	GetLedgerRange(ctx context.Context) (ledgerbucketwindow.LedgerRange, error)
 	StreamLedgerRange(ctx context.Context, startLedger uint32, endLedger uint32, f StreamLedgerFn) error
@@ -103,6 +104,25 @@ func (r ledgerReader) GetLedger(ctx context.Context, sequence uint32) (xdr.Ledge
 	}
 }
 
+// BatchGetLedgers fetches ledgers in batches from the db.
+func (r ledgerReader) BatchGetLedgers(ctx context.Context, sequence uint32,
+	batchSize uint,
+) ([]xdr.LedgerCloseMeta, error) {
+	sql := sq.Select("meta").
+		From(ledgerCloseMetaTableName).
+		Where(sq.And{
+			sq.GtOrEq{"sequence": sequence},
+			sq.LtOrEq{"sequence": sequence + uint32(batchSize) - 1},
+		})
+
+	results := make([]xdr.LedgerCloseMeta, 0, batchSize)
+	if err := r.db.Select(ctx, &results, sql); err != nil {
+		return nil, err
+	}
+
+	return results, nil
+}
+
 // GetLedgerRange pulls the min/max ledger sequence numbers from the meta table.
 func (r ledgerReader) GetLedgerRange(ctx context.Context) (ledgerbucketwindow.LedgerRange, error) {
 	r.db.cache.RLock()

cmd/soroban-rpc/internal/db/ledger_test.go

@@ -183,25 +183,8 @@ func TestGetLedgerRange_EmptyDB(t *testing.T) {
 }
 
 func BenchmarkGetLedgerRange(b *testing.B) {
-	db := NewTestDB(b)
-	logger := log.DefaultLogger
-	writer := NewReadWriter(logger, db, interfaces.MakeNoOpDeamon(), 100, 1_000_000, passphrase)
-	write, err := writer.NewTx(context.TODO())
-	require.NoError(b, err)
-
-	// create 100k tx rows
-	lcms := make([]xdr.LedgerCloseMeta, 0, 100_000)
-	for i := range cap(lcms) {
-		lcms = append(lcms, txMeta(uint32(1234+i), i%2 == 0))
-	}
-
-	ledgerW, txW := write.LedgerWriter(), write.TransactionWriter()
-	for _, lcm := range lcms {
-		require.NoError(b, ledgerW.InsertLedger(lcm))
-		require.NoError(b, txW.InsertTransactions(lcm))
-	}
-	require.NoError(b, write.Commit(lcms[len(lcms)-1]))
-	reader := NewLedgerReader(db)
+	testDB, lcms := setupBenchmarkingDB(b)
+	reader := NewLedgerReader(testDB)
 
 	b.ResetTimer()
 	for range b.N {
@@ -212,6 +195,20 @@ func BenchmarkGetLedgerRange(b *testing.B) {
 	}
 }
 
+func BenchmarkBatchGetLedgers(b *testing.B) {
+	testDB, lcms := setupBenchmarkingDB(b)
+	reader := NewLedgerReader(testDB)
+	batchSize := uint(200) // using the current maximum value for getLedgers endpoint
+
+	b.ResetTimer()
+	for range b.N {
+		ledgers, err := reader.BatchGetLedgers(context.TODO(), 1334, batchSize)
+		require.NoError(b, err)
+		assert.Equal(b, lcms[0].LedgerSequence(), ledgers[0].LedgerSequence())
+		assert.Equal(b, lcms[batchSize-1].LedgerSequence(), ledgers[batchSize-1].LedgerSequence())
+	}
+}
+
 func NewTestDB(tb testing.TB) *DB {
 	tmp := tb.TempDir()
 	dbPath := path.Join(tmp, "db.sqlite")
@@ -222,3 +219,25 @@ func NewTestDB(tb testing.TB) *DB {
 	})
 	return db
 }
+
+func setupBenchmarkingDB(b *testing.B) (*DB, []xdr.LedgerCloseMeta) {
+	testDB := NewTestDB(b)
+	logger := log.DefaultLogger
+	writer := NewReadWriter(logger, testDB, interfaces.MakeNoOpDeamon(),
+		100, 1_000_000, passphrase)
+	write, err := writer.NewTx(context.TODO())
+	require.NoError(b, err)
+
+	lcms := make([]xdr.LedgerCloseMeta, 0, 100_000)
+	for i := range cap(lcms) {
+		lcms = append(lcms, txMeta(uint32(1234+i), i%2 == 0))
+	}
+
+	ledgerW, txW := write.LedgerWriter(), write.TransactionWriter()
+	for _, lcm := range lcms {
+		require.NoError(b, ledgerW.InsertLedger(lcm))
+		require.NoError(b, txW.InsertTransactions(lcm))
+	}
+	require.NoError(b, write.Commit(lcms[len(lcms)-1]))
+	return testDB, lcms
+}

cmd/soroban-rpc/internal/db/mocks.go

@@ -97,6 +97,12 @@ func (m *MockLedgerReader) GetLedger(_ context.Context, sequence uint32) (xdr.Le
 	return *lcm, true, nil
 }
 
+func (m *MockLedgerReader) BatchGetLedgers(_ context.Context, _ uint32,
+	_ uint,
+) ([]xdr.LedgerCloseMeta, error) {
+	return []xdr.LedgerCloseMeta{}, nil
+}
+
 func (m *MockLedgerReader) StreamAllLedgers(_ context.Context, _ StreamLedgerFn) error {
 	return nil
 }

cmd/soroban-rpc/internal/integrationtest/get_ledgers_test.go

@@ -0,0 +1,71 @@
+package integrationtest
+
+import (
+	"context"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/stellar/soroban-rpc/cmd/soroban-rpc/internal/integrationtest/infrastructure"
+	"github.com/stellar/soroban-rpc/cmd/soroban-rpc/internal/methods"
+)
+
+func TestGetLedgers(t *testing.T) {
+	test := infrastructure.NewTest(t, nil)
+	client := test.GetRPCLient()
+
+	// Get all ledgers
+	request := methods.GetLedgersRequest{
+		StartLedger: 8,
+		Pagination: &methods.LedgerPaginationOptions{
+			Limit: 3,
+		},
+	}
+	var result methods.GetLedgersResponse
+	err := client.CallResult(context.Background(), "getLedgers", request, &result)
+	require.NoError(t, err)
+	assert.Len(t, result.Ledgers, 3)
+	prevLedgers := result.Ledgers
+
+	// Get ledgers using previous result's cursor
+	request = methods.GetLedgersRequest{
+		Pagination: &methods.LedgerPaginationOptions{
+			Cursor: result.Cursor,
+			Limit:  2,
+		},
+	}
+	err = client.CallResult(context.Background(), "getLedgers", request, &result)
+	require.NoError(t, err)
+	assert.Len(t, result.Ledgers, 2)
+	assert.Equal(t, prevLedgers[len(prevLedgers)-1].Sequence+1, result.Ledgers[0].Sequence)
+
+	// Test with JSON format
+	request = methods.GetLedgersRequest{
+		StartLedger: 8,
+		Pagination: &methods.LedgerPaginationOptions{
+			Limit: 1,
+		},
+		Format: methods.FormatJSON,
+	}
+	err = client.CallResult(context.Background(), "getLedgers", request, &result)
+	require.NoError(t, err)
+	assert.NotEmpty(t, result.Ledgers[0].LedgerHeaderJSON)
+	assert.NotEmpty(t, result.Ledgers[0].LedgerCloseMetaJSON)
+
+	// Test invalid requests
+	invalidRequests := []methods.GetLedgersRequest{
+		{StartLedger: result.OldestLedger - 1},
+		{StartLedger: result.LatestLedger + 1},
+		{
+			Pagination: &methods.LedgerPaginationOptions{
+				Cursor: "invalid",
+			},
+		},
+	}
+
+	for _, req := range invalidRequests {
+		err = client.CallResult(context.Background(), "getLedgers", req, &result)
+		assert.Error(t, err)
+	}
+}

cmd/soroban-rpc/internal/jsonrpc.go

@@ -199,6 +199,14 @@ func NewJSONRPCHandler(cfg *config.Config, params HandlerParams) Handler {
 			queueLimit:           cfg.RequestBacklogGetLatestLedgerQueueLimit,
 			requestDurationLimit: cfg.MaxGetLatestLedgerExecutionDuration,
 		},
+		{
+			methodName: "getLedgers",
+			underlyingHandler: methods.NewGetLedgersHandler(params.LedgerReader,
+				cfg.MaxLedgersLimit, cfg.DefaultLedgersLimit),
+			longName:             "get_ledgers",
+			queueLimit:           cfg.RequestBacklogGetLedgersQueueLimit,
+			requestDurationLimit: cfg.MaxGetLedgersExecutionDuration,
+		},
 		{
 			methodName:           "getLedgerEntry",
 			underlyingHandler:    methods.NewGetLedgerEntryHandler(params.Logger, params.LedgerEntryReader),

cmd/soroban-rpc/internal/methods/get_latest_ledger_test.go

@@ -56,6 +56,12 @@ func (ledgerReader *ConstantLedgerReader) GetLedger(_ context.Context,
 	return createLedger(sequence, expectedLatestLedgerProtocolVersion, expectedLatestLedgerHashBytes), true, nil
 }
 
+func (ledgerReader *ConstantLedgerReader) BatchGetLedgers(_ context.Context, _ uint32,
+	_ uint,
+) ([]xdr.LedgerCloseMeta, error) {
+	return []xdr.LedgerCloseMeta{}, nil
+}
+
 func (ledgerReader *ConstantLedgerReader) StreamAllLedgers(_ context.Context, _ db.StreamLedgerFn) error {
 	return nil
 }