@parity/product-sdk-contracts 0.2.2 → 0.4.0

package/dist/index.d.ts

@@ -1,10 +1,187 @@
-import { PolkadotClient, HexString } from 'polkadot-api';
-import { InkSdk } from '@polkadot-api/sdk-ink';
-import { C as CdmJson, a as ContractManagerOptions, b as ContractDefaults, c as Contracts, d as Contract, e as ContractDef, A as AbiEntry, f as ContractOptions } from './codegen-BPDBGrJC.js';
-export { g as AbiParam, h as CdmJsonContract, i as CdmJsonTarget, P as PrepareOptions, Q as QueryOptions, j as QueryResult, T as TxOptions, k as generateContractTypes } from './codegen-BPDBGrJC.js';
+import { HexString, SS58String, PolkadotClient, PolkadotSigner } from 'polkadot-api';
+import { Weight, SubmittableTransaction, TxResult } from '@parity/product-sdk-tx';
 export { BatchableCall, TxResult } from '@parity/product-sdk-tx';
+import { C as CdmJson, a as ContractManagerOptions, b as ContractDefaults, c as Contracts, d as Contract, e as ContractDef, A as AbiEntry, f as ContractOptions } from './types-DJDMz91q.js';
+export { g as AbiParam, h as CdmJsonContract, i as CdmJsonTarget, P as PrepareOptions, Q as QueryOptions, j as QueryResult, T as TxOptions } from './types-DJDMz91q.js';
 import '@parity/product-sdk-signer';
 
+/**
+ * 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;
+    };
+}
+/** 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): 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) => 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 },
+ *     rpcs: { assetHub: ["wss://sys.ibp.network/asset-hub-paseo"] },
+ * });
+ * 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`.
+     */
+    readonly dryRunCall: ReviveDryRunCall;
+}
+/**
+ * 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): 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): 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 The `TxResult` from the mapping extrinsic, or `null` if already mapped.
+ *
+ * @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<TxResult | null>;
+
 /**
  * Manages typed contract interactions backed by a `cdm.json` manifest.
  *
@@ -15,21 +192,19 @@ import '@parity/product-sdk-signer';
  * @example
  * ```ts
  * import { createChainClient } from "@parity/product-sdk-chain-client";
- * import { createInkSdk } from "@polkadot-api/sdk-ink";
  * import { paseo_asset_hub } from "@parity/product-sdk-descriptors/paseo-asset-hub";
- * import { ContractManager } from "@parity/product-sdk-contracts";
+ * import { ContractManager, createContractRuntime } from "@parity/product-sdk-contracts";
  * import cdmJson from "./cdm.json";
  *
  * const client = await createChainClient({
  *     chains: { assetHub: paseo_asset_hub },
- *     rpcs: { assetHub: ["wss://sys.ibp.network/asset-hub-paseo"] },
+ *     rpcs: { assetHub: ["wss://paseo-asset-hub-next-rpc.polkadot.io"] },
  * });
- * const inkSdk = createInkSdk(client.raw.assetHub, { atBest: true });
- * const manager = new ContractManager(cdmJson, inkSdk, {
- *     signerManager: signerManager, // from @parity/product-sdk-signer
+ * const runtime = createContractRuntime(client.assetHub);
+ * const manager = new ContractManager(cdmJson, runtime, {
+ *     signerManager,
  * });
  *
- * // Uses the host's logged-in account automatically
  * const counter = manager.getContract("@example/counter");
  * const { value } = await counter.getCount.query();
  * await counter.increment.tx();
@@ -38,41 +213,25 @@ import '@parity/product-sdk-signer';
 declare class ContractManager {
     private cdmJson;
     private targetHash;
-    private inkSdk;
+    private runtime;
     private defaults;
-    constructor(cdmJson: CdmJson, inkSdk: InkSdk, options?: ContractManagerOptions);
+    constructor(cdmJson: CdmJson, runtime: ContractRuntime, options?: ContractManagerOptions);
     /** Update the default origin, signer, or signerManager used by all contract handles. */
     setDefaults(defaults: ContractDefaults): void;
     /**
-     * Create a ContractManager from a raw `PolkadotClient`.
-     *
-     * Convenience factory that creates the InkSdk internally via dynamic import
-     * of `@polkadot-api/sdk-ink`. The ~4 MB sdk-ink metadata is loaded lazily
-     * only when this method is called.
+     * Create a `ContractManager` from a raw `PolkadotClient`.
      *
-     * For size-sensitive apps, prefer the constructor with a pre-created `InkSdk`
-     * to control exactly when `@polkadot-api/sdk-ink` is loaded.
+     * Convenience factory: builds a `ContractRuntime` internally from the
+     * client's typed API. Requires that the chain's typed API exposes the
+     * `Revive` pallet and `ReviveApi` runtime API (Asset Hub Paseo /
+     * Polkadot / Kusama).
      *
      * @param cdmJson - The CDM manifest.
-     * @param client - A `PolkadotClient` for the chain where contracts are deployed (e.g., `client.raw.assetHub`).
+     * @param client - A `PolkadotClient` for the chain where contracts are deployed.
+     * @param descriptor - The chain descriptor used to derive the typed API.
      * @param options - Optional configuration (signerManager, defaults).
-     *
-     * @example
-     * ```ts
-     * import { createChainClient } from "@parity/product-sdk-chain-client";
-     * import { paseo_asset_hub } from "@parity/product-sdk-descriptors/paseo-asset-hub";
-     * import { ContractManager } from "@parity/product-sdk-contracts";
-     *
-     * const client = await createChainClient({
-     *     chains: { assetHub: paseo_asset_hub },
-     *     rpcs: { assetHub: ["wss://sys.ibp.network/asset-hub-paseo"] },
-     * });
-     * const manager = await ContractManager.fromClient(cdmJson, client.raw.assetHub, {
-     *     signerManager,
-     * });
-     * ```
      */
-    static fromClient(cdmJson: CdmJson, client: PolkadotClient, options?: ContractManagerOptions): Promise<ContractManager>;
+    static fromClient<TDescriptor>(cdmJson: CdmJson, client: PolkadotClient, descriptor: TDescriptor, options?: ContractManagerOptions): ContractManager;
     private getContractData;
     /**
      * Get a typed contract handle.
@@ -87,36 +246,43 @@ declare class ContractManager {
     getContract(library: string): Contract<ContractDef>;
     /** Get the on-chain address of an installed contract. */
     getAddress(library: string): HexString;
+    /**
+     * Get the underlying {@link ContractRuntime} backing this manager.
+     *
+     * Useful when a consumer needs to call helpers that take a runtime
+     * directly — most commonly {@link ensureContractAccountMapped} at app
+     * boot. Avoids the alternative of building a second runtime against the
+     * same client and descriptor.
+     */
+    getRuntime(): ContractRuntime;
 }
 /**
- * Create a contract handle from a raw address and ABI — no `cdm.json` needed.
+ * Create a contract handle from a raw H160 address and ABI — no `cdm.json` needed.
  *
  * @example
  * ```ts
- * import { createInkSdk } from "@polkadot-api/sdk-ink";
+ * import { createContractRuntime, createContract } from "@parity/product-sdk-contracts";
  *
- * const inkSdk = createInkSdk(client.raw.assetHub, { atBest: true });
- * const counter = createContract(inkSdk, "0xC472...", abi, {
- *     signerManager: signerManager,
- * });
+ * const runtime = createContractRuntime(client.assetHub);
+ * const counter = createContract(runtime, "0xC472...", abi, { signerManager });
  * await counter.getCount.query();
  * await counter.increment.tx();
  * ```
  */
-declare function createContract(inkSdk: InkSdk, address: HexString, abi: AbiEntry[], options?: ContractOptions): Contract<ContractDef>;
+declare function createContract(runtime: ContractRuntime, address: HexString, abi: AbiEntry[], options?: ContractOptions): Contract<ContractDef>;
 /**
- * Create a contract handle from a raw `PolkadotClient`, address, and ABI.
+ * Create a contract handle from a raw `PolkadotClient`, descriptor, address, and ABI.
  *
- * Convenience wrapper that creates the InkSdk internally via dynamic import.
- * For size-sensitive apps, use {@link createContract} with a pre-created `InkSdk`.
+ * Convenience wrapper that builds the `ContractRuntime` from the client's
+ * typed API. The chain must expose `Revive` + `ReviveApi`.
  *
  * @example
  * ```ts
- * const counter = await createContractFromClient(client.raw.assetHub, "0xC472...", abi);
+ * const counter = createContractFromClient(client, paseo_asset_hub, "0xC472...", abi);
  * const { value } = await counter.getCount.query();
  * ```
  */
-declare function createContractFromClient(client: PolkadotClient, address: HexString, abi: AbiEntry[], options?: ContractOptions): Promise<Contract<ContractDef>>;
+declare function createContractFromClient<TDescriptor>(client: PolkadotClient, descriptor: TDescriptor, address: HexString, abi: AbiEntry[], options?: ContractOptions): Contract<ContractDef>;
 
 /** Base class for all contract errors. Use `instanceof ContractError` to catch any contract-related error. */
 declare class ContractError extends Error {
@@ -132,5 +298,19 @@ declare class ContractNotFoundError extends ContractError {
     readonly targetHash: string;
     constructor(library: string, targetHash: string);
 }
+/**
+ * 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);
+}
 
-export { AbiEntry, CdmJson, Contract, ContractDef, ContractDefaults, ContractError, ContractManager, ContractManagerOptions, ContractNotFoundError, ContractOptions, ContractSignerMissingError, Contracts, createContract, createContractFromClient };
+export { AbiEntry, CdmJson, Contract, ContractDef, ContractDefaults, ContractDryRunFailedError, ContractError, ContractManager, ContractManagerOptions, ContractNotFoundError, ContractOptions, type ContractRuntime, ContractSignerMissingError, Contracts, type ReviveDryRunCall, type ReviveDryRunResult, type ReviveTypedApi, createContract, createContractFromClient, createContractRuntime, createContractRuntimeFromClient, ensureContractAccountMapped };