Client Extension

[hayes-mysten]

Client Extension

As we've been developing more and more SDKs for the sui ecosystem, we have identified a need for unified patterns, shared utilities, and composability between SDKs.

There are a number of pain points we've identified as common issues faced by most SDKs:

• Almost all SDKs today depend directly on SuiClient (a thin wrapper of JSON RPC) which makes migration to other APIs (GraphQL and GRPC) effectively impossible
• Coordinating network specific client/sdk instances in multi-network apps can be complicated
  • This is specifically true for frontend/react Apps where clients are generally injected through context providers
    • SDKs are either forced to provide their own react bindings, or leave this complexity to users
    • Integrating with the existing dap-kit context providers is not trivial, and may require the SDK to add a dependency on dapp-kit which not all users need
• Many SDKs need common functionality, and end up re-implementing variants of the same patterns including:
  • caching
  • batch object loading
  • package configuration
  • transaction building patterns

What we're building to solve these problems

There are a couple tightly coupled pieces to our solution:

• A new extendable BaseClient that SDKs can extend via client extensions
• A new CoreClient that defines a common set of functionality that will be supported by JSON RPC (SuiClient), GraphQL, and GRPC apis.
• A new set of conventions for building SDKs that works as "Client Extensions"
• New versions of most of our SDKs that implement the new client extension pattern

BaseClient

The new BaseClient will allow clients (like SuiClient) to be extended via "client extensions":

import { SuiClient, getFullnodeUrl } from '@mysten/typescript/client';

class MyCustomSDK {
  #client: SuiClient;
  constructor(client: SuiClient) {
    this.#client = client;
  }

  myMethod() {}
}

const client = new SuiClient({
  url: getFullnodeUrl('testnet'),
}).$extend({
  name: 'myCustomSDK',
  register: (client) => new MyCustomSDK(client),
});

client.myCustomSDK.myMethod();

This pattern will allow any SDK to extend existing clients with new functionality. This solves the problem of
needing custom context providers for each SDK.

To make this work properly, dapp-kit will be updated so that it can provide an extended client via it's existing hooks.

For end users, client extensions will likely be easier to use:

const client = new SuiClient({
  url: getFullnodeUrl('testnet'),
}).$extend(createSuiNSExtension(), createWalrusExtension(), ...etc);

const blob = await client.walrus.readBlob(blodId);

CoreClient

The new CoreClient is intended as a target for SDKs that want to be compatible across different APIs
(currently JSON RPC, GraphQL, and GRPC). SuiClient already implements an experimental version of this API.

The CoreClient will support most common functionality needed by SDKs including:

• fetching objects
• fetching balances
• fetching coins
• fetching dynamic fields
• fetching transactions
• executing transactions
• dryRunning transactions

These APIs are not fully defined yet, and will be expanded as the GRPC API adds more functionality.

An early version of the interface is defined here.

Rather than accepting a SuiClient, they can accept a BaseClient with the extensions they need to function.
The CoreClient will be implemented implemented as a client extension that is enable by default by some client
like the existing SuiClient.

If your SDK depends on the CoreClient and the Walrus SDK, you can define something like:

class MyCustomSDK {
  constructor(
    client: ClientWithExtension<{
      core: CoreClient;
      walrus: WalrusClient;
    }>
  ) {
    this.#client = client;
  }
}

const client = new SuiClient({
  url: getFullnodeUrl('testnet'),
})
  .$extend(createWalrusExtension())
  .$extend({
    name: 'myCustomSDK',
    register: (client) => new MyCustomSDK(client),
  });

This will allow only allow your SDK to be registered with a client that has the right extensions, and allow your
SDK to access the walrus SDK without requiring it to be explicitly provided.

This will also ensure your SDK works with future GraphQL and GRPC clients.

SDK conventions

We are still in the early stages of this work stream, and are exploring what conventions we want to standardize on for our SDKs.

Our current plan is to write up public documentation about the standards we are using for our own SDKs as a set of best
practices for 3rd parties to adopt in their own SDKs.

Some important concepts we know we want to standardize include:

• SDKs all being client extensions
• Standard patterns for transaction construction
  • This includes the new "async thunk" pattern described here
• Patterns around caching and cache clearing

We'll have more to share on this once we've updated more of our SDKs to use these patterns.

New SDKs

So far, we've landed experimental versions of some of these APIs and updated the Walrus SDK to be usable as a client extension.

This isn't documented yet, and we aren't expecting them to be used yet, but we will be updating more SDKs in the coming weeks.

Our goal is for most of the changes to be fully backwards compatible, but we will need to evaluate our exact approach to migrations on a case by case basis.