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

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,309 @@
+# @parity/product-sdk-contracts
+
+Typed contract interactions on Polkadot Asset Hub. Resolve deployed contracts from a `cdm.json` manifest (or directly from `cargo pvm-contract build` artefacts), get fully-typed handles for `query`, `tx`, and batched `prepare` calls — backed by `pallet-revive` via PAPI typed APIs, with viem providing the Solidity ABI codec.
+
+## Install
+
+```bash
+pnpm add @parity/product-sdk-contracts
+```
+
+## Quick start (with cdm.json)
+
+The `cdm.json` flow is the primary path. A `cdm.json` manifest in your project root pins each installed contract to an address + ABI; `ContractManager.fromClient(cdm, client, descriptor)` resolves them at runtime.
+
+```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";
+import { SignerManager } from "@parity/product-sdk-signer";
+import cdmJson from "./cdm.json";
+
+const client = await createChainClient({
+    chains: { assetHub: paseo_asset_hub },
+});
+
+const signerManager = new SignerManager();
+await signerManager.connect();
+
+const manager = ContractManager.fromClient(cdmJson, client.raw.assetHub, paseo_asset_hub, {
+    signerManager,
+});
+
+// Resolve by library name — typed handle returned.
+const registry = manager.getContract("@w3s/playground-registry");
+
+// Read state
+const { value } = await registry.publish.query("my-app00", "ipfs://...", 0);
+
+// Submit a tx (uses signerManager's logged-in account)
+await registry.publish.tx("my-app00", "ipfs://...", 0);
+```
+
+## `ContractManager` API
+
+### `ContractManager.fromClient(cdmJson, client, descriptor, options?)`
+
+Synchronous factory. Builds a `ContractRuntime` internally that wires the typed API (for extrinsics + storage) and the unsafe API (for the `ReviveApi.call` dry-run, sidesteps compat-token drift when the descriptor lags a runtime upgrade) on the same `PolkadotClient`.
+
+| Param | Type | Notes |
+| --- | --- | --- |
+| `cdmJson` | `CdmJson` | Imported `cdm.json` |
+| `client` | `PolkadotClient` | E.g. `client.raw.assetHub` |
+| `descriptor` | `ChainDefinition` | E.g. `paseo_asset_hub` from `@parity/product-sdk-descriptors` |
+| `options.signerManager?` | `SignerManager` | Resolves signer + origin from the logged-in account |
+| `options.defaultOrigin?` | `SS58String` | Static fallback origin for queries |
+| `options.defaultSigner?` | `PolkadotSigner` | Static fallback signer for txs |
+
+### `manager.getContract(library)`
+
+Returns a typed `Contract<C>` handle. Each ABI method exposes:
+
+- `.query(...args, opts?)` — read-only dry-run; returns `{ success, value, gasRequired }`
+- `.tx(...args, opts?)` — sign, submit, and watch; resolves at best-block
+- `.prepare(...args, opts?)` — batch-ready handle (see *Batching* below)
+
+When codegen-generated types are present, the call is fully typed:
+
+```ts
+const registry = manager.getContract("@w3s/playground-registry");
+//                                    ^ autocompletes from cdm.json
+await registry.publish.tx("domain", "ipfs://cid", 0);
+//             ^ method name typed
+//                       ^ args typed
+```
+
+Throws `ContractNotFoundError` if the library name isn't in the manifest.
+
+### `manager.getAddress(library)`
+
+Returns the on-chain address. Useful for logging or display.
+
+### `manager.setDefaults(defaults)`
+
+Update `origin`, `signer`, or `signerManager` after construction. Only the fields you pass are updated.
+
+### `ContractManager.fromLive(cdmJson, runtime, options?)` / `fromLiveClient(cdmJson, client, descriptor, options?)`
+
+**Async** factories. Like `fromClient`, but before constructing the manager they resolve each installed contract's address from the **live CDM registry** instead of trusting the address baked into `cdm.json`. ABIs still come from the installed snapshot — only addresses are refreshed. Dependencies requested as `"latest"` resolve the registry's latest address; pinned numeric dependencies resolve `getAddressAtVersion(...)` so the live address stays aligned with the installed ABI/version.
+
+```ts
+const manager = await ContractManager.fromLiveClient(cdmJson, client.raw.assetHub, paseo_asset_hub, {
+    signerManager,
+    // registryAddress?: HexString  — defaults to cdmJson.registry
+    // libraries?: string[]         — subset to resolve; defaults to every contract
+    // registryOrigin?: SS58String  — origin for the registry dry-run; defaults to defaultOrigin
+});
+```
+
+This path is **strict**: if `cdmJson.registry` (or `registryAddress`) is missing, or a contract isn't registered on-chain, or the registry query fails, the promise rejects with `ContractLiveAddressResolutionError` — it never silently falls back to the snapshot address. Use `fromClient` for snapshot-only behavior.
+
+### `withLiveContractAddresses(cdmJson, runtime, options?)`
+
+Standalone helper behind `fromLive`. Returns a **cloned** `cdm.json` whose contract addresses have been replaced with live registry addresses (the input is never mutated). Useful when you want the resolved manifest without immediately building a manager. Takes the same `LiveContractResolutionOptions` as `fromLive`.
+
+## Signer / origin resolution
+
+Order, highest wins:
+
+1. Explicit `{ signer }` / `{ origin }` in the call options
+2. `signerManager`'s currently selected account
+3. Static `defaultSigner` / `defaultOrigin`
+4. (Queries only) pallet-revive account fallback for the dry-run
+
+Throws `ContractSignerMissingError` from `.tx()` if no signer is available. `.query()` and `.prepare()` never need a signer.
+
+## Account mapping (`pallet-revive` prerequisite)
+
+`pallet-revive` requires every signing SS58 account to have a registered `OriginalAccount` mapping to its derived H160 before `Revive.call` extrinsics from it are accepted. Call `ensureContractAccountMapped(runtime, address, signer)` once at app boot per signing account — it's idempotent (reads `Revive.OriginalAccount` first, short-circuits with `null` if already mapped) so the worst case is one extra storage read on every boot.
+
+```ts
+import { ensureContractAccountMapped } from "@parity/product-sdk-contracts";
+
+await ensureContractAccountMapped(manager.getRuntime(), address, signer);
+// safe to call manager.getContract(...).<method>.tx({ signer }) from here
+```
+
+Without this, every fresh-account `.tx()` fails the pre-flight dry-run with `AccountNotMapped` before signing.
+
+## Dry-run preflight
+
+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.
+
+```ts
+import { batchSubmitAndWatch } from "@parity/product-sdk-tx";
+
+const a = registry.publish.prepare("app-one00", "ipfs://...", 0);
+const b = registry.publish.prepare("app-two00", "ipfs://...", 0);
+
+await batchSubmitAndWatch([a, b], client.raw.assetHub, signer);
+```
+
+**`.prepare()` doesn't require a signer.** The resolved origin is only used for the dry-run; the batch submission's signer is the dispatched origin at submission time.
+
+`PrepareOptions` accepts: `origin`, `value`, `gasLimit`, `storageDepositLimit`. Signer and submission lifecycle options (`signer`, `waitFor`, etc.) are intentionally absent — those belong to the batch submit, not the individual prepared call.
+
+## Without cdm.json — manual path
+
+If you don't have a `cdm.json` (or want to test against a contract not yet in your manifest), use `createContract` / `createContractFromClient` with an explicit address and ABI:
+
+```ts
+import { createContractFromClient } from "@parity/product-sdk-contracts";
+import { paseo_asset_hub } from "@parity/product-sdk-descriptors/paseo-asset-hub";
+
+const counter = createContractFromClient(
+    client.raw.assetHub,
+    paseo_asset_hub,
+    "0xC472...",
+    counterAbi,
+    { signerManager },
+);
+
+const { value } = await counter.getCount.query();
+await counter.increment.tx();
+```
+
+`createContract` is the same but takes a pre-built `ContractRuntime` (from `createContractRuntime` / `createContractRuntimeFromClient`) instead of a raw `PolkadotClient` + descriptor. Use it when you want to share a single runtime across multiple contract handles or wire your own dry-run path.
+
+For projects that build with `cargo pvm-contract` and don't want to maintain a `cdm.json`, the `@parity/product-sdk-contracts/pvm` subpath exports `parsePvmContractAbi`, `loadPvmContractAbi`, `loadPvmContractCode`, and `loadPvmContractArtifacts` — load the ABI (and bytecode for deployment) directly from the toolchain's `<name>.release.abi.json` / `<name>.release.polkavm` output.
+
+## cdm.json schema
+
+Top-level shape:
+
+```jsonc
+{
+  "registry": "0xf62c2ece29cd8df2e10040ecfa5a894a5c5d9cb0",
+  "dependencies": {
+    "@org/contract-name": "latest"
+  },
+  "contracts": {
+    "@org/contract-name": {
+      "version": 6,
+      "address": "0x4A37B123b0BA2A894cA5953f472264921d44e298",
+      "abi": [ /* Solidity-compatible ABI entries */ ]
+    }
+  }
+}
+```
+
+`registry` is used by `ContractManager.fromLive(...)` / `withLiveContractAddresses(...)` to resolve current contract addresses from the live CDM registry. `ContractManager.fromClient(...)` uses the installed `contracts` snapshot directly.
+
+A real-world example: [`paritytech/playground-cli/cdm.json`](https://github.com/paritytech/playground-cli/blob/main/cdm.json).
+
+## Type generation
+
+`generateContractTypes(...)` (from `@parity/product-sdk-contracts/codegen`) emits a `.d.ts` that augments the package's `Contracts` interface so `manager.getContract("@org/name")` returns a fully-typed handle:
+
+```ts
+import { generateContractTypes, resolveContractTypeInputs } from "@parity/product-sdk-contracts/codegen";
+import { writeFileSync } from "node:fs";
+
+// Mix inline ABIs (from your cdm.json) and cargo-pvm-contract build artefacts.
+const resolved = await resolveContractTypeInputs([
+    { library: "@example/counter", abiPath: "./target/counter.release.abi.json" },
+    { library: "@example/inline", abi: inlineAbi },
+]);
+const src = generateContractTypes(resolved);
+writeFileSync(".cdm/contracts.d.ts", src);
+```
+
+Wire `.cdm/contracts.d.ts` into your `tsconfig.json`'s `include` and the next time you call `getContract("@org/name")`, the method names, parameter types, and return types come straight from the ABI.
+
+Without codegen, `getContract()` still works — methods are accessible but untyped (`Contract<ContractDef>`).
+
+## Errors
+
+| Error | When |
+| --- | --- |
+| `ContractNotFoundError` | `getContract(name)` and `name` isn't in the manifest |
+| `ContractSignerMissingError` | `.tx()` called with no signer + no signerManager + no defaultSigner |
+| `ContractLiveAddressResolutionError` | `fromLive(...)` / `withLiveContractAddresses(...)` couldn't resolve an address from the live CDM registry (no `registry` set, contract unregistered, or the registry query failed) |
+| `ContractDryRunFailedError` | `.tx()` pre-flight `ReviveApi.call` reported failure — `dispatchError` carries the chain's encoded error (e.g. `ContractReverted`, `OutOfGas`, `AccountNotMapped`) |
+| Generic | viem ABI decode failures, RPC errors, weight/storage-limit estimation failures — surface from the underlying PAPI typed API |
+
+## Public API
+
+```ts
+// `@parity/product-sdk-contracts` (browser-safe runtime entry)
+export {
+    ContractManager,
+    createContract,
+    createContractFromClient,
+    createContractRuntime,
+    createContractRuntimeFromClient,
+    withLiveContractAddresses,
+    ensureContractAccountMapped,
+    ContractError,
+    ContractSignerMissingError,
+    ContractNotFoundError,
+    ContractLiveAddressResolutionError,
+    ContractDryRunFailedError,
+};
+export type {
+    ContractRuntime,
+    ReviveTypedApi,
+    ReviveDryRunResult,
+    ReviveDryRunCall,
+    CdmJson,
+    CdmJsonContract,
+    CdmJsonDependencyVersion,
+    AbiParam,
+    AbiEntry,
+    Contract,
+    ContractDef,
+    Contracts,
+    QueryResult,
+    QueryOptions,
+    TxOptions,
+    TxResult,
+    PrepareOptions,
+    BatchableCall,
+    ContractDefaults,
+    ContractManagerOptions,
+    ContractOptions,
+    LiveContractResolutionOptions,
+};
+
+// `@parity/product-sdk-contracts/codegen` (Node-only — build tooling)
+export { generateContractTypes, resolveContractTypeInputs };
+export type { ContractTypeInput };
+
+// `@parity/product-sdk-contracts/pvm` (Node-only — cargo-pvm-contract artefact loaders)
+export {
+    parsePvmContractAbi,
+    loadPvmContractAbi,
+    loadPvmContractCode,
+    loadPvmContractArtifacts,
+};
+export type { PvmContractArtifacts };
+```

package/dist/chunk-2UN4YA25.js

@@ -0,0 +1,53 @@
+// src/pvm.ts
+function parsePvmContractAbi(source) {
+  let value = source;
+  if (value instanceof Uint8Array) {
+    value = new TextDecoder().decode(value);
+  }
+  if (typeof value === "string") {
+    try {
+      value = JSON.parse(value);
+    } catch (cause) {
+      throw new Error("Invalid PVM ABI: not valid JSON", { cause });
+    }
+  }
+  if (value && typeof value === "object" && !Array.isArray(value) && "abi" in value) {
+    value = value.abi;
+  }
+  if (!Array.isArray(value)) {
+    throw new Error("Invalid PVM ABI: expected an array of ABI entries");
+  }
+  for (const entry of value) {
+    if (!entry || typeof entry !== "object" || typeof entry.type !== "string") {
+      throw new Error(
+        "Invalid PVM ABI: every entry must have a string `type` (function/event/constructor/...)"
+      );
+    }
+    const inputs = entry.inputs;
+    if (inputs !== void 0 && !Array.isArray(inputs)) {
+      throw new Error("Invalid PVM ABI: `inputs` must be an array when present");
+    }
+  }
+  return value;
+}
+async function loadPvmContractAbi(path) {
+  const { readFile } = await import('fs/promises');
+  const buf = await readFile(path);
+  return parsePvmContractAbi(buf);
+}
+async function loadPvmContractCode(path) {
+  const { readFile } = await import('fs/promises');
+  const buf = await readFile(path);
+  return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+}
+async function loadPvmContractArtifacts(basePath) {
+  const [abi, bytecode] = await Promise.all([
+    loadPvmContractAbi(`${basePath}.abi.json`),
+    loadPvmContractCode(`${basePath}.polkavm`)
+  ]);
+  return { abi, bytecode };
+}
+
+export { loadPvmContractAbi, loadPvmContractArtifacts, loadPvmContractCode, parsePvmContractAbi };
+//# sourceMappingURL=chunk-2UN4YA25.js.map
+//# sourceMappingURL=chunk-2UN4YA25.js.map

package/dist/chunk-2UN4YA25.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/pvm.ts"],"names":[],"mappings":";AAqBO,SAAS,oBAAoB,MAAA,EAA6B;AAC7D,EAAA,IAAI,KAAA,GAAiB,MAAA;AAErB,EAAA,IAAI,iBAAiB,UAAA,EAAY;AAC7B,IAAA,KAAA,GAAQ,IAAI,WAAA,EAAY,CAAE,MAAA,CAAO,KAAK,CAAA;AAAA,EAC1C;AACA,EAAA,IAAI,OAAO,UAAU,QAAA,EAAU;AAC3B,IAAA,IAAI;AACA,MAAA,KAAA,GAAQ,IAAA,CAAK,MAAM,KAAK,CAAA;AAAA,IAC5B,SAAS,KAAA,EAAO;AACZ,MAAA,MAAM,IAAI,KAAA,CAAM,iCAAA,EAAmC,EAAE,OAAO,CAAA;AAAA,IAChE;AAAA,EACJ;AACA,EAAA,IAAI,KAAA,IAAS,OAAO,KAAA,KAAU,QAAA,IAAY,CAAC,MAAM,OAAA,CAAQ,KAAK,CAAA,IAAK,KAAA,IAAS,KAAA,EAAO;AAC/E,IAAA,KAAA,GAAS,KAAA,CAA2B,GAAA;AAAA,EACxC;AACA,EAAA,IAAI,CAAC,KAAA,CAAM,OAAA,CAAQ,KAAK,CAAA,EAAG;AACvB,IAAA,MAAM,IAAI,MAAM,mDAAmD,CAAA;AAAA,EACvE;AACA,EAAA,KAAA,MAAW,SAAS,KAAA,EAAO;AACvB,IAAA,IAAI,CAAC,SAAS,OAAO,KAAA,KAAU,YAAY,OAAQ,KAAA,CAAmB,SAAS,QAAA,EAAU;AACrF,MAAA,MAAM,IAAI,KAAA;AAAA,QACN;AAAA,OACJ;AAAA,IACJ;AACA,IAAA,MAAM,SAAU,KAAA,CAAmB,MAAA;AACnC,IAAA,IAAI,WAAW,MAAA,IAAa,CAAC,KAAA,CAAM,OAAA,CAAQ,MAAM,CAAA,EAAG;AAChD,MAAA,MAAM,IAAI,MAAM,yDAAyD,CAAA;AAAA,IAC7E;AAAA,EACJ;AACA,EAAA,OAAO,KAAA;AACX;AAOA,eAAsB,mBAAmB,IAAA,EAAmC;AACxE,EAAA,MAAM,EAAE,QAAA,EAAS,GAAI,MAAM,OAAO,aAAkB,CAAA;AACpD,EAAA,MAAM,GAAA,GAAM,MAAM,QAAA,CAAS,IAAI,CAAA;AAC/B,EAAA,OAAO,oBAAoB,GAAG,CAAA;AAClC;AAYA,eAAsB,oBAAoB,IAAA,EAAmC;AACzE,EAAA,MAAM,EAAE,QAAA,EAAS,GAAI,MAAM,OAAO,aAAkB,CAAA;AACpD,EAAA,MAAM,GAAA,GAAM,MAAM,QAAA,CAAS,IAAI,CAAA;AAC/B,EAAA,OAAO,IAAI,UAAA,CAAW,GAAA,CAAI,QAAQ,GAAA,CAAI,UAAA,EAAY,IAAI,UAAU,CAAA;AACpE;AAYA,eAAsB,yBAAyB,QAAA,EAAiD;AAC5F,EAAA,MAAM,CAAC,GAAA,EAAK,QAAQ,CAAA,GAAI,MAAM,QAAQ,GAAA,CAAI;AAAA,IACtC,kBAAA,CAAmB,CAAA,EAAG,QAAQ,CAAA,SAAA,CAAW,CAAA;AAAA,IACzC,mBAAA,CAAoB,CAAA,EAAG,QAAQ,CAAA,QAAA,CAAU;AAAA,GAC5C,CAAA;AACD,EAAA,OAAO,EAAE,KAAK,QAAA,EAAS;AAC3B","file":"chunk-2UN4YA25.js","sourcesContent":["// Copyright 2026 Parity Technologies (UK) Ltd.\n// SPDX-License-Identifier: Apache-2.0\nimport type { AbiEntry } from \"./types.js\";\n\n/** ABI + PolkaVM bytecode pair emitted by `cargo pvm-contract build`. */\nexport interface PvmContractArtifacts {\n    abi: AbiEntry[];\n    bytecode: Uint8Array;\n}\n\n/**\n * Parse an in-memory cargo-pvm-contract ABI artifact.\n *\n * Accepts the shapes the toolchain may produce or that products may pass:\n * - parsed JSON array — `AbiEntry[]`\n * - parsed JSON object with an `abi` property — `{ abi: AbiEntry[] }`\n * - JSON string of either of the above\n * - `Uint8Array` containing UTF-8 JSON of either of the above\n *\n * @throws if the input cannot be coerced to a non-empty `AbiEntry[]`.\n */\nexport function parsePvmContractAbi(source: unknown): AbiEntry[] {\n    let value: unknown = source;\n\n    if (value instanceof Uint8Array) {\n        value = new TextDecoder().decode(value);\n    }\n    if (typeof value === \"string\") {\n        try {\n            value = JSON.parse(value);\n        } catch (cause) {\n            throw new Error(\"Invalid PVM ABI: not valid JSON\", { cause });\n        }\n    }\n    if (value && typeof value === \"object\" && !Array.isArray(value) && \"abi\" in value) {\n        value = (value as { abi: unknown }).abi;\n    }\n    if (!Array.isArray(value)) {\n        throw new Error(\"Invalid PVM ABI: expected an array of ABI entries\");\n    }\n    for (const entry of value) {\n        if (!entry || typeof entry !== \"object\" || typeof (entry as AbiEntry).type !== \"string\") {\n            throw new Error(\n                \"Invalid PVM ABI: every entry must have a string `type` (function/event/constructor/...)\",\n            );\n        }\n        const inputs = (entry as AbiEntry).inputs;\n        if (inputs !== undefined && !Array.isArray(inputs)) {\n            throw new Error(\"Invalid PVM ABI: `inputs` must be an array when present\");\n        }\n    }\n    return value as AbiEntry[];\n}\n\n/**\n * Read a cargo-pvm-contract ABI file from disk and parse it.\n *\n * Node-only. For browser/in-memory inputs use {@link parsePvmContractAbi}.\n */\nexport async function loadPvmContractAbi(path: string): Promise<AbiEntry[]> {\n    const { readFile } = await import(\"node:fs/promises\");\n    const buf = await readFile(path);\n    return parsePvmContractAbi(buf);\n}\n\n/**\n * Read the `.polkavm` bytecode artifact produced by `cargo pvm-contract build`.\n *\n * Returned bytes are ready to hand to `Revive.instantiate_with_code` (or to\n * any future deploy helper layered on top of it). Use this when you already\n * have an ABI in hand (e.g. inline or fetched separately) and only need the\n * PolkaVM blob — otherwise prefer {@link loadPvmContractArtifacts}.\n *\n * Node-only.\n */\nexport async function loadPvmContractCode(path: string): Promise<Uint8Array> {\n    const { readFile } = await import(\"node:fs/promises\");\n    const buf = await readFile(path);\n    return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);\n}\n\n/**\n * Read both the `.abi.json` and `.polkavm` artifacts produced by\n * `cargo pvm-contract build` for a given base path.\n *\n * `basePath` is the path prefix shared by both files — typically\n * `target/<name>.release`. The function reads `${basePath}.abi.json` and\n * `${basePath}.polkavm`.\n *\n * Node-only.\n */\nexport async function loadPvmContractArtifacts(basePath: string): Promise<PvmContractArtifacts> {\n    const [abi, bytecode] = await Promise.all([\n        loadPvmContractAbi(`${basePath}.abi.json`),\n        loadPvmContractCode(`${basePath}.polkavm`),\n    ]);\n    return { abi, bytecode };\n}\n\nif (import.meta.vitest) {\n    const { test, expect, describe, beforeAll, afterAll } = import.meta.vitest;\n\n    const sampleAbi: AbiEntry[] = [\n        { type: \"constructor\", inputs: [], stateMutability: \"nonpayable\" },\n        {\n            type: \"function\",\n            name: \"increment\",\n            inputs: [],\n            outputs: [],\n            stateMutability: \"nonpayable\",\n        },\n        {\n            type: \"function\",\n            name: \"get\",\n            inputs: [],\n            outputs: [{ name: \"\", type: \"uint32\" }],\n            stateMutability: \"view\",\n        },\n    ];\n\n    describe(\"parsePvmContractAbi\", () => {\n        test(\"accepts a parsed AbiEntry[] array directly\", () => {\n            expect(parsePvmContractAbi(sampleAbi)).toEqual(sampleAbi);\n        });\n\n        test(\"accepts a wrapped { abi } object\", () => {\n            expect(parsePvmContractAbi({ abi: sampleAbi })).toEqual(sampleAbi);\n        });\n\n        test(\"accepts a JSON string of an array\", () => {\n            expect(parsePvmContractAbi(JSON.stringify(sampleAbi))).toEqual(sampleAbi);\n        });\n\n        test(\"accepts a JSON string of a wrapped object\", () => {\n            expect(parsePvmContractAbi(JSON.stringify({ abi: sampleAbi }))).toEqual(sampleAbi);\n        });\n\n        test(\"accepts a UTF-8 Uint8Array\", () => {\n            const bytes = new TextEncoder().encode(JSON.stringify(sampleAbi));\n            expect(parsePvmContractAbi(bytes)).toEqual(sampleAbi);\n        });\n\n        test(\"throws on invalid JSON string\", () => {\n            expect(() => parsePvmContractAbi(\"{not json\")).toThrow(/not valid JSON/);\n        });\n\n        test(\"throws when input is not an array\", () => {\n            expect(() => parsePvmContractAbi(42)).toThrow(/expected an array/);\n            expect(() => parsePvmContractAbi({ foo: \"bar\" })).toThrow(/expected an array/);\n        });\n\n        test(\"throws when an entry is missing `type`\", () => {\n            expect(() => parsePvmContractAbi([{ name: \"noType\" }])).toThrow(/string `type`/);\n        });\n\n        test(\"throws when `inputs` is not an array\", () => {\n            expect(() =>\n                parsePvmContractAbi([{ type: \"function\", inputs: \"not an array\" }]),\n            ).toThrow(/`inputs` must be an array/);\n        });\n\n        test(\"treats null as invalid\", () => {\n            expect(() => parsePvmContractAbi(null)).toThrow();\n        });\n    });\n\n    describe(\"loadPvmContractAbi / loadPvmContractArtifacts\", () => {\n        // Cover the Node-only filesystem helpers via a real tmpdir round-trip.\n        // The cargo-pvm-contract toolchain emits files at\n        //   target/<name>.release.abi.json\n        //   target/<name>.release.polkavm\n        // — we recreate that layout here.\n        let dir = \"\";\n        let base = \"\";\n        let lonely = \"\";\n        let badAbi = \"\";\n        // Minimal PolkaVM magic (`PVM\\0`) is enough to exercise the path —\n        // we don't validate bytecode contents in the loader.\n        const fakeBytecode = new Uint8Array([0x50, 0x56, 0x4d, 0x00, 0x01, 0x02, 0x03]);\n\n        beforeAll(async () => {\n            const { mkdtempSync, writeFileSync } = await import(\"node:fs\");\n            const { tmpdir } = await import(\"node:os\");\n            const { join } = await import(\"node:path\");\n            dir = mkdtempSync(join(tmpdir(), \"pvm-loader-test-\"));\n            base = join(dir, \"counter.release\");\n            lonely = join(dir, \"lonely.release\");\n            badAbi = join(dir, \"bad.release\");\n            writeFileSync(`${base}.abi.json`, JSON.stringify(sampleAbi));\n            writeFileSync(`${base}.polkavm`, fakeBytecode);\n            writeFileSync(`${lonely}.abi.json`, JSON.stringify(sampleAbi));\n            writeFileSync(`${badAbi}.abi.json`, \"{not valid json\");\n        });\n\n        afterAll(async () => {\n            const { rmSync } = await import(\"node:fs\");\n            try {\n                rmSync(dir, { recursive: true, force: true });\n            } catch {\n                /* ignore */\n            }\n        });\n\n        test(\"loadPvmContractAbi parses a JSON file from disk\", async () => {\n            const abi = await loadPvmContractAbi(`${base}.abi.json`);\n            expect(abi).toEqual(sampleAbi);\n        });\n\n        test(\"loadPvmContractArtifacts reads abi + bytecode pair\", async () => {\n            const out = await loadPvmContractArtifacts(base);\n            expect(out.abi).toEqual(sampleAbi);\n            expect(out.bytecode).toBeInstanceOf(Uint8Array);\n            expect(Array.from(out.bytecode)).toEqual(Array.from(fakeBytecode));\n        });\n\n        test(\"loadPvmContractCode reads only the .polkavm blob\", async () => {\n            const code = await loadPvmContractCode(`${base}.polkavm`);\n            expect(code).toBeInstanceOf(Uint8Array);\n            expect(Array.from(code)).toEqual(Array.from(fakeBytecode));\n        });\n\n        test(\"loadPvmContractAbi rejects a missing file\", async () => {\n            await expect(loadPvmContractAbi(`${base}.does-not-exist`)).rejects.toThrow();\n        });\n\n        test(\"loadPvmContractArtifacts rejects when bytecode is missing\", async () => {\n            // Only `${lonely}.abi.json` exists — `.polkavm` is absent.\n            await expect(loadPvmContractArtifacts(lonely)).rejects.toThrow();\n        });\n\n        test(\"loadPvmContractAbi propagates parse errors with helpful message\", async () => {\n            await expect(loadPvmContractAbi(`${badAbi}.abi.json`)).rejects.toThrow(\n                /not valid JSON/,\n            );\n        });\n    });\n}\n"]}

package/dist/codegen.d.ts

@@ -0,0 +1,67 @@
+import { A as AbiEntry } from './types-Dtu4IsSh.js';
+import '@parity/result';
+import '@parity/product-sdk-signer';
+import '@parity/product-sdk-tx';
+import 'polkadot-api';
+import '@parity/product-sdk-errors';
+
+/** A contract input to {@link generateContractTypes}: either an inline ABI or a `cargo-pvm-contract` artefact path. */
+type ContractTypeInput = {
+    library: string;
+    abi: AbiEntry[];
+} | {
+    library: string;
+    abiPath: string;
+};
+/**
+ * Resolve a heterogeneous list of {@link ContractTypeInput} entries into the
+ * `{ library, abi }` shape consumed by {@link generateContractTypes}. Reads any
+ * `abiPath` entries off disk via {@link loadPvmContractAbi} (Node only).
+ *
+ * @example
+ * ```ts
+ * const resolved = await resolveContractTypeInputs([
+ *     { library: "@example/counter", abiPath: "./target/counter.release.abi.json" },
+ *     { library: "@example/inline", abi: counterAbi },
+ * ]);
+ * const src = generateContractTypes(resolved);
+ * ```
+ */
+declare function resolveContractTypeInputs(inputs: readonly ContractTypeInput[]): Promise<{
+    library: string;
+    abi: AbiEntry[];
+}[]>;
+/**
+ * Generate a TypeScript module augmentation that extends the
+ * {@link Contracts} interface with typed method signatures for each
+ * installed contract.
+ *
+ * The output is written to `.cdm/contracts.d.ts` (or equivalent) and
+ * augments `"@parity/product-sdk-contracts"` so that
+ * `ContractManager.getContract()` returns fully-typed handles.
+ *
+ * Accepts `{ library, abi }` directly. To pull ABIs from
+ * `cargo-pvm-contract` build artefacts on disk, use
+ * {@link resolveContractTypeInputs} first.
+ *
+ * @example
+ * ```ts
+ * // Inline ABIs
+ * const src = generateContractTypes([
+ *     { library: "@example/counter", abi },
+ * ]);
+ * writeFileSync(".cdm/contracts.d.ts", src);
+ *
+ * // From cargo-pvm-contract artefacts
+ * const resolved = await resolveContractTypeInputs([
+ *     { library: "@example/counter", abiPath: "./target/counter.release.abi.json" },
+ * ]);
+ * writeFileSync(".cdm/contracts.d.ts", generateContractTypes(resolved));
+ * ```
+ */
+declare function generateContractTypes(contracts: {
+    library: string;
+    abi: AbiEntry[];
+}[]): string;
+
+export { type ContractTypeInput, generateContractTypes, resolveContractTypeInputs };