Proposal for getEvents v2 endpoint

[tamirms]

Overview

This proposal specifies an improved getEvents Stellar RPC API for querying events on the Stellar blockchain. It is designed to work identically over a 7-day retention window and over full history.

Design Goals

The API addresses specific problems reported in GitHub issues stellar/stellar-rpc#426 and stellar/stellar-rpc#575:

Problem (#426, #575)	Solution
Filters match on topic count, not content	Positional semantics: topic0..topic3 fields match topic positions
Nested filter arrays are confusing	One flat filter object per branch: OR across branches, AND within
Cursor encoding exposes implementation details	Opaque cursor string hides internal structure
endLedger ignored during pagination	Cursor encodes original bounds, honored throughout
No recovery info when cursor expires	Errors carry machine-readable context (oldestLedger, latestLedger)
Empty pages confuse clients with sparse data	scanStatus + scannedLedger show scan progress
No way to get a transaction's events in event form	events.parsed on getTransaction (companion change, below)
No descending order for "latest events"	order: "desc" iterates newest-first
Cross-position OR requires multiple queries	The filters list unions flat filters in one request

Request

The API accepts two mutually exclusive request modes:

Mode	Discriminator	Purpose
RangeQuery	Default (no cursor)	Query events within a ledger range
CursorQuery	cursor present	Continue pagination from a prior response

Type Definitions

// An ScVal is encoded per the request's xdrInputFormat:
//   "base64" (default): base64-encoded XDR string
//   "json": JSON representation ({ symbol: "..." }, { address: "..." }, etc.)
type ScVal = string | object

// A filter matches an event when every field it specifies matches.
// Omitted topic positions match any value. At least one field is required.
type Filter = {
  contractId?: string,   // events emitted by this contract
  type?: "contract" | "system",  // events of this type
  topic0?: ScVal,        // exact match on topic[0]
  topic1?: ScVal,        // exact match on topic[1]
  topic2?: ScVal,        // exact match on topic[2]
  topic3?: ScVal         // exact match on topic[3]
}

type RangeQuery = {
  minLedger?: number,           // Starting ledger (inclusive); required for ascending
  maxLedger?: number,           // Ending ledger (inclusive)
  order?: "asc" | "desc",
  filters?: Filter[],     // OR across filters
  limit?: number,
  xdrFormat?: "base64" | "json",      // response encoding
  xdrInputFormat?: "base64" | "json"  // request ScVal encoding
}

type CursorQuery = {
  cursor: string,
  limit?: number,
  xdrFormat?: "base64" | "json"
}

type GetEventsRequest = RangeQuery | CursorQuery

Field Definitions

Field	Type	Description
minLedger	number	Starting ledger (inclusive)
maxLedger	number	Ending ledger (inclusive)
order	"asc" | "desc"	Iteration direction. Default: "asc" (oldest first)
filters	Filter[]	Event filters (OR across the list). Max 256
limit	number	Max events per response. Default: 100, max: 1,000
cursor	string	Opaque token to continue from a previous response
xdrFormat	"base64" | "json"	Encoding of XDR values in the response. Default: "base64"
xdrInputFormat	"base64" | "json"	Encoding of ScVal values in the request. Default: "base64"

An event matches the request when it matches at least one filter, and matches a filter when every specified field matches. Omitted fields are unconstrained.

Ledger bounds are inclusive on both ends. (v1's endLedger was exclusive: a v1 request ported unchanged now includes one more ledger than before.) Bounds may extend beyond what the node holds; the few ranges rejected outright are listed under Errors.

Empty values are invalid: omit filters entirely to match all events, and every filter must specify at least one field. A filter's type matches the event's type label; note that fee and refund events carry type contract. Unknown request fields are rejected: an omitted field is a wildcard here, so silently ignoring a misspelled field would silently widen the results.

Filters

Each filter is a flat object with positional semantics: topic0 matches topic[0], topic1 matches topic[1], and so on.

• Fields within a filter are AND
• Filters within the filters list are OR
• Omitted topic positions match any value
• Events with more topics than the filter constrains still match

Topic values are encoded per xdrInputFormat. Examples in this document use the JSON form and therefore set xdrInputFormat: "json":

// xdrInputFormat: "base64" (default)
"AAAADwAAAAh0cmFuc2Zlcg=="

// xdrInputFormat: "json"
{ symbol: "transfer" }

The examples below follow the SEP-41 token convention, where a transfer event's topics are:

topic[0]: symbol "transfer" (event type)
topic[1]: from address
topic[2]: to address
topic[3]: amount or asset info

Query patterns:

Use Case	Filters
All transfers	[{ topic0: transfer }]
Transfers I sent	[{ topic0: transfer, topic1: me }]
Transfers I received	[{ topic0: transfer, topic2: me }]
Transfers involving me	[{ topic0: transfer, topic1: me }, { topic0: transfer, topic2: me }]
Several event types	[{ topic0: transfer }, { topic0: approve }]
Different events on different contracts	[{ contractId: A, topic0: transfer }, { contractId: B, topic0: swap }]

Limits

Constraint	Limit	Rationale
Distinct index terms per request	15 (default; providers may configure)	Each term costs one index lookup; bounds I/O and memory
filters	Max 256 (default)	Parser sanity; the term budget is the real limit
Topic positions	Max 4 (topic0..topic3)	Matches Stellar event structure
limit	Max 1,000	Bounds response payload size

The term budget counts how many distinct values a query asks the index about. Each distinct contract id is one term, each distinct type is one term, and each distinct value at a given topic position is one term. The same value at the same position is counted once no matter how many filters repeat it, while the same value at two different positions counts twice. For example, [{ topic0: transfer, topic1: me }, { topic0: transfer, topic2: me }] uses 3 terms: transfer at topic0, me at topic1, and me at topic2. A five-branch token filter (transfer from/to, mint to, burn from, clawback from) uses 7: one contract id, four topic0 symbols, and the account at topic1 and at topic2. Queries over the budget return invalid_params with termsUsed and termBudget in the error data; split them into parallel queries and merge by event id (to checkpoint a split query, persist its least-advanced sub-query's scannedLedger).

RangeQuery Rules

Order	Required	Optional (defaults)
asc (default)	minLedger	maxLedger (none: follows the chain tip)
desc	nothing	maxLedger (the node's latest ledger at query start), minLedger (2, the genesis ledger)

Rationale:

• Ascending requires minLedger: ensures portable queries across RPCs with different retention (a full-history node and a 7-day node would otherwise silently answer differently)
• Descending requires nothing: "latest N events" gives consistent results regardless of retention

Bounds:

• Bounds past the chain tip are legal and never clamped: the scan waits for the chain to produce those ledgers. Ascending serves what the node already has, then each new ledger as it closes; descending starts once the chain reaches its maxLedger
• An ascending query with no maxLedger is the API's one open edge: it follows the chain tip forever
• A descending query never picks up new ledgers: its maxLedger, given or defaulted, is fixed when the query starts
• A descending minLedger older than the node's oldestLedger is legal, with or without maxLedger: the node serves the ledgers it holds
• One combination is rejected: descending with maxLedger omitted and minLedger above the tip. Such a scan would start at the tip and descend, but minLedger lies above its starting point, so nothing could ever match

Examples:

// Ascending, bounded: ledgers 1000-5000
{ minLedger: 1000, maxLedger: 5000 }

// Ascending, unbounded: ledger 1000 to the chain tip, then follow it (live tracking)
{ minLedger: 1000 }

// Descending, latest 50 events
{ order: "desc", limit: 50 }

// Descending, bounded range newest-first
{ minLedger: 1000, maxLedger: 5000, order: "desc" }

// Error: ascending requires minLedger
{ order: "asc" }  // invalid_params: "minLedger is required for ascending order"

Response

type GetEventsResponse = {
  events: Event[],
  cursor: string,          // always present
  scanStatus: "HAS_MORE" | "WAITING_FOR_LEDGERS" | "OLDEST_REACHED" | "COMPLETE",
  scannedLedger: number,
  oldestLedger: number,    // earliest ledger this node holds
  latestLedger: number     // most recent ledger this node holds
}

Field	Description
events	Matching events for this page
cursor	Token to continue pagination, present on every response except "COMPLETE", where it is omitted: an absent cursor means the query is finished. It carries the whole query (bounds, order, filters) and does not expire
scanStatus	"HAS_MORE": more to scan on this node right now; request the next page (a page can be empty when the internal scan limit was hit first; see Sparse data). "WAITING_FOR_LEDGERS": the query needs ledgers this node does not have yet; retry the same cursor later. "OLDEST_REACHED": the query wants history older than this node holds; you have everything this node can give, but the query is not complete. "COMPLETE": the query is finished and will never return more; the response carries no cursor
scannedLedger	Checkpoint: every matching event between the query's starting bound and this ledger has been delivered. If a page ends in the middle of a ledger, scannedLedger names the last fully delivered ledger and the cursor resumes inside the partial one. If no ledger of the range is complete yet, it is the ledger just before the range: minLedger - 1 ascending, maxLedger + 1 descending
oldestLedger	Earliest ledger this node holds (same field getTransactions returns)
latestLedger	Most recent ledger this node holds

A scan that finishes its range exactly at the newest or oldest ledger the node holds reports COMPLETE, not WAITING_FOR_LEDGERS or OLDEST_REACHED.

The universal client loop:

while (true) {
  process(response.events);
  if (response.scanStatus === "COMPLETE") break;              // never more
  if (response.scanStatus === "OLDEST_REACHED") break;        // all this node has
  if (response.scanStatus === "WAITING_FOR_LEDGERS") await sleep(5000);
  response = await getEvents({ cursor: response.cursor });
}

Sparse data

Every request runs under an internal scan limit. The server scans a bounded amount of ledgers per request so that response time stays predictable no matter how rare the matching events are; the bound is set by the node operator. limit caps how many events a page may carry, not how much the server reads to find them.

A query for rare events can therefore return an empty page: the scan hit its limit before finding a match. scannedLedger still advances, and the next request continues from there. How far one request advances varies widely: a selective query can cheaply rule out long stretches of ledgers and jump far ahead, while a broad query moves a few hundred ledgers at a time:

{
  events: [],
  scanStatus: "HAS_MORE",
  cursor: "abc",
  scannedLedger: 400000,
  oldestLedger: 2,
  latestLedger: 2000000
}

This means: no matches yet, and everything through ledger 400000 has been scanned. Keep following the cursor.

Event Schema

The event object is unchanged from the current getEvents response, except that v1's deprecated inSuccessfulContractCall field is dropped:

type Event = {
  id: string,
  type: "contract" | "system",
  ledger: number,
  ledgerClosedAt: string,   // ISO 8601
  contractId: string,
  txHash: string,
  transactionIndex: number,
  operationIndex: number,
  topic?: string[],         // when xdrFormat: "base64"
  topicJson?: any[],        // when xdrFormat: "json"
  value?: string,           // when xdrFormat: "base64"
  valueJson?: any           // when xdrFormat: "json"
}

Exactly one of topic/topicJson and one of value/valueJson is present, per xdrFormat. Clients must ignore unknown response fields and tolerate unknown type values, so fields and event kinds can be added later without breaking anyone.

Ordering and ids (behavior the current API has but never documented):

• Events arrive in the order they were executed on chain: earlier ledgers first; within a ledger, fee charges, then each transaction's operation events, then refunds at the end
• order: "desc" returns the exact reverse
• Sorting ids as strings reproduces that order; ids are unique and identical on every node
• Ids are stable: once a ledger closes, the ids of its events never change, across software versions and API versions
• Paginating with the cursor never skips an event and never returns one twice

Errors

Errors are standard JSON-RPC 2.0 error objects. error.data carries a machine-readable reason plus the additional fields listed per reason below, so clients can react without parsing message text. Request validation runs before any scanning, and no error consumes or advances a cursor:

reason	Fields in error.data	When	Retry?
invalid_params	varies	The request is malformed; see the conditions below	No
ledger_out_of_range	missingLedger (the ledger the query needs that this node does not have), oldestLedger, latestLedger	Serving would skip data, or the range resolved empty: an ascending minLedger below oldestLedger (pruned or not yet backfilled; missingLedger is minLedger), an ascending continuation whose next ledger fell below oldestLedger (pruning overtook the cursor; missingLedger is that next ledger), or a descending minLedger above latestLedger with maxLedger omitted (the defaulted maxLedger is the tip; missingLedger is minLedger). Descending scans never get this error: they stop with OLDEST_REACHED instead	missingLedger below oldestLedger: retrying helps only on a node that holds, or backfills, older history. missingLedger above latestLedger: retrying succeeds once this node holds ledger minLedger
cursor_malformed	oldestLedger, latestLedger	Cursor cannot be decoded (corrupted, or from an incompatible implementation or version)	No

Conditions producing invalid_params

Condition	Message
cursor with other query params	"cursor is mutually exclusive with minLedger, maxLedger, order, filters, xdrInputFormat"
min > max	"minLedger must be <= maxLedger"
order: "asc" without minLedger	"minLedger is required for ascending order"
limit < 1 or > 1000	"limit must be between 1 and 1000"
filters empty or over 256	"filters must contain 1 to 256 filters"
Filter with no fields	"filter must specify type, contractId, or at least one topic position"
Bad type in a filter	"type must be "contract" or "system""
Unknown field	"unknown field: contractID"
Over the term budget	"query uses 18 distinct index terms, exceeding the budget of 15" (termsUsed, termBudget in data)
Bad xdrFormat / xdrInputFormat	"xdrFormat must be "base64" or "json""
Undecodable ScVal	"filters[0].topic1 is not valid base64-encoded XDR"

Companion Change: getTransaction

getEvents v2 has no transaction mode. Instead, getTransaction and getTransactions add one field to the events object they already return:

// getTransaction response, events portion. Only `parsed` is new.
events: {
  transactionEventsXdr?: string[],   // unchanged: raw fee/refund events
  contractEventsXdr?: string[][],    // unchanged: raw per-operation contract events
  diagnosticEventsXdr?: string[],    // unchanged: raw diagnostic events
  // (matching *Json variants unchanged as well)

  parsed: Event[]                    // NEW: see below
}

The existing fields carry raw, unparsed XDR blobs grouped by kind, with no event ids and no single ordering. parsed carries the same fee/refund and contract events decoded into the Event objects defined above, in execution order, with the same ids they have in the getEvents stream, so a client needs no XDR decoding and can correlate directly with getEvents. Nothing existing moves or changes shape, so the addition breaks no client, and a transaction detail page becomes one call: status, result, and usable events together. parsed excludes diagnostic events, which have no position in the event stream and therefore no ids; diagnostics remain available through the existing raw field and through simulateTransaction.

Appendix: Code Examples

Latest N events:

const response = await getEvents({ order: "desc", limit: 50 });
display(response.events);  // newest first
// A page may hold fewer than 50 if the scan budget was hit;
// loop while scanStatus is "HAS_MORE" to fill the window.

Historical range with pagination:

const transfer = { symbol: "transfer" };
const myAddr = { address: "GABC...XYZ" };

let response = await getEvents({
  minLedger: 1000,
  maxLedger: 5000,
  filters: [{ topic0: transfer, topic1: myAddr }],  // Transfers I sent
  xdrInputFormat: "json"
});

while (true) {
  process(response.events);
  if (response.scanStatus === "COMPLETE") break;
  if (response.scanStatus === "WAITING_FOR_LEDGERS") await sleep(5000); // maxLedger was past the tip
  response = await getEvents({ cursor: response.cursor });
}

Live tracking:

const transfer = { symbol: "transfer" };
const myAddr = { address: "GABC...XYZ" };

let response = await getEvents({
  minLedger: 1000,
  filters: [{ topic0: transfer, topic2: myAddr }],  // Transfers I received
  xdrInputFormat: "json"
});

while (true) {
  process(response.events);
  if (response.scanStatus === "WAITING_FOR_LEDGERS") await sleep(5000);
  response = await getEvents({ cursor: response.cursor });
}

Resume from database:

const saved = await db.load();

let response = await getEvents({ cursor: saved.cursor });

while (true) {
  for (const event of response.events) {
    await process(event);
  }
  if (response.scanStatus === "COMPLETE") break;  // final page carries no cursor
  // Save the cursor atomically with the effects of process(), or make
  // process() idempotent: a crash between the two replays this page.
  await db.save({ cursor: response.cursor });
  if (response.scanStatus === "OLDEST_REACHED") break;  // all this node has
  if (response.scanStatus === "WAITING_FOR_LEDGERS") await sleep(5000);
  response = await getEvents({ cursor: response.cursor });
}

Wallet activity (sent + received), one request:

const transfer = { symbol: "transfer" };
const myAddr = { address: "GABC...XYZ" };

const response = await getEvents({
  minLedger: 1000,
  filters: [
    { topic0: transfer, topic1: myAddr },  // sent
    { topic0: transfer, topic2: myAddr }   // received
  ],
  xdrInputFormat: "json"
});
// First page only: loop as in the examples above to sync full history.

Transaction detail page (companion change):

const tx = await getTransaction({ hash: "7758a3..." });
render(tx.status, tx.resultXdr);
for (const event of tx.events.parsed) {
  renderEvent(event);   // same Event shape and ids as the getEvents stream
}

[tomerweller]

How do you express a topic filter that is "all TRANSFER events to 0xme"?

[mootz12]

I do share concerns that people will use the existing topicFilter as if position matters, especially since the input is taken as an array. If we opt for not enforcing position, this needs to be repeated x10 in documentation.

This being said, I think what is being proposed is functional for just about any use case I can think of, we just need to be as clear as possible how it works so the proper validation is included on the client side.

--

Curious if we explored the eth_getLogs API for topic filters?

e.g. assume event is topics = ["transfer", sender, receiver]

topics = ["transfer", *, ["alice", "bob"]]

would match all transfer events where alice or bob are the receiver and anyone was the sender. Not sure if this simplifies the current query at all given it contains "or" logic (given it can't be nested further than once), but it would reduce the topic filters to only 1.

[tamirms]

@mootz12 the ethereum API is very similar to the current stellar getEvents API and it also features positional topic filters. But, it is not possible to do a request which finds all transfers where 0xme is the sender or recipient. You would have to do two requests and combine the results to get a view of all incoming and outgoing transfers for a particular address:

// 1. Fetch Sent
const sent = await getEvents({ topic1: "Me" });
// 2. Fetch Received
const received = await getEvents({ topic2: "Me" });

// 3. EXTRA CODE: Merge and Sort
const allEvents = [...sent, ...received].sort((a, b) => b.block - a.block);

// 4. Render
allEvents.forEach(e => {
  if (e.topics[1] == "Me") render("Sent", e);
  else render("Received", e);
});

[tomerweller]

Thanks for the detailed response @tamirms. I think your reasoning makes sense in terms meeting general indexing requirements and why this is good for performance.

The thing that gives me pause is the non-obviousness of it. I recognize that this is a subjective quality but the fact that @mootz12 insists that we need to document this behavior 10x times is a red flag - an API should make sense.

If you think filtering topic positions are necessary then I think we should remove the possibility of nesting in the topic filtering and we make the topic filter a flat array which does only intersection.

I agree that the nesting in the current getEvents is excessive (and also confusing) but I think it's worth supporting a small numbers of topic filters and union between them. I suggested something like this in my comment here

But if you think this is prohibitive from a performance perspective then I think a single topic filter per request (similar to your eth example above) is still easier to reason about than the current proposal.

[tamirms]

Updated the proposal to use positional topic filters

[teddav]

so were the any/all filters dropped in favor of a single positional topics filter?
could we allow some (limited) composition on top of positional filters?
for the "all transfer events involving 0xme", we could have:

{
  "any": [
    [{ "symbol": "transfer" }, { "address": "0xme" }],
    [{ "symbol": "transfer" }, null, { "address": "0xme" }]
  ]
}

That would preserve positional semantics, but avoid forcing clients to issue two requests for a very common view

[kalepail]

I had AI do a deep dive into all of the GitHub issues and even our own Discord to find all of the complaints and issues that we've heard over the last few years and matched it against this proposal. The results are here in this Gist:

https://gist.github.com/kalepail/f0b14c806f01b69817d128504d0ec523

The TLDR is that it seems like what's being proposed is a good solution. And personally, as I reviewed it, I'm pretty excited about it. Great work.

[urvisavla]

Quick clarification: for order=desc, is the ordering applied to the full event position tuple (ledger, tx_index, op_index, event_index) (i.e. fully reversed) or the intent is to only reverse ledger order while keeping tx/event order ascending within each ledger? Asking because this may impact cursor and index implementation.

[tamirms]

I think the most intuitive behavior would be for order=desc to mean reverse order applied on the full event position tuple. But, I'm open to discussing this if you think it would be detrimental to backend performance

[leighmcculloch]

Form	Example	Meaning
Number	1000	Ledger 1000, inclusive
String	"evt_abc"	Event ID, inclusive
Object	{ ledger: 1000, exclusive: true }	Ledger 1000, exclusive
Object	{ eventId: "evt_abc", exclusive: true }	Event ID, exclusive

Field	Type	Description
min	Boundary	Lower bound of range (earlier in time)
max	Boundary	Upper bound of range (later in time)
...	...	...
cursor	string	Opaque token to continue from previous response

Are there two ways to do cursor-like pagination? I see the boundary type supports an event ID, and separately there's a cursor. What are the planned use cases for the former?

[leighmcculloch]

@Shaptic then is your thinking that in the use case @tamirms showed above the integrator would store the opaque cursor in the db so that they'd resume from that point using the opaque cursor?

[tamirms]

@leighmcculloch I'm confused could you elaborate on why the problem of resuming from db is created by the existence of an opaque cursor? If we got rid of the opaque cursor what exactly would be different and better?

[leighmcculloch]

@tamirms I think either one of a transparent event id cursor, or a opaque cursor, are good for resuming. I'm just raising the concern that there are two cursor-like pagination mechanisms in the api.

I wasn't clear in my response in #1872 (reply in thread) but I 👍🏻 @Shaptic's comment to keep supporting a cursor while leaving out the event id range lookup. That seems great.

The resume example shared at #1872 (reply in thread) should work fine if the id used to resume is just the cursor instead of the event id. Is that accurate?

[tamirms]

yeah, that works. I think it make sense to proceed with @Shaptic's suggestion

[tamirms]

Updated the proposal to get rid of event id bounds

[leighmcculloch]

Form	Example	Meaning
Number	1000	Ledger 1000, inclusive
String	"evt_abc"	Event ID, inclusive
Object	{ ledger: 1000, exclusive: true }	Ledger 1000, exclusive
Object	{ eventId: "evt_abc", exclusive: true }	Event ID, exclusive

It looks like the proposal introduces a new lever to control whether queries should be inclusive or exclusive of inputs. I don't think I've ever seen this in an API before, it seems novel. What problem is it solving for? It's not clear to me which problem at the start of the proposal it aligns with.

When the min/max is a ledger I think inclusive makes sense as a default. And if someone wants exclusive it is very easy to plus or minus one.

The event ID, I'm not clear on what the use case is for that and started a separate thread about that: #1872 (comment). If the goal is pagination, those inputs should probably be always exclusive. Unless the goal is to get a single event, in which case it might be clearer to offer a getEvent API to get a single event.

[tamirms]

I'm ok with removing the exclusive field and making the behavior inclusive for ledgers and exclusive for event ids. the rationale for the exclusive field was to make the behavior explicit but I think simplifying the behavior based on ledger vs event ids is a fine approach

[mootz12]

+1 for removing the exclusive field. The following seems adequate:

ledger (inclusive)
eventId (exclusive)

It would also be easier to add this than remove it in the future if we are wrong.

[leighmcculloch]

I think it will be easy for someone to assume that the inclusive / exclusive property applies to the field min, rather than the value ledger or eventId being passed in, and therefore to introduce off-by-one errors into their program because of it. So it might be better to more fully separate the query input variables for the two.

Note that this issue disappears if we do what @Shaptic suggested and remove the eventId as a min/max input. (#1872 (reply in thread))

[tamirms]

Updated the proposal to get rid of event id bounds. Ledger bounds are always inclusive

[leighmcculloch]

I realise just after posting this that doing this ☝🏻 would require removing the unbounded max on the ledger range, which makes the API harder to use and is a pain point today worth solving for I think. And the small complexity of scannedLedger seems like a good tradeoff to be able to offer unbounded, especially given that a developer would not need to do anything with the field and just keep iterating if hasMore is true.

[teddav]

The events system needs to be more robust. I agree with several points raised so far, but the most critical issue is the 7-day retention window. It needs to be removed.

Being able to reliably fetch historical events is mandatory for any real application. A 7-day limit is a major blocker for app developers. Apps are not temporary experiments. They are meant to live for a long time (forever?), and require durable event access for indexing, recovery, analytics, and user state.

In our case, we are building a privacy pool. By design, we do not want to rely on a backend, because users should not have to trust any backend service. The RPC must be the source of truth. Short-lived events or reliance on third-party infrastructure directly break this model.

I understand and support the goal of decentralization and not forcing the Stellar Foundation to operate heavy indexers indefinitely. However, the ecosystem is (unfortunately) still small !
At this stage, builders need the easiest and most reliable option to get started, which should be the Foundation-provided infrastructure. Once an app grows, switching to another provider is reasonable.

I asked on Discord and was pointed to the Providers page.
After reading it, it’s still unclear:

• which provider is reliable?
• do providers retain events for more than 7 days
• pricing?
• will I need an API key (and therefore a backend)?

Needing to deploy a backend just to fetch historical events significantly slows development and increases complexity. For early-stage builders, this friction is often enough to push them to another chain.

[tupui]

I totally agree on the need for decentralization. We know that a decentralized network is not much if all the necessary infrastructure that must run around is centralized. That list has at least 2 projects from the ecosystem: Lightsail and Lobstr. Though things are very hard for them.

[tamirms]

@teddav @tupui thanks for the feedback, we are actually designing this new API with full history retention in mind! It would be really helpful for us if you could weigh in on the importance of topic filtering. Is the this proposed API sufficient for your needs or do you need more sophisticated topic filtering (if so, please describe how you use topic filtering) ?

[tupui]

Wooo this is amazing to read! I can ping some folks who would have more sensible input than me on that.

[tomerweller]

type TopicClause = { all: string[] }

IIRC topics are ScVal. What are the strings in the topic filter clause? Are these b64 encoded ScVals (similar to the current api)?

[tamirms]

yeah, the strings should be b64 encoded ScVals. I don't use b64 values in the examples because it's hard to decipher. the examples are more like pseudocode

[tomerweller]

Can we allow using standard ScVal json conversions using something like stellar-xdr-json? This can make the API friendlier and less opaque. This also matches the ability to present json in the response. cc @janewang @leighmcculloch

in the past I suggested something like this here

"filters": [
  {
    "type": "contract",
    "contractId": "CAS3J7GYLGXMF6TDJBBYYSE3HQ6BBSMLNUQ34T6TZMYMW2EVH34XOWMA",
    "topic0": {"type": "symbol", "val": "transfer"},
    "topic1": {"type": "address", "val": "GAIH3ULLFQ4DGSECF2AR555KZ4KNDGEKN4AFI4SU2M7B43MGK3QJZNSR"}
  },
  {
    "type": "contract",
    "contractId": "CAS3J7GYLGXMF6TDJBBYYSE3HQ6BBSMLNUQ34T6TZMYMW2EVH34XOWMA",
    "topic0": {"type": "symbol", "val": "transfer"},
    "topic2": {"type": "address", "val": "GAIH3ULLFQ4DGSECF2AR555KZ4KNDGEKN4AFI4SU2M7B43MGK3QJZNSR"}
  }
]

[leighmcculloch]

The values in the topics should look like this for xdr-json:

{"symbol":"transfer"}
{"u32":4008401800}
{"u64":"3964442654822814847"}
{"address":"GAIH3ULLFQ4DGSECF2AR555KZ4KNDGEKN4AFI4SU2M7B43MGK3QJZNSR"}

[leighmcculloch]

The reduced nesting simplifies things. And I've had agents trip up on the deep nesting.

I wonder if it might be easy to make a mistake and send topic1 instead of topic2, because on a quick glance I missed that the second one was querying on topic2 and not topic1.

Reducing the nesting, but keeping the topics array might be clearer (see below).

I don't feel strongly about that though, I think topicN works too.

"filters": [
  {
    "type": "contract",
    "contractId": "CAS3J7GYLGXMF6TDJBBYYSE3HQ6BBSMLNUQ34T6TZMYMW2EVH34XOWMA",
    "topics": [
      {"symbol":"transfer"},
      {"address":"GAIH3ULLFQ4DGSECF2AR555KZ4KNDGEKN4AFI4SU2M7B43MGK3QJZNSR"}
    ]
  },
  {
    "type": "contract",
    "contractId": "CAS3J7GYLGXMF6TDJBBYYSE3HQ6BBSMLNUQ34T6TZMYMW2EVH34XOWMA",
    "topics": [
      {"symbol":"transfer"},
      "*",
      {"address":"GAIH3ULLFQ4DGSECF2AR555KZ4KNDGEKN4AFI4SU2M7B43MGK3QJZNSR"}
    ]
  }
]

[tamirms]

updated the proposal to accept either JSON or b64 encoded scvals

[Shaptic]

I think it would be valuable to elaborate on the feature subset we plan to support for full history: it seems this v2 variant has both way more features yet also less than the original. If we could compare and contrast it with what's feasible for full history, it may clue us in better as to what can be pared down from this endpoint.

[oceans404]

+1

The proposal says v2 works identically over 7 days and full history, but full history is a much larger dataset to index, so I'd expect some queries to be more restricted there. Can you clarify: does a query that works on a 7-day node also work over full history, or are some filters (like topic-only or no contractId) limited to the recent window? If different, what error does the full-history node return?

Thinking about this to make sure JS SDK and others surface the right errors

[tamirms]

The query should actually work the same whether it's served by an RPC node with 7 days of retention or with full history. We're able to achieve that because every request is anchored to a specific starting ledger: either the bound you gave (min for ascending or max for descending) or the position carried in the cursor. A request never means "search all of history"; it means "continue from this ledger".

On top of that, there's an internal scan limit that caps how much history a single request will cover. In our implementation it's 10,000 ledgers: a request scans from its starting point until it has either collected limit events or covered 10,000 ledgers, whichever comes first, and reports how far it got in scannedLedger. A dense query fills its page within a few hundred ledgers; a sparse one covers the full 10,000 and may return few or even zero events with scanStatus: "HAS_MORE", and the cursor picks up from there.

For example, take { min: 1000, max: 500000, filters: [...] } on a full-history node. The first request scans at most ledgers 1000 through 10999. If only 12 events match in that stretch, the page carries those 12 events and scannedLedger: 10999, even though limit would have allowed 100. The next request continues from ledger 11000, and so on until the scan passes max and reports COMPLETE.

So retention depth changes how many pages a long range takes, never how expensive one request is or which queries are allowed.

[steven-tomlinson]

This is a timely proposal from my perspective and I look forward to implementing it for use in my sparse history Pakana Node.

[FrankSzendzielarz]

Couple of random thoughts related to above:

• As part of an SDK I developed a year ago, I have a tool that converts the Stellar XDR schemas to protobuf and gRPC and marshalls to JsonRPC. It is used to drive a wrapper that can be hosted as an in-memory server on the client for gRPC interaction with Stellar RPC, or it can be run next to the server (clients of any language can codegen all the SDK objects). Or if you want it you can bake it in or use the tooling to offer a gRPC interface as well. (PS: it also uses AutoFixture to spit out a load of XDR strings for each object to test roundtrip serialisation, so if you want you can have that too, hundreds of test vectors)

• Consider pubsub/push models. If multiple clients are hitting the server watching for something (like a mobile app or video game), you want a push model with topics and subscribers. MQ. Furthermore, you could look into streaming both directions (forward for new ledgers, backwards for scans) by supporting query language integrated observables

• Corollary to above - GraphQL (DoS prevention in complexity config)

[tupui]

Please no GraphQL 😅 I think that would bring unnecessary complexity. Proper RPC API is good enough for that IMO.

[FrankSzendzielarz]

Yeah I dont really know anything about GraphQL lol. Just thought I would mention it because it was not mentioned.

[tomerweller]

Starting a dedicated thread for nesting, following up on @leighmcculloch's comment here.

Arrays of arrays tend to be confusing and there's a lot of potential nesting in the current structure. The following proposal replaces the current TransactionQuery with a FiltersQuery that combines all filters into a strictly flat filters list. Should allow for the same functionality but with less footguns and more predictable performance (though slightly more verbose sometimes).

Definitions

type Filter = { // AND between txhash, contract id and all topic values
  txHash?: string;
  contractId?: string;
  type?: "contract" | "system";
  topics?: ScVal[]; //no further nesting 
};

type FiltersQuery = {
  filters: Filter[];  // UNION between filters
};

Example, XLM transfers to and from a specific address

{
  filters: [
    {  
      contractId: "CAS3J7GYLGXMF6TDJBBYYSE3HQ6BBSMLNUQ34T6TZMYMW2EVH34XOWMA",
      type: "contract", 
      topics: [{ symbol: "transfer"}, { address: "GABC..." }] 
    },
    { 
      contractId: "CAS3J7GYLGXMF6TDJBBYYSE3HQ6BBSMLNUQ34T6TZMYMW2EVH34XOWMA",
      type: "contract", 
      topics: [{ symbol: "transfer"}, "*", { address: "GABC..." }] 
    }
  ]
}

Example with topicN instead of topics array

I find the topic array and the wildcards somewhat confusing so prefer a topicN approach as follows. Though not religious about it.

{
  filters: [
    { 
      contractId: "CAS3J7GYLGXMF6TDJBBYYSE3HQ6BBSMLNUQ34T6TZMYMW2EVH34XOWMA",
      type: "contract", 
      topic0: { symbol: "transfer"},
      topic1: { address: "GABC..."}
    },
    { 
      contractId: "CAS3J7GYLGXMF6TDJBBYYSE3HQ6BBSMLNUQ34T6TZMYMW2EVH34XOWMA",
      type: "contract", 
      topic0: { symbol: "transfer"},
      topic2: { address: "GABC..."}
    }
  ]
}

[leighmcculloch]

How about xdrInputFormat sitting alongside?

I think including xdrInputFormat or a similar named field in the request alongside xdrFormat would be simpler, and it continues the existing pattern that we use xdrFormat to control the format of the response. Wdyt?

[leighmcculloch]

Thinking out loud, another way to distinguish would be a different key, such as topicXdr for the base64. That would be consistent with how we distinguish xdr vs text inputs in some parts of the cli.

[tamirms]

ok, either of xdrInputFormat or topicXdr is fine by me. We can defer that decision until we decide on how we want the API for contract / topic filtering to look like as I think the pros / cons of xdrInputFormat vs topicXdr might differ depending on how the request shape looks like.

[Shaptic]

Should we consider contractId XOR topicN filters for simplicity? I can't foresee a big use case where you'd want both at the same time.

@Shaptic mind unpacking this with some examples?

Sorry, haven't been caught up here. I take back my XOR comment but I'll expand on simplification: since we know with near-certainly that we cannot serve complex filter queries in a full history environment, and it's inadvisable from a performance standpoint to provide a comprehensive SEP-41 event filter (5 topic filters), I don't think it's unreasonable to propose paring down the feature set to be precise and tight:

• either ledger range or cursor
• a single contract ID and a single topic filter

So you could have

"filter": {
  "contractID": "<xlm-contract-id>", // or a list up to some reasonable max
  // and/or
  "topics": {
    "topic0": "transfer", // base64-encoded scval or json, ignoring the "void"-etc issues discussed above
    "topic2": "G..."
  } // omitted topics imply wildcards
}

and only exactly one filter can be supplied. I wonder if this is really that restrictive? Events are sortable and should be atomic within a ledger, so multiple topic filters can be interleaved client-side fairly easily.

[leighmcculloch]

Events are sortable

Events are sortable because their 'id' exposed by RPC is ordered, but I don't think the docs communicate this today. Regardless of the design that gets decided here, but especially if developers need to rely on the sort-ability, this seems like something we can improve so opened:

• Document properties of event id field in the RPC getEvents response stellar-docs#2250

[leighmcculloch]

Below I describe a search-style query language for the events endpoint that I think we could consider and has advantages with regards to straddling the simple vs expressive boundary. The API is similar in experience to the GitHub Search API.

Note

There's an example of a query syntax API like the one described here at:
https://stellar-events-api-search-queries.fly.dev

One of the challenges with our existing API and the proposals we've been discussing is that we are constantly trading between two things:

• An API structure that is simple to understand.
• An API structure that is expressive and powerful enough.

In a fixed schema request format these two things are at odds, because the more powerful the filter parameters are, the more challenging it is for humans and machine to understand and due to the fixed nature of the request that complexity is always exposed. (e.g. the nested topics)

Search-style query languages can be expressive while still being very easy to use, especially for basic queries. This is because they naturally provide gradual complexity to a user.

For example, for Stellar events, this would mean replacing the filters JSON object with a q query string parameter, containing a search-style query syntax built from series of key:value qualifiers and AND (implied) and OR (explicit) operators.

Some keys that I expect would be supported:

Key	Value	Description
type	contract, system	Match events of this type. Case-sensitive.
contract	Stellar contract strkey (C…)	Match events emitted by this contract.
ledger	Positive integer	Match events from this ledger sequence number.
tx	Transaction hash hex string	Match events from this transaction. Requires ledger.
topic0 … topic3	XDR-JSON ScVal object	Match events whose topic at position 0–3 equals this value exactly.
topic	XDR-JSON ScVal object	Match events that contain this value in any topic position.

All contract events from a specific ledger:

ledger:58000000 type:contract

Transfer events for a contract:

contract:CCW67TSZV3SSS2HXMBQ5JFGCKJNXKZM7UQUWUZPUTHXSTZLEO7SJMI75 topic0:{"symbol":"transfer"}

Events from a specific transaction:

tx:7758a34695323011e177c932cb899f3ea55c5af4d95c954e946ddddaafca0296

Transfer, mint, clawback, and burn events for XLM and USDC:

(
  contract:CAS3J7GYLGXMF6TDJBBYYSE3HQ6BBSMLNUQ34T6TZMYMW2EVH34XOWMA OR 
  contract:CCW67TSZV3SSS2HXMBQ5JFGCKJNXKZM7UQUWUZPUTHXSTZLEO7SJMI75
) 
(
  topic0:{"symbol":"transfer"} OR 
  topic0:{"symbol":"mint"} OR 
  topic0:{"symbol":"clawback"} OR 
  topic0:{"symbol":"burn"}
)

Events where a specific address appears in any topic position, and noting how topic and topicN could sit side-by-side in docs without having the same heavy experience on a readers cognitive load that one large JSON request has, because the query syntax encourages incremental learning:

contract:CCW67TSZV3SSS2HXMBQ5JFGCKJNXKZM7UQUWUZPUTHXSTZLEO7SJMI75 topic:{"address":"GABC..."}

Query syntaxes come with their own challenges. Without good documentation it is often hard for a developer to learn exactly how to query something because there is no inherent structure that captures the full scope of all possibilities. Good documentation is super important for supporting the advanced use cases.

An API shaped like this can still have limits, expressed either as generically or specifically as necessary. For example:

Limit	Value
Maximum query length	1,024 bytes
Maximum terms (key:value pairs)	20
Maximum parenthesis nesting depth	4
Maximum filter combinations after DNF expansion	20
Maximum number of topic queries	5

[tamirms]

I'm ok with this proposal if the query language is restricted to contract id and topic filtering only. I don't like having the query language replace the structure around range queries vs cursor queries vs tx hash queries:

type RangeQuery = {
  min?: number,           // Starting ledger (inclusive)
  max?: number,           // Ending ledger (inclusive)
  order?: "asc" | "desc",
  contractIds?: string[],
  topics?: TopicFilter,
  limit?: number
}

type TransactionQuery = {
  txHash: string,
  contractIds?: string[],
  topics?: TopicFilter,
  limit?: number
}

type CursorQuery = {
  cursor: string,
  limit?: number
}

type GetEventsRequest = RangeQuery | TransactionQuery | CursorQuery

The reason is about ruling out illegal states. For example, all of these queries are semantically invalid even though they are syntactically valid:

• cursor:abc123 txHash:7758a3... — cursor with txHash
• txHash:7758a3... order:desc min:1000 — txHash with range params
• min:1000 OR min:2000 — what would this even mean?
• order:desc OR order:asc — contradictory

Keeping iteration as structured fields means most of these combinations can't be constructed in the first place. The three request modes (range, transaction, cursor) are enforced by the request shape, not by parsing a string and checking for contradictions after the fact.

So what I'd propose: q handles what to match, structured fields handle which window of events (txhash or ledger range) to look at:

{
  "min": 1000,
  "max": 5000,
  "order": "desc",
  "q": "contract:CCW67... topic0:{\"symbol\":\"transfer\"}",
  "limit": 100
}

{
  "txHash": "7758a3...",
  "q": "topic0:{\"symbol\":\"transfer\"}"
}

{
  "cursor": "abc123",
  "limit": 50
}

[leighmcculloch]

Keeping iteration as structured fields means most of these combinations can't be constructed in the first place.

{
  "min": 1000,
  "max": 5000,
  "order": "desc",
  "q": "contract:CCW67... topic0:{\"symbol\":\"transfer\"}",
  "limit": 100
}

{
  "txHash": "7758a3...",
  "q": "topic0:{\"symbol\":\"transfer\"}"
}

{
  "cursor": "abc123",
  "limit": 50
}

I don't think the structure proposed ☝🏻 prevents the use of unsupported combinations. The min, max, txHash, and cursor fields can be provided at the same time. Presumably the API would return a http 400 in that case. Similar, if a search query contains an invalid combination a http 400 error can be returned.

I don't think we need it to be structurally impossible either. Very few APIs can guarantee that structure alone prevents the need for any validations.

[tamirms]

the type system prevent you from representing in an illegal state where, for example, you have both txHash and a min / max:

type GetEventsRequest = RangeQuery | TransactionQuery | CursorQuery

Presumably the API would return a http 400 in that case. Similar, if a search query contains an invalid combination a http 400 error can be returned.

yes, the advantage of types is making the validation apparent by construction. the types communicate validation rules in a concise way. also, it provides a model for client implementations.

Very few APIs can guarantee that structure alone prevents the need for any validations.

It's not an all or nothing proposition. If it's not possible to eliminate invalid sates we should try to minimize them. Generally speaking making illegal states unrepre­sentable is a good property to have in your API:

https://functional-architecture.org/make_illegal_states_unrepresentable/
https://www.pathsensitive.com/2018/07/when-your-data-model-means-something.html
https://inside.java/2024/06/03/dop-v1-1-illegal-states/
https://note89.github.io/state-of-emergency/

[leighmcculloch]

Have we considered a minimal modification to getEvents? Taking a step back it seems to me like some of the problems could be solve minimally in ways that are almost backwards compatible, without significant changes to the API, and maybe that would be sufficient.

For example, all the following changes make subtle changes, some technically breaking, but all in very forgiving ways, without a significantly new endpoint.

Filters match on topic count, not content

Assume "**" is always passed at the end of the topic search, so filter count never matters.

Cursor encoding exposes implementation details

Is this actually a problem? Seems like an internal concern. Either way, make it opaque.

endLedger ignored during pagination

Error on endLedger passed if already paginating an earlier query.

Empty pages confuse clients with sparse data

The proposal with hasMore: true + scannedLedger showing scan progress sounds good, and we can add those fields to the pagination section of the existing response.

No way to filter by transaction

Add as new top level field without any other structural changes, and error 400 if combined in incompatible ways.

No descending order for "latest events"

order: "desc" iterates newest-first.

• Descending requires nothing

This issue isn't listed in the top of the documents problem list, but the getEvents method requiring either startLedger or cursor, and so to use the endpoint in anyway you need to first know at least what the latest ledger. The problem is captured in this issue: stellar/stellar-rpc#23. order: desc fixes that, so would also defaulting startLedger to latestLedger, and I think we should do both.

nested topics

This issue isn't listed in the top of the documents problem list, but it came up in the discussion. The topics field could accept either a single topic list or the array of topic lists. It'd make the easy case work. I think this was suggested by someone in this discussion but I can't find the comment.

(I realise I'm posting a couple of suggestions ^{1 2} at either end of the spectrum.)

[tamirms]

We should first try to agree on what API would solve the existing pain points and provide a good developer experience. I think we are close to having consensus. I think the only remaining issue is agreeing on how to do the contract id / topic filtering. Once we have alignment there, we can see if it's possible to take the proposal for getEvents v2 and introduce it in a backwards compatible way

[teddav]

Hey! Any news on this? 😊

[aolieman]

You can track the most recent progress here: stellar/stellar-rpc#777

[tamirms]

I've rewritten the proposal at the top of this discussion, incorporating the feedback from the different threads:

Filters now use the flat shape @tomerweller proposed: a filters list of {contractId?, topic0..topic3?} objects, AND within a filter, OR across the list, and omission as the only wildcard. Cross-position queries like "transfers involving me" now fit in one request, so that use-case gap is gone.

One open question, do we need to filter by event type (e.g. system vs contract)? I have removed the event type selector from the filter object because I don't think anyone uses this feature of the current getEvents API. The event type has little selective power today. The only system events are executable_update notifications, already selectable via topic0.

Also, note that filters are limited by the number of distinct index terms used.

ScVal encoding is explicit. Following @leighmcculloch's observation that some xdr-json values are bare strings, value encoding is no longer inferred from shape: xdrInputFormat declares the request encoding and xdrFormat the response encoding, both defaulting to base64.

Pagination is rebuilt. The hasMore boolean becomes a four-value scanStatus: HAS_MORE, WAITING_FOR_LEDGERS, OLDEST_REACHED, and COMPLETE, so "pull now", "retry later", "this node has nothing older", and "done forever" are distinct signals rather than readings of one flag. A scan that reaches a node's retention floor says so on that final page instead of erroring on the next request, bounds past the chain tip are legal and never clamped.

The transaction mode is removed in favor of a companion change: getTransaction gains an events.parsed field returning the same Event objects with the same ids as this API, so a transaction detail page is one call.

The event object is unchanged from v1 except that the deprecated inSuccessfulContractCall is dropped.

Please review the latest proposal and let me know what you think!

[aolieman]

Thank you for the considerable improvements made to your proposal. I'll enjoy using this v2 when it is implemented.

One open question, do we need to filter by event type (e.g. system vs contract)?

No, I don't think so. The type is in the event object and API consumers don't need it to filter, as you already have argued.

Two questions:

1. Is the event id incorporated into the cursor?
2. Can the cursor be constructed/encoded client-side, e.g. knowing a query template and a latest-stored event id?

I'm asking to gauge the client-side requirements for cursor persistence. In case of an unexpected shutdown and subsequent restart, would the client need to implement strong guarantees that the latest cursor returned by the RPC has been stored, or would recovery/continuation be possible when the full query and the latest stored event are known?

If a more detailed cursor design is available elsewhere, I'd be happy to go over it.

[tamirms]

Thanks @aolieman !

On your questions:

1. The cursor encodes the full resume position, which amounts to the same information as your last delivered event id plus the original query. It is deliberately opaque though: the encoding is unspecified and free to change, so nothing should be read out of it or constructed to look like it.

2. No, and that's by design. But the recovery you're describing doesn't need it: if you know the original query and the id of the last event you processed, run the same query again starting at that event's ledger (set min to it for ascending, max for descending). The response will begin with some events you have already processed. Because event ids are unique and sort lexicographically in stream order, you can either dedupe by id or discard every event whose id is at or before the stored one (at or after, for a descending query).

[chowbao]

One open question, do we need to filter by event type (e.g. system vs contract)?

I would opt to keep system and contract event type filter to provide flexibility in the future. Right now there's only the single system event but that doesn't mean there won't be more system events added in the future (maybe someone from the core team can tell us if this is true or not). If we were to remove it now it would be a much larger lift to add a system event filter to getEvents()/RPC in the future.

[oceans404]

Thinking about how the JS SDK will support v2.

Since v2 changes the request shape (min/max, inclusive bounds) and unknown fields are rejected as invalid_params, v1 and v2 requests are mutually incompatible if they share a method name. During the adoption window, SDKs and multi-provider apps will hit a mix of upgraded and non-upgraded nodes, so we need a cheap way to detect support. 2 qs

1. Is v2 a new method name, or an in-place change to getEvents?
2. Will getVersionInfo (or similar) advertise v2 support? ideally there'd be a capability flag to let SDKs pick v1 vs v2

[tamirms]

Yes, I think a new method name (e.g. getEventsV2) would be the best option.

Most likely we will support both getEvents and getEventsV2 for a period of time before getEvents is removed. Calling getEventsV2 on a node that doesn't support it returns the standard JSON-RPC method-not-found error.

I didn't think about updating getVersionInfo to include a capability flag before you mentioned it. I think updating getVersionInfo to include a list of supported methods could be a solution for this problem:

{ "version": "...", "commitHash": "...", "protocolVersion": 23, "methods": ["getEvents", "getEventsV2", "getHealth", ...] }

Would that work for the JS SDK's needs? I'm happy to adjust based on your feedback!

[oceans404]

Yes, the methods list in getVersionInfo works. The SDK will fetch it once per connection and gate on "getEventsV2" membership, falling back to v1 otherwise. This is the right shape because it lets us detect support in one round trip during the mixed-version adoption window, instead of firing a getEventsV2 call and catching method-not-found per node. Advertising capabilities is also the standard answer to JSON-RPC having no version field: OpenRPC defines rpc.discover for this: https://spec.open-rpc.org/#service-discovery-method

Would it be possible to advertise the limits here too? If the term budget and related limits are deployment configurable, you could expose them in the same response, for example limits: { termBudget, maxFilters, scanLedgers, maxLimit }. One known EVM pain point I saw is that eth_getLogs block-range limits differ per provider and are not discoverable, so clients hardcode a number and break when they switch RPCs. Discoverable limits (as GitHub does via /rate_limit) let SDKs and query builders validate before sending and let each provider tune limits without every SDK shipping a new constant.

[tamirms]

The design and API for getEvents V2 has been finalized so I will close the discussion. The work to implement the endpoint is tracked here stellar/stellar-rpc#774