RFC-8 support

[josepot]

Now that RFC-8 has been finally implemented in PolkadotSDK 🎉, I think this is a great opportunity to improve the ergonomics and clarity of the public API by revisiting the Client interface.

Specifically, I’d like to propose a redesign of the Client interface to make it more ergonomic and less error-prone. One key motivation is to remove the problematic potentialRelayChains property, which has historically caused confusion and race conditions.

Proposed Interface

type JsonChainOptions = {
  disableJsonRpc?: boolean;
  jsonRpcMaxPendingRequests?: number;
  jsonRpcMaxSubscriptions?: number;
};

type AddRelayChainOptions = {
  chainSpec: string;
  databaseContent?: string;
} & JsonChainOptions;

type AddParaChainFromParaIdOptions = {
  paraId: number;
} & JsonChainOptions;

type AddParaChainFromChainSpecOptions = {
  chainSpec: string;
} & JsonChainOptions;

type AddParaChainOptions =
  | AddParaChainFromParaIdOptions
  | AddParaChainFromChainSpecOptions;

// Reuses the existing `Chain` interface
type RelayChain = Chain & {
  addParaChain: (options: AddParaChainOptions) => Promise<Chain>;
};

interface Client {
  addRelayChain(options: AddRelayChainOptions): Promise<RelayChain>;
  terminate(): Promise<void>;
}

Benefits

• Simplifies API ergonomics: Easier to understand and more intuitive to use.
• Removes race conditions: Eliminates potentialRelayChains, addressing an important source of bugs and complexity.
• Improves developer experience: Clearer structure for adding relay and parachains.

Example Usage

const smoldot = start();
const polkadot = await smoldot.addRelayChain({ chainSpec });
const assetHub = await polkadot.addParaChain({ paraId: 1000 });

WDYT?

Also, we (the PAPI team) would like to help with this.

[tomaka]

That new API should work, but be aware that it is a huge undertaking.

The biggest problem is that smoldot can't verify the parachain genesis hash and fork id that the relay chain nodes return, so it needs to handle the possibility where multiple different genesis hash/fork id values are sent by the relay chain, some of them being malicious.
I don't precisely know from the top of my head how difficult it is, but it does seem difficult.

[josepot]

The biggest problem is that smoldot can't verify the parachain genesis hash and fork id that the relay chain nodes return, so it needs to handle the possibility where multiple different genesis hash/fork id values are sent by the relay chain, some of them being malicious.
I don't precisely know from the top of my head how difficult it is, but it does seem difficult.

I see... yep, I get it! Then, it's probably best to do things one step at a time. So, let's separate the "improved API" from smoldot leveraging the bootnodes available via the relay-chain DHT.

Meaning that: let's leave the public API untouched, and then "simply" have smoldot use the bootnodes available on the relay-chain DHT when it doesn't have another means of connecting to its peers... As in when the databaseContent has not been provided (or it has been provided but the nodes are not reachable), and the list of bootnodes provided on the chainSpec are empty (or inaccessible due to protocol limitations, eg ws on browser, etc).

Although, I guess that until now using databaseContent was a simple perf-optimization, while now we should try to make sure that if smoldot is fetching the bootnodes from the relay-chain's DHT, that the consumer is caching that information... 🤔 PAPI can facilitate that for those using the smoldot-provider.