@pezkuwi/api-contract 16.5.6 → 16.5.8

package/src/Abi/toLatestCompatible.ts

@@ -0,0 +1,52 @@
+// Copyright 2017-2025 @pezkuwi/api-contract authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { ContractMetadataV4, ContractMetadataV5, ContractMetadataV6 } from '@pezkuwi/types/interfaces';
+import type { Registry } from '@pezkuwi/types/types';
+import type { ContractMetadataSupported } from './index.js';
+
+import { v0ToV1 } from './toV1.js';
+import { v1ToV2 } from './toV2.js';
+import { v2ToV3 } from './toV3.js';
+import { v3ToV4 } from './toV4.js';
+
+// The versions where an enum is used, aka V0 is missing
+// (Order from newest, i.e. we expect more on newest vs oldest)
+export const enumVersions = ['V6', 'V5', 'V4', 'V3', 'V2', 'V1'] as const;
+
+type Versions = typeof enumVersions[number] | 'V0';
+
+type Converter = (registry: Registry, vx: any) => ContractMetadataSupported;
+
+// Helper to convert metadata from one step to the next
+function createConverter <I, O> (next: (registry: Registry, input: O) => ContractMetadataSupported, step: (registry: Registry, input: I) => O): (registry: Registry, input: I) => ContractMetadataSupported {
+  return (registry: Registry, input: I): ContractMetadataSupported =>
+    next(registry, step(registry, input));
+}
+
+export function v6ToLatestCompatible (_registry: Registry, v6: ContractMetadataV6): ContractMetadataV6 {
+  return v6;
+}
+
+export function v5ToLatestCompatible (_registry: Registry, v5: ContractMetadataV5): ContractMetadataV5 {
+  return v5;
+}
+
+export function v4ToLatestCompatible (_registry: Registry, v4: ContractMetadataV4): ContractMetadataV4 {
+  return v4;
+}
+
+export const v3ToLatestCompatible = /*#__PURE__*/ createConverter(v4ToLatestCompatible, v3ToV4);
+export const v2ToLatestCompatible = /*#__PURE__*/ createConverter(v3ToLatestCompatible, v2ToV3);
+export const v1ToLatestCompatible = /*#__PURE__*/ createConverter(v2ToLatestCompatible, v1ToV2);
+export const v0ToLatestCompatible = /*#__PURE__*/ createConverter(v1ToLatestCompatible, v0ToV1);
+
+export const convertVersions: [Versions, Converter][] = [
+  ['V6', v6ToLatestCompatible],
+  ['V5', v5ToLatestCompatible],
+  ['V4', v4ToLatestCompatible],
+  ['V3', v3ToLatestCompatible],
+  ['V2', v2ToLatestCompatible],
+  ['V1', v1ToLatestCompatible],
+  ['V0', v0ToLatestCompatible]
+];

package/src/Abi/toV1.ts

@@ -0,0 +1,35 @@
+// Copyright 2017-2025 @pezkuwi/api-contract authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { ContractMetadataV0, ContractMetadataV1 } from '@pezkuwi/types/interfaces';
+import type { Registry } from '@pezkuwi/types/types';
+
+import { convertSiV0toV1 } from '@pezkuwi/types';
+import { objectSpread } from '@pezkuwi/util';
+
+interface Named {
+  name: unknown;
+}
+
+function v0ToV1Names (all: Named[]): unknown[] {
+  return all.map((e) =>
+    objectSpread({}, e, {
+      name: Array.isArray(e.name)
+        ? e.name
+        : [e.name]
+    }));
+}
+
+export function v0ToV1 (registry: Registry, v0: ContractMetadataV0): ContractMetadataV1 {
+  if (!v0.metadataVersion.length) {
+    throw new Error('Invalid format for V0 (detected) contract metadata');
+  }
+
+  return registry.createType('ContractMetadataV1', objectSpread({}, v0, {
+    spec: objectSpread({}, v0.spec, {
+      constructors: v0ToV1Names(v0.spec.constructors),
+      messages: v0ToV1Names(v0.spec.messages)
+    }),
+    types: convertSiV0toV1(registry, v0.types)
+  }));
+}

package/src/Abi/toV2.ts

@@ -0,0 +1,58 @@
+// Copyright 2017-2025 @pezkuwi/api-contract authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { Text } from '@pezkuwi/types';
+import type { ContractConstructorSpecV0, ContractEventSpecV0, ContractMessageSpecV0, ContractMetadataV1, ContractMetadataV2 } from '@pezkuwi/types/interfaces';
+import type { Registry } from '@pezkuwi/types/types';
+
+import { objectSpread } from '@pezkuwi/util';
+
+type WithArgs = keyof typeof ARG_TYPES;
+
+interface NamedEntry {
+  name: Text | Text[];
+}
+
+type GetArgsType<T extends WithArgs> = T extends 'ContractConstructorSpec'
+  ? ContractConstructorSpecV0
+  : T extends ContractEventSpecV0
+    ? ContractEventSpecV0
+    : ContractMessageSpecV0;
+
+interface ArgsEntry <T extends WithArgs> extends NamedEntry {
+  args: GetArgsType<T>['args'][0][];
+}
+
+const ARG_TYPES = {
+  ContractConstructorSpec: 'ContractMessageParamSpecV2',
+  ContractEventSpec: 'ContractEventParamSpecV2',
+  ContractMessageSpec: 'ContractMessageParamSpecV2'
+} as const;
+
+function v1ToV2Label (entry: NamedEntry): { label: Text } {
+  return objectSpread({}, entry, {
+    label: Array.isArray(entry.name)
+      ? entry.name.join('::')
+      : entry.name
+  });
+}
+
+function v1ToV2Labels <T extends WithArgs> (registry: Registry, outType: T, all: ArgsEntry<T>[]): unknown[] {
+  return all.map((e) =>
+    registry.createType(`${outType}V2`, objectSpread(v1ToV2Label(e), {
+      args: e.args.map((a) =>
+        registry.createType(ARG_TYPES[outType], v1ToV2Label(a))
+      )
+    }))
+  );
+}
+
+export function v1ToV2 (registry: Registry, v1: ContractMetadataV1): ContractMetadataV2 {
+  return registry.createType('ContractMetadataV2', objectSpread({}, v1, {
+    spec: objectSpread({}, v1.spec, {
+      constructors: v1ToV2Labels(registry, 'ContractConstructorSpec', v1.spec.constructors),
+      events: v1ToV2Labels(registry, 'ContractEventSpec', v1.spec.events),
+      messages: v1ToV2Labels(registry, 'ContractMessageSpec', v1.spec.messages)
+    })
+  }));
+}

package/src/Abi/toV3.ts

@@ -0,0 +1,18 @@
+// Copyright 2017-2025 @pezkuwi/api-contract authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { ContractMetadataV2, ContractMetadataV3 } from '@pezkuwi/types/interfaces';
+import type { Registry } from '@pezkuwi/types/types';
+
+import { objectSpread } from '@pezkuwi/util';
+
+export function v2ToV3 (registry: Registry, v2: ContractMetadataV2): ContractMetadataV3 {
+  return registry.createType('ContractMetadataV3', objectSpread({}, v2, {
+    spec: objectSpread({}, v2.spec, {
+      constructors: v2.spec.constructors.map((c) =>
+        // V3 introduces the payable flag on constructors, for <V3, it is always true
+        registry.createType('ContractConstructorSpecV3', objectSpread({}, c, { payable: true }))
+      )
+    })
+  }));
+}

package/src/Abi/toV4.ts

@@ -0,0 +1,21 @@
+// Copyright 2017-2025 @pezkuwi/api-contract authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { ContractMetadataV3, ContractMetadataV4 } from '@pezkuwi/types/interfaces';
+import type { Registry } from '@pezkuwi/types/types';
+
+import { objectSpread } from '@pezkuwi/util';
+
+export function v3ToV4 (registry: Registry, v3: ContractMetadataV3): ContractMetadataV4 {
+  return registry.createType('ContractMetadataV4', objectSpread({}, v3, {
+    spec: objectSpread({}, v3.spec, {
+      constructors: v3.spec.constructors.map((c) =>
+        registry.createType('ContractConstructorSpecV4', objectSpread({}, c))
+      ),
+      messages: v3.spec.messages.map((m) =>
+        registry.createType('ContractMessageSpecV3', objectSpread({}, m))
+      )
+    }),
+    version: registry.createType('Text', '4')
+  }));
+}

package/src/augment.ts

@@ -0,0 +1,4 @@
+// Copyright 2017-2025 @pezkuwi/api-contract authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import '@pezkuwi/api-augment';

package/src/base/Base.ts

@@ -0,0 +1,52 @@
+// Copyright 2017-2025 @pezkuwi/api authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { ApiBase } from '@pezkuwi/api/base';
+import type { ApiTypes, DecorateMethod } from '@pezkuwi/api/types';
+import type { WeightV2 } from '@pezkuwi/types/interfaces';
+import type { Registry } from '@pezkuwi/types/types';
+
+import { isFunction } from '@pezkuwi/util';
+
+import { Abi } from '../Abi/index.js';
+
+export abstract class Base<ApiType extends ApiTypes> {
+  readonly abi: Abi;
+  readonly api: ApiBase<ApiType>;
+
+  protected readonly _decorateMethod: DecorateMethod<ApiType>;
+  protected readonly _isWeightV1: boolean;
+  protected readonly _isRevive: boolean;
+
+  constructor (api: ApiBase<ApiType>, abi: string | Record<string, unknown> | Abi, decorateMethod: DecorateMethod<ApiType>) {
+    if (!api || !api.isConnected || !api.tx) {
+      throw new Error('Your API has not been initialized correctly and is not connected to a chain');
+    }
+
+    this.abi = abi instanceof Abi
+      ? abi
+      : new Abi(abi, api.registry.getChainProperties());
+    this.api = api;
+    this._decorateMethod = decorateMethod;
+    this._isWeightV1 = !api.registry.createType<WeightV2>('Weight').proofSize;
+    this._isRevive = this.abi.isRevive;
+
+    if (this._isRevive) {
+      if (!api.tx.revive || !isFunction(api.tx.revive.instantiateWithCode) || api.tx.revive.instantiateWithCode.meta.args.length !== 6) {
+        throw new Error('The runtime does not expose api.tx.revive.instantiateWithCode with storageDepositLimit');
+      } else if (!api.call.reviveApi || !isFunction(api.call.reviveApi.call)) {
+        throw new Error('Your runtime does not expose the api.call.reviveApi.call runtime interfaces');
+      }
+    } else {
+      if (!api.tx.contracts || !isFunction(api.tx.contracts.instantiateWithCode) || api.tx.contracts.instantiateWithCode.meta.args.length !== 6) {
+        throw new Error('The runtime does not expose api.tx.contracts.instantiateWithCode with storageDepositLimit');
+      } else if (!api.call.contractsApi || !isFunction(api.call.contractsApi.call)) {
+        throw new Error('Your runtime does not expose the api.call.contractsApi.call runtime interfaces');
+      }
+    }
+  }
+
+  public get registry (): Registry {
+    return this.api.registry;
+  }
+}

package/src/base/Blueprint.ts

@@ -0,0 +1,90 @@
+// Copyright 2017-2025 @pezkuwi/api-contract authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { ApiBase } from '@pezkuwi/api/base';
+import type { SubmittableExtrinsic } from '@pezkuwi/api/submittable/types';
+import type { ApiTypes, DecorateMethod } from '@pezkuwi/api/types';
+import type { AccountId, EventRecord, Hash } from '@pezkuwi/types/interfaces';
+import type { ISubmittableResult } from '@pezkuwi/types/types';
+import type { Abi } from '../Abi/index.js';
+import type { AbiConstructor, BlueprintOptions } from '../types.js';
+import type { MapConstructorExec } from './types.js';
+
+import { SubmittableResult } from '@pezkuwi/api';
+import { BN_ZERO, isUndefined } from '@pezkuwi/util';
+
+import { applyOnEvent } from '../util.js';
+import { Base } from './Base.js';
+import { Contract } from './Contract.js';
+import { convertWeight, createBluePrintTx, encodeSalt } from './util.js';
+
+export type BlueprintConstructor<ApiType extends ApiTypes> = new(api: ApiBase<ApiType>, abi: string | Record<string, unknown> | Abi, codeHash: string | Hash | Uint8Array) => Blueprint<ApiType>;
+
+export class BlueprintSubmittableResult<ApiType extends ApiTypes> extends SubmittableResult {
+  readonly contract?: Contract<ApiType> | undefined;
+
+  constructor (result: ISubmittableResult, contract?: Contract<ApiType>) {
+    super(result);
+
+    this.contract = contract;
+  }
+}
+
+export class Blueprint<ApiType extends ApiTypes> extends Base<ApiType> {
+  /**
+   * @description The on-chain code hash for this blueprint
+   */
+  readonly codeHash: Hash;
+
+  readonly #tx: MapConstructorExec<ApiType> = {};
+
+  constructor (api: ApiBase<ApiType>, abi: string | Record<string, unknown> | Abi, codeHash: string | Hash | Uint8Array, decorateMethod: DecorateMethod<ApiType>) {
+    super(api, abi, decorateMethod);
+
+    this.codeHash = this.registry.createType('Hash', codeHash);
+
+    this.abi.constructors.forEach((c): void => {
+      if (isUndefined(this.#tx[c.method])) {
+        this.#tx[c.method] = createBluePrintTx(c, (o, p) => this.#deploy(c, o, p));
+      }
+    });
+  }
+
+  public get tx (): MapConstructorExec<ApiType> {
+    return this.#tx;
+  }
+
+  #deploy = (constructorOrId: AbiConstructor | string | number, { gasLimit = BN_ZERO, salt, storageDepositLimit = null, value = BN_ZERO }: BlueprintOptions, params: unknown[]): SubmittableExtrinsic<ApiType, BlueprintSubmittableResult<ApiType>> => {
+    const palletTx = this._isRevive
+      ? this.api.tx.revive
+      : this.api.tx.contracts;
+
+    return palletTx.instantiate(
+      value,
+      // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+      // @ts-ignore jiggle v1 weights, metadata points to latest
+      this._isWeightV1
+        ? convertWeight(gasLimit).v1Weight
+        : convertWeight(gasLimit).v2Weight,
+      storageDepositLimit,
+      this.codeHash,
+      this.abi.findConstructor(constructorOrId).toU8a(params),
+      encodeSalt(salt)
+    ).withResultTransform((result: ISubmittableResult) =>
+      new BlueprintSubmittableResult(result, applyOnEvent(result, ['Instantiated'], ([record]: EventRecord[]) =>
+        new Contract<ApiType>(this.api, this.abi, record.event.data[1] as AccountId, this._decorateMethod), this._isRevive
+      )
+      )
+    );
+  };
+}
+
+export function extendBlueprint <ApiType extends ApiTypes> (type: ApiType, decorateMethod: DecorateMethod<ApiType>): BlueprintConstructor<ApiType> {
+  return class extends Blueprint<ApiType> {
+    static __BlueprintType = type;
+
+    constructor (api: ApiBase<ApiType>, abi: string | Record<string, unknown> | Abi, codeHash: string | Hash | Uint8Array) {
+      super(api, abi, codeHash, decorateMethod);
+    }
+  };
+}

package/src/base/Code.spec.ts

@@ -0,0 +1,47 @@
+// Copyright 2017-2025 @pezkuwi/api-contract authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@pezkuwi/dev-test/globals.d.ts" />
+
+import fs from 'node:fs';
+
+import { toPromiseMethod } from '@pezkuwi/api';
+
+import v0contractFlipper from '../test/contracts/ink/v0/flipper.contract.json' assert { type: 'json' };
+import v0abiFlipper from '../test/contracts/ink/v0/flipper.json' assert { type: 'json' };
+import v1contractFlipper from '../test/contracts/ink/v1/flipper.contract.json' assert { type: 'json' };
+import v6contractErc20 from '../test/contracts/ink/v6/erc20.contract.json' assert { type: 'json' };
+import { Code } from './Code.js';
+import { mockApi, mockReviveApi } from './mock.js';
+
+const v0wasmFlipper = fs.readFileSync(new URL('../test/contracts/ink/v0/flipper.wasm', import.meta.url), 'utf-8');
+
+describe('Code', (): void => {
+  it('can construct with an individual ABI/WASM combo', (): void => {
+    expect(
+      () => new Code(mockApi, v0abiFlipper as Record<string, unknown>, v0wasmFlipper, toPromiseMethod)
+    ).not.toThrow();
+  });
+
+  it('can construct with an .contract ABI (v0)', (): void => {
+    expect(
+      () => new Code(mockApi, v0contractFlipper as Record<string, unknown>, null, toPromiseMethod)
+    ).not.toThrow();
+  });
+
+  it('can construct with an .contract ABI (v1)', (): void => {
+    expect(
+      () => new Code(mockApi, v1contractFlipper as Record<string, unknown>, null, toPromiseMethod)
+    ).not.toThrow();
+  });
+
+  it('can construct a revive compatible contract (v6)', (): void => {
+    expect(
+      () => new Code(mockApi, v6contractErc20 as Record<string, unknown>, null, toPromiseMethod)
+    ).toThrow('The runtime does not expose api.tx.revive.instantiateWithCode with storageDepositLimit');
+
+    expect(
+      () => new Code(mockReviveApi, v6contractErc20 as Record<string, unknown>, null, toPromiseMethod)
+    ).not.toThrow();
+  });
+});

package/src/base/Code.ts

@@ -0,0 +1,142 @@
+// Copyright 2017-2025 @pezkuwi/api-contract authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { ApiBase } from '@pezkuwi/api/base';
+import type { SubmittableExtrinsic } from '@pezkuwi/api/submittable/types';
+import type { ApiTypes, DecorateMethod } from '@pezkuwi/api/types';
+import type { AccountId, EventRecord } from '@pezkuwi/types/interfaces';
+import type { ISubmittableResult } from '@pezkuwi/types/types';
+import type { Codec } from '@pezkuwi/types-codec/types';
+import type { Abi } from '../Abi/index.js';
+import type { AbiConstructor, BlueprintOptions } from '../types.js';
+import type { MapConstructorExec } from './types.js';
+
+import { SubmittableResult } from '@pezkuwi/api';
+import { BN_ZERO, compactAddLength, isRiscV, isUndefined, isWasm, u8aToU8a } from '@pezkuwi/util';
+
+import { applyOnEvent } from '../util.js';
+import { Base } from './Base.js';
+import { Blueprint } from './Blueprint.js';
+import { Contract } from './Contract.js';
+import { convertWeight, createBluePrintTx, encodeSalt } from './util.js';
+
+export type CodeConstructor<ApiType extends ApiTypes> = new(api: ApiBase<ApiType>, abi: string | Record<string, unknown> | Abi, wasm: Uint8Array | string | Buffer | null | undefined) => Code<ApiType>;
+
+export class CodeSubmittableResult<ApiType extends ApiTypes> extends SubmittableResult {
+  readonly blueprint?: Blueprint<ApiType> | undefined;
+  readonly contract?: Contract<ApiType> | undefined;
+
+  constructor (result: ISubmittableResult, blueprint?: Blueprint<ApiType> | undefined, contract?: Contract<ApiType> | undefined) {
+    super(result);
+
+    this.blueprint = blueprint;
+    this.contract = contract;
+  }
+}
+
+// checks to see if the code (or at least the header)
+// is a valid/supported format
+function isValidCode (code: Uint8Array): boolean {
+  return isWasm(code) || isRiscV(code);
+}
+
+export class Code<ApiType extends ApiTypes> extends Base<ApiType> {
+  readonly code: Uint8Array;
+
+  readonly #tx: MapConstructorExec<ApiType> = {};
+
+  constructor (api: ApiBase<ApiType>, abi: string | Record<string, unknown> | Abi, wasm: Uint8Array | string | Buffer | null | undefined, decorateMethod: DecorateMethod<ApiType>) {
+    super(api, abi, decorateMethod);
+
+    this.code = isValidCode(this.abi.info.source.wasm)
+      ? this.abi.info.source.wasm
+      : u8aToU8a(wasm);
+
+    if (!isValidCode(this.code)) {
+      throw new Error('Invalid code provided');
+    }
+
+    this.abi.constructors.forEach((c): void => {
+      if (isUndefined(this.#tx[c.method])) {
+        this.#tx[c.method] = createBluePrintTx(c, (o, p) => this.#instantiate(c, o, p));
+      }
+    });
+  }
+
+  public get tx (): MapConstructorExec<ApiType> {
+    return this.#tx;
+  }
+
+  #instantiate = (constructorOrId: AbiConstructor | string | number, { gasLimit = BN_ZERO, salt, storageDepositLimit = null, value = BN_ZERO }: BlueprintOptions, params: unknown[]): SubmittableExtrinsic<ApiType, CodeSubmittableResult<ApiType>> => {
+    const palletTx = this._isRevive ? this.api.tx.revive : this.api.tx.contracts;
+
+    if (this._isRevive) {
+      return palletTx.instantiateWithCode(
+        value,
+        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+        // @ts-ignore jiggle v1 weights, metadata points to latest
+        this._isWeightV1
+          ? convertWeight(gasLimit).v1Weight
+          : convertWeight(gasLimit).v2Weight,
+        storageDepositLimit,
+        compactAddLength(this.code),
+        this.abi.findConstructor(constructorOrId).toU8a(params),
+        encodeSalt(salt)
+      ).withResultTransform((result: ISubmittableResult) =>
+        new CodeSubmittableResult(
+          result,
+          ...(applyOnEvent(result, ['Instantiated'], (records: EventRecord[]) =>
+            records.reduce<[Blueprint<ApiType> | undefined, Contract<ApiType> | undefined]>(
+              ([blueprint, contract], { event }) =>
+                this.api.events.revive['Instantiated'].is(event)
+                  ? [
+                    blueprint,
+                    new Contract<ApiType>(
+                      this.api,
+                      this.abi,
+                      (event as unknown as { data: [Codec, AccountId] }).data[1],
+                      this._decorateMethod
+                    )
+                  ]
+                  : [blueprint, contract],
+              [undefined, undefined]
+            ), this._isRevive
+          ) || [undefined, undefined])
+        )
+      );
+    }
+
+    return palletTx.instantiateWithCode(
+      value,
+      // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+      // @ts-ignore jiggle v1 weights, metadata points to latest
+      this._isWeightV1
+        ? convertWeight(gasLimit).v1Weight
+        : convertWeight(gasLimit).v2Weight,
+      storageDepositLimit,
+      compactAddLength(this.code),
+      this.abi.findConstructor(constructorOrId).toU8a(params),
+      encodeSalt(salt)
+    ).withResultTransform((result: ISubmittableResult) =>
+      new CodeSubmittableResult(result, ...(applyOnEvent(result, ['CodeStored', 'Instantiated'], (records: EventRecord[]) =>
+        records.reduce<[Blueprint<ApiType> | undefined, Contract<ApiType> | undefined]>(([blueprint, contract], { event }) =>
+          this.api.events.contracts.Instantiated.is(event)
+            ? [blueprint, new Contract<ApiType>(this.api, this.abi, (event as unknown as { data: [Codec, AccountId] }).data[1], this._decorateMethod)]
+            : this.api.events.contracts.CodeStored.is(event)
+              ? [new Blueprint<ApiType>(this.api, this.abi, (event as unknown as { data: [AccountId] }).data[0], this._decorateMethod), contract]
+              : [blueprint, contract],
+        [undefined, undefined]), this._isRevive
+      ) || [undefined, undefined]))
+    );
+  };
+}
+
+export function extendCode <ApiType extends ApiTypes> (type: ApiType, decorateMethod: DecorateMethod<ApiType>): CodeConstructor<ApiType> {
+  return class extends Code<ApiType> {
+    static __CodeType = type;
+
+    constructor (api: ApiBase<ApiType>, abi: string | Record<string, unknown> | Abi, wasm: Uint8Array | string | Buffer | null | undefined) {
+      super(api, abi, wasm, decorateMethod);
+    }
+  };
+}