@parity/product-sdk-terminal 0.0.0-dev.312.0 → 0.0.0-dev.421.0

package/dist/index.d.ts

@@ -1,13 +1,50 @@
-import { T as TerminalAdapter } from './host-C3KVvc1j.js';
-export { A as AllocatableResource, a as ApAllocationOutcome, O as OnExistingAllowancePolicy, R as RequestResourceAllocationOptions, b as TerminalAdapterOptions, c as createTerminalAdapter, r as requestResourceAllocation, s as sendResourceAllocation } from './host-C3KVvc1j.js';
+import { T as TerminalAdapter } from './host-_G9M0isV.js';
+export { A as AllocatableResource, a as ApAllocationOutcome, O as OnExistingAllowancePolicy, R as RequestResourceAllocationOptions, b as TerminalAdapterOptions, c as createTerminalAdapter, i as isBenignTeardownError, r as requestResourceAllocation, s as sendResourceAllocation } from './host-_G9M0isV.js';
 import { UserSession } from '@novasamatech/host-papp';
-export { AllowanceError, AllowanceErrorReason, AllowanceService, HostMetadata, PairingStatus, PappAdapter, SS_PASEO_STABLE_STAGE_ENDPOINTS, SS_STABLE_STAGE_ENDPOINTS, SigningPayloadRequest, SigningPayloadResponse, SigningRawRequest, StoredUserSession, UserSession } from '@novasamatech/host-papp';
+export { AllowanceError, AllowanceErrorReason, AllowanceService, HostMetadata, PairingStatus, PappAdapter, SS_STABLE_STAGE_ENDPOINTS, SigningPayloadRequest, SigningPayloadResponse, SigningRawRequest, StoredUserSession, UserSession } from '@novasamatech/host-papp';
 import { PolkadotSigner } from 'polkadot-api';
 export { AllowanceExpiredError, SignerError } from '@parity/product-sdk-signer/errors';
 import { StatementProver } from '@novasamatech/statement-store';
 import { StorageAdapter } from '@novasamatech/storage-adapter';
 import 'neverthrow';
 
+/**
+ * Statement store networks terminal can pair against, keyed as `BULLETIN_RPCS`
+ * in `@parity/product-sdk-host`, where `paseo` is Paseo Next v2.
+ *
+ * Both sides of a pairing must sit on the same people chain. The Polkadot app's
+ * nightly build uses `paseo`, which is why it is the default.
+ */
+
+declare const StatementStoreNetworks: {
+    paseo: string[];
+    previewnet: string[];
+};
+
+/** Network keys with built-in endpoints in {@link StatementStoreNetworks}. */
+type StatementStoreEnvironment = keyof typeof StatementStoreNetworks;
+
+/**
+ * The product-subtree public key of `//product//{productId}` (RFC-0022).
+ *
+ * The request is consent-free and cacheable. The disk layer is what makes that
+ * worth having: without it every CLI command would need the phone reachable
+ * just to render a product address.
+ */
+
+interface ProductSubtreeOptions {
+    /** Names the cache file. Defaults to the productId. */
+    appId?: string;
+    storageDir?: string;
+}
+/**
+ * Fetch the subtree public key for `productId`, reaching the wallet only on a
+ * cold cache.
+ *
+ * @throws Error when the wallet rejects the request or returns a malformed key.
+ */
+declare function getProductSubtreePublicKey(session: UserSession, productId: string, options?: ProductSubtreeOptions): Promise<Uint8Array>;
+
 /**
  * Create a PolkadotSigner from a QR-paired session.
  *
@@ -37,10 +74,10 @@ import 'neverthrow';
  * const [session] = adapter.sessions.sessions.read();
  *
  * // Default account — uses [adapter.appId, 0]:
- * const signer = createSessionSigner(session, adapter);
+ * const signer = await createSessionSigner(session, adapter);
  *
  * // Non-default derivation index, or a different productId:
- * const subSigner = createSessionSignerForAccount(session, {
+ * const subSigner = await createSessionSignerForAccount(session, {
  *     productId: "my-product",
  *     derivationIndex: 3,
  * });
@@ -52,7 +89,7 @@ import 'neverthrow';
 /**
  * Identifies which sub-account of a paired session should sign.
  *
- * Mirrors the `host-papp` wire format `productAccountId: [productId, derivationIndex]`:
+ * Mirrors the `host-papp` wire format `productAccountId: [productId, index]`:
  * `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.
@@ -66,46 +103,36 @@ interface ProductAccountRef {
      * 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.
+     * PAPI stamps this into the extrinsic's signer address and verifies against
+     * it, so 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.
+     * When omitted, the signer fetches the subtree key and derives it. Supply it
+     * to skip that round trip.
      */
     publicKey?: Uint8Array;
 }
+interface SessionSignerOptions extends ProductSubtreeOptions {
+    /** Extension version of the supplied signTx bytes. Defaults to 0; does not change encoding. */
+    txExtVersion?: number;
+}
 declare const INCOMPLETE_SESSION_MESSAGE = "Stored login session is missing the root account public key. Run \"logout\" and then \"login\" to pair again.";
 /**
- * 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.
+ * The wallet's own root account key. Product accounts do **not** derive from it:
+ * RFC-0022 puts two hard junctions in between.
  *
  * @throws {@link INCOMPLETE_SESSION_MESSAGE} if the session predates the
- *   `rootAccountId` field (a stale login that must re-pair).
+ *   `rootAccountId` field.
  */
 declare function sessionRootPublicKey(session: UserSession): Uint8Array;
 /**
- * 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.
+ * The product account's sr25519 public key for `ref`.
  *
- * 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}"`.
+ * The one place product-account math happens, so a displayed address cannot
+ * desync from what the signer signs with.
  *
- * @throws {@link INCOMPLETE_SESSION_MESSAGE} on a stale session with no root key.
+ * @throws Error when the wallet is unreachable on a cold cache.
  */
-declare function deriveProductPublicKey(session: UserSession, ref: ProductAccountRef): Uint8Array;
+declare function deriveProductPublicKey(session: UserSession, ref: ProductAccountRef, options?: ProductSubtreeOptions): Promise<Uint8Array>;
 /**
  * Create a `PolkadotSigner` backed by a QR-paired mobile wallet session,
  * using the session's **default account** (`derivationIndex: 0`).
@@ -116,10 +143,10 @@ declare function deriveProductPublicKey(session: UserSession, ref: ProductAccoun
  * @param adapter The {@link TerminalAdapter} that loaded the session. Its `appId`
  *   is used as the `productId` in the wire request.
  * @param publicKey The product account's sr25519 public key for
- *   `[adapter.appId, 0]`. Optional — when omitted it's soft-derived from the
- *   session root. See {@link ProductAccountRef.publicKey}.
+ *   `[adapter.appId, 0]`. Optional — when omitted it's fetched and derived.
+ *   See {@link ProductAccountRef.publicKey}.
  */
-declare function createSessionSigner(session: UserSession, adapter: TerminalAdapter, publicKey?: Uint8Array): PolkadotSigner;
+declare function createSessionSigner(session: UserSession, adapter: TerminalAdapter, publicKey?: Uint8Array, options?: SessionSignerOptions): Promise<PolkadotSigner>;
 /**
  * Create a `PolkadotSigner` for a specific sub-account of a paired session.
  *
@@ -130,7 +157,7 @@ declare function createSessionSigner(session: UserSession, adapter: TerminalAdap
  * @param session The paired user session.
  * @param ref The product account to sign as: `{ productId, derivationIndex }`.
  */
-declare function createSessionSignerForAccount(session: UserSession, ref: ProductAccountRef): PolkadotSigner;
+declare function createSessionSignerForAccount(session: UserSession, ref: ProductAccountRef, options?: SessionSignerOptions): Promise<PolkadotSigner>;
 
 /**
  * Get a `PolkadotSigner` for a Bulletin allowance slot.
@@ -259,4 +286,4 @@ declare function renderQrCode(data: string, options?: QrRenderOptions): Promise<
  */
 declare function createNodeStorageAdapter(appId: string, storageDir?: string): StorageAdapter;
 
-export { INCOMPLETE_SESSION_MESSAGE, type ProductAccountRef, type QrRenderOptions, TerminalAdapter, createNodeStorageAdapter, createSessionSigner, createSessionSignerForAccount, deriveProductPublicKey, getBulletinSigner, getStatementStoreProver, hasBulletinAllowance, hasStatementStoreAllowance, renderQrCode, sessionRootPublicKey, waitForSessions };
+export { INCOMPLETE_SESSION_MESSAGE, type ProductAccountRef, type ProductSubtreeOptions, type QrRenderOptions, type SessionSignerOptions, type StatementStoreEnvironment, StatementStoreNetworks, TerminalAdapter, createNodeStorageAdapter, createSessionSigner, createSessionSignerForAccount, deriveProductPublicKey, getBulletinSigner, getProductSubtreePublicKey, getStatementStoreProver, hasBulletinAllowance, hasStatementStoreAllowance, renderQrCode, sessionRootPublicKey, waitForSessions };