services/soroban-rpc: design event streaming API interface

[tsachiherman]

epic - stellar/stellar-rpc#43

related(but not blocked by), back-end data acquisition strategy for streaming - #4681

Create a detailed design document describing the intended implementation of the event stream API. The event stream API are the websocket subscription methods for the soroban-rpc service, so that clients can subscribe/unsubscribe from events.

This design should include :

• define the WS interface - add it to existing soroban rpc api docs
• secure wss or plain ws?
• event endpoint - wss://<rpc_host>/contracts/{contract_id}/events
• event filtering
• event aggregation
• obtain team consensus on result

[leighmcculloch]

What's driving the technology selection (ws/wss)? What are the use cases we're planning for? What requirements do we have for resuming when there are connectivity issues, or across restarts?

[paulbellamy]

This might want to use the existing api docs https://stellarorg.atlassian.net/wiki/spaces/PJC/pages/4402151440/soroban-rpc+API+Docs#Websocket-Subscription as a starting point.

I'd suggest the desired outcome here is updating the above api docs with a more "final" design.

Nice-to-have: We might also want a new pseudo-event for contract deployment.

[paulbellamy]

The design should consider:

• how to deduplicate events (e.g. subscribing to multiple soroban-rpc servers)
• How to incorporate historical replay or catch-up so clients can make sure they have received everything in spite of unreliable connections.

[paulbellamy]

@leighmcculloch

What's driving the technology selection (ws/wss)?

• "Industry standard", it's what other chains all use alongside their jsonrpc server. Doesn't seem like a worthwhile place to innovate.
• Websockets have (afaik) better built-in browser support (compared to server-sent-events or grpc). I expect at least some of these method will be used directly from dapps to trigger UI refreshes when things happen (e.g. balance updates after a transfer).

What are the use cases we're planning for?

• Primary: Browsers on a dapp website listening for events and triggering UI updates based on that (e.g. balance updates after a transfer).
• Secondly: Other backend components in the dapp streaming events to "ingest" into their own domain-specific database.

What requirements do we have for resuming when there are connectivity issues, or across restarts?

• Restarts are indistinguishable from connectivity issues, so should be handled the same.
• In event of a disconnect, the client should be able to esume event replay from a given ledger.
  • The client subscribes with the ledger sequence number they last saw, and replay begins from there.
  • Having the client tell us what ledger they last saw is more reliable, but also means we don't need any server-side per-client persistence (a nightmare to scale).
  • Could be limited to x days of recent ledgers to make scaling easier?
• Idle TCP socket detection is a total pain, so we probably want to add a heartbeat to the websocket protocol, and require clients to call that periodically. However, that can be in v2 release of this.

[paulbellamy]

See google doc https://docs.google.com/document/d/1TZUDgo_3zPz7TiPMMHVW_mtogjLyPL0plvzGMsxSz6A/edit#, and discussion on discord

• https://discord.com/channels/897514728459468821/1037073682599780494/threads/1040009826387902565
• https://discord.com/channels/897514728459468821/1037073682599780494/threads/1040709194115977267
  for design discussion

[paulbellamy]

Per the google design doc linked above, no websockets or push notifications for this. Just the request/response getEvents method, as per: https://docs.google.com/document/d/1TZUDgo_3zPz7TiPMMHVW_mtogjLyPL0plvzGMsxSz6A/edit#heading=h.t03hji406t76