Skip to content

Clarify ankr_getLogs empty-result completeness, syncCheck and terminal pagination on Base #13

Open

Description

@Zundar

Could you clarify the source contract for an empty ankr_getLogs result on Base?

The current Query API reference describes standard eth_getLogs filter semantics plus indexed pagination. The Python SDK exposes GetLogsRequest.syncCheck, GetLogsReply.syncStatus, and ends automatic pagination when nextPageToken is absent. However, the current Query API OpenAPI operation does not document syncCheck or syncStatus.

For a fixed inclusive fromBlock..toBlock range independently known to be finalized, a fixed address/topics filter, syncCheck=true, and a successful response with:

  • logs: [];
  • no remaining nextPageToken;
  • syncStatus.status: synced;
  • integer syncStatus.blockNumber >= toBlock;
  • current timestamp and non-positive index lag;

is the intended API contract that there are no matching indexed events anywhere in that requested range, so a consumer may advance its cursor to toBlock + 1 without a second eth_getLogs call?

Specifically:

  1. Does syncCheck=true only add index-head metadata, or does it also detect incomplete indexing relevant to the requested range?
  2. Can historical holes, partial indexing, or an internal result limit produce HTTP/JSON-RPC success with an empty terminal result and status=synced, or are such incomplete results signalled by an error/status/continuation token?
  3. Does absent/empty nextPageToken always mean the filtered range was exhausted, including a zero-result first page? Can an intermediate page be empty while still carrying a continuation token?
  4. Are there Base-specific historical coverage limits or caveats, and is there an authoritative reference for these guarantees?

This asks about the ordinary trusted-indexer completeness contract, not a cryptographic proof or an absolute uptime guarantee. One bounded finalized empty-block comparison agrees with an independent indexed source and RPC, but that observation alone cannot establish the general API contract.

References:

  • https://www.ankr.com/docs/api-reference/aapi/query-api/#ankr_getlogs
  • https://www.ankr.com/docs/advanced-api/query-methods/#ankr_getlogs
  • def call_method_paginated(
    self,
    *,
    rpc: str,
    request: Any,
    reply: Any,
    iterable_name: str,
    iterable_type: Type[Any],
    limit: Optional[int] = None,
    ) -> Iterable[Any]:
    response = self.make_request(RPCEndpoint(rpc), request)
    reply = reply.from_dict(**response["result"])
    items: List[Any] = getattr(reply, iterable_name) or []
    if limit:
    if limit <= len(items):
    yield from items[:limit]
    return
    limit -= len(items)
    yield from items
    if reply.nextPageToken:
    request.pageToken = reply.nextPageToken
    yield from self.call_method_paginated(
    rpc=RPCEndpoint(rpc),
    request=request,
    reply=reply,
    iterable_name=iterable_name,
    iterable_type=iterable_type,
    limit=limit,
    )
  • class GetLogsRequest:
    def __init__(
    self,
    blockchain: Blockchain | List[Blockchain],
    fromBlock: float
    | Literal[Literal["latest"]]
    | Literal[Literal["earliest"]] = None,
    toBlock: float
    | Literal[Literal["latest"]]
    | Literal[Literal["earliest"]] = None,
    fromTimestamp: float
    | Literal[Literal["latest"]]
    | Literal[Literal["earliest"]] = None,
    toTimestamp: float
    | Literal[Literal["latest"]]
    | Literal[Literal["earliest"]] = None,
    address: List[str] = None,
    topics: List[str | List[str]] = None,
    pageToken: str = None,
    pageSize: float = None,
    descOrder: bool = None,
    decodeLogs: bool = None,
    syncCheck: bool = None,
    ):
    self.blockchain = blockchain
    self.fromBlock = fromBlock
    self.toBlock = toBlock
    self.fromTimestamp = fromTimestamp
    self.toTimestamp = toTimestamp
    self.address = address
    self.topics = topics
    self.pageToken = pageToken
    self.pageSize = pageSize
    self.descOrder = descOrder
    self.decodeLogs = decodeLogs
    self.syncCheck = syncCheck
    def to_dict(self):
    if isinstance(self.blockchain, str):
    blockchain_value = self.blockchain
    elif isinstance(self.blockchain, list):
    blockchain_value = [
    block.value if isinstance(block, Blockchain) else block
    for block in self.blockchain
    ]
    elif self.blockchain is not None:
    blockchain_value = self.blockchain.value
    else:
    blockchain_value = None
    return {
    "blockchain": blockchain_value,
    "fromBlock": self.fromBlock,
    "toBlock": self.toBlock,
    "fromTimestamp": self.fromTimestamp,
    "toTimestamp": self.toTimestamp,
    "address": self.address,
    "topics": self.topics,
    "pageToken": self.pageToken,
    "pageSize": self.pageSize,
    "descOrder": self.descOrder,
    "decodeLogs": self.decodeLogs,
    "syncCheck": self.syncCheck,
    }

If this belongs with the AAPI backend/support team, please route it to them or point to the appropriate public clarification. Thanks.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions