@parity/product-sdk-contracts 0.5.0 → 0.6.0

package/README.md

@@ -113,6 +113,31 @@ Without this, every fresh-account `.tx()` fails the pre-flight dry-run with `Acc
 
 Every `.tx()` runs a `ReviveApi.call` dry-run first to size `weight_limit` / `storage_deposit_limit` and to fail fast on revert, OOG, or `AccountNotMapped` before any signing happens. Throws `ContractDryRunFailedError` (with the chain's `dispatchError`) when the dry-run reports failure — caller pays no gas on a tx the chain already rejected. Pass both `gasLimit` and `storageDepositLimit` overrides on `TxOptions` to skip the dry-run entirely.
 
+## Query block selection
+
+`.query()` and the `.tx()` / `.prepare()` sizing dry-runs target best-block by default, matching `submitAndWatch`'s default resolution. This keeps reads consistent with the state a freshly-submitted transaction observes.
+
+Override per call via `QueryOptions.at`, `TxOptions.at`, or `PrepareOptions.at` — each accepts `"best"`, `"finalized"`, or a block hash:
+
+```ts
+await counter.getCount.query();                    // best-block (default)
+await counter.getCount.query({ at: "finalized" }); // canonical, lagged
+await counter.getCount.query({ at: blockHash });   // pin to a historical block
+
+await counter.increment.tx({ at: "finalized" });   // size the dry-run against finalized
+await counter.increment.prepare({ at: blockHash }); // pin the batched call's sizing dry-run
+```
+
+`.tx({ at })` / `.prepare({ at })` is a no-op when both `gasLimit` and `storageDepositLimit` overrides are supplied — the sizing dry-run is skipped entirely in that case.
+
+Change the runtime default by passing `{ at }` to the factory:
+
+```ts
+const runtime = createContractRuntimeFromClient(client.raw.assetHub, paseo_asset_hub, {
+    at: "finalized", // read finalized state by default
+});
+```
+
 ## Batching with `.prepare()`
 
 Use `.prepare()` to build `BatchableCall` handles consumable by `batchSubmitAndWatch` from `@parity/product-sdk-tx`. Combine multiple contract calls — or contract calls mixed with other Asset Hub transactions — into a single atomic `Utility.batch_all` extrinsic.

package/dist/codegen.d.ts

@@ -1,4 +1,4 @@
-import { A as AbiEntry } from './types-BdHp-xWt.js';
+import { A as AbiEntry } from './types-Bh0tqK9s.js';
 import 'polkadot-api';
 import '@parity/product-sdk-tx';
 import '@parity/product-sdk-signer';

package/dist/index.d.ts

@@ -1,187 +1,9 @@
-import { HexString, SS58String, PolkadotClient, PolkadotSigner } from 'polkadot-api';
-import { Weight, SubmittableTransaction, TxResult } from '@parity/product-sdk-tx';
+import { PolkadotClient, HexString } from 'polkadot-api';
+import { C as CdmJson, a as ContractRuntime, b as ContractManagerOptions, c as ContractDefaults, d as ContractRuntimeOptions, e as Contracts, f as Contract, g as ContractDef, A as AbiEntry, h as ContractOptions } from './types-Bh0tqK9s.js';
+export { i as AbiParam, j as CdmJsonContract, k as CdmJsonTarget, l as ContractDryRunAt, P as PrepareOptions, Q as QueryOptions, m as QueryResult, R as ReviveDryRunCall, n as ReviveDryRunCallOptions, o as ReviveDryRunResult, p as ReviveTypedApi, T as TxOptions, q as createContractRuntime, r as createContractRuntimeFromClient, s as ensureContractAccountMapped } from './types-Bh0tqK9s.js';
 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-BdHp-xWt.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-BdHp-xWt.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.
  *
@@ -231,7 +53,7 @@ declare class ContractManager {
      * @param descriptor - The chain descriptor used to derive the typed API.
      * @param options - Optional configuration (signerManager, defaults).
      */
-    static fromClient<TDescriptor>(cdmJson: CdmJson, client: PolkadotClient, descriptor: TDescriptor, options?: ContractManagerOptions): ContractManager;
+    static fromClient<TDescriptor>(cdmJson: CdmJson, client: PolkadotClient, descriptor: TDescriptor, options?: ContractManagerOptions & ContractRuntimeOptions): ContractManager;
     private getContractData;
     /**
      * Get a typed contract handle.
@@ -282,7 +104,7 @@ declare function createContract(runtime: ContractRuntime, address: HexString, ab
  * const { value } = await counter.getCount.query();
  * ```
  */
-declare function createContractFromClient<TDescriptor>(client: PolkadotClient, descriptor: TDescriptor, address: HexString, abi: AbiEntry[], options?: ContractOptions): Contract<ContractDef>;
+declare function createContractFromClient<TDescriptor>(client: PolkadotClient, descriptor: TDescriptor, address: HexString, abi: AbiEntry[], options?: ContractOptions & ContractRuntimeOptions): Contract<ContractDef>;
 
 /** Base class for all contract errors. Use `instanceof ContractError` to catch any contract-related error. */
 declare class ContractError extends Error {
@@ -312,5 +134,33 @@ declare class ContractDryRunFailedError extends ContractError {
     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;
+    });
+}
 
-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 };
+export { AbiEntry, CdmJson, Contract, ContractDef, ContractDefaults, ContractDryRunFailedError, ContractError, ContractManager, ContractManagerOptions, ContractNotFoundError, ContractOptions, type ContractRevertInfo, ContractRevertedError, ContractRuntime, ContractRuntimeOptions, ContractSignerMissingError, Contracts, type DecodedContractRevert, createContract, createContractFromClient };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { encodeFunctionData, decodeFunctionResult } from 'viem';
+import { encodeFunctionData, bytesToHex, decodeErrorResult, decodeFunctionResult } from 'viem';
 import { ensureAccountMapped, submitAndWatch } from '@parity/product-sdk-tx';
 import { seedToAccount } from '@parity/product-sdk-keys';
 import { createLogger } from '@parity/product-sdk-logger';
@@ -44,6 +44,27 @@ var ContractDryRunFailedError = class extends ContractError {
     this.dispatchError = dispatchError;
   }
 };
+function stringifyArg(arg) {
+  if (typeof arg === "bigint") return arg.toString();
+  return JSON.stringify(arg, (_, v) => typeof v === "bigint" ? v.toString() : v);
+}
+var ContractRevertedError = class extends ContractError {
+  methodName;
+  data;
+  reason;
+  decoded;
+  constructor(methodName, data, info) {
+    const suffix = info?.reason ?? (info?.decoded ? `${info.decoded.errorName}(${(info.decoded.args ?? []).map(stringifyArg).join(", ")})` : data);
+    super(
+      `Contract reverted in "${methodName}": ${suffix}. The transaction was not submitted.`
+    );
+    this.name = "ContractRevertedError";
+    this.methodName = methodName;
+    this.data = data;
+    this.reason = info?.reason;
+    this.decoded = info?.decoded;
+  }
+};
 
 // src/wrap.ts
 var log = createLogger("contracts");
@@ -95,6 +116,49 @@ function hexToBytes(hex) {
   }
   return out;
 }
+var REVERT_FLAG = 1;
+var PANIC_REASONS = {
+  "0x01": "assertion failed",
+  "0x11": "arithmetic overflow",
+  "0x12": "division by zero",
+  "0x21": "invalid enum value",
+  "0x22": "improperly encoded storage byte array",
+  "0x31": "pop on empty array",
+  "0x32": "array index out of bounds",
+  "0x41": "memory allocation overflow",
+  "0x51": "call to uninitialized internal function"
+};
+function decodeRevert(abi, data) {
+  const hex = bytesToHex(data);
+  const info = {
+    type: "ContractRevertedWithPayload",
+    data: hex
+  };
+  if (data.byteLength === 0) return info;
+  try {
+    const decoded = decodeErrorResult({
+      abi,
+      data: hex
+    });
+    info.decoded = {
+      errorName: decoded.errorName,
+      args: decoded.args
+    };
+    if (decoded.errorName === "Error" && typeof decoded.args?.[0] === "string") {
+      info.reason = decoded.args[0];
+    } else if (decoded.errorName === "Panic" && typeof decoded.args?.[0] === "bigint") {
+      const code = `0x${decoded.args[0].toString(16).padStart(2, "0")}`;
+      info.reason = PANIC_REASONS[code] ? `Panic: ${PANIC_REASONS[code]}` : `Panic(${code})`;
+    }
+    return info;
+  } catch {
+    try {
+      info.reason = new TextDecoder("utf-8", { fatal: true }).decode(data);
+    } catch {
+    }
+    return info;
+  }
+}
 function encodeCalldata(abi, methodName, args) {
   return encodeFunctionData({
     abi,
@@ -104,14 +168,10 @@ function encodeCalldata(abi, methodName, args) {
 }
 function decodeReturn(abi, methodName, returnData) {
   if (returnData.byteLength === 0) return void 0;
-  let hex = "0x";
-  for (let i = 0; i < returnData.byteLength; i++) {
-    hex += returnData[i].toString(16).padStart(2, "0");
-  }
   const decoded = decodeFunctionResult({
     abi,
     functionName: methodName,
-    data: hex
+    data: bytesToHex(returnData)
   });
   const entry = abi.find((e) => e.type === "function" && e.name === methodName);
   const outputs = entry?.outputs ?? [];
@@ -134,11 +194,17 @@ async function buildReviveCall(runtime, dest, abi, methodName, positionalArgs, o
       value,
       void 0,
       void 0,
-      calldata
+      calldata,
+      overrides?.at !== void 0 ? { at: overrides.at } : void 0
     );
     if (!dryRun.result.success) {
       throw new ContractDryRunFailedError(methodName, dryRun.result.value);
     }
+    if ((dryRun.result.value.flags & REVERT_FLAG) !== 0) {
+      const { data, reason, decoded } = decodeRevert(abi, dryRun.result.value.data);
+      log.debug("Contract reverted", { methodName, reason, errorName: decoded?.errorName });
+      throw new ContractRevertedError(methodName, data, { reason, decoded });
+    }
     weightLimit = weightLimit ?? dryRun.weight_required;
     if (storageDepositLimit === void 0) {
       storageDepositLimit = dryRun.storage_deposit.type === "Charge" ? dryRun.storage_deposit.value : 0n;
@@ -175,7 +241,8 @@ function wrapContract(runtime, address, abi, defaults) {
             value,
             void 0,
             void 0,
-            calldata
+            calldata,
+            overrides?.at !== void 0 ? { at: overrides.at } : void 0
           );
           if (!dryRun.result.success) {
             return {
@@ -184,6 +251,19 @@ function wrapContract(runtime, address, abi, defaults) {
               gasRequired: dryRun.weight_required
             };
           }
+          if ((dryRun.result.value.flags & REVERT_FLAG) !== 0) {
+            const info = decodeRevert(abi, dryRun.result.value.data);
+            log.debug("Contract reverted", {
+              methodName,
+              reason: info.reason,
+              errorName: info.decoded?.errorName
+            });
+            return {
+              success: false,
+              value: info,
+              gasRequired: dryRun.weight_required
+            };
+          }
           const decoded = decodeReturn(abi, methodName, dryRun.result.value.data);
           return {
             success: true,
@@ -237,20 +317,26 @@ function wrapContract(runtime, address, abi, defaults) {
     }
   });
 }
-function createContractRuntime(api) {
+function createContractRuntime(api, options) {
+  const defaultAt = options?.at ?? "best";
   return {
     api,
-    dryRunCall: (origin, dest, value, gas, deposit, data) => api.apis.ReviveApi.call(origin, dest, value, gas, deposit, data)
+    dryRunCall: (origin, dest, value, gas, deposit, data, callOpts) => api.apis.ReviveApi.call(origin, dest, value, gas, deposit, data, {
+      at: callOpts?.at ?? defaultAt
+    })
   };
 }
-function createContractRuntimeFromClient(client, descriptor) {
+function createContractRuntimeFromClient(client, descriptor, options) {
+  const defaultAt = options?.at ?? "best";
   const typed = client.getTypedApi(
     descriptor
   );
   const unsafe = client.getUnsafeApi();
   return {
     api: typed,
-    dryRunCall: (origin, dest, value, gas, deposit, data) => unsafe.apis.ReviveApi.call(origin, dest, value, gas, deposit, data)
+    dryRunCall: (origin, dest, value, gas, deposit, data, callOpts) => unsafe.apis.ReviveApi.call(origin, dest, value, gas, deposit, data, {
+      at: callOpts?.at ?? defaultAt
+    })
   };
 }
 async function ensureContractAccountMapped(runtime, address, signer, options) {
@@ -308,7 +394,7 @@ var ContractManager = class _ContractManager {
   static fromClient(cdmJson, client, descriptor, options) {
     return new _ContractManager(
       cdmJson,
-      createContractRuntimeFromClient(client, descriptor),
+      createContractRuntimeFromClient(client, descriptor, options),
       options
     );
   }
@@ -349,13 +435,13 @@ function createContract(runtime, address, abi, options) {
 }
 function createContractFromClient(client, descriptor, address, abi, options) {
   return createContract(
-    createContractRuntimeFromClient(client, descriptor),
+    createContractRuntimeFromClient(client, descriptor, options),
     address,
     abi,
     options
   );
 }
 
-export { ContractDryRunFailedError, ContractError, ContractManager, ContractNotFoundError, ContractSignerMissingError, createContract, createContractFromClient, createContractRuntime, createContractRuntimeFromClient, ensureContractAccountMapped };
+export { ContractDryRunFailedError, ContractError, ContractManager, ContractNotFoundError, ContractRevertedError, ContractSignerMissingError, createContract, createContractFromClient, createContractRuntime, createContractRuntimeFromClient, ensureContractAccountMapped };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map