Client

The client here is an instance interact with Phala Blockchain. Like other substrate based blockchains, you can accessing Phala Blockchain via polkadot/api packages, but you also need connecting dedicated RPC node (we call it PRuntime node) for the offchain functional. The client here to made interact with the chain and PRuntime node easily.

The getClient function sets up the Client with given configurations.

Import

import { getClient } from '@phala/sdk'

Usage

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

Parameters

transport

• Type: string | HttpProvider | WsProvider

The transport to use to connect to a Phala Blockchain RPC endpoint. It can be a string of the endpoint, or a HttpProvider or WsProvider instance.

If it's string, it must one of follow:

• Prefixed with ws:// or wss://, then it will connect to the RPC endpoint will WebSocket. It's most common way to connect to a RPC endpoint and play around easily.
• Prefixed with http:// or https://, then it will connect to the RPC endpoint will HTTP. It's useful when you only performant communication without state.
• The WsProvider or HttpProvider instance from @polkadot/api. It use to more advanced controls, e.g. connection management and reuse.

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, the client will try to fetch metadata from a performant HTTP endpoint instead fetching from chain, this behavior can give a more stable bootstrap time when you working SDK.

If you create client with a HttpProvider or WsProvider instance, the preload behavior will be skipped.

If you create client with the metadata parameter, the preload behavios will be skipped as well.

It rarely used in practice.

autoConnect (optional)

• Type: boolean

Indicate whether to connect to the RPC endpoint immediately after the client is created.

clusterId (optional)

• Type: string

Indicate the cluster id of the Cluster you want to connect with.

It usaully looks like 0x0000000000000000000000000000000000000000000000000000000000000001.

When you set this parameter with pruntimeURL together, you must ensure the PRuntime node is in the same cluster with clusterId associated with.

pruntimeURL (optional)

• Type: string

Indicate the PRuntime node URL you want to connect with.

The pruntimeURL is a HTTP URL like https://phat-cluster-ca.phala.network/pruntime/0x128d1eec.

When you set this parameter with clusterId together, you must ensure the PRuntime node is in the same cluster with clusterId associated with.

strategy (optional)

• Type: ack-first | function

Specified the PRuntime node lookup strategy when pruntimeURL is not provided.

The default strategy is ack-first, which always connect to the first PRuntime node registered in the cluster. It's easily to get started with, but you should not use it in production.

The SDK provides another two build-in strategies: periodicityChecker and fixture.

periodicityChecker

This strategy will fetch the available PRuntime nodes from the Official Healthy PRuntime Worker List. The list is update by GitHub actions every 5 minutes. You can check it out here.

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

fixture

The strategy is useful when you maintain a list of preferred pruntime node URLs.

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

You can customized the strategy by providing an async function.

@TBD