@parity/product-sdk-host 0.17.0 → 0.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parity/product-sdk-host",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Host container detection and storage access for Polkadot Desktop and Mobile environments",
   "type": "module",
   "sideEffects": false,
@@ -27,9 +27,9 @@
     "@polkadot-api/substrate-bindings": "^0.20.3",
     "neverthrow": "^8.2.0",
     "polkadot-api": "^2.1.6",
-    "@parity/product-sdk-logger": "0.1.1",
+    "@parity/product-sdk-errors": "0.2.0",
     "@parity/result": "0.2.0",
-    "@parity/product-sdk-errors": "0.2.0"
+    "@parity/product-sdk-logger": "0.1.1"
   },
   "devDependencies": {
     "tsup": "^8.5.1",

package/src/accounts.ts

@@ -23,7 +23,7 @@
  */
 
 import { decAnyMetadata, unifyMetadata } from "@polkadot-api/substrate-bindings";
-import type { ResultAsync } from "neverthrow";
+import { errAsync, okAsync, ResultAsync } from "neverthrow";
 import { AccountId, type PolkadotSigner } from "polkadot-api";
 
 import type {
@@ -55,6 +55,7 @@ import type {
 } from "@parity/truapi";
 
 import { getClient, subscribeWithInterrupt } from "./transport.js";
+import { HostResponseDecodeError } from "./errors.js";
 import { fromHex, toHex, unwrapHostResult } from "./truapi.js";
 import type { HostSubscription } from "./types.js";
 
@@ -223,6 +224,14 @@ export type VrfTranscriptItem = { [K in keyof WireVrfTranscriptItem]: Uint8Array
  */
 export type VrfSignature = { [K in keyof WireVrfSignature]: Uint8Array };
 
+/**
+ * A call's declared `Err` channel, plus {@link HostResponseDecodeError}: any
+ * host reply can fail to decode if the host and the product's `@parity/truapi`
+ * client are on different protocol versions, so every decoded call can surface
+ * it in addition to its own typed errors.
+ */
+export type WithDecodeError<E> = E | HostResponseDecodeError;
+
 /**
  * Accounts provider handle, backed by `truApi.account.*` / `truApi.signing.*`.
  * Surfaces the user's wallet accounts, app-scoped product accounts, Ring VRF,
@@ -231,20 +240,29 @@ export type VrfSignature = { [K in keyof WireVrfSignature]: Uint8Array };
  * Lookup methods return a neverthrow `ResultAsync` (use `.match(ok, err)`);
  * the signer factories return a synchronous PAPI `PolkadotSigner`. The `err`
  * channel carries truapi's canonical `CallErrorValue` envelope around the
- * per-call versioned domain error, exactly as the generated client returns it.
+ * per-call versioned domain error, exactly as the generated client returns it,
+ * plus a {@link HostResponseDecodeError} for the case where the host's reply
+ * cannot be decoded at all (a host/client protocol-version skew) — see
+ * {@link WithDecodeError}.
  */
 export interface AccountsProvider {
     getUserId(): ResultAsync<
         { primaryUsername: string },
-        scale.CallErrorValue<VersionedHostGetUserIdError>
+        WithDecodeError<scale.CallErrorValue<VersionedHostGetUserIdError>>
     >;
     requestLogin(
         reason?: string,
-    ): ResultAsync<HostRequestLoginResponse, scale.CallErrorValue<VersionedHostRequestLoginError>>;
+    ): ResultAsync<
+        HostRequestLoginResponse,
+        WithDecodeError<scale.CallErrorValue<VersionedHostRequestLoginError>>
+    >;
     getProductAccount(
         dotNsIdentifier: string,
         derivationIndex?: number,
-    ): ResultAsync<ProductAccount, scale.CallErrorValue<VersionedHostAccountGetError>>;
+    ): ResultAsync<
+        ProductAccount,
+        WithDecodeError<scale.CallErrorValue<VersionedHostAccountGetError>>
+    >;
     /**
      * Register a ring-VRF key owned by the calling product.
      *
@@ -259,7 +277,7 @@ export interface AccountsProvider {
         ring: RingLocation,
     ): ResultAsync<
         RingVrfPublicKey,
-        scale.CallErrorValue<VersionedHostAccountRegisterRingVrfKeyError>
+        WithDecodeError<scale.CallErrorValue<VersionedHostAccountRegisterRingVrfKeyError>>
     >;
     /** List an owner's registered ring-VRF keys. */
     listRingVrfKeys(
@@ -267,17 +285,20 @@ export interface AccountsProvider {
         disclosure?: RingVrfKeyDisclosure,
     ): ResultAsync<
         RegisteredRingVrfKey[],
-        scale.CallErrorValue<VersionedHostAccountListRingVrfKeysError>
+        WithDecodeError<scale.CallErrorValue<VersionedHostAccountListRingVrfKeysError>>
     >;
     /** Derive a contextual alias with an explicitly registered ring-VRF key. */
     getProductAccountAlias(
         keyHandle: RingVrfKeyHandle,
         context: ProductProofContext,
         location: RingLocation,
-    ): ResultAsync<ContextualAlias, scale.CallErrorValue<VersionedHostAccountGetAliasError>>;
+    ): ResultAsync<
+        ContextualAlias,
+        WithDecodeError<scale.CallErrorValue<VersionedHostAccountGetAliasError>>
+    >;
     getLegacyAccounts(): ResultAsync<
         HostAccount[],
-        scale.CallErrorValue<VersionedHostGetLegacyAccountsError>
+        WithDecodeError<scale.CallErrorValue<VersionedHostGetLegacyAccountsError>>
     >;
     /**
      * Generate a Ring VRF proof with an explicitly registered key, binding
@@ -288,7 +309,10 @@ export interface AccountsProvider {
         context: ProductProofContext,
         location: RingLocation,
         message: Uint8Array,
-    ): ResultAsync<RingVRFProof, scale.CallErrorValue<VersionedHostAccountCreateProofError>>;
+    ): ResultAsync<
+        RingVRFProof,
+        WithDecodeError<scale.CallErrorValue<VersionedHostAccountCreateProofError>>
+    >;
     /**
      * Sign `message` directly with an explicitly registered ring-VRF key.
      *
@@ -299,7 +323,10 @@ export interface AccountsProvider {
     ringVrfSign(
         keyHandle: RingVrfKeyHandle,
         message: Uint8Array,
-    ): ResultAsync<Uint8Array, scale.CallErrorValue<VersionedHostAccountRingVrfSignError>>;
+    ): ResultAsync<
+        Uint8Array,
+        WithDecodeError<scale.CallErrorValue<VersionedHostAccountRingVrfSignError>>
+    >;
     /**
      * Produce an sr25519 VRF signature from a product account (RFC-0023).
      *
@@ -323,7 +350,10 @@ export interface AccountsProvider {
         account: ProductAccountLookup,
         transcriptLabel: Uint8Array,
         items: VrfTranscriptItem[],
-    ): ResultAsync<VrfSignature, scale.CallErrorValue<VersionedHostAccountSignVrfError>>;
+    ): ResultAsync<
+        VrfSignature,
+        WithDecodeError<scale.CallErrorValue<VersionedHostAccountSignVrfError>>
+    >;
     /**
      * Build a `PolkadotSigner` for a product account. Signing routes through the
      * host's `createTransaction` path: the host decodes the metadata and forwards
@@ -341,30 +371,57 @@ export interface AccountsProvider {
     ): HostSubscription;
 }
 
+/** The transaction-extension version used by V5 general transactions. */
+const GENERAL_TX_EXT_VERSION = 5;
+
 /**
- * Map metadata's supported extrinsic formats to the host wire protocol.
+ * Choose the wire `txExtVersion` — the **transaction-extension** version the
+ * host must assemble under, which is distinct from the extrinsic *format*
+ * version (4 / 5).
+ *
+ * - `formatVersions` — `metadata.extrinsic.version`, the extrinsic *formats* the
+ *   runtime accepts (e.g. `[4]`, `[5]`, `[4, 5]`).
+ * - `txExtVersions` — the keys of `metadata.extrinsic.signedExtensions`, the
+ *   transaction-extension versions the runtime supports (its v16
+ *   `transactionExtensionsByVersion`; always includes `0`).
  *
- * V4 carries the account signature in its envelope. V5 General transactions
- * delegate authorization to the runtime's extension pipeline, but metadata
- * alone does not say whether the connected host can implement that pipeline.
- * Prefer an advertised V4 until the host protocol can negotiate V5
- * authorization capabilities; V5-only and unknown future runtimes retain the
- * previous highest-version behavior and the host remains authoritative.
+ * A V4 signed extrinsic always uses transaction-extension version `0` (a fixed
+ * sentinel, independent of what the extension map contains). Prefer V4 while it
+ * is offered — it carries the account signature in its envelope, and the host
+ * can build it. Only when V4 is absent do we fall to a V5 general transaction,
+ * whose transaction-extension version is `5` (the key the runtime and host
+ * agree on for the general format); require it to actually be present in the
+ * map rather than assuming it.
+ *
+ * Passing the extrinsic *format* number here was the bug (host-rust-core#528):
+ * `5` is both a format version and the general extension version, so it looked
+ * right, but the two are unrelated in general and the host decodes extension
+ * values by this number.
  */
-function selectHostTxExtVersion(versions: readonly number[]): number {
-    if (versions.length === 0) {
+function selectHostTxExtVersion(
+    formatVersions: readonly number[],
+    txExtVersions: readonly number[],
+): number {
+    if (formatVersions.length === 0) {
         throw new Error("No extrinsic version found in metadata");
     }
-    if (versions.includes(4)) {
+    if (formatVersions.includes(4)) {
         return 0;
     }
-    return versions.reduce((acc, version) => Math.max(acc, version), 0);
+    if (txExtVersions.includes(GENERAL_TX_EXT_VERSION)) {
+        return GENERAL_TX_EXT_VERSION;
+    }
+    throw new Error(
+        `Runtime offers no V4 extrinsic and no transaction-extension version ${GENERAL_TX_EXT_VERSION} ` +
+            `(supported: ${txExtVersions.join(", ") || "none"}); cannot select a txExtVersion the host can assemble.`,
+    );
 }
 
 /** Derive the host's transaction-extension version from SCALE metadata. */
 function deriveTxExtVersion(metadata: Uint8Array): number {
-    const versions = unifyMetadata(decAnyMetadata(metadata)).extrinsic.version;
-    return selectHostTxExtVersion(versions);
+    const extrinsic = unifyMetadata(decAnyMetadata(metadata)).extrinsic;
+    const txExtVersions = Object.keys(extrinsic.signedExtensions).map(Number);
+    return selectHostTxExtVersion(extrinsic.version, txExtVersions);
 }
 
 /** Internal seam so `import.meta.vitest` can stub the metadata decode. @internal */
@@ -400,6 +457,28 @@ function toWireProductAccountId({
     return { dotNsIdentifier, derivationIndex: { tag: "Index", value: derivationIndex } };
 }
 
+/**
+ * Route a thrown/rejected response-decode error onto the `Result` err channel.
+ *
+ * The truapi client catches a decode throw in its message handler and turns it
+ * into a promise rejection, then wraps each call with
+ * `ResultAsync.fromSafePromise`, which installs no rejection handler — so when
+ * the host's reply doesn't match the client's codec (a version skew), that
+ * rejection escapes the `Result` channel rather than landing on its err side,
+ * surfacing as a raw `RangeError`. Wrapping the call re-homes that rejection as
+ * a typed {@link HostResponseDecodeError} that names the call, while ok values
+ * and the call's own typed `Err` values pass through untouched.
+ */
+function guardDecode<T, E>(
+    call: string,
+    result: ResultAsync<T, E>,
+): ResultAsync<T, E | HostResponseDecodeError> {
+    return ResultAsync.fromPromise(
+        Promise.resolve(result),
+        (cause) => new HostResponseDecodeError(call, cause),
+    ).andThen((inner) => inner);
+}
+
 /** Build an {@link AccountsProvider} over a TruAPI client's `account` / `signing` domains. */
 function adaptAccountsProvider(client: TrUApiClient): AccountsProvider {
     const account = client.account;
@@ -407,98 +486,128 @@ function adaptAccountsProvider(client: TrUApiClient): AccountsProvider {
 
     return {
         getUserId() {
-            return account.getUserId().map((response) => ({
-                primaryUsername: response.primaryUsername,
-            }));
+            return guardDecode(
+                "getUserId",
+                account.getUserId().map((response) => ({
+                    primaryUsername: response.primaryUsername,
+                })),
+            );
         },
         requestLogin(reason) {
-            return account.requestLogin({ reason });
+            return guardDecode("requestLogin", account.requestLogin({ reason }));
         },
         getProductAccount(dotNsIdentifier, derivationIndex = 0) {
-            return account
-                .getAccount({
-                    productAccountId: toWireProductAccountId({ dotNsIdentifier, derivationIndex }),
-                })
-                .map((response) => ({
-                    publicKey: fromHex(response.account.publicKey),
-                    dotNsIdentifier,
-                    derivationIndex,
-                }));
+            return guardDecode(
+                "getProductAccount",
+                account
+                    .getAccount({
+                        productAccountId: toWireProductAccountId({
+                            dotNsIdentifier,
+                            derivationIndex,
+                        }),
+                    })
+                    .map((response) => ({
+                        publicKey: fromHex(response.account.publicKey),
+                        dotNsIdentifier,
+                        derivationIndex,
+                    })),
+            );
         },
         registerRingVrfKey(index, ring) {
-            return account
-                .registerRingVrfKey({ index: { tag: "Index", value: index }, ring })
-                .map(fromHex);
+            return guardDecode(
+                "registerRingVrfKey",
+                account
+                    .registerRingVrfKey({ index: { tag: "Index", value: index }, ring })
+                    .map(fromHex),
+            );
         },
         listRingVrfKeys(owner, disclosure = "Anonymized") {
-            return account.listRingVrfKeys({ owner, disclosure }).map((keys) =>
-                keys.map((key) => ({
-                    ...key,
-                    handle: key.handle as unknown as RingVrfKeyHandle,
-                    publicKey: key.publicKey === undefined ? undefined : fromHex(key.publicKey),
-                })),
+            return guardDecode(
+                "listRingVrfKeys",
+                account.listRingVrfKeys({ owner, disclosure }).map((keys) =>
+                    keys.map((key) => ({
+                        ...key,
+                        handle: key.handle as unknown as RingVrfKeyHandle,
+                        publicKey: key.publicKey === undefined ? undefined : fromHex(key.publicKey),
+                    })),
+                ),
             );
         },
         getProductAccountAlias(keyHandle, context, location) {
-            return account
-                .getAccountAlias({
-                    keyHandle: keyHandle as unknown as ProductAccountId,
-                    context,
-                    ringLocation: location,
-                })
-                .map((response) => ({
-                    context: fromHex(response.context),
-                    alias: fromHex(response.alias),
-                }));
+            return guardDecode(
+                "getProductAccountAlias",
+                account
+                    .getAccountAlias({
+                        keyHandle: keyHandle as unknown as ProductAccountId,
+                        context,
+                        ringLocation: location,
+                    })
+                    .map((response) => ({
+                        context: fromHex(response.context),
+                        alias: fromHex(response.alias),
+                    })),
+            );
         },
         getLegacyAccounts() {
-            return account.getLegacyAccounts().map((response) =>
-                response.accounts.map((a) => ({
-                    publicKey: fromHex(a.publicKey),
-                    name: a.name,
-                })),
+            return guardDecode(
+                "getLegacyAccounts",
+                account.getLegacyAccounts().map((response) =>
+                    response.accounts.map((a) => ({
+                        publicKey: fromHex(a.publicKey),
+                        name: a.name,
+                    })),
+                ),
             );
         },
         createRingVRFProof(keyHandle, context, location, message) {
-            return account
-                .createAccountProof({
-                    keyHandle: keyHandle as unknown as ProductAccountId,
-                    context,
-                    ringLocation: location,
-                    message: toHex(message),
-                })
-                .map((response) => ({
-                    proof: fromHex(response.proof),
-                    contextualAlias: {
-                        context: fromHex(response.contextualAlias.context),
-                        alias: fromHex(response.contextualAlias.alias),
-                    },
-                    ringIndex: response.ringIndex,
-                    ringRevision: response.ringRevision,
-                }));
+            return guardDecode(
+                "createRingVRFProof",
+                account
+                    .createAccountProof({
+                        keyHandle: keyHandle as unknown as ProductAccountId,
+                        context,
+                        ringLocation: location,
+                        message: toHex(message),
+                    })
+                    .map((response) => ({
+                        proof: fromHex(response.proof),
+                        contextualAlias: {
+                            context: fromHex(response.contextualAlias.context),
+                            alias: fromHex(response.contextualAlias.alias),
+                        },
+                        ringIndex: response.ringIndex,
+                        ringRevision: response.ringRevision,
+                    })),
+            );
         },
         ringVrfSign(keyHandle, message) {
-            return account
-                .ringVrfSign({
-                    keyHandle: keyHandle as unknown as ProductAccountId,
-                    message: toHex(message),
-                })
-                .map(fromHex);
+            return guardDecode(
+                "ringVrfSign",
+                account
+                    .ringVrfSign({
+                        keyHandle: keyHandle as unknown as ProductAccountId,
+                        message: toHex(message),
+                    })
+                    .map(fromHex),
+            );
         },
         signVrf(account_, transcriptLabel, items) {
-            return account
-                .signVrf({
-                    account: toWireProductAccountId(account_),
-                    transcriptLabel: toHex(transcriptLabel),
-                    items: items.map(({ label, value }) => ({
-                        label: toHex(label),
-                        value: toHex(value),
+            return guardDecode(
+                "signVrf",
+                account
+                    .signVrf({
+                        account: toWireProductAccountId(account_),
+                        transcriptLabel: toHex(transcriptLabel),
+                        items: items.map(({ label, value }) => ({
+                            label: toHex(label),
+                            value: toHex(value),
+                        })),
+                    })
+                    .map((response) => ({
+                        preOutput: fromHex(response.preOutput),
+                        proof: fromHex(response.proof),
                     })),
-                })
-                .map((response) => ({
-                    preOutput: fromHex(response.preOutput),
-                    proof: fromHex(response.proof),
-                }));
+            );
         },
         getProductAccountSigner(account_) {
             const productAccountId = toWireProductAccountId(account_);
@@ -593,34 +702,44 @@ export async function getAccountsProvider(): Promise<AccountsProvider | null> {
 }
 
 if (import.meta.vitest) {
-    const { test, expect, vi } = import.meta.vitest;
+    const { test, expect, vi, describe } = import.meta.vitest;
 
-    test("host signing prefers V4 on a dual V4/V5 runtime", () => {
-        expect(selectHostTxExtVersion([4, 5])).toBe(0);
+    test("host signing prefers V4 (tx-ext version 0) on a dual V4/V5 runtime", () => {
+        // txExtVersion 0 regardless of what the extension map lists.
+        expect(selectHostTxExtVersion([4, 5], [0])).toBe(0);
     });
 
-    test("host signing uses V5 when V4 is unavailable", () => {
-        expect(selectHostTxExtVersion([5])).toBe(5);
+    test("host signing uses the general tx-ext version 5 when V4 is unavailable", () => {
+        // The value comes from the extension-version map, not the format list.
+        expect(selectHostTxExtVersion([5], [0, 5])).toBe(5);
     });
 
     test("host signing maps a V4-only runtime to the wire sentinel", () => {
-        expect(selectHostTxExtVersion([4])).toBe(0);
+        expect(selectHostTxExtVersion([4], [0])).toBe(0);
+    });
+
+    test("host signing does not confuse extrinsic format 5 with a tx-ext version", () => {
+        // V5-only runtime that only supports tx-ext version 0 (no general
+        // extension set): the old code returned 5 (the format number); now this
+        // must throw rather than send an unsupported txExtVersion.
+        expect(() => selectHostTxExtVersion([5], [0])).toThrow(/no.*version 5/i);
     });
 
     test("host signing rejects metadata with no extrinsic version", () => {
-        expect(() => selectHostTxExtVersion([])).toThrow("No extrinsic version found in metadata");
+        expect(() => selectHostTxExtVersion([], [0])).toThrow(
+            "No extrinsic version found in metadata",
+        );
     });
 
     /** Minimal fake of the truapi account/signing domains used to test the adapter. */
     function makeFakeClient(opts: { onCall?: (method: string, args: unknown) => void } = {}) {
-        const okMatch = (value: unknown) => ({
-            // neverthrow ResultAsync surface used by the adapter: .map + .match.
-            map: (fn: (v: unknown) => unknown) => okMatch(fn(value)),
-            match: (ok: (v: unknown) => unknown, _err: (e: unknown) => unknown) => ok(value),
-        });
+        // A real neverthrow `okAsync`, not a hand-rolled `{ map, match }` stub:
+        // a stub with no `.then` would be passed through un-awaited by
+        // `guardDecode`'s `Promise.resolve(result)`, so the tests would bypass
+        // the guard's real path. A genuine `ResultAsync` exercises it.
         const method = (name: string, response: unknown) => (args: unknown) => {
             opts.onCall?.(name, args);
-            return okMatch(response);
+            return okAsync(response);
         };
         return {
             account: {
@@ -1073,4 +1192,87 @@ if (import.meta.vitest) {
         expect(signed).toEqual(fromHex("0xfeed"));
         vi.restoreAllMocks();
     });
+
+    describe("response-decode boundary (guardDecode)", () => {
+        // A client whose `createAccountProof` returns a REAL neverthrow
+        // `ResultAsync` — the hand-rolled `okMatch` fake can't reject, and
+        // rejection (a thrown SCALE decode) is exactly what this boundary
+        // exists to catch. `createRingVRFProof` is the reported call (#270).
+        function clientWithProof(result: ResultAsync<unknown, unknown>): TrUApiClient {
+            return {
+                account: { createAccountProof: () => result },
+            } as unknown as TrUApiClient;
+        }
+
+        const KEY_HANDLE = {
+            dotNsIdentifier: "people.dot",
+            derivationIndex: { tag: "Index", value: 0 },
+        } as unknown as RingVrfKeyHandle;
+        const CONTEXT = {
+            productId: "app.dot",
+            suffix: { tag: "Index", value: 0 },
+        } as ProductProofContext;
+        const RING: RingLocation = { chainId: "0x01", junctions: [] };
+        const MESSAGE = new Uint8Array([1, 2, 3]);
+
+        const callProof = (result: ResultAsync<unknown, unknown>) =>
+            adaptAccountsProvider(clientWithProof(result)).createRingVRFProof(
+                KEY_HANDLE,
+                CONTEXT,
+                RING,
+                MESSAGE,
+            );
+
+        test("a thrown decode error (RangeError) becomes a HostResponseDecodeError naming the call", async () => {
+            const rangeError = new RangeError("Offset is outside the bounds of the DataView");
+            const result = await callProof(ResultAsync.fromSafePromise(Promise.reject(rangeError)));
+
+            expect(result.isErr()).toBe(true);
+            const error = result._unsafeUnwrapErr();
+            expect(error).toBeInstanceOf(HostResponseDecodeError);
+            expect((error as HostResponseDecodeError).call).toBe("createRingVRFProof");
+            // The original error is preserved as `cause` so a bug report can see it.
+            expect((error as HostResponseDecodeError).cause).toBe(rangeError);
+        });
+
+        test("a synchronous throw in the response mapping is caught too", async () => {
+            // e.g. a malformed hex field reaching `fromHex` inside `.map`.
+            const result = await callProof(
+                okAsync({
+                    proof: "not-hex",
+                    contextualAlias: { context: "0x01", alias: "0x02" },
+                    ringIndex: 0,
+                    ringRevision: 0,
+                }),
+            );
+            expect(result.isErr()).toBe(true);
+            expect(result._unsafeUnwrapErr()).toBeInstanceOf(HostResponseDecodeError);
+        });
+
+        test("a well-formed response passes through unchanged", async () => {
+            const result = await callProof(
+                okAsync({
+                    proof: "0xc0ffee",
+                    contextualAlias: { context: "0x01", alias: "0x02" },
+                    ringIndex: 3,
+                    ringRevision: 7,
+                }),
+            );
+            expect(result.isOk()).toBe(true);
+            const proof = result._unsafeUnwrap();
+            expect(proof.proof).toEqual(fromHex("0xc0ffee"));
+            expect(proof.ringIndex).toBe(3);
+            expect(proof.ringRevision).toBe(7);
+        });
+
+        test("the call's own typed Err passes through, not wrapped as a decode error", async () => {
+            const typedErr = { tag: "Domain", value: { tag: "RingNotFound" } };
+            const result = await callProof(errAsync(typedErr));
+
+            expect(result.isErr()).toBe(true);
+            const error = result._unsafeUnwrapErr();
+            expect(error).not.toBeInstanceOf(HostResponseDecodeError);
+            expect(error).toEqual(typedErr);
+        });
+    });
 }

package/src/errors.ts

@@ -144,6 +144,38 @@ export class HostCallFailedError extends HostError {
     }
 }
 
+/**
+ * A host call could not be processed to completion: the `ResultAsync` the
+ * truapi client returns rejected instead of resolving to an ok/err. The usual
+ * cause is a response the client's SCALE codec can't decode (a
+ * `RangeError: Offset is outside the bounds of the DataView`) because the host
+ * and the `@parity/truapi` version the product is built against disagree on the
+ * wire shape of that call — a protocol-version skew. A host channel that closed
+ * mid-call looks identical from here, so this does not assert the skew; the
+ * real error is preserved on {@link cause}.
+ *
+ * The truapi client catches the decode throw in its message handler and turns
+ * it into a promise rejection, then wraps the call with
+ * `ResultAsync.fromSafePromise`, which installs no rejection handler — so the
+ * rejection escapes the `Result` channel rather than landing on its err side.
+ * Without this boundary that surfaces as a raw `RangeError` with a stack naming
+ * neither the call nor the cause. This names the call, so a bug report has
+ * somewhere to start.
+ */
+export class HostResponseDecodeError extends HostError {
+    /** The host-API call whose response failed to decode, e.g. `"createRingVRFProof"`. */
+    readonly call: string;
+
+    constructor(call: string, cause: unknown) {
+        super(
+            `Could not process the host's response to ${call}: ${formatHostError(cause)}. The usual cause is a protocol-version skew between the host app and the @parity/truapi version this product is built against; a host channel that closed mid-call looks the same.`,
+            { cause },
+        );
+        this.name = "HostResponseDecodeError";
+        this.call = call;
+    }
+}
+
 /** Check whether a value is any {@link HostError}. */
 export function isHostError(error: unknown): error is HostError {
     return error instanceof HostError;
@@ -192,9 +224,23 @@ if (import.meta.vitest) {
             expect(e.message).toBe("submit failed: timeout");
         });
 
+        test("HostResponseDecodeError names the call, interpolates the cause, and preserves it", () => {
+            const cause = new RangeError("Offset is outside the bounds of the DataView");
+            const e = new HostResponseDecodeError("createRingVRFProof", cause);
+            expect(e).toBeInstanceOf(HostError);
+            expect(e.name).toBe("HostResponseDecodeError");
+            expect(e.call).toBe("createRingVRFProof");
+            expect(e.cause).toBe(cause);
+            expect(e.message).toContain("createRingVRFProof");
+            // The rendered cause is in the message, not just on `.cause`.
+            expect(e.message).toContain("Offset is outside the bounds of the DataView");
+            expect(e.message).toContain("protocol-version skew");
+        });
+
         test("isHostError narrows host errors only", () => {
             expect(isHostError(new HostUnavailableError())).toBe(true);
             expect(isHostError(new HostCallFailedError("x", { tag: "Denied" }))).toBe(true);
+            expect(isHostError(new HostResponseDecodeError("c", new Error("boom")))).toBe(true);
             expect(isHostError(new Error("plain"))).toBe(false);
             expect(isHostError("string")).toBe(false);
         });