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:
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.
What problem does your feature solve?
The
getEventsAPI reference describes theidfield in the response as: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:
idis used as a cursor for pagination and is lexicographically ordered, meaning events can be sorted byidto get chronological order. This is important for developers building event streaming or indexing systems, but it's not stated.idfor a given event stable across protocol versions? If a developer stores event IDs for deduplication or tracking, will they remain valid after protocol upgrades?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:
What would you like to see?
Explicitly document the properties of the
idfield in thegetEventsresponse. For example:idis ordered — events with a higheridoccurred later, andidvalues can be compared lexicographically to determine order. The docs also need to say how that works in the context of parallel execution on network.idis stable across protocol versions — i.e. whether the same event will always produce the sameidregardless of protocol upgrades.idthat developers should know about.What alternatives are there?
idis used as a pagination cursor, but this is implicit and not a documented guarantee.