Skip to content

Client

Think of the client as a bridge to the Phala Blockchain. It uses the polkadot/api packages for a connection, just like other Substrate-based blockchains. To use the offchain features, you also connect to a unique RPC node, the PRuntime. The purpose of the client is to make these interactions easy.

Use getClient to set up the Client with your chosen options.

Import

import { getClient } from '@phala/sdk'

Usage

const client = await getClient({ transport: 'wss://api.phala.network/ws' })

Parameters

transport

  • Type: string | HttpProvider | WsProvider

Choose a transport method to connect to Phala Blockchain's RPC endpoint. You can use either the endpoint's URL as a string or select an HttpProvider or WsProvider instance.

For the transport string, it should begin with:

  • ws:// or wss:// if you want to use WebSocket to connect to the RPC endpoint, which is easy for general use.
  • http:// or https:// when connecting via HTTP, which is good for fast and simple communication.

Or, choose a WsProvider or HttpProvider from @polkadot/api for better connection control and to reuse connections.

metadata (optional)

  • Type: Record<string, HexString>

A map of 'genesis hash and runtime spec version' as key to metadata hex string. When the genesis hash and runtime spec version matched, if will use the metadata instead fetch it from the chain.

It's useful when you need to speed up the client initialization. See also the fetchMetadata.

noPreloadMetadata (optional)

  • Type: boolean

By default, our client fetches metadata from a fast HTTP endpoint rather than from the blockchain. This approach helps the SDK start up more reliably and quickly.

If you use a HttpProvider or WsProvider instance to create the client, it won't do the preloading step.

When you create a client with the metadata parameter, it will also skip the preloading process.

It is rarely used in practice.

autoConnect (optional)

  • Type: boolean

Choose if the client should connect to the RPC endpoint right after being created. The default setting is true.

clusterId (optional)

  • Type: string

Specify the cluster id for the Cluster you wish to connect to. It typically looks like this: 0x000...0001. Make sure that the PRuntime node and the clusterId match if you set this parameter along with the pruntimeURL.

pruntimeURL (optional)

  • Type: string

Specify the PRuntime node URL you want to use. The pruntimeURL looks like a web address, for example, https://phat-cluster-ca.phala.network/pruntime/0x128d1eec. If you also set the clusterId, make sure it matches the cluster of your selected PRuntime node.

strategy (optional)

  • Type: ack-first | function

Decide how the SDK should locate a PRuntime node if there's no pruntimeURL. The default ack-first strategy connects to the cluster's first registered PRuntime node quickly, suitable for initial trials but not for production. The SDK includes two other strategies, periodicityChecker and fixture, for more advanced needs.

periodicityChecker

This strategy randomly selects a PRuntime node from the Official Healthy PRuntime Worker List. This list is updated every 5 minutes through GitHub actions. You can see the list here.

import { getClient, periodicityChecker } from '@phala/sdk'
 
const client = await getClient({
  transport: 'wss://api.phala.network/ws',
  strategy: periodicityChecker(), 
})

fixture

This approach is great when you choose pruntime node URLs that are best for your area. You can select a list of PRuntime nodes based on where they are located.

import { getClient, fixture } from '@phala/sdk'
 
const preferredNodes: string[] = [/* List of `https://` URLs of to PRuntime nodes */]
const client = await getClient({
  transport: 'wss://api.phala.network/ws',
  strategy: 
function fixture(endpoints: string[]): (_apiPromise: ApiPromise, _clusterId: string) => Promise<readonly [string, string, pruntime_rpc.PhactoryAPI]>
fixture(preferredNodes), 
})

Customized Strategy

Customize the strategy with an async function you create.

@TBD