soroban-rpc: add an endpoint on soroban RPC to self report versions for downstream clients

[janewang]

What problem does your feature solve?

To help downstream clients that depend on the RPC to versions (such as XDR), the RPC could provide an endpoints to self report build stamp, release semver, xdr versions, and rs/contract interface versions, giving any remote rpc client as much info to interrogate the rpc capabilities.

What would you like to see?

A new endpoint on the RPC that reports this information, similar to the information provided by Horizon's root url (horizon.stellar.org)

[2opremio]

Things we could also add:

• captive core version
• protocol version (provided by captive core?)
• interface version (which should be possible to obtain from the rs-soroban-env library and ideally also from captive core, although I don't think it was exposed in the info endpoint in the end, @marta-lokhova do you know?).

[2opremio]

Related: stellar/stellar-core#3960 (comment)

[marta-lokhova]

relaying some info from stellar/stellar-core#3960 for posterity: core won't start if its own protocol version doesn't match env's interface version. So interface version isn't exposed in core's info endpoint to avoid confusion. Interface version also contains "pre-release version" used for development; this version can be obtained via stellar-core version command if needed.

[psheth9]

Thanks @2opremio and @marta-lokhova for the context

Few questions:

1. Currently getNetwork returns the protocolVersion from core, do we still need it in this endpoint?

2. Based on the above discussion, it seems like protocol version is same as interface version so if thats the case can we also assume the same on our end (RPC world)? - This means that we dont have to expose interface version in this endpoint.

3. Can we get into the situation where interface version that we get from captive core is different from the soroban-env-host lib that we use in RPC? @2opremio we talked about this issue briefly. Should we add this check during the boot up of the service to make sure that version of soroban-env-host and interface stays consistent b/w core and rpc?

@janewang we get following information when we run stellar-core version. it might be worth it to add all the values as a part of this endpoint. what do you think?

stellar-core version
v20.2.0rc3-2-g6e73c0a88
rust version: rustc 1.74.1 (a28077b28 2023-12-04)
soroban-env-host:
    curr:
        package version: 20.2.0
        git version: 1bfc0f2a2ee134efc1e1b0d5270281d0cba61c2e
        ledger protocol version: 20
        pre-release version: 0
        rs-stellar-xdr:
            package version: 20.1.0
            git version: 8b9d623ef40423a8462442b86997155f2c04d3a1
            base XDR git version: b96148cd4acc372cc9af17b909ffe4b12c43ecb6

[psheth9]

@2opremio Need your input on 3rd question:

Can we get into the situation where interface version that we get from captive core is different from the soroban-env-host lib that we use in RPC? @2opremio we talked about this issue briefly. Should we add this check during the boot up of the service to make sure that version of soroban-env-host and interface stays consistent b/w core and rpc?

Also currently from what I know, we do not expose interface version from soroban-env-host. if thats the case, I would like to track it in follow up issue/PR to update the rust bindings.

[2opremio]

Yes, technically it can happen that the versions are different, particularly since soroban-rpc is not multiversion.

I bet there is a simple way to get the protocol (i.e. interface) version from the library. @dmkozh may be able to assist

[dmkozh]

I think we're overloading the term 'protocol version' - there is the 'current' protocol version that is set in the ledger header and upgraded via vote, and there is 'maximum' protocol version supported by a given library. The actual behavior and supported interface is always defined by the 'current' protocol version, not the maximum one.
Here is some general info on versioning that could hopefully help to make a decision as to what should be shown to the users:

• 'Interface version' comprises the maximum protocol version supported by a given env library and the pre-release version (which is only relevant for 'WIP' builds for the next protocol, so this will never occur in pubnet builds, and probably is unlikely even in testnet builds). The env is able to run any contract with protocol version that is not greater than the value defined in the library.
• Any library that imports soroban-env-common crate can get the maximum protocol version it supports using meta::get_ledger_protocol_version(meta::INTERFACE_VERSION).
• In order to reduce the risk of divergence, Core uses two builds of env during the 'transitionary' period between the protocol versions (specifically the build that will be used for validator vote to upgrade from protocol N to protocol N + 1). The 'prev' version is used to close ledger up to protocol N, then the 'curr' version is used. After the upgrade has happened, a new build of core is used where 'curr' version is used to close all the ledgers up until N + 1.
  • This is an implementation detail that is only relevant for interpreting the output of stellar-core version. For 'dual-env' Core builds you should be getting information for both 'prev' and 'curr' envs. But as a general rule, any given build of core supports ledger protocol versions up to the version defined in 'curr' env. So maybe it's a good idea to always omit prev for the sake of clarity.
  • There is no need to use 'dual-env' builds in the RPC. Even in case of divergence (which is highly unlikely), the simulation results are likely to be within the error margin that already exists. So the 'curr' build can be used to simulate both ledger protocol versions N and N + 1.
• Any build of RPC that uses env with interface version N is good to simulate transactions up to ledger protocol version N (modulo bug fixes). For example, a current RPC build that only supports protocol 20 can be used with a new build of captive core that supports protocols up to 21, but only until the upgrade happens. Another example is that an RPC build that uses the new env (interface version 21) is good to simulate transactions with the 'old' captive core (say, 20.4), but the core itself has to be updated before the network upgrade to 21 happens. So there is no technical requirement for env versions to match between the captive core and RPC (but of course you still can demand that for some other reason).

[leighmcculloch]

If we're planning to report the maximum supported protocol version and the current protocol version from the RPC, we can look to Horizon for how to do that because Horizon has done that for a long time with little confusion as far as I'm aware.

Horizon exposes three fields:

  "current_protocol_version": 19, // current protocol version of the network
  "supported_protocol_version": 20, // max supported protocol version of horizon
  "core_supported_protocol_version": 20 // max supported protocol version of core that horizon is using

It's worthwhile exposing all three on the endpoint that returns versions.

Given that these fields have caused little confusion, probably worth using the same or similar names if there's no value in innovating on that.