refactor(experimental): move RPC API types from rpc-transport to rpc-types

[lorisleiva]

This PR moves the following types from @solana/rpc-transport to @solana/rpc-types:

• Rpc
• RpcSubscriptions
• IRpcApi
• IRpcSubscriptionsApi
• IRpcApiMethods
• IRpcApiSubscriptions
• RpcRequest
• RpcSubscription
• PendingRpcRequest
• PendingRpcSubscription
• SendOptions
• SubscribeOptions

As a result, packages such as @solana/accounts now no longer need to import @solana/rpc-transport in order to simply define an Rpc type with a few handpicked methods.

---

Side note A: Ideally I wanted @solana/rpc-core to also no longer need @solana/transport but the former doesn't only export type, it also export functions that create an RPC API with transports. I think this is fine but we may consider breaking @solana/rpc-core into two packages such as one only defined the method/subscription types, and the other one imports everything to offer factory functions.

---

Side note B: When seeing all the exported types laid out like that, we can see the naming for the Subscription side is a little ambiguous. For instance, it is not immediately clear what the difference between IRpcSubscriptionsApi and IRpcApiSubscriptions is. The reason behind this is the Subscription side doesn't have equivalents to the names Method and Request. A good refactoring could be to rename types like IRpcApiSubscriptions to IRpcApiSubscriptionMethods or PendingRpcSubscription to PendingRpcSubscriptionRequest, so they are consistent with the non-subscription API. What do you think?

[lorisleiva]

Current dependencies on/for this PR:

• master
  • PR refactor(experimental): move RPC API types from rpc-transport to rpc-types #2049 👈
    • PR refactor(experimental): move RpcResponse and typed bigints to rpc-types #2050
      • PR refactor(experimental): decouple @solana/accounts from @solana/rpc-core #2051

This stack of pull requests is managed by Graphite.

[buffalojoec]

You know, I thought to myself "this makes sense, but damn this is going to affect a looot of files", and then:

[buffalojoec]

Side note A: Ideally I wanted @solana/rpc-core to also no longer need @solana/transport but the former doesn't only export type, it also export functions that create an RPC API with transports. I think this is fine but we may consider breaking @solana/rpc-core into two packages such as one only defined the method/subscription types, and the other one imports everything to offer factory functions.

Interesting. Is the API definition alone useful anywhere else as its own library?

Side note B: When seeing all the exported types laid out like that, we can see the naming for the Subscription side is a little ambiguous. For instance, it is not immediately clear what the difference between IRpcSubscriptionsApi and IRpcApiSubscriptions is. The reason behind this is the Subscription side doesn't have equivalents to the names Method and Request. A good refactoring could be to rename types like IRpcApiSubscriptions to IRpcApiSubscriptionMethods or PendingRpcSubscription to PendingRpcSubscriptionRequest, so they are consistent with the non-subscription API. What do you think?

Agreed that the two aren't really at parity. The factories use Method and Notification as analogous. Maybe we can leverage that nomenclature?

[buffalojoec]

I think this commit combined with your next one makes me thing about whether or not we should potentially isolate between the following:

• Types that are for an RPC as per our various packages' definition of the official JSON RPC spec
• Types that are specifically Solana types that will be vended by a Solana JSON RPC, specifically

What do you think?

[lorisleiva]

[A]: Not that I can think of so maybe it's not so much of an issue right now.

[B]: I do like RPC Subscription Notifications as a parallel to RPC Methods. My slight concern is people thinking of notifications as subscription events but if we're consistent with the naming that I think that can work. I'm struggling to find a better alternative.

[C — splitting RPC types]: That's interesting. Do you mean we'd be splitting rpc-types into something like rpc-types (for the core spec types) and rpc-solana-types (for the Solana specific RPC types)?

[buffalojoec]

[B]: I do like RPC Subscription Notifications as a parallel to RPC Methods. My slight concern is people thinking of notifications as subscription events but if we're consistent with the naming that I think that can work. I'm struggling to find a better alternative.

I guess maybe we could go with something like packet or message, but imo I think notification is fine.

[C — splitting RPC types]: That's interesting. Do you mean we'd be splitting rpc-types into something like rpc-types (for the core spec types) and rpc-solana-types (for the Solana specific RPC types)?

Yeah that's exactly what I mean! Because someone who might be defining their own RPC API shouldn't need to also pull in Solana-related types, considering they may define data a totally different way, even if they are still working on Solana.

[lorisleiva]

[B]: Subscription notifications is fine by me. 👌

[C]: I like that idea very much. If we're gonna do that though, I think we need to rethink our rpc-* packages altogether because we have to think about how that will look next to, say, rpc-parsed-types which is very Solana specific.

Current we have:

• rpc-core: Solana API types and factory functions to create full Solana RPC & RPC Subscriptions.
• rpc-graphql: GraphQL version of rpc-core.
• rpc-parsed-types: JSON parsed types for Solana RPCs — as returned by the RPCs.
• rpc-transport: Defines the foundations for interacting with HTTP and WebSocket RPCs. This also contains Solana specific types such as SolanaJsonRpcErrorCode.
• rpc-types: Defines low-level primitives for building RPCs on Solana. It includes both Solana-specific types and generic types such as Rpc.

My ideal refactoring of these packages is as-follow:

• rpc-core: Describes the core JSON RPC spec non-specific to Solana. It defines types such as Rpc, RpcSubscriptions, RpcResponse, IRpcMethods, etc.
• rpc-transport: Defines the foundations for sending HTTP requests and receiving WebSocket notifications via the JSON RPC spec without any Solana specific types or functions.
• rpc-graphql: Defines a non-Solana specific GraphQL version of rpc-core.
• rpc-solana-api: Same as current rpc-core.
• rpc-solana-types: Same as current rpc-types but without non-Solana specific types as they now live under the new rpc-core.
• rpc-solana-parsed-types: Same as current rpc-parsed-types.
• rpc-solana-graphql: Same as current rpc-graphql but only the Solana-specific part.
• rpc: (optional) An umbrella package (much like codecs) that re-exports all rpc-* packages. We could also move all the RPC-specific helpers from the main library package here so people can technically import the full Solana RPC stuff without the full library.

What do you think?

[B+C]: I don't think I'll have time to tackle these before I go on holiday but I can tackle that when I'm back if that's something we all agree on. Ideally I'd love it for that current stack to be merged before I'm OOO though because it changes so many file, I don't think it can afford to be stale for more than a week.

[buffalojoec]

I think I'm mostly aligned with what you're driving at, yeah.

A quick note on GraphQL, it's really Solana-specific atm, so in order to accomplish what you're describing we'd need to basically define an interface for it, and then extract the Solana bits into the new package. I have no idea what that would look like at the moment, so I don't think that will happen anytime soon.

As far as the other stuff goes, the naming convention would be:

• @solana/rpc-*: RPC interface packages
• @solana/rpc-solana-*: Solana RPC interface implementations

The fact that the org @solana is inescapable here may confuse people at first. If only we had another org name we could use for the RPC interface ones.

What would happen to rpc-parsed-types? Afaict those are all Solana types, since it's jsonParsed directly from the accounts/transaction decoders.

I also like the idea of the umbrellas for both, actually.

[lorisleiva]

Fair enough about the GraphQL stuff.

Yeah I can see the weirdness of @solana/rpc-solana-*. Another org name could fix this but not sure how I feel about having the monorepo spread into multiple NPM namespaces.

An alternative could be @solana/rpc-spec-* for the generic stuff and @solana/rpc-* for the Solana specific stuff.

[steveluscher]

Y'all have already hashed a lot of this out, and I agree that all of your proposed changes would make an improvement here!

Only other input:

• The dream for rpc-core was always to finish it up and then elevate it to the level of Architecture discussion: JSON RPC API specification solana-foundation/specs#22. Whatever gets this closer to that is great.
• I'm totally down with changing the subscription type namings. Just don't confuse the action nouns and the data nouns. I don't know how best to map ‘Subscriptions’ and ‘Notifications’ on to this pattern:
  • RPC (remote procedure call)
    • Calls are the things you make…
    • …as part of Requests (ie. to a remote server)…
    • …to receive Responses.
  • For subscriptions, then.
    • ??? are the things you make…
    • …as part of ???…
    • …to receive Notifications.

Maybe the unlock is just SubscriptionCall and SubscriptionRequest, as you suggested in this PR's description!

[lorisleiva]

Merge activity

• Jan 23, 11:10 PM: @lorisleiva started a stack merge that includes this pull request via Graphite.
• Jan 23, 11:10 PM: @lorisleiva merged this pull request with Graphite.

[github-actions]

🎉 This PR is included in version 1.90.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[github-actions]

Because there has been no activity on this PR for 14 days since it was merged, it has been automatically locked. Please open a new issue if it requires a follow up.