@parity/product-sdk-contracts 0.8.3 → 0.9.1

package/dist/pvm.d.ts

@@ -1,7 +1,9 @@
-import { A as AbiEntry } from './types-pkS1R9Bk.js';
-import 'polkadot-api';
-import '@parity/product-sdk-tx';
+import { A as AbiEntry } from './types-BKcrGoiN.js';
+import '@parity/result';
 import '@parity/product-sdk-signer';
+import '@parity/product-sdk-tx';
+import 'polkadot-api';
+import '@parity/product-sdk-errors';
 
 /** ABI + PolkaVM bytecode pair emitted by `cargo pvm-contract build`. */
 interface PvmContractArtifacts {

package/dist/testing.d.ts

@@ -0,0 +1,85 @@
+import { HexString, SS58String } from 'polkadot-api';
+import { Weight } from '@parity/product-sdk-tx';
+import { A as AbiEntry, a as ContractRuntime, v as ReviveDryRunResult } from './types-BKcrGoiN.js';
+import '@parity/result';
+import '@parity/product-sdk-signer';
+import '@parity/product-sdk-errors';
+
+/** Options for {@link fakeDryRunResult}. */
+interface FakeDryRunResultOptions {
+    /** Raw ABI-encoded return bytes. Ignored when the runtime encodes for you. */
+    data?: Uint8Array;
+    /** Simulate a revert: `true` for an empty reason, a string for a UTF-8 reason. Sets the revert flag. */
+    revert?: boolean | string;
+    /** Simulate a dispatch failure (`result.success: false`) carrying this payload. */
+    failure?: unknown;
+    /** Weight surfaced as a query's `gasRequired`. Default `{ ref_time: 1n, proof_size: 1n }`. */
+    weightRequired?: Weight;
+}
+/**
+ * Build a {@link ReviveDryRunResult}. Defaults to a successful, empty return;
+ * pass `data` for a raw payload, `revert` for a revert, or `failure` for a
+ * dispatch error.
+ */
+declare function fakeDryRunResult(options?: FakeDryRunResultOptions): ReviveDryRunResult;
+/** The dry-run / query a fake runtime was asked to perform. */
+interface DecodedContractCall {
+    origin: SS58String;
+    dest: HexString;
+    value: bigint;
+    data: Uint8Array;
+    /** Decoded function name — present only when `abi` was supplied. */
+    functionName?: string;
+    /** Decoded arguments — present only when `abi` was supplied. */
+    args?: unknown[];
+}
+/** The extrinsic a fake runtime was asked to build via `.tx()` / `.prepare()`. */
+interface BuiltContractCall {
+    dest: HexString;
+    value: bigint;
+    weight_limit: Weight;
+    storage_deposit_limit: bigint;
+    data: Uint8Array;
+}
+/** A fake {@link ContractRuntime} with an inspection surface for tests. */
+interface FakeContractRuntime extends ContractRuntime {
+    /** Every dry-run / query the runtime handled, in order. */
+    readonly calls: ReadonlyArray<DecodedContractCall>;
+    /** Clear the recorded calls. */
+    reset(): void;
+}
+/** Options for {@link createFakeContractRuntime}. */
+interface CreateFakeContractRuntimeOptions {
+    /**
+     * ABI used to decode inbound calldata (so `onQuery` gets `functionName` /
+     * `args`) and to encode a value `onQuery` returns. Omit only if `onQuery`
+     * returns raw bytes or a {@link fakeDryRunResult}.
+     */
+    abi?: AbiEntry[];
+    /**
+     * Handle each query / dry-run. Return the value to decode to (encoded via
+     * `abi`), raw bytes, or a {@link fakeDryRunResult}. Default: empty success.
+     */
+    onQuery?: (call: DecodedContractCall) => unknown;
+    /** Called with the extrinsic `.tx()` / `.prepare()` builds. */
+    onCall?: (call: BuiltContractCall) => void;
+}
+/**
+ * Create an in-memory {@link ContractRuntime}.
+ *
+ * @example
+ * ```ts
+ * import { createContract } from "@parity/product-sdk-contracts";
+ * import { createFakeContractRuntime } from "@parity/product-sdk-contracts/testing";
+ *
+ * const runtime = createFakeContractRuntime({
+ *   abi: erc20Abi,
+ *   onQuery: ({ functionName }) => (functionName === "balanceOf" ? 1000n : 0n),
+ * });
+ * const token = createContract(runtime, ADDRESS, erc20Abi);
+ * const { value } = await token.balanceOf.query(HOLDER); // 1000n
+ * ```
+ */
+declare function createFakeContractRuntime(options?: CreateFakeContractRuntimeOptions): FakeContractRuntime;
+
+export { type BuiltContractCall, type CreateFakeContractRuntimeOptions, type DecodedContractCall, type FakeContractRuntime, type FakeDryRunResultOptions, createFakeContractRuntime, fakeDryRunResult };

package/dist/testing.js

@@ -0,0 +1,99 @@
+import { decodeFunctionData, bytesToHex, hexToBytes, encodeFunctionResult } from 'viem';
+
+// src/testing.ts
+var REVERT_FLAG = 1;
+var textEncoder = new TextEncoder();
+function fakeDryRunResult(options) {
+  const base = {
+    weight_consumed: { ref_time: 0n, proof_size: 0n },
+    weight_required: options?.weightRequired ?? { ref_time: 1n, proof_size: 1n },
+    storage_deposit: { type: "Refund", value: 0n },
+    max_storage_deposit: { type: "Refund", value: 0n },
+    gas_consumed: 0n
+  };
+  if (options?.failure !== void 0) {
+    return { ...base, result: { success: false, value: options.failure } };
+  }
+  if (options?.revert !== void 0 && options.revert !== false) {
+    const reason = typeof options.revert === "string" ? options.revert : "";
+    return {
+      ...base,
+      result: {
+        success: true,
+        value: { flags: REVERT_FLAG, data: textEncoder.encode(reason) }
+      }
+    };
+  }
+  return {
+    ...base,
+    result: { success: true, value: { flags: 0, data: options?.data ?? new Uint8Array(0) } }
+  };
+}
+function isDryRunResult(value) {
+  return typeof value === "object" && value !== null && "result" in value && "weight_required" in value;
+}
+function createFakeContractRuntime(options) {
+  const abi = options?.abi;
+  const calls = [];
+  const dryRunCall = async (origin, dest, value, _gasLimit, _storageDepositLimit, data) => {
+    let functionName;
+    let args;
+    if (abi) {
+      const decoded = decodeFunctionData({
+        abi,
+        data: bytesToHex(data)
+      });
+      functionName = decoded.functionName;
+      args = decoded.args ? [...decoded.args] : [];
+    }
+    const call = { origin, dest, value, data, functionName, args };
+    calls.push(call);
+    const out = options?.onQuery ? options.onQuery(call) : void 0;
+    if (isDryRunResult(out)) return out;
+    if (out instanceof Uint8Array) return fakeDryRunResult({ data: out });
+    if (out === void 0) return fakeDryRunResult();
+    if (!abi || !functionName) {
+      throw new Error(
+        "createFakeContractRuntime: onQuery returned a value but no abi is set to encode it. Pass `abi`, or return a Uint8Array or fakeDryRunResult()."
+      );
+    }
+    const encoded = hexToBytes(
+      encodeFunctionResult({
+        abi,
+        functionName,
+        result: out
+      })
+    );
+    return fakeDryRunResult({ data: encoded });
+  };
+  const api = {
+    tx: {
+      Revive: {
+        call: (built) => {
+          options?.onCall?.(built);
+          return {};
+        },
+        map_account: () => ({})
+      }
+    },
+    query: { Revive: { OriginalAccount: { getValue: async () => void 0 } } },
+    apis: {
+      ReviveApi: {
+        // Same signature as dryRunCall (it ignores the 7th `options` arg).
+        call: dryRunCall
+      }
+    }
+  };
+  return {
+    api,
+    dryRunCall,
+    calls,
+    reset() {
+      calls.length = 0;
+    }
+  };
+}
+
+export { createFakeContractRuntime, fakeDryRunResult };
+//# sourceMappingURL=testing.js.map
+//# sourceMappingURL=testing.js.map

package/dist/testing.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/testing.ts"],"names":[],"mappings":"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","file":"testing.js","sourcesContent":["// Copyright 2026 Parity Technologies (UK) Ltd.\n// SPDX-License-Identifier: Apache-2.0\n/**\n * Test fakes for `@parity/product-sdk-contracts`.\n *\n * `createFakeContractRuntime` is an in-memory `ContractRuntime` for\n * `createContract(runtime, address, abi)` — test `.query()` / `.prepare()` with\n * no chain and no deployed contract. `fakeDryRunResult` builds the fiddly\n * `ReviveDryRunResult` when you need full control over reverts / failures.\n *\n * @packageDocumentation\n */\nimport {\n    type Abi as ViemAbi,\n    bytesToHex,\n    decodeFunctionData,\n    encodeFunctionResult,\n    hexToBytes,\n} from \"viem\";\nimport type { HexString, SS58String } from \"polkadot-api\";\nimport type { SubmittableTransaction, Weight } from \"@parity/product-sdk-tx\";\n\nimport type { ContractRuntime, ReviveDryRunResult, ReviveTypedApi } from \"./runtime.js\";\nimport type { AbiEntry } from \"./types.js\";\n\n/** pallet-revive sets bit 0 of `flags` when a call reverts (mirror of wrap.ts). */\nconst REVERT_FLAG = 1;\n\nconst textEncoder = new TextEncoder();\n\n/** Options for {@link fakeDryRunResult}. */\nexport interface FakeDryRunResultOptions {\n    /** Raw ABI-encoded return bytes. Ignored when the runtime encodes for you. */\n    data?: Uint8Array;\n    /** Simulate a revert: `true` for an empty reason, a string for a UTF-8 reason. Sets the revert flag. */\n    revert?: boolean | string;\n    /** Simulate a dispatch failure (`result.success: false`) carrying this payload. */\n    failure?: unknown;\n    /** Weight surfaced as a query's `gasRequired`. Default `{ ref_time: 1n, proof_size: 1n }`. */\n    weightRequired?: Weight;\n}\n\n/**\n * Build a {@link ReviveDryRunResult}. Defaults to a successful, empty return;\n * pass `data` for a raw payload, `revert` for a revert, or `failure` for a\n * dispatch error.\n */\nexport function fakeDryRunResult(options?: FakeDryRunResultOptions): ReviveDryRunResult {\n    const base = {\n        weight_consumed: { ref_time: 0n, proof_size: 0n },\n        weight_required: options?.weightRequired ?? { ref_time: 1n, proof_size: 1n },\n        storage_deposit: { type: \"Refund\" as const, value: 0n },\n        max_storage_deposit: { type: \"Refund\" as const, value: 0n },\n        gas_consumed: 0n,\n    };\n    if (options?.failure !== undefined) {\n        return { ...base, result: { success: false, value: options.failure } };\n    }\n    if (options?.revert !== undefined && options.revert !== false) {\n        const reason = typeof options.revert === \"string\" ? options.revert : \"\";\n        return {\n            ...base,\n            result: {\n                success: true,\n                value: { flags: REVERT_FLAG, data: textEncoder.encode(reason) },\n            },\n        };\n    }\n    return {\n        ...base,\n        result: { success: true, value: { flags: 0, data: options?.data ?? new Uint8Array(0) } },\n    };\n}\n\nfunction isDryRunResult(value: unknown): value is ReviveDryRunResult {\n    return (\n        typeof value === \"object\" &&\n        value !== null &&\n        \"result\" in value &&\n        \"weight_required\" in value\n    );\n}\n\n/** The dry-run / query a fake runtime was asked to perform. */\nexport interface DecodedContractCall {\n    origin: SS58String;\n    dest: HexString;\n    value: bigint;\n    data: Uint8Array;\n    /** Decoded function name — present only when `abi` was supplied. */\n    functionName?: string;\n    /** Decoded arguments — present only when `abi` was supplied. */\n    args?: unknown[];\n}\n\n/** The extrinsic a fake runtime was asked to build via `.tx()` / `.prepare()`. */\nexport interface BuiltContractCall {\n    dest: HexString;\n    value: bigint;\n    weight_limit: Weight;\n    storage_deposit_limit: bigint;\n    data: Uint8Array;\n}\n\n/** A fake {@link ContractRuntime} with an inspection surface for tests. */\nexport interface FakeContractRuntime extends ContractRuntime {\n    /** Every dry-run / query the runtime handled, in order. */\n    readonly calls: ReadonlyArray<DecodedContractCall>;\n    /** Clear the recorded calls. */\n    reset(): void;\n}\n\n/** Options for {@link createFakeContractRuntime}. */\nexport interface CreateFakeContractRuntimeOptions {\n    /**\n     * ABI used to decode inbound calldata (so `onQuery` gets `functionName` /\n     * `args`) and to encode a value `onQuery` returns. Omit only if `onQuery`\n     * returns raw bytes or a {@link fakeDryRunResult}.\n     */\n    abi?: AbiEntry[];\n    /**\n     * Handle each query / dry-run. Return the value to decode to (encoded via\n     * `abi`), raw bytes, or a {@link fakeDryRunResult}. Default: empty success.\n     */\n    onQuery?: (call: DecodedContractCall) => unknown;\n    /** Called with the extrinsic `.tx()` / `.prepare()` builds. */\n    onCall?: (call: BuiltContractCall) => void;\n}\n\n/**\n * Create an in-memory {@link ContractRuntime}.\n *\n * @example\n * ```ts\n * import { createContract } from \"@parity/product-sdk-contracts\";\n * import { createFakeContractRuntime } from \"@parity/product-sdk-contracts/testing\";\n *\n * const runtime = createFakeContractRuntime({\n *   abi: erc20Abi,\n *   onQuery: ({ functionName }) => (functionName === \"balanceOf\" ? 1000n : 0n),\n * });\n * const token = createContract(runtime, ADDRESS, erc20Abi);\n * const { value } = await token.balanceOf.query(HOLDER); // 1000n\n * ```\n */\nexport function createFakeContractRuntime(\n    options?: CreateFakeContractRuntimeOptions,\n): FakeContractRuntime {\n    const abi = options?.abi;\n    const calls: DecodedContractCall[] = [];\n\n    const dryRunCall: ContractRuntime[\"dryRunCall\"] = async (\n        origin,\n        dest,\n        value,\n        _gasLimit,\n        _storageDepositLimit,\n        data,\n    ) => {\n        let functionName: string | undefined;\n        let args: unknown[] | undefined;\n        if (abi) {\n            const decoded = decodeFunctionData({\n                abi: abi as unknown as ViemAbi,\n                data: bytesToHex(data),\n            });\n            functionName = decoded.functionName;\n            args = decoded.args ? [...decoded.args] : [];\n        }\n        const call: DecodedContractCall = { origin, dest, value, data, functionName, args };\n        calls.push(call);\n\n        const out = options?.onQuery ? options.onQuery(call) : undefined;\n        if (isDryRunResult(out)) return out;\n        if (out instanceof Uint8Array) return fakeDryRunResult({ data: out });\n        if (out === undefined) return fakeDryRunResult();\n\n        if (!abi || !functionName) {\n            throw new Error(\n                \"createFakeContractRuntime: onQuery returned a value but no abi is set to encode it. Pass `abi`, or return a Uint8Array or fakeDryRunResult().\",\n            );\n        }\n        const encoded = hexToBytes(\n            encodeFunctionResult({\n                abi: abi as unknown as ViemAbi,\n                functionName,\n                result: out,\n            }),\n        );\n        return fakeDryRunResult({ data: encoded });\n    };\n\n    const api: ReviveTypedApi = {\n        tx: {\n            Revive: {\n                call: (built) => {\n                    options?.onCall?.(built);\n                    return {} as unknown as SubmittableTransaction;\n                },\n                map_account: () => ({}) as unknown as SubmittableTransaction,\n            },\n        },\n        query: { Revive: { OriginalAccount: { getValue: async () => undefined } } },\n        apis: {\n            ReviveApi: {\n                // Same signature as dryRunCall (it ignores the 7th `options` arg).\n                call: dryRunCall,\n            },\n        },\n    };\n\n    return {\n        api,\n        dryRunCall,\n        calls,\n        reset() {\n            calls.length = 0;\n        },\n    } satisfies FakeContractRuntime;\n}\n\nif (import.meta.vitest) {\n    // Round-trip guard: drive the fake through the *real* createContract.\n    const { describe, test, expect } = import.meta.vitest;\n    const { createContract } = await import(\"./manager.js\");\n\n    const abi: AbiEntry[] = [\n        {\n            type: \"function\",\n            name: \"balanceOf\",\n            stateMutability: \"view\",\n            inputs: [{ name: \"owner\", type: \"address\" }],\n            outputs: [{ name: \"\", type: \"uint256\" }],\n        },\n        {\n            type: \"function\",\n            name: \"transfer\",\n            stateMutability: \"nonpayable\",\n            inputs: [\n                { name: \"to\", type: \"address\" },\n                { name: \"amount\", type: \"uint256\" },\n            ],\n            outputs: [{ name: \"\", type: \"bool\" }],\n        },\n    ];\n\n    const CONTRACT = `0x${\"22\".repeat(20)}` as HexString;\n    const HOLDER = `0x${\"11\".repeat(20)}` as HexString;\n\n    // Minimal typed handle for the two ABI methods above.\n    type TestToken = {\n        balanceOf: {\n            query: (\n                owner: HexString,\n            ) => Promise<{ success: true; value: bigint } | { success: false; value: unknown }>;\n        };\n        transfer: {\n            prepare: (\n                to: HexString,\n                amount: bigint,\n                opts?: { gasLimit?: Weight; storageDepositLimit?: bigint },\n            ) => Promise<unknown>;\n        };\n    };\n    const makeToken = (runtime: ContractRuntime) =>\n        createContract(runtime, CONTRACT, abi) as unknown as TestToken;\n\n    describe(\"createFakeContractRuntime\", () => {\n        test(\"query decodes a value the runtime encodes from onQuery\", async () => {\n            const runtime = createFakeContractRuntime({\n                abi,\n                onQuery: ({ functionName }) => (functionName === \"balanceOf\" ? 1000n : 0n),\n            });\n            const token = makeToken(runtime);\n\n            const res = await token.balanceOf.query(HOLDER);\n            expect(res.success).toBe(true);\n            if (res.success) expect(res.value).toBe(1000n);\n            expect(runtime.calls[0]?.functionName).toBe(\"balanceOf\");\n        });\n\n        test(\"query surfaces a revert as success:false\", async () => {\n            const runtime = createFakeContractRuntime({\n                abi,\n                onQuery: () => fakeDryRunResult({ revert: \"InsufficientBalance\" }),\n            });\n            const res = await makeToken(runtime).balanceOf.query(HOLDER);\n            expect(res.success).toBe(false);\n        });\n\n        test(\"query surfaces a dispatch failure with its payload\", async () => {\n            const runtime = createFakeContractRuntime({\n                abi,\n                onQuery: () => fakeDryRunResult({ failure: { type: \"AccountNotMapped\" } }),\n            });\n            const res = await makeToken(runtime).balanceOf.query(HOLDER);\n            expect(res.success).toBe(false);\n            expect(res.value).toEqual({ type: \"AccountNotMapped\" });\n        });\n\n        test(\"prepare builds an extrinsic that onCall captures\", async () => {\n            let captured: BuiltContractCall | undefined;\n            const runtime = createFakeContractRuntime({\n                abi,\n                onCall: (c) => {\n                    captured = c;\n                },\n            });\n            // Supply both limits so the sizing dry-run is skipped (no origin needed).\n            await makeToken(runtime).transfer.prepare(HOLDER, 5n, {\n                gasLimit: { ref_time: 100n, proof_size: 200n },\n                storageDepositLimit: 0n,\n            });\n\n            expect(captured?.dest).toBe(CONTRACT);\n            expect(captured?.value).toBe(0n);\n            expect(captured?.weight_limit).toEqual({ ref_time: 100n, proof_size: 200n });\n            expect(captured?.data).toBeInstanceOf(Uint8Array);\n        });\n    });\n}\n"]}

package/dist/{types-pkS1R9Bk.d.ts → types-BKcrGoiN.d.ts}

@@ -1,6 +1,80 @@
-import { HexString, SS58String, PolkadotClient, PolkadotSigner } from 'polkadot-api';
-import { Weight, SubmittableTransaction, TxResult, SubmitOptions, BatchableCall } from '@parity/product-sdk-tx';
+import { Result } from '@parity/result';
 import { SignerManager } from '@parity/product-sdk-signer';
+import { Weight, SubmittableTransaction, TxResult, TxError, SubmitOptions, BatchableCall } from '@parity/product-sdk-tx';
+import { HexString, SS58String, PolkadotClient, PolkadotSigner } from 'polkadot-api';
+import { SdkError } from '@parity/product-sdk-errors';
+
+/**
+ * Base class for all contract errors. Use `instanceof ContractError` to catch any
+ * contract-related error. Implements the cross-package {@link SdkError} marker so
+ * `isSdkError(e)` also recognizes it.
+ */
+declare class ContractError extends Error implements SdkError {
+    readonly isSdkError: true;
+    readonly source = "contracts";
+    constructor(message: string, options?: ErrorOptions);
+}
+/** No signer was available for a transaction call. */
+declare class ContractSignerMissingError extends ContractError {
+    constructor();
+}
+/** A contract was not found in the cdm.json manifest. */
+declare class ContractNotFoundError extends ContractError {
+    readonly library: string;
+    constructor(library: string);
+}
+/** Live CDM registry address resolution failed. */
+declare class ContractLiveAddressResolutionError extends ContractError {
+    readonly library: string | undefined;
+    readonly detail: unknown;
+    constructor(message: string, options?: {
+        library?: string;
+        detail?: unknown;
+        cause?: unknown;
+    });
+}
+/**
+ * A pre-flight `ReviveApi.call` dry-run reported failure. Thrown from the `.tx()`
+ * path before the extrinsic is built — prevents callers from paying gas on a
+ * transaction the chain already told us would revert.
+ *
+ * `dispatchError` carries the chain's encoded error (typically `ModuleError`,
+ * `ContractReverted`, `OutOfGas`, or `AccountNotMapped` — see the `Revive`
+ * pallet error variants).
+ */
+declare class ContractDryRunFailedError extends ContractError {
+    readonly methodName: string;
+    readonly dispatchError: unknown;
+    constructor(methodName: string, dispatchError: unknown);
+}
+/** viem-decoded standard or ABI-defined contract error. */
+interface DecodedContractRevert {
+    errorName: string;
+    args: readonly unknown[] | undefined;
+}
+/**
+ * Tagged-enum value surfaced on `QueryResult.value` when a contract reverts
+ * via the REVERT flag. The discriminant is intentionally distinct from
+ * `pallet-revive`'s bare `{ type: "ContractReverted" }` dispatch-error variant,
+ * which is the other path that can populate `QueryResult.value` on failure.
+ */
+interface ContractRevertInfo {
+    type: "ContractRevertedWithPayload";
+    data: HexString;
+    reason?: string;
+    decoded?: DecodedContractRevert;
+}
+/** A contract call returned with the `REVERT` flag set on a dispatched-OK call. */
+declare class ContractRevertedError extends ContractError {
+    readonly methodName: string;
+    readonly data: HexString;
+    readonly reason?: string;
+    readonly decoded?: DecodedContractRevert;
+    constructor(methodName: string, data: HexString, info?: {
+        reason?: string;
+        decoded?: DecodedContractRevert;
+    });
+}
 
 /**
  * Result of a `Revive.call` extrinsic — present on the typed API as
@@ -202,7 +276,8 @@ declare function createContractRuntimeFromClient<TDescriptor>(client: PolkadotCl
  * @param address - The SS58 address of the account to map.
  * @param signer - A signer matching `address`.
  * @param options - Optional timeout / status callback (forwarded to the underlying tx).
- * @returns The `TxResult` from the mapping extrinsic, or `null` if already mapped.
+ * @returns A `Result`: `ok(TxResult)` from the mapping extrinsic, `ok(null)` if already mapped,
+ *   or `err(TxError)` on failure. Delegates to `@parity/product-sdk-tx`'s `ensureAccountMapped`.
  *
  * @example
  * ```ts
@@ -216,7 +291,7 @@ declare function createContractRuntimeFromClient<TDescriptor>(client: PolkadotCl
 declare function ensureContractAccountMapped(runtime: ContractRuntime, address: SS58String, signer: PolkadotSigner, options?: {
     timeoutMs?: number;
     onStatus?: (s: string) => void;
-}): Promise<TxResult | null>;
+}): Promise<Result<TxResult | null, TxError>>;
 
 type CdmJsonDependencyVersion = number | string;
 /**
@@ -402,9 +477,13 @@ type Contract<C extends ContractDef> = {
          * Resolves at best-block by default (configurable via `waitFor`).
          *
          * Signer is resolved from: explicit `{ signer }` option → signerManager →
-         * defaultSigner. Throws {@link ContractSignerMissingError} if none available.
+         * defaultSigner.
+         *
+         * @returns A {@link Result}: `ok(TxResult)` once included/finalized, or `err`
+         *   carrying a `ContractError` (no signer available, pre-submit dry-run failed,
+         *   or the call reverted) or a `TxError` (submission/dispatch failure).
          */
-        tx: (...args: [...C["methods"][K]["args"], opts?: TxOptions]) => Promise<TxResult>;
+        tx: (...args: [...C["methods"][K]["args"], opts?: TxOptions]) => Promise<Result<TxResult, ContractError | TxError>>;
         /**
          * Prepare the method as a {@link BatchableCall} — returns the same
          * submittable that `.tx()` would build, but without signing or
@@ -423,14 +502,17 @@ type Contract<C extends ContractDef> = {
          * omitted, `.prepare()` runs a `ReviveApi.call` dry-run (same as
          * `.tx()`) against the fallback origin to fill the missing
          * field(s) — pass both to skip the dry-run entirely. A failing
-         * dry-run throws {@link ContractDryRunFailedError} before the
+         * dry-run yields `err({@link ContractDryRunFailedError})` before the
          * call is constructed.
          *
          * `.prepare()` does not require a signer; the batch's signer
          * replaces the dispatched origin at submission.
+         *
+         * @returns A {@link Result}: `ok(BatchableCall)`, or `err(ContractError)` if the
+         *   pre-build dry-run fails or the call reverts.
          */
-        prepare: (...args: [...C["methods"][K]["args"], opts?: PrepareOptions]) => Promise<BatchableCall>;
+        prepare: (...args: [...C["methods"][K]["args"], opts?: PrepareOptions]) => Promise<Result<BatchableCall, ContractError>>;
     };
 };
 
-export { type AbiEntry as A, type CdmJson as C, type LiveContractResolutionOptions as L, type PrepareOptions as P, type QueryOptions as Q, type ReviveDryRunCall as R, type TxOptions as T, type ContractRuntime as a, type ContractManagerOptions as b, type ContractDefaults as c, type ContractRuntimeOptions as d, type Contracts as e, type Contract as f, type ContractDef as g, type ContractOptions as h, type AbiParam as i, type CdmJsonContract as j, type CdmJsonDependencyVersion as k, type ContractDryRunAt as l, type QueryResult as m, type ReviveDryRunCallOptions as n, type ReviveDryRunResult as o, type ReviveTypedApi as p, createContractRuntime as q, createContractRuntimeFromClient as r, ensureContractAccountMapped as s };
+export { type AbiEntry as A, type CdmJson as C, type DecodedContractRevert as D, type LiveContractResolutionOptions as L, type PrepareOptions as P, type QueryOptions as Q, type ReviveDryRunCall as R, type TxOptions as T, type ContractRuntime as a, type ContractManagerOptions as b, type ContractDefaults as c, type ContractRuntimeOptions as d, ContractError as e, type Contracts as f, type Contract as g, type ContractDef as h, type ContractOptions as i, type AbiParam as j, type CdmJsonContract as k, type CdmJsonDependencyVersion as l, type ContractDryRunAt as m, ContractDryRunFailedError as n, ContractLiveAddressResolutionError as o, ContractNotFoundError as p, type ContractRevertInfo as q, ContractRevertedError as r, ContractSignerMissingError as s, type QueryResult as t, type ReviveDryRunCallOptions as u, type ReviveDryRunResult as v, type ReviveTypedApi as w, createContractRuntime as x, createContractRuntimeFromClient as y, ensureContractAccountMapped as z };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@parity/product-sdk-contracts",
   "description": "Typed contract interactions on Polkadot Asset Hub",
-  "version": "0.8.3",
+  "version": "0.9.1",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -17,6 +17,10 @@
     "./pvm": {
       "types": "./dist/pvm.d.ts",
       "import": "./dist/pvm.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js"
     }
   },
   "files": [
@@ -30,11 +34,13 @@
     "@polkadot-labs/hdkd-helpers": "^0.0.30",
     "polkadot-api": "^2.1.6",
     "viem": "^2.52.0",
-    "@parity/product-sdk-signer": "0.9.0",
-    "@parity/product-sdk-keys": "0.3.13",
     "@parity/product-sdk-address": "0.1.1",
     "@parity/product-sdk-logger": "0.1.1",
-    "@parity/product-sdk-tx": "0.2.17"
+    "@parity/product-sdk-errors": "0.2.0",
+    "@parity/result": "0.2.0",
+    "@parity/product-sdk-keys": "0.3.15",
+    "@parity/product-sdk-signer": "0.11.0",
+    "@parity/product-sdk-tx": "0.3.1"
   },
   "devDependencies": {
     "tsup": "^8.5.1",
@@ -45,6 +51,7 @@
   "scripts": {
     "build": "tsup",
     "clean": "rm -rf dist",
-    "test": "vitest run"
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.typecheck.json"
   }
 }