@parity/product-sdk-contracts 0.0.0-dev.312.0

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-Dtu4IsSh.d.ts

@@ -0,0 +1,552 @@
+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);
+}
+/**
+ * A dry-run / transaction origin was not a valid SS58 address.
+ *
+ * Raised *before* the origin reaches PAPI's `AccountId` codec, which would
+ * otherwise fail deep inside the encode stack with a bare `Invalid checksum`
+ * and no hint that the origin was the wrong format. The most common mistake
+ * is passing the account's H160 (`0x…`): pallet-revive derives the H160
+ * `msg.sender` *from* the SS58 origin, so the origin itself must be SS58 —
+ * the message calls that case out with a `h160ToSs58` pointer.
+ *
+ * Deliberately a validation error, not an auto-conversion: silently converting
+ * an H160 here would hide which account the caller believes is calling.
+ */
+declare class ContractInvalidOriginError extends ContractError {
+    /** The rejected origin value. */
+    readonly origin: string;
+    constructor(origin: 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
+ * `api.tx.Revive.call(args)`. Returned object is a PAPI submittable that
+ * `submitAndWatch` consumes natively.
+ *
+ * `dest` is an H160 hex string and `data` is a raw `Uint8Array`: this matches
+ * what `polkadot-api` ≥2.0 codecs accept and produce. The class-based
+ * `Binary` / `FixedSizeBinary` wrappers from `@polkadot-api/substrate-bindings`
+ * 0.12 are *not* accepted by PAPI 2.x's compatibility check.
+ */
+type ReviveCallTx = (args: {
+    dest: HexString;
+    value: bigint;
+    weight_limit: Weight;
+    storage_deposit_limit: bigint;
+    data: Uint8Array;
+}) => SubmittableTransaction;
+/**
+ * Dry-run result returned by `ReviveApi.call`. Mirrors the shape exposed by
+ * descriptors (`paseo-asset-hub`, `polkadot-asset-hub`, `kusama-asset-hub`).
+ *
+ * `data` is a raw `Uint8Array` because PAPI ≥2.0 dropped the `Binary` class
+ * wrapper for `Vec<u8>` codecs.
+ */
+interface ReviveDryRunResult {
+    weight_consumed: Weight;
+    weight_required: Weight;
+    storage_deposit: {
+        type: "Refund" | "Charge";
+        value: bigint;
+    };
+    max_storage_deposit: {
+        type: "Refund" | "Charge";
+        value: bigint;
+    };
+    gas_consumed: bigint;
+    /**
+     * `success: true` carries `{ flags, data }`; `success: false` carries the
+     * dispatch error as the chain encoded it.
+     */
+    result: {
+        success: true;
+        value: {
+            flags: number;
+            data: Uint8Array;
+        };
+    } | {
+        success: false;
+        value: unknown;
+    };
+}
+/**
+ * Block reference used to target `ReviveApi.call` dry-runs. Matches PAPI's
+ * runtime-call `at` option: `"best"`, `"finalized"`, or a block hash.
+ */
+type ContractDryRunAt = "best" | "finalized" | HexString;
+/**
+ * Per-call options accepted by {@link ReviveDryRunCall}.
+ *
+ * Note on the trailing `options` arg: pallet-revive's Rust runtime API
+ * `ReviveApi::call` only takes the 6 positional args (origin, dest, value,
+ * gas_limit, storage_deposit_limit, input_data). This 7th `options` object
+ * is **injected by PAPI** on every `api.apis.X.Y` runtime-API call via its
+ * `WithCallOptions` type wrapper (see
+ * `polkadot-api/packages/client/src/viewFns.ts:9-11` upstream — defined
+ * as `WithCallOptions$2` in the bundled `.d.ts` due to TS bundler suffixing).
+ * It never reaches the Rust side — PAPI's `viewFns.ts:38-41` consumes it in
+ * JS, reads `options.at`, resolves it to a concrete block hash via the
+ * chain-head's runtime context, and uses that hash on the JSON-RPC
+ * `state_call` invocation. The 6-arg payload sent over the wire is
+ * unchanged.
+ */
+interface ReviveDryRunCallOptions {
+    at?: ContractDryRunAt;
+}
+/** Structural shape consumed by `ContractManager` / `createContract`. */
+interface ReviveTypedApi {
+    tx: {
+        Revive: {
+            call: ReviveCallTx;
+            map_account(): SubmittableTransaction;
+        };
+    };
+    query: {
+        Revive: {
+            OriginalAccount: {
+                getValue(address: HexString): Promise<SS58String | undefined>;
+            };
+        };
+    };
+    apis: {
+        ReviveApi: {
+            call(origin: SS58String, dest: HexString, value: bigint, gas_limit: Weight | undefined, storage_deposit_limit: bigint | undefined, input_data: Uint8Array, options?: ReviveDryRunCallOptions): Promise<ReviveDryRunResult>;
+        };
+    };
+}
+/**
+ * Signature of a `ReviveApi.call` dry-run, used by the wrapped contract layer
+ * to estimate weight + storage deposit and surface revert / OOG /
+ * `AccountNotMapped` failures before a tx is signed.
+ *
+ * Identical to `ReviveTypedApi.apis.ReviveApi.call`, but extracted so the
+ * runtime can route this single hot call through PAPI's *unsafe* API
+ * (skipping compatibility-token checks) on production runtimes whose
+ * descriptors lag a chain upgrade — every other surface still uses the
+ * compat-checked typed API.
+ */
+type ReviveDryRunCall = (origin: SS58String, dest: HexString, value: bigint, gas_limit: Weight | undefined, storage_deposit_limit: bigint | undefined, input_data: Uint8Array, options?: ReviveDryRunCallOptions) => Promise<ReviveDryRunResult>;
+/**
+ * Runtime handle that drives queries and transactions against a
+ * pallet-revive-capable chain.
+ *
+ * @example
+ * ```ts
+ * import { createChainClient } from "@parity/product-sdk-chain-client";
+ * import { paseo_asset_hub } from "@parity/product-sdk-descriptors/paseo-asset-hub";
+ * import { createContractRuntimeFromClient } from "@parity/product-sdk-contracts";
+ *
+ * const client = await createChainClient({
+ *     chains: { assetHub: paseo_asset_hub },
+ * });
+ * const runtime = createContractRuntimeFromClient(client.raw.assetHub, paseo_asset_hub);
+ * ```
+ */
+interface ContractRuntime {
+    readonly api: ReviveTypedApi;
+    /**
+     * Dry-run entry point. Production factories route this through the
+     * *unsafe* API to avoid compatibility-token failures when the descriptor
+     * trails a runtime upgrade. The {@link createContractRuntime} test factory
+     * delegates to `api.apis.ReviveApi.call`.
+     *
+     * The runtime default `at` (set via {@link ContractRuntimeOptions.at} on
+     * the factory) is applied when the caller does not pass an explicit
+     * `options.at`. `.query()` per-call overrides flow through this argument.
+     */
+    readonly dryRunCall: ReviveDryRunCall;
+}
+/** Options for {@link createContractRuntime} / {@link createContractRuntimeFromClient}. */
+interface ContractRuntimeOptions {
+    /**
+     * Block to target for `ReviveApi.call` dry-runs. Defaults to `"best"`
+     * so contract `.query()` reads observe the same state as transactions
+     * resolved at best-block (the product-sdk `.tx()` default). Set to
+     * `"finalized"` to read the canonical, lagged state, or to a specific
+     * block hash to pin reads to a historical block. Can be overridden per
+     * call via `QueryOptions.at`.
+     */
+    at?: ContractDryRunAt;
+}
+/**
+ * Wrap a typed PAPI API as a `ContractRuntime`. Intended for tests and
+ * advanced setups where the caller already holds a typed API. Routes the
+ * dry-run through the typed (compatibility-token-checked) `ReviveApi.call`
+ * — fine for mocks but susceptible to `Incompatible runtime entry` errors
+ * on a live chain whose descriptor lags. Prefer
+ * {@link createContractRuntimeFromClient} for production use.
+ */
+declare function createContractRuntime(api: ReviveTypedApi, options?: ContractRuntimeOptions): ContractRuntime;
+/**
+ * Build a `ContractRuntime` from a raw `PolkadotClient` plus its descriptor.
+ *
+ * The typed API powers `tx.Revive.call`, `tx.Revive.map_account`, and
+ * `query.Revive.OriginalAccount` (extrinsics + storage are tolerant of
+ * descriptor drift). The runtime-API dry-run, which is *not* tolerant of
+ * descriptor drift on PAPI's compat-token path, is routed through
+ * `client.getUnsafeApi()` — bypassing the compat check while preserving
+ * argument and return shapes.
+ *
+ * Use this on every production code path that calls a contract's `.tx()` or
+ * `.query()` against a live chain.
+ *
+ * @example
+ * ```ts
+ * import { paseo_asset_hub } from "@parity/product-sdk-descriptors/paseo-asset-hub";
+ * import { createContractRuntimeFromClient } from "@parity/product-sdk-contracts";
+ *
+ * const runtime = createContractRuntimeFromClient(rawClient, paseo_asset_hub);
+ * ```
+ */
+declare function createContractRuntimeFromClient<TDescriptor>(client: PolkadotClient, descriptor: TDescriptor, options?: ContractRuntimeOptions): ContractRuntime;
+/**
+ * Ensure the SS58 account is mapped to its derived H160 on `pallet-revive`.
+ *
+ * `pallet-revive` requires every signing account to have a registered
+ * `OriginalAccount` mapping before the runtime accepts its `Revive.call`
+ * extrinsics. The mapping is one-time and cheap. This helper:
+ *
+ *   1. Reads `Revive.OriginalAccount` for the H160 derived from `address`.
+ *   2. Returns `null` if already mapped (idempotent fast-path).
+ *   3. Otherwise submits `Revive.map_account()` and waits for inclusion.
+ *
+ * Call this once per signing account at app startup — after that, every
+ * subsequent `contract.<method>.tx({ signer })` against the same chain will
+ * succeed without further mapping work.
+ *
+ * @param runtime - The contract runtime (typically `createContractRuntime(...)`).
+ * @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 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
+ * import { createContractRuntime, ensureContractAccountMapped } from "@parity/product-sdk-contracts";
+ *
+ * const runtime = createContractRuntime(client.getTypedApi(paseo_asset_hub));
+ * await ensureContractAccountMapped(runtime, signerManager.getState().selectedAccount!.address, signer);
+ * // now safe to call contract.<method>.tx({ signer })
+ * ```
+ */
+declare function ensureContractAccountMapped(runtime: ContractRuntime, address: SS58String, signer: PolkadotSigner, options?: {
+    timeoutMs?: number;
+    onStatus?: (s: string) => void;
+}): Promise<Result<TxResult | null, TxError>>;
+/**
+ * Read-only probe: is `address` mapped on `pallet-revive`?
+ *
+ * The read half of {@link ensureContractAccountMapped}: checks
+ * `Revive.OriginalAccount` for the H160 derived from `address` without
+ * needing a signer, so it can never submit a transaction or prompt a wallet.
+ * Use it for readiness checks ("can this account make contract calls right
+ * now?") from paths that must stay side-effect free.
+ *
+ * @param runtime - The contract runtime (typically `createContractRuntime(...)`).
+ * @param address - The SS58 address to check.
+ * @returns A {@link Result}: `ok(true)` when the mapping exists, `ok(false)` when it
+ *   doesn't, or `err(ContractError)` when the address can't be converted or the
+ *   storage query fails (underlying error attached as `cause`).
+ */
+declare function isContractAccountMapped(runtime: ContractRuntime, address: SS58String): Promise<Result<boolean, ContractError>>;
+
+type CdmJsonDependencyVersion = number | string;
+/**
+ * A deployed contract's on-chain address, ABI, and optional metadata CID.
+ *
+ * `metadataCid` is optional because real-world cdm.json files (e.g.
+ * `paritytech/playground-cli/cdm.json`) don't always include it — only
+ * `version`, `address`, and `abi` are load-bearing for `getContract()`.
+ */
+interface CdmJsonContract {
+    version: number;
+    address: HexString;
+    abi: AbiEntry[];
+    metadataCid?: string;
+}
+/** A project's `cdm.json` manifest. */
+interface CdmJson {
+    dependencies: Record<string, CdmJsonDependencyVersion>;
+    contracts?: Record<string, CdmJsonContract>;
+    registry?: HexString;
+}
+/** An ABI parameter or return value, with support for nested tuple and struct types. */
+interface AbiParam {
+    name: string;
+    type: string;
+    components?: AbiParam[];
+}
+/** One function, constructor, or event in a contract's ABI. */
+interface AbiEntry {
+    type: string;
+    name?: string;
+    inputs: AbiParam[];
+    outputs?: AbiParam[];
+    stateMutability?: string;
+}
+/** Per-contract definition shape — generated into `.cdm/contracts.d.ts` via module augmentation. */
+interface ContractDef {
+    methods: Record<string, {
+        args: any[];
+        response: any;
+    }>;
+}
+/**
+ * Augmentable interface extended by codegen with per-contract method types.
+ *
+ * After running `cdm install`, a generated `.d.ts` file augments this
+ * interface so that `ContractManager.getContract()` returns fully-typed
+ * contract handles.
+ */
+interface Contracts {
+}
+/**
+ * Result from a read-only contract query.
+ *
+ * On success, `value` is the decoded response and `gasRequired` is the
+ * `Weight` consumed by `ReviveApi.call`'s dry-run — consumable directly by
+ * `Revive.call`'s `weight_limit` parameter.
+ *
+ * On failure, `value` carries the raw dispatch-error payload the runtime
+ * returned (typically a tagged enum like `{ type: "Module", value: ... }`,
+ * `{ type: "ContractReverted" }`, or `{ type: "AccountNotMapped" }` — see the
+ * `Revive` pallet error variants). Surfacing it lets callers narrow on shape
+ * to diagnose silent failures instead of seeing `undefined` and being unable
+ * to tell whether the contract reverted, gas estimation failed, or the
+ * dry-run never ran. `gasRequired` is still populated when the runtime
+ * reported a weight even though the call ultimately failed (e.g. a revert
+ * after partial execution); it's optional because some failure modes don't
+ * carry one.
+ */
+type QueryResult<T> = {
+    success: true;
+    value: T;
+    gasRequired: Weight;
+} | {
+    success: false;
+    value: unknown;
+    gasRequired?: Weight;
+};
+/** Options for query calls — passed as the last argument after positional args. */
+interface QueryOptions {
+    origin?: SS58String;
+    value?: bigint;
+    /**
+     * Override the block targeted by this dry-run. Accepts `"best"`,
+     * `"finalized"`, or a block hash. Defaults to the runtime's configured
+     * `at` (see `createContractRuntimeFromClient({ at })`), which is `"best"`
+     * unless overridden — chosen so `.query()` observes the same state as
+     * `.tx()` resolved at best-block.
+     */
+    at?: ContractDryRunAt;
+}
+/** Options for transaction calls — passed as the last argument after positional args. */
+interface TxOptions extends SubmitOptions {
+    signer?: PolkadotSigner;
+    origin?: SS58String;
+    value?: bigint;
+    gasLimit?: Weight;
+    storageDepositLimit?: bigint;
+    /**
+     * Override the block targeted by the sizing dry-run that `.tx()` runs
+     * before submission. Accepts `"best"`, `"finalized"`, or a block hash.
+     * Defaults to the runtime's configured `at` (see
+     * `createContractRuntimeFromClient({ at })`), which is `"best"` unless
+     * overridden. No-op when both `gasLimit` and `storageDepositLimit` are
+     * passed — the dry-run is skipped entirely in that case.
+     */
+    at?: ContractDryRunAt;
+}
+/**
+ * Options for `.prepare()` — subset of {@link TxOptions}.
+ *
+ * Signer and submission lifecycle options (`signer`, `waitFor`, `timeoutMs`,
+ * `mortalityPeriod`, `onStatus`) are intentionally absent — those belong to
+ * the batch submission, not the individual prepared call.
+ */
+interface PrepareOptions {
+    origin?: SS58String;
+    value?: bigint;
+    gasLimit?: Weight;
+    storageDepositLimit?: bigint;
+    /**
+     * Override the block targeted by the sizing dry-run. See
+     * {@link TxOptions.at}.
+     */
+    at?: ContractDryRunAt;
+}
+/** Mutable defaults shared across all contract handles from a manager. */
+interface ContractDefaults {
+    origin?: SS58String;
+    signer?: PolkadotSigner;
+    signerManager?: SignerManager;
+}
+/**
+ * Options for {@link createContract} and base for {@link ContractManagerOptions}.
+ *
+ * Signer resolution order (highest wins):
+ * 1. Explicit override in call options
+ * 2. `signerManager` (current logged-in account)
+ * 3. Static `defaultSigner` / `defaultOrigin`
+ */
+interface ContractOptions {
+    /**
+     * Signer manager from `@parity/product-sdk-signer`. When provided, the
+     * currently selected account is used as the default signer and origin
+     * for all contract interactions. Resolved at call time so account
+     * switches are reflected immediately.
+     */
+    signerManager?: SignerManager;
+    /** Static fallback caller address for queries. */
+    defaultOrigin?: SS58String;
+    /** Static fallback signer for transactions. */
+    defaultSigner?: PolkadotSigner;
+}
+/** Options for {@link ContractManager} construction. */
+type ContractManagerOptions = ContractOptions;
+/** Options for resolving installed CDM contract addresses from the live CDM registry. */
+interface LiveContractResolutionOptions {
+    /** CDM registry contract address. Defaults to `cdm.json.registry`. */
+    registryAddress?: HexString;
+    /** Subset of installed libraries to resolve. Defaults to every contract in the manifest. */
+    libraries?: readonly string[];
+    /** Origin used for CDM registry dry-run queries. Defaults to `defaultOrigin` in manager helpers. */
+    registryOrigin?: SS58String;
+}
+/**
+ * A typed contract handle where each ABI method exposes `.query()` and `.tx()`.
+ *
+ * Both accept the method's positional arguments followed by an optional
+ * options object as the last argument.
+ */
+type Contract<C extends ContractDef> = {
+    [K in keyof C["methods"]]: {
+        /**
+         * Dry-run the method (read-only). Does not submit a transaction or
+         * cost gas. Returns the decoded response and estimated gas required.
+         *
+         * Origin is resolved from: explicit `{ origin }` option → signerManager →
+         * defaultOrigin → pallet-revive account fallback.
+         */
+        query: (...args: [...C["methods"][K]["args"], opts?: QueryOptions]) => Promise<QueryResult<C["methods"][K]["response"]>>;
+        /**
+         * Sign, submit, and watch the method as an on-chain transaction.
+         * Resolves at best-block by default (configurable via `waitFor`).
+         *
+         * Signer is resolved from: explicit `{ signer }` option → signerManager →
+         * 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<Result<TxResult, ContractError | TxError>>;
+        /**
+         * Prepare the method as a {@link BatchableCall} — returns the same
+         * submittable that `.tx()` would build, but without signing or
+         * submitting. Consumable directly by `batchSubmitAndWatch` from
+         * `@parity/product-sdk-tx`:
+         *
+         * ```ts
+         * import { batchSubmitAndWatch } from "@parity/product-sdk-tx";
+         *
+         * const a = contract.transfer.prepare(addr1, 100n);
+         * const b = contract.transfer.prepare(addr2, 200n);
+         * await batchSubmitAndWatch([a, b], api, signer);
+         * ```
+         *
+         * Sizing: when either `gasLimit` or `storageDepositLimit` is
+         * 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 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<Result<BatchableCall, ContractError>>;
+    };
+};
+
+export { type AbiEntry as A, ensureContractAccountMapped as B, type CdmJson as C, type DecodedContractRevert as D, isContractAccountMapped as E, 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, ContractInvalidOriginError as o, ContractLiveAddressResolutionError as p, ContractNotFoundError as q, type ContractRevertInfo as r, ContractRevertedError as s, ContractSignerMissingError as t, type QueryResult as u, type ReviveDryRunCallOptions as v, type ReviveDryRunResult as w, type ReviveTypedApi as x, createContractRuntime as y, createContractRuntimeFromClient as z };