Document properties of event `id` field in the RPC `getEvents` response

[leighmcculloch]

What problem does your feature solve?

The getEvents API reference describes the id field in the response as:

Unique identifier for this event, based on the TOID format. It combines a 19-character TOID and a 10-character, zero-padded event index, separated by a hyphen.

This describes the format of the ID, of which much can be inferred, but for developers building on the API it would be ideal if the doc stated the properties of the id explicitly. So it is really clear what they can and can't rely on.

For example:

• Ordering: The id is used as a cursor for pagination and is lexicographically ordered, meaning events can be sorted by id to get chronological order. This is important for developers building event streaming or indexing systems, but it's not stated.
• Stability: Is the event id for a given event stable across protocol versions? If a developer stores event IDs for deduplication or tracking, will they remain valid after protocol upgrades?
• Other properties?

Without these properties being explicitly documented, developers have to infer them.

This becomes even more critical if core workflows using the RPC will require developers to sort events themselves, which is something being discussed here:

• https://github.com/orgs/stellar/discussions/1872#discussioncomment-15786554

What would you like to see?

Explicitly document the properties of the id field in the getEvents response. For example:

• State that the id is ordered — events with a higher id occurred later, and id values can be compared lexicographically to determine order. The docs also need to say how that works in the context of parallel execution on network.
• Clarify whether the id is stable across protocol versions — i.e. whether the same event will always produce the same id regardless of protocol upgrades.
• Any other guarantees or caveats about the id that developers should know about.

What alternatives are there?

• Developers can infer the ordering property from the fact that id is used as a pagination cursor, but this is implicit and not a documented guarantee.
• Developers can read the RPC server source code to understand the TOID construction, but this shouldn't be necessary for an API consumer.