fix: make start_ledger optional and mutually exclusive with cursor

.gitignore

@@ -105,3 +105,4 @@ venv.bak/
 
 # IDE
 .idea/
+.vscode/

CHANGELOG.md

@@ -5,6 +5,7 @@ Release History
 
 #### Update
 - fix: fix the issue where sending assets using `Transaction.append_payment_to_contract_op` fails when the sender's account is the same as the asset issuer's account. ([#1029](https://github.com/StellarCN/py-stellar-base/pull/1029))
+- fix: allow `SorobanServer.get_events()`, `.get_transactions()`, and `.get_ledgers()` to be paginated by making the `start_ledger` argument optional. ([#1032](https://github.com/StellarCN/py-stellar-base/pull/1032))
 
 ### Version 12.2.0
 

pyproject.toml

@@ -58,6 +58,7 @@ toml = "^0.10.2"
 pydantic = "^2.5.2"
 xdrlib3 = "^0.1.1"
 requests-sse = ">=0.3,<0.6"
+typing-extensions = "^4.13.2"
 
 [tool.poetry.extras]
 aiohttp = ["aiohttp", "aiohttp-sse-client"]

stellar_sdk/soroban_rpc.py

@@ -2,7 +2,8 @@
 from enum import Enum
 from typing import Any, Dict, Generic, List, Optional, Sequence, TypeVar, Union
 
-from pydantic import BaseModel, ConfigDict, Field
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+from typing_extensions import Self
 
 T = TypeVar("T")
 
@@ -75,16 +76,27 @@ class PaginationOptions(BaseModel):
     limit: Optional[int] = None
 
 
-class GetEventsRequest(BaseModel):
+class PaginationMixin:
+    pagination: Optional[PaginationOptions] = None
+
+    @model_validator(mode="after")
+    def verify_ledger_or_cursor(self) -> Self:
+        if self.pagination and (
+            getattr(self, "start_ledger") and self.pagination.cursor
+        ):
+            raise ValueError("start_ledger and cursor cannot both be set")
+        return self
+
+
+class GetEventsRequest(PaginationMixin, BaseModel):
     """Response for JSON-RPC method getEvents.
 
     See `getEvents documentation <https://developers.stellar.org/docs/data/rpc/api-reference/methods/getEvents>`__ for
     more information.
     """
 
-    start_ledger: int = Field(alias="startLedger")
+    start_ledger: Optional[int] = Field(alias="startLedger", default=None)
     filters: Optional[Sequence[EventFilter]] = None
-    pagination: Optional[PaginationOptions] = None
 
 
 class GetEventsResponse(BaseModel):
@@ -376,14 +388,13 @@ class GetFeeStatsResponse(BaseModel):
 
 
 # get_transactions
-class GetTransactionsRequest(BaseModel):
+class GetTransactionsRequest(PaginationMixin, BaseModel):
     """Request for JSON-RPC method getTransactions.
 
     See `getTransactions documentation <https://developers.stellar.org/docs/data/rpc/api-reference/methods/getTransactions>`__ for
     more information."""
 
-    start_ledger: int = Field(alias="startLedger")
-    pagination: Optional[PaginationOptions] = None
+    start_ledger: Optional[int] = Field(alias="startLedger", default=None)
 
 
 class Transaction(BaseModel):
@@ -430,14 +441,13 @@ class GetVersionInfoResponse(BaseModel):
 
 
 # get_ledgers
-class GetLedgersRequest(BaseModel):
+class GetLedgersRequest(PaginationMixin, BaseModel):
     """Request for JSON-RPC method getLedgers.
 
     See `getLedgers documentation <https://developers.stellar.org/docs/data/rpc/api-reference/methods/getLedgers>`__ for
     more information."""
 
-    start_ledger: int = Field(alias="startLedger")
-    pagination: Optional[PaginationOptions] = None
+    start_ledger: Optional[int] = Field(alias="startLedger", default=None)
 
 
 class LedgerInfo(BaseModel):

stellar_sdk/soroban_server.py

@@ -67,7 +67,7 @@ def get_health(self) -> GetHealthResponse:
 
     def get_events(
         self,
-        start_ledger: int,
+        start_ledger: int = None,
         filters: Sequence[EventFilter] = None,
         cursor: str = None,
         limit: int = None,
@@ -85,7 +85,7 @@ def get_events(
         """
         pagination = PaginationOptions(cursor=cursor, limit=limit)
         data = GetEventsRequest(
-            startLedger=str(start_ledger),
+            startLedger=start_ledger,
             filters=filters,
             pagination=pagination,
         )
@@ -243,7 +243,7 @@ def get_fee_stats(self) -> GetFeeStatsResponse:
 
     def get_transactions(
         self,
-        start_ledger: int,
+        start_ledger: int = None,
         cursor: str = None,
         limit: int = None,
     ) -> GetTransactionsResponse:
@@ -260,7 +260,7 @@ def get_transactions(
         """
         pagination = PaginationOptions(cursor=cursor, limit=limit)
         data = GetTransactionsRequest(
-            startLedger=str(start_ledger),
+            startLedger=start_ledger,
             pagination=pagination,
         )
         request: Request = Request[GetTransactionsRequest](
@@ -269,7 +269,10 @@ def get_transactions(
         return self._post(request, GetTransactionsResponse)
 
     def get_ledgers(
-        self, start_ledger: int, cursor: str = None, limit: int = None
+        self,
+        start_ledger: int = None,
+        cursor: str = None,
+        limit: int = None,
     ) -> GetLedgersResponse:
         """Fetch a detailed list of ledgers starting from the user specified starting point that you can paginate
         as long as the pages fall within the history retention of their corresponding RPC provider.
@@ -284,7 +287,7 @@ def get_ledgers(
         """
         pagination = PaginationOptions(cursor=cursor, limit=limit)
         data = GetLedgersRequest(
-            startLedger=str(start_ledger),
+            startLedger=start_ledger,
             pagination=pagination,
         )
         request: Request = Request[GetLedgersRequest](

stellar_sdk/soroban_server_async.py

@@ -67,7 +67,7 @@ async def get_health(self) -> GetHealthResponse:
 
     async def get_events(
         self,
-        start_ledger: int,
+        start_ledger: int = None,
         filters: Sequence[EventFilter] = None,
         cursor: str = None,
         limit: int = None,
@@ -85,7 +85,7 @@ async def get_events(
         """
         pagination = PaginationOptions(cursor=cursor, limit=limit)
         data = GetEventsRequest(
-            startLedger=str(start_ledger),
+            startLedger=start_ledger,
             filters=filters,
             pagination=pagination,
         )
@@ -242,7 +242,7 @@ async def get_fee_stats(self) -> GetFeeStatsResponse:
 
     async def get_transactions(
         self,
-        start_ledger: int,
+        start_ledger: int = None,
         cursor: str = None,
         limit: int = None,
     ) -> GetTransactionsResponse:
@@ -259,7 +259,7 @@ async def get_transactions(
         """
         pagination = PaginationOptions(cursor=cursor, limit=limit)
         data = GetTransactionsRequest(
-            startLedger=str(start_ledger),
+            startLedger=start_ledger,
             pagination=pagination,
         )
         request: Request = Request[GetTransactionsRequest](
@@ -268,7 +268,10 @@ async def get_transactions(
         return await self._post(request, GetTransactionsResponse)
 
     async def get_ledgers(
-        self, start_ledger: int, cursor: str = None, limit: int = None
+        self,
+        start_ledger: int = None,
+        cursor: str = None,
+        limit: int = None,
     ) -> GetLedgersResponse:
         """Fetch a detailed list of ledgers starting from the user specified starting point that you can paginate
         as long as the pages fall within the history retention of their corresponding RPC provider.
@@ -283,7 +286,7 @@ async def get_ledgers(
         """
         pagination = PaginationOptions(cursor=cursor, limit=limit)
         data = GetLedgersRequest(
-            startLedger=str(start_ledger),
+            startLedger=start_ledger,
             pagination=pagination,
         )
         request: Request = Request[GetLedgersRequest](