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://
orwss://
, 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://
orhttps://
, then it will connect to the RPC endpoint will HTTP. It's useful when you only performant communication without state. - The
WsProvider
orHttpProvider
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