`@parity/product-sdk`

Unified SDK for building products on the Polkadot ecosystem.


npm install @parity/product-sdk


pnpm add @parity/product-sdk


yarn add @parity/product-sdk


bun add @parity/product-sdk

Exports

Functions

Name	Summary
`calculateCid()`	Create a CID for data with specified codec and hashing algorithm
`createApp()`	Create a new Product SDK app instance

Interfaces

Name	Summary
`Account`	Account information
`App`	The main App instance returned by createApp
`AppConfig`	Configuration for createApp
`ChainApi`	Chain API exposed by the SDK
`CloudStorageApi`	Cloud Storage API exposed by the SDK
`LocalStorageApi`	Storage API exposed by the SDK
`PolkadotClient`	—
`WalletApi`	Wallet API exposed by the SDK

Type Aliases

Name	Summary
`ChainDefinition`	—
`TypedApi`	—

Re-exports

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

Name	Kind	Source package
`ChainClient`	type	`@parity/product-sdk-chain-client`
`CloudStorageClient`	class	`@parity/product-sdk-cloud-storage`
`configure()`	function	`@parity/product-sdk-logger`
`createChainClient()`	function	`@parity/product-sdk-chain-client`
`createLocalKvStore()`	function	`@parity/product-sdk-local-storage`
`createLogger()`	function	`@parity/product-sdk-logger`
`isInsideContainer()`	function	`@parity/product-sdk-host`
`isInsideContainerSync()`	function	`@parity/product-sdk-host`
`LogEntry`	interface	`@parity/product-sdk-logger`
`Logger`	interface	`@parity/product-sdk-logger`
`LoggerConfig`	interface	`@parity/product-sdk-logger`
`LogHandler`	type	`@parity/product-sdk-logger`
`LogLevel`	type	`@parity/product-sdk-logger`
`SignerManager`	class	`@parity/product-sdk-signer`

Functions

`calculateCid()`

Create a CID for data with specified codec and hashing algorithm

Default to raw codec (0x55) with blake2b-256 hash (0xb220)


calculateCid(data: Uint8Array, cidCodec?: number, hashAlgorithm?: HashAlgorithm): Promise<CID<unknown, number, number, Version>>

`createApp()`

Create a new Product SDK app instance


createApp(config: AppConfig): Promise<App>

Parameters

config: Application configuration

Returns

App instance with all APIs

Examples


import { createApp } from '@parity/product-sdk';
 
// Default: cloud storage enabled with paseo environment
const app = await createApp({
  name: 'my-app',
  logLevel: 'info',
});
 
// Custom cloud storage environment
const prodApp = await createApp({
  name: 'my-app',
  cloudStorage: { environment: 'polkadot' },
});
 
// Disable cloud storage entirely
const noCloudStorageApp = await createApp({
  name: 'my-app',
  cloudStorage: false,
});
 
// Connect wallet
const { accounts } = await app.wallet.connect();
 
// Use storage
await app.localStorage.set('key', 'value');
 
// Use cloud storage (check for null if it might be disabled)
if (app.cloudStorage) {
  const cid = await app.cloudStorage.upload('hello world');
}

Interfaces

`interface Account`

Account information

Properties

`address`

propertystring

Account address (SS58 format)

`name`

propertyoptionalstring

Account name/label (if available)

`source`

propertystring

Source of the account (host, dev signer, etc.)

`interface App`

The main App instance returned by createApp

Properties

`chain`

propertyChainApi

Chain interaction operations

`cloudStorage`

propertyCloudStorageApi | null

Cloud Storage operations (null if disabled via config)

`localStorage`

propertyLocalStorageApi

Local Key-value storage operations

`wallet`

propertyWalletApi

Wallet/signing operations

Methods

`getAppInfo`

Get app configuration


getAppInfo(): AppConfig

`interface AppConfig`

Configuration for createApp

Properties

`cloudStorage`

propertyoptionalfalse | CloudStorageConfig

Cloud Storage configuration.

Omit or pass config object to enable (default: { environment: “paseo” })
Pass false to disable cloud storage initialization

`logLevel`

propertyoptionalLogLevel

Log level for SDK operations (default: ‘info’)

`name`

propertystring

Application name - used to derive product accounts and namespace storage

`interface ChainApi`

Chain API exposed by the SDK

Methods

`connect`

Connect to one or more chains.

Connections are routed through the host provider (container-only). Results are cached - calling with the same descriptors returns existing connections.


connect(chains: T): Promise<ChainClient<T>>

Parameters

chains: Record of named chain descriptors

Returns

Connected chain client with typed APIs

`destroyAll`

Destroy all chain connections.


destroyAll(): void

`getClient`

Get a typed PAPI client for a chain.

Connections are routed through the host provider. The chain must be connected first via connect.


getClient(descriptor: T): TypedApi<T>

Parameters

descriptor: PAPI chain descriptor (from @parity/product-sdk-descriptors or custom)

Returns

Typed API for the chain

Throws

If the chain is not connected

`getRawClient`

Get the raw PolkadotClient for a chain.

Use this for advanced APIs like createContractRuntime from @parity/product-sdk-contracts.


getRawClient(descriptor: ChainDefinition): PolkadotClient

Parameters

descriptor: PAPI chain descriptor

Returns

Raw PolkadotClient instance

Throws

If the chain is not connected

`isConnected`

Check if a chain is currently connected.


isConnected(descriptor: ChainDefinition): boolean

`interface CloudStorageApi`

Cloud Storage API exposed by the SDK

Methods

`computeCid`

Compute the CID for data without uploading.

Async because the underlying hash is computed via Web Crypto.


computeCid(data: string | Uint8Array<ArrayBufferLike>): Promise<string>

`fetch`

Fetch data by CID.


fetch(cid: string): Promise<Uint8Array<ArrayBufferLike>>

`upload`

Upload data to the Cloud.

Requires a wallet to be connected and an account selected. Throws “No signer available …” otherwise.


upload(data: string | Uint8Array<ArrayBufferLike>): Promise<string>

`interface LocalStorageApi`

Storage API exposed by the SDK

Methods

`clear`

Clear all values


clear(): Promise<void>

`get`

Get a value by key


get(key: string): Promise<string | null>

`getJSON`

Get a JSON value by key


getJSON(key: string): Promise<T | null>

`remove`

Remove a value by key


remove(key: string): Promise<void>

`set`

Set a value by key


set(key: string, value: string): Promise<void>

`setJSON`

Set a JSON value by key


setJSON(key: string, value: T): Promise<void>

`interface PolkadotClient`

Properties

`_request`

property(method: string, params: Params) => Promise<Reply>

This API is meant as an “escape hatch” to allow access to debug endpoints such as system_version, and other useful endpoints that are not spec compliant.

`_subscribe`

property(method: string, unsubscribeMethod: string, params: Params) => Observable<Reply>

This API is meant as an “escape hatch” to allow access to subscription endpoints

Unstable: The stability of this API is not guaranteed across minor versions.

`bestBlocks$`

propertyObservable<BlockInfo[]>

Observable that emits an Array of BlockInfo, being the first element the latest known best block, and the last element the latest known finalized block. It’s a multicast and stateful observable, that will synchronously replay its latest known state. This array is an immutable data structure; i.e. a new array is emitted at every event but the reference to its children are stable if the children didn’t change.

Note that some blocks might not get reported, e.g. if they become finalized immediately without being part of the best block chain.

`blocks$`

propertyObservable<BlockInfo>

Observable of new blocks that have been discovered by the client. There is the strong guarantee that for every block emitted its parent has been emitted already in the subscription (except the first block). After subscription, the latest finalized block and all of its known descendants will be emitted synchronously. The Observable will complete if the continuity of the blocks cannot be guaranteed.

`destroy`

property() => void

This will unfollow the provider, disconnect and error every subscription. After calling it nothing can be done with the client.

`finalizedBlock$`

propertyObservable<BlockInfo>

Observable that emits BlockInfo for every new finalized block. It’s a multicast and stateful observable, that will synchronously replay its latest known state.

`getBestBlocks`

property() => Promise<BlockInfo[]>

`getBlockBody`

property(hash: HexString, signal?: AbortSignal) => Promise<Uint8Array<ArrayBufferLike>[]>

Get Block Body (Promise-based)

`getBlockBody$`

property(hash: HexString) => Observable<Uint8Array<ArrayBufferLike>[]>

Get Block Body (Observable-based)

`getBlockHeader`

property

(hash: HexString, signal?: AbortSignal) => Promise<{ digests: Enum<{ consensus: { engine: string; payload: HexString }; other: Uint8Array<ArrayBufferLike>; preRuntime: { engine: string; payload: HexString }; runtimeUpdated: undefined; seal: { engine: string; payload: HexString } }>[]; extrinsicRoot: HexString; number: number; parentHash: HexString; stateRoot: HexString }>

Get Block Header (Promise-based)

`getBlockHeader$`

property

(hash: HexString) => Observable<{ digests: Enum<{ consensus: { engine: string; payload: HexString }; other: Uint8Array<ArrayBufferLike>; preRuntime: { engine: string; payload: HexString }; runtimeUpdated: undefined; seal: { engine: string; payload: HexString } }>[]; extrinsicRoot: HexString; number: number; parentHash: HexString; stateRoot: HexString }>

Get Block Header (Observable-based)

`getChainSpecData`

property() => Promise<ChainSpecData>

Retrieve the ChainSpecData as it comes from the JSON-RPC spec

`getFinalizedBlock`

property() => Promise<BlockInfo>

`getMetadata`

property(hash: HexString, signal?: AbortSignal) => Promise<Uint8Array<ArrayBufferLike>>

Retrieves the most modern stable version of the metadata for a given block.

`getMetadata$`

property(hash: HexString) => Observable<Uint8Array<ArrayBufferLike>>

Retrieves the most modern stable version of the metadata for a given block.

`getTypedApi`

property(descriptors: D) => TypedApi<D>

Returns an instance of a TypedApi.

`getUnsafeApi`

property() => TypedApi<D, false>

Returns an instance of a UnsafeApi.

Note that this method is only meant for advanced users that really know what are they doing. This API does not provide any runtime compatibility checks protection and the consumer should implement them on their own.

`hodlBlock`

property(blockHash: HexString) => () => void

Ensures that a block stays available, even after it has been finalized and no operations are running for that block.

`rawQuery`

property

(storageKey: string | HexString, options?: Partial<{ at: "best" | "finalized" | object & string; signal: AbortSignal }>) => Promise<HexString | null>

Returns a Promise that resolves into the encoded value of a storage entry or null if the key doesn’t have a corresponding value.

`submit`

property(transaction: Uint8Array, at?: HexString) => Promise<TxFinalizedPayload>

Broadcasts a transaction (Promise-based). The promise will resolve when the transaction is found in a finalized block; and will reject if the transaction is invalid and can’t be broadcasted, or if it is deemed invalid later on.

`submitAndWatch`

property(transaction: Uint8Array, at?: HexString) => Observable<TxBroadcastEvent>

Broadcasts a transaction and returns an Observable. The observable will complete as soon as the transaction is in a finalized block. See https://papi.how/typed/tx#signsubmitandwatch to learn about all possible events.

`interface WalletApi`

Wallet API exposed by the SDK

Methods

`connect`

Connect to available wallet providers


connect(): Promise<{ accounts: Account[] }>

`createProof`

Create Ring VRF proof (container mode only)


createProof(message: Uint8Array): Promise<Uint8Array<ArrayBufferLike>>

`disconnect`

Disconnect from wallet


disconnect(): Promise<void>

`getAccounts`

Get all available accounts


getAccounts(): Account[]

`getAnonymousAlias`

Get anonymous alias via Ring VRF (container mode only)


getAnonymousAlias(): string | null

`getProductAccount`

Get product-scoped account (container mode only)


getProductAccount(): Account | null

`getSelectedAccount`

Get currently selected account


getSelectedAccount(): Account | null

`onAccountChange`

Subscribe to account changes


onAccountChange(callback: (account: Account | null) => void): () => void

`selectAccount`

Select an account by address


selectAccount(address: string): void

`signMessage`

Sign an arbitrary message


signMessage(message: string | Uint8Array<ArrayBufferLike>): Promise<Uint8Array<ArrayBufferLike>>

Type Aliases

`type ChainDefinition`


type ChainDefinition = unknown

`type TypedApi`


type TypedApi = unknown