@parity/product-sdk-chain-client

Exports

Classes

Functions

Interfaces

Type Aliases

Variables

Re-exports

Convenience re-exports from leaf packages. Click through for the canonical documentation.

Classes

class EnvironmentMismatchError

The environment passed to getChainAPI is not the one the host runs.

Extends: Error

Constructors

constructor

new EnvironmentMismatchError(requested: string, hostNetwork: string): EnvironmentMismatchError

Properties

hostNetwork

Network the host reports being configured for.

requested

Environment the caller asked for, e.g. "paseo".

class GenesisMismatchError

A bundled descriptor’s genesis hash disagrees with the host’s answer.

Extends: Error

Constructors

constructor

new GenesisMismatchError(chain: string, descriptorGenesis: string, hostGenesis: string): GenesisMismatchError

Properties

chain

Preset chain key, e.g. "assetHub".

descriptorGenesis

Genesis hash baked into the bundled descriptor.

hostGenesis

Genesis hash the host serves for this chain.

Functions

createChainClient()

Create a multi-chain client with user-provided descriptors. No RPC endpoints are configured: the host resolves each connection from the descriptor’s genesis hash.

Returns fully-typed APIs for each chain plus raw PolkadotClient access via .raw. Connections route through the host provider (@parity/product-sdk-host) — the SDK is designed to run exclusively inside a host container (Polkadot Browser / Desktop). Throws if no host provider is available; there is no direct-WebSocket fallback.

Results are cached by genesis-hash fingerprint — calling with the same descriptors returns the same instance.

createChainClient(config: ChainClientConfig<TChains>): Promise<ChainClient<TChains>>

Examples

import { createChainClient } from "@parity/product-sdk-chain-client";
import { paseo_asset_hub } from "@parity/product-sdk-descriptors/paseo-asset-hub";
import { paseo_bulletin } from "@parity/product-sdk-descriptors/paseo-bulletin";
 
const client = await createChainClient({
    chains: { assetHub: paseo_asset_hub, bulletin: paseo_bulletin },
});
 
// Fully typed from your descriptors
const account = await client.assetHub.query.System.Account.getValue(addr);
const fee = await client.bulletin.query.TransactionStorage.ByteFee.getValue();
 
// Raw client for advanced use (e.g., a ContractRuntime for pallet-revive contracts)
import { createContractRuntimeFromClient } from "@parity/product-sdk-contracts";
const runtime = createContractRuntimeFromClient(client.raw.assetHub, paseo_asset_hub);
 
// Cleanup
client.destroy();

destroyAll()

Destroy all chain client instances and reset internal caches.

Tears down every connection created by createChainClient.

destroyAll(): void

getChainAPI()

Get a chain client for a known environment with built-in descriptors.

This is the zero-config path — no need to import descriptors or specify endpoints. For custom chains or BYOD descriptors, use createChainClient instead.

Returns the same ChainClient type as createChainClient, with assetHub, bulletin, and individuality chain keys.

When called with no argument, the environment is derived from the host via chain discovery. This is the recommended mode inside a container. The zero-arg form is typed with the “paseo” shape, and runtime descriptors always match the host’s actual network. It needs a host that serves discovery: outside a container, or on a host that predates it, the zero-arg form throws and the environment has to be passed explicitly.

An explicit environment that disagrees with the host’s network throws EnvironmentMismatchError. A bundled asset hub descriptor whose genesis hash disagrees with the host throws GenesisMismatchError, since it anchors the environment; a mismatch on bulletin or individuality warns and leaves that one chain throwing on use. Hosts that predate discovery skip validation entirely.

This function has multiple overloads.

Overload 1

getChainAPI(): Promise<ChainClient<{ assetHub: any; bulletin: any; individuality: any }>>

Get a chain client for a known environment with built-in descriptors.

This is the zero-config path — no need to import descriptors or specify endpoints. For custom chains or BYOD descriptors, use createChainClient instead.

Returns the same ChainClient type as createChainClient, with assetHub, bulletin, and individuality chain keys.

When called with no argument, the environment is derived from the host via chain discovery. This is the recommended mode inside a container. The zero-arg form is typed with the “paseo” shape, and runtime descriptors always match the host’s actual network. It needs a host that serves discovery: outside a container, or on a host that predates it, the zero-arg form throws and the environment has to be passed explicitly.

An explicit environment that disagrees with the host’s network throws EnvironmentMismatchError. A bundled asset hub descriptor whose genesis hash disagrees with the host throws GenesisMismatchError, since it anchors the environment; a mismatch on bulletin or individuality warns and leaves that one chain throwing on use. Hosts that predate discovery skip validation entirely.

Examples

Let the host decide, the recommended path inside a container:

import { getChainAPI } from "@parity/product-sdk-chain-client";
 
const client = await getChainAPI();
const account = await client.assetHub.query.System.Account.getValue(addr);
client.destroy();

Pin the environment explicitly:

import { getChainAPI } from "@parity/product-sdk-chain-client";
 
const client = await getChainAPI("paseo");
 
// Fully typed — no descriptor imports needed
const account = await client.assetHub.query.System.Account.getValue(addr);
const fee = await client.bulletin.query.TransactionStorage.ByteFee.getValue();
 
// Raw client for advanced use (e.g., a ContractRuntime for pallet-revive contracts)
import { createContractRuntimeFromClient } from "@parity/product-sdk-contracts";
import { paseo_asset_hub } from "@parity/product-sdk-descriptors/paseo-asset-hub";
const runtime = createContractRuntimeFromClient(client.raw.assetHub, paseo_asset_hub);
 
client.destroy();

Overload 2

getChainAPI(env: E): Promise<ChainClient<PresetChains<E>>>

Get a chain client for a known environment with built-in descriptors.

This is the zero-config path — no need to import descriptors or specify endpoints. For custom chains or BYOD descriptors, use createChainClient instead.

Returns the same ChainClient type as createChainClient, with assetHub, bulletin, and individuality chain keys.

When called with no argument, the environment is derived from the host via chain discovery. This is the recommended mode inside a container. The zero-arg form is typed with the “paseo” shape, and runtime descriptors always match the host’s actual network. It needs a host that serves discovery: outside a container, or on a host that predates it, the zero-arg form throws and the environment has to be passed explicitly.

An explicit environment that disagrees with the host’s network throws EnvironmentMismatchError. A bundled asset hub descriptor whose genesis hash disagrees with the host throws GenesisMismatchError, since it anchors the environment; a mismatch on bulletin or individuality warns and leaves that one chain throwing on use. Hosts that predate discovery skip validation entirely.

Examples

Let the host decide, the recommended path inside a container:

import { getChainAPI } from "@parity/product-sdk-chain-client";
 
const client = await getChainAPI();
const account = await client.assetHub.query.System.Account.getValue(addr);
client.destroy();

Pin the environment explicitly:

import { getChainAPI } from "@parity/product-sdk-chain-client";
 
const client = await getChainAPI("paseo");
 
// Fully typed — no descriptor imports needed
const account = await client.assetHub.query.System.Account.getValue(addr);
const fee = await client.bulletin.query.TransactionStorage.ByteFee.getValue();
 
// Raw client for advanced use (e.g., a ContractRuntime for pallet-revive contracts)
import { createContractRuntimeFromClient } from "@parity/product-sdk-contracts";
import { paseo_asset_hub } from "@parity/product-sdk-descriptors/paseo-asset-hub";
const runtime = createContractRuntimeFromClient(client.raw.assetHub, paseo_asset_hub);
 
client.destroy();

getClient()

Get the raw PolkadotClient for a connected chain by its descriptor.

The chain must have been initialized via createChainClient first. Alternatively, use client.raw.<name> on the returned ChainClient.

getClient(descriptor: ChainDefinition): PolkadotClient

Throws

• If the chain has not been connected yet.

isConnected()

Check if a chain is currently connected.

Synchronous — no side effects, no initialization.

isConnected(descriptor: ChainDefinition): boolean

Interfaces

interface ChainClientConfig

Configuration for createChainClient.

Provide named chain descriptors. The SDK routes all connections through the host provider, so no RPC endpoints are required, and only chains the host routes are reachable.

Examples

import { createChainClient } from "@parity/product-sdk-chain-client";
import { paseo_asset_hub } from "@parity/product-sdk-descriptors/paseo-asset-hub";
import { paseo_bulletin } from "@parity/product-sdk-descriptors/paseo-bulletin";
 
const client = await createChainClient({
    chains: { assetHub: paseo_asset_hub, bulletin: paseo_bulletin },
});

Properties

chains

Named chain descriptors (PAPI ChainDefinition objects).

interface ChainEntry

Internal per-chain state stored in the HMR-safe cache.

Properties

api

client

Type Aliases

type ChainClient

A connected chain client returned by createChainClient.

Each key from your config maps to a fully-typed PAPI TypedApi. Access raw PolkadotClient instances via .raw for advanced use cases like creating a ContractRuntime for pallet-revive contract interactions.

type ChainClient = { [K in string & keyof TChains]: TypedApi<TChains[K]> } & { destroy: () => void; raw: { [K in string & keyof TChains]: PolkadotClient } }

Examples

// Typed API access — fully typed from your descriptors
const account = await client.assetHub.query.System.Account.getValue(addr);
 
// Raw client for advanced use (e.g., a ContractRuntime for pallet-revive contracts)
import { createContractRuntimeFromClient } from "@parity/product-sdk-contracts";
const runtime = createContractRuntimeFromClient(client.raw.assetHub, paseo_asset_hub);

type Environment

Known network environment with built-in descriptors.

• "polkadot" / "kusama" — production networks. Reserved: their Bulletin and Individuality chains are not live yet, so getChainAPI throws for both.
• "paseo" — the Paseo Next v2 deployment
• "previewnet" — a zombienet deployment running a Paseo runtime, kept a step ahead of paseo-next-v2 so products can build against upcoming runtime changes early.
• "devnet" — the public “products devnet” on the Paseo testnet system chains, community-run by the Polkadot Community Foundation.

type Environment = typeof ENVIRONMENTS[number]

type PresetChains

The chain shape returned by getChainAPI for a given environment.

type PresetChains = PresetDescriptors[E]

type WellKnownChainHash

Genesis hash of a well-known chain - the value type of WellKnownChain.

type WellKnownChainHash = typeof WellKnownChain[keyof typeof WellKnownChain]

Variables

WellKnownChain

Genesis hashes of well-known chains.

Mirrors WellKnownChain from @novasamatech/host-api-wrapper. Hand-copied (not re-exported) so chain-client doesn’t pick up a direct Novasama runtime dependency; genesis hashes are immutable so drift is impossible.

let WellKnownChain: { readonly kusamaAssetHub: "0x48239ef607d7928874027a43a67689209727dfb3d3dc5e5b03a39bdc2eda771a"; readonly kusamaRelay: "0xb0a8d493285c2df73290dfb7e61f870f17b41801197a149ca93654499ea3dafe"; readonly polkadotAssetHub: "0x68d56f15f85d3136970ec16946040bc1752654e906147f7e43e9d539d7c3de2f"; readonly polkadotRelay: "0x91b171bb158e2d3848fa23a9f1c25182fb8e20313b2c1eb49219da7a70ce90c3"; readonly rococo: "0x6408de7737c59c238890533af25896a2c20608d8b380bb01029acb392781063e"; readonly westendAssetHub: "0x67f9723393ef76214df0118c34bbbd3dbebc8ed46a10973a8c969d48fe7598c9"; readonly westendRelay: "0xe143f23803ac50e8f6f8e62695d1ce9e4e1d68aa36c1cd2cfd15340213f3423e" } = ...