@parity/product-sdk-terminal

Exports

Classes

Functions

Interfaces

Type Aliases

Variables

Re-exports

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

Classes

class AllowanceError

Extends: Error

Constructors

constructor

new AllowanceError(reason: AllowanceErrorReason, message?: string): AllowanceError

Properties

reason

Functions

createNodeStorageAdapter()

Create a file-based StorageAdapter for use with the host-papp SDK in Node.js.

Data is stored as individual JSON files in the given directory (defaults to ~/.polkadot-apps/).

createNodeStorageAdapter(appId: string, storageDir?: string): StorageAdapter

createSessionSigner()

Create a PolkadotSigner backed by a QR-paired mobile wallet session, using the session’s default account (derivationIndex: 0).

For non-default sub-accounts, use createSessionSignerForAccount.

createSessionSigner(session: UserSession, adapter: TerminalAdapter, publicKey?: Uint8Array<ArrayBufferLike>): PolkadotSigner

Parameters

• session: The paired user session.
• adapter: The TerminalAdapter that loaded the session. Its appId is used as the productId in the wire request.
• publicKey: The product account’s sr25519 public key for [adapter.appId, 0]. Optional — when omitted it’s soft-derived from the session root. See ProductAccountRef.publicKey.

createSessionSignerForAccount()

Create a PolkadotSigner for a specific sub-account of a paired session.

Use this when you need a derivation index other than 0, or a productId different from the adapter’s appId. For the common default-account case, prefer createSessionSigner.

createSessionSignerForAccount(session: UserSession, ref: ProductAccountRef): PolkadotSigner

Parameters

• session: The paired user session.
• ref: The product account to sign as: \{ productId, derivationIndex \}.

createTerminalAdapter()

createTerminalAdapter(options: TerminalAdapterOptions): TerminalAdapter

deriveProductPublicKey()

Soft-derive a product account’s sr25519 public key from a paired session’s root account.

This is the single source of truth for product-account math. The session signer uses it to stamp the correct signer address; consumers that need the product address without building a signer (e.g. a login-status display triple) call it directly so the displayed address can’t desync from what the signer actually signs with.

sr25519 soft derivation is composable on public keys alone, so deriving from session.rootAccountId locally produces the SAME key the host derives privately via mnemonic + "/product/{productId}/{derivationIndex}".

deriveProductPublicKey(session: UserSession, ref: ProductAccountRef): Uint8Array

Throws

• INCOMPLETE_SESSION_MESSAGE on a stale session with no root key.

getBulletinSigner()

Get a PolkadotSigner for a Bulletin allowance slot.

Allocates an allowance slot via the paired wallet (or returns the cached one), derives the slot-account keypair, and returns a PolkadotSigner that signs Bulletin extrinsics with it. Replaces the manual requestResourceAllocation + createSlotAccountSigner two-step for the common case.

getBulletinSigner(adapter: TerminalAdapter, productId: string, sessionId?: string): Promise<PolkadotSigner>

Parameters

• adapter: Terminal adapter.
• productId: The product id the slot is allocated under. Passed to the host as the calling product id in the allowance request.
• sessionId: Paired session to allocate against. Defaults to the only paired session; throws AllowanceError('NoSession') when zero or more than one sessions are paired and no explicit id is supplied.

Throws

• On rejection, missing session, host-side failure, or unexpected response shape.

Examples

import { createTerminalAdapter, getBulletinSigner } from "@parity/product-sdk-terminal";
 
const adapter = createTerminalAdapter({ appId: "my-cli" });
// ... QR pair, wait for session ...
const signer = await getBulletinSigner(adapter, "my-cli.dot");
await client.bulletin.tx.TransactionStorage.store({ data }).signAndSubmit(signer);

getStatementStoreProver()

Get a StatementProver for a statement-store allowance slot.

Allocates an allowance slot via the paired wallet (or returns the cached one) and returns the upstream StatementProver for the slot. Use when publishing statements through @novasamatech/statement-store without holding a long-lived key yourself.

getStatementStoreProver(adapter: TerminalAdapter, productId: string, sessionId?: string): Promise<StatementProver>

Parameters

• adapter: Terminal adapter.
• productId: The product id the slot is allocated under.
• sessionId: Paired session to allocate against. Defaults to the only paired session; throws AllowanceError('NoSession') when zero or more than one sessions are paired and no explicit id is supplied.

Throws

• On rejection, missing session, host-side failure, or unexpected response shape.

hasBulletinAllowance()

Cache-only probe for a Bulletin allowance slot. Resolves true when a slot key for (sessionId, productId, bulletin) is already cached on disk; false when it is not. Never prompts the paired wallet.

Pair with getBulletinSigner for the “check first, fetch only if needed” flow:

hasBulletinAllowance(adapter: TerminalAdapter, productId: string, sessionId?: string): Promise<boolean>

Examples

if (await hasBulletinAllowance(adapter, "my-cli.dot")) {
    // happy path — fetch the signer without risking a wallet prompt
    const signer = await getBulletinSigner(adapter, "my-cli.dot");
} else {
    // tell the user a wallet prompt will fire, then call getBulletinSigner
}

hasStatementStoreAllowance()

Cache-only probe for a Statement Store allowance slot. Resolves true when a slot key for (sessionId, productId, statementStore) is already cached on disk; false when it is not. Never prompts the paired wallet.

Pair with getStatementStoreProver for the “check first, fetch only if needed” flow.

hasStatementStoreAllowance(adapter: TerminalAdapter, productId: string, sessionId?: string): Promise<boolean>

renderQrCode()

Encode a string as a QR code rendered in Unicode half-block characters.

Returns a multi-line string suitable for console.log.

renderQrCode(data: string, options?: QrRenderOptions): Promise<string>

requestResourceAllocation()

Send the AP request_resource_allocation message over the paired session; block on the user’s mobile dialog; return outcomes in request order. Granted key material is cached on disk so subsequent calls skip the wallet prompt.

requestResourceAllocation(session: UserSession, adapter: TerminalAdapter, resources: { tag: "StatementStoreAllowance"; value: undefined } | { tag: "SmartContractAllowance"; value: number } | { tag: "AutoSigning"; value: undefined } | { tag: "BulletInAllowance"; value: undefined }[], options: RequestResourceAllocationOptions = {}): Promise<{ tag: "Rejected"; value: undefined } | { tag: "Allocated"; value: { tag: "StatementStoreAllowance"; value: { slotAccountKey: Uint8Array<ArrayBufferLike> } } | { tag: "SmartContractAllowance"; value: undefined } | { tag: "AutoSigning"; value: { productDerivationSecret: string; productRootPrivateKey: Uint8Array<ArrayBufferLike> } } | { tag: "BulletInAllowance"; value: { slotAccountKey: Uint8Array<ArrayBufferLike> } } } | { tag: "NotAvailable"; value: undefined }[]>

Throws

• If the session call fails (transport, timeout, AH protocol error).

Examples

const [session] = adapter.sessions.sessions.read();
const outcomes = await requestResourceAllocation(session, adapter, [
  { tag: "BulletInAllowance", value: undefined },
]);

sendResourceAllocation()

Send an AP request_resource_allocation message over the paired session and return the outcomes in request order. This is the raw wire call: no disk cache, no onExisting auto-pick, no adapter. Callers that want the caching / slot-reuse behaviour should use requestResourceAllocation instead; this primitive exists for consumers (e.g. @parity/product-sdk-auth) that only hold a productId and manage their own policy.

sendResourceAllocation(session: UserSession, productId: string, resources: { tag: "StatementStoreAllowance"; value: undefined } | { tag: "SmartContractAllowance"; value: number } | { tag: "AutoSigning"; value: undefined } | { tag: "BulletInAllowance"; value: undefined }[], onExisting: "Ignore" | "Increase"): Promise<{ tag: "Rejected"; value: undefined } | { tag: "Allocated"; value: { tag: "StatementStoreAllowance"; value: { slotAccountKey: Uint8Array<ArrayBufferLike> } } | { tag: "SmartContractAllowance"; value: undefined } | { tag: "AutoSigning"; value: { productDerivationSecret: string; productRootPrivateKey: Uint8Array<ArrayBufferLike> } } | { tag: "BulletInAllowance"; value: { slotAccountKey: Uint8Array<ArrayBufferLike> } } } | { tag: "NotAvailable"; value: undefined }[]>

Throws

• If the session call fails (transport, timeout, AH protocol error).

sessionRootPublicKey()

The session’s handshake-time root account public key (rootUserAccountId = the user’s bare-mnemonic keypair on current mobile builds). This is the parent key product accounts soft-derive from. host-papp’s live UserSession doesn’t surface it on the public type, so we read it structurally.

sessionRootPublicKey(session: UserSession): Uint8Array

Throws

• INCOMPLETE_SESSION_MESSAGE if the session predates the rootAccountId field (a stale login that must re-pair).

waitForSessions()

Wait for the adapter to load at least one persisted session, or resolve with an empty array after timeoutMs.

The session manager loads sessions from storage asynchronously, so a synchronous adapter.sessions.sessions.read() immediately after createTerminalAdapter() may return [] even when sessions exist on disk. Use this helper to give the loader a chance to populate before deciding whether the user is logged in.

waitForSessions(adapter: TerminalAdapter, timeoutMs: number = 3000): Promise<UserSession[]>

Interfaces

interface ProductAccountRef

Identifies which sub-account of a paired session should sign.

Mirrors the host-papp wire format productAccountId: [productId, derivationIndex]: productId is the dotNS-style identifier for the requesting product (matches the adapter’s appId in normal usage); derivationIndex is the BIP32-style child-key index, where 0 is the session’s default account.

Properties

derivationIndex

Child-key derivation index. 0 is the default account.

productId

The product identifier. Usually equal to the adapter’s appId.

publicKey

The product account’s sr25519 public key (32 bytes), as derived by the host for [productId, derivationIndex].

PAPI stamps this into the extrinsic’s signer address and verifies the signature against it, so it must be the product account’s key — not the wallet’s selected/root account (session.remoteAccount.accountId). A mismatch produces an invalid signature.

When omitted, the signer soft-derives it from the session’s root account (mnemonic + "/product/{productId}/{derivationIndex}"), which is correct for every product account. Supply it explicitly only to avoid the re-derivation or when you’ve already derived it elsewhere.

interface QrRenderOptions

Options for QR code rendering.

Properties

errorCorrectionLevel

Error correction level. Default: “M”.

margin

Quiet zone size in modules. Default: 2.

interface RequestResourceAllocationOptions

Properties

onExisting

Override the auto-picked onExisting. Default: Ignore unless every requested resource is a cached slot-table variant, then Increase.

productId

Product id the allocation is scoped to. Sent on the wire as callingProductId and used as the slot-cache namespace. Defaults to adapter.appId.

Pass this when the product id the app signs as differs from the terminal’s storage appId — the wallet derives every per-product artifact (including the on-chain account PGAS is minted to and auto-mapped for) from this id, so allocating under the wrong id lands the allowance on the wrong account. Mirrors the explicit productId that getBulletinSigner already takes.

interface TerminalAdapterOptions

Options for creating a terminal adapter.

Properties

appId

Unique app identifier. Used as the storage namespace.

endpoints

Statement store WebSocket endpoints. Defaults to Paseo stable endpoints.

hostMetadata

Optional host metadata for the Sign-In screen.

storageDir

Directory where session files are persisted. Defaults to ~/.polkadot-apps/. Override in tests to point at a temporary directory populated with createTestSession from @parity/product-sdk-terminal/testing.

Type Aliases

type AllocatableResource

One resource a Host can request from the Account Holder. AutoSigning currently returns NotAvailable on both Android and iOS wallets.

type AllocatableResource = ResourceAllocationRequest["resources"][number]

type AllowanceErrorReason

type AllowanceErrorReason = "NoSession" | "Rejected" | "NotAvailable" | "UnexpectedResponse"

type AllowanceService

type AllowanceService = unknown

type ApAllocationOutcome

Per-resource outcome. Allocated.value carries the materialized payload (slot account key for Bulletin/SSS; subtree key + secret for AutoSigning; undefined for SC). Each entry is independent — no rollback on partial success.

type ApAllocationOutcome = ExtractOk<ReturnType<UserSession["requestResourceAllocation"]>>[number]

type HostMetadata

type HostMetadata = HandshakeMetadata

type OnExistingAllowancePolicy

"Ignore": return existing keys if any, else allocate one slot. "Increase": add one slot to an existing allowance account.

type OnExistingAllowancePolicy = ResourceAllocationRequest["onExisting"]

type PairingStatus

type PairingStatus = { step: "none" } | { step: "initial" } | { payload: string; step: "pairing" } | { stage: string; step: "pending" } | { message: string; step: "pairingError" } | { session: StoredUserSession; step: "finished" }

type PappAdapter

type PappAdapter = unknown

type SigningPayloadRequest

type SigningPayloadRequest = CodecType<typeof SigningPayloadRequestCodec>

type SigningPayloadResponse

type SigningPayloadResponse = CodecType<typeof SigningResponseCodec>

type SigningRawRequest

type SigningRawRequest = CodecType<typeof SigningRawRequestCodec>

type StoredUserSession

type StoredUserSession = CodecType<typeof storedUserSessionCodec>

type TerminalAdapter

A PappAdapter with the appId it was created with and a destroy method for cleanup.

type TerminalAdapter = PappAdapter & { readonly appId: string; readonly storageDir?: string; destroy: unknown }

type UserSession

type UserSession = StoredUserSession & { abortPendingRequests: unknown; createTransaction: unknown; createTransactionLegacy: unknown; dispose: unknown; getRingVrfAlias: unknown; requestResourceAllocation: unknown; sendDisconnectMessage: unknown; signPayload: unknown; signRaw: unknown; signRawLegacy: unknown; subscribe: unknown }

Variables

INCOMPLETE_SESSION_MESSAGE

let INCOMPLETE_SESSION_MESSAGE: "Stored login session is missing the root account public key. Run \"logout\" and then \"login\" to pair again." = 'Stored login session is missing the root account public key. Run "logout" and then "login" to pair again.'

SS_PASEO_STABLE_STAGE_ENDPOINTS

let SS_PASEO_STABLE_STAGE_ENDPOINTS: string[]

SS_STABLE_STAGE_ENDPOINTS

let SS_STABLE_STAGE_ENDPOINTS: string[]