@alephium/web3 0.5.0-rc.0 → 0.5.0-rc.2

package/dist/src/constants.d.ts

@@ -2,3 +2,4 @@ export declare const TOTAL_NUMBER_OF_GROUPS = 4;
 export declare const MIN_UTXO_SET_AMOUNT: bigint;
 export declare const ALPH_TOKEN_ID: string;
 export declare const ONE_ALPH: bigint;
+export declare const DUST_AMOUNT: bigint;

package/dist/src/constants.js

@@ -17,8 +17,9 @@ You should have received a copy of the GNU Lesser General Public License
 along with the library. If not, see <http://www.gnu.org/licenses/>.
 */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ONE_ALPH = exports.ALPH_TOKEN_ID = exports.MIN_UTXO_SET_AMOUNT = exports.TOTAL_NUMBER_OF_GROUPS = void 0;
+exports.DUST_AMOUNT = exports.ONE_ALPH = exports.ALPH_TOKEN_ID = exports.MIN_UTXO_SET_AMOUNT = exports.TOTAL_NUMBER_OF_GROUPS = void 0;
 exports.TOTAL_NUMBER_OF_GROUPS = 4;
 exports.MIN_UTXO_SET_AMOUNT = BigInt(1000000000000);
 exports.ALPH_TOKEN_ID = ''.padStart(64, '0');
 exports.ONE_ALPH = 10n ** 18n;
+exports.DUST_AMOUNT = 10n ** 15n;

package/dist/src/contract/contract.d.ts

@@ -1,6 +1,6 @@
-import { NamedVals, node, Number256, Token, Val } from '../api';
-import { SignDeployContractTxParams, SignDeployContractTxResult, SignExecuteScriptTxParams, SignerProvider } from '../signer';
-import { SubscribeOptions } from '../utils';
+import { NamedVals, node, Number256, Token } from '../api';
+import { SignDeployContractTxParams, SignDeployContractTxResult, SignExecuteScriptTxParams, SignerProvider, Address } from '../signer';
+import { SubscribeOptions, Optional } from '../utils';
 import { EventSubscription } from './events';
 export declare type FieldsSig = node.FieldsSig;
 export declare type EventSig = node.EventSig;
@@ -127,12 +127,12 @@ export declare class Contract extends Artifact {
     static ContractDestroyedEventIndex: number;
     static ContractDestroyedEvent: EventSig;
     static fromApiEvent(event: node.ContractEventByTxId, codeHash: string | undefined, txId: string): ContractEvent;
-    fromApiTestContractResult(methodIndex: number, result: node.TestContractResult, txId: string): TestContractResult;
+    fromApiTestContractResult(methodName: string, result: node.TestContractResult, txId: string): TestContractResult<unknown>;
     txParamsForDeployment<P extends Fields>(signer: SignerProvider, params: DeployContractParams<P>): Promise<SignDeployContractTxParams>;
     buildByteCodeToDeploy(initialFields: Fields): string;
     static fromApiEvents(events: node.ContractEventByTxId[], addressToCodeHash: Map<string, string>, txId: string): ContractEvent[];
     toApiCallContract<T extends Arguments>(params: CallContractParams<T>, groupIndex: number, contractAddress: string, methodIndex: number): node.CallContract;
-    fromApiCallContractResult(result: node.CallContractResult, txId: string, methodIndex: number): CallContractResult;
+    fromApiCallContractResult(result: node.CallContractResult, txId: string, methodIndex: number): CallContractResult<unknown>;
 }
 export declare class Script extends Artifact {
     readonly bytecodeTemplate: string;
@@ -185,10 +185,10 @@ export interface ContractEvent<T extends Fields = Fields> {
     fields: T;
 }
 export declare type DebugMessage = node.DebugMessage;
-export interface TestContractResult {
+export interface TestContractResult<R> {
     contractId: string;
     contractAddress: string;
-    returns: Val[];
+    returns: R;
     gasUsed: number;
     contracts: ContractState[];
     txOutputs: Output[];
@@ -220,11 +220,12 @@ export interface DeployContractParams<P extends Fields = Fields> {
 export declare type DeployContractResult<T> = SignDeployContractTxResult & {
     instance: T;
 };
-export declare abstract class ContractFactory<T, P extends Fields = Fields> {
+export declare abstract class ContractFactory<I, F extends Fields = Fields> {
     readonly contract: Contract;
     constructor(contract: Contract);
-    deploy(signer: SignerProvider, deployParams: DeployContractParams<P>): Promise<DeployContractResult<T>>;
-    abstract at(address: string): T;
+    abstract at(address: string): I;
+    deploy(signer: SignerProvider, deployParams: DeployContractParams<F>): Promise<DeployContractResult<I>>;
+    stateForTest(initFields: F, asset?: Asset, address?: string): ContractState<F>;
 }
 export interface ExecuteScriptParams<P extends Fields = Fields> {
     initialFields: P;
@@ -248,8 +249,8 @@ export interface CallContractParams<T extends Arguments = Arguments> {
     existingContracts?: string[];
     inputAssets?: node.TestInputAsset[];
 }
-export interface CallContractResult {
-    returns: Val[];
+export interface CallContractResult<R> {
+    returns: R;
     gasUsed: number;
     contracts: ContractState[];
     txInputs: string[];
@@ -264,5 +265,19 @@ export declare type ContractDestroyedEvent = ContractEvent<{
 }>;
 export declare function decodeContractCreatedEvent(event: node.ContractEvent): Omit<ContractCreatedEvent, 'contractAddress'>;
 export declare function decodeContractDestroyedEvent(event: node.ContractEvent): Omit<ContractDestroyedEvent, 'contractAddress'>;
-export declare function subscribeEventsFromContract<T extends Fields>(options: SubscribeOptions<ContractEvent<T>>, address: string, eventIndex: number, decodeFunc: (event: node.ContractEvent) => ContractEvent<T>, fromCount?: number): EventSubscription;
+export declare function subscribeEventsFromContract<T extends Fields, M extends ContractEvent<T>>(options: SubscribeOptions<M>, address: string, eventIndex: number, decodeFunc: (event: node.ContractEvent) => M, fromCount?: number): EventSubscription;
+export declare function testMethod<I, F extends Fields, A extends Arguments, R>(contract: ContractFactory<I, F>, methodName: string, params: Optional<TestContractParams<F, A>, 'testArgs' | 'initialFields'>): Promise<TestContractResult<R>>;
+export declare abstract class ContractInstance {
+    readonly address: Address;
+    readonly contractId: string;
+    readonly groupIndex: number;
+    constructor(address: Address);
+}
+export declare function fetchContractState<F extends Fields, I extends ContractInstance>(contract: ContractFactory<I, F>, instance: ContractInstance): Promise<ContractState<F>>;
+export declare function subscribeContractCreatedEvent(instance: ContractInstance, options: SubscribeOptions<ContractCreatedEvent>, fromCount?: number): EventSubscription;
+export declare function subscribeContractDestroyedEvent(instance: ContractInstance, options: SubscribeOptions<ContractDestroyedEvent>, fromCount?: number): EventSubscription;
+export declare function decodeEvent<F extends Fields, M extends ContractEvent<F>>(contract: Contract, instance: ContractInstance, event: node.ContractEvent, targetEventIndex: number): M;
+export declare function subscribeContractEvent<F extends Fields, M extends ContractEvent<F>>(contract: Contract, instance: ContractInstance, options: SubscribeOptions<M>, eventName: string, fromCount?: number): EventSubscription;
+export declare function subscribeAllEvents(contract: Contract, instance: ContractInstance, options: SubscribeOptions<ContractEvent<any>>, fromCount?: number): EventSubscription;
+export declare function callMethod<I, F extends Fields, A extends Arguments, R>(contract: ContractFactory<I, F>, instance: ContractInstance, methodName: string, params: Optional<CallContractParams<A>, 'args'>): Promise<CallContractResult<R>>;
 export {};

package/dist/src/contract/contract.js

@@ -43,7 +43,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.subscribeEventsFromContract = exports.decodeContractDestroyedEvent = exports.decodeContractCreatedEvent = exports.ContractFactory = exports.randomTxId = exports.toApiVals = exports.Script = exports.Contract = exports.Artifact = exports.Project = exports.DEFAULT_COMPILER_OPTIONS = exports.DEFAULT_NODE_COMPILER_OPTIONS = void 0;
+exports.callMethod = exports.subscribeAllEvents = exports.subscribeContractEvent = exports.decodeEvent = exports.subscribeContractDestroyedEvent = exports.subscribeContractCreatedEvent = exports.fetchContractState = exports.ContractInstance = exports.testMethod = exports.subscribeEventsFromContract = exports.decodeContractDestroyedEvent = exports.decodeContractCreatedEvent = exports.ContractFactory = exports.randomTxId = exports.toApiVals = exports.Script = exports.Contract = exports.Artifact = exports.Project = exports.DEFAULT_COMPILER_OPTIONS = exports.DEFAULT_NODE_COMPILER_OPTIONS = void 0;
 const buffer_1 = require("buffer/");
 const crypto_1 = require("crypto");
 const fs_1 = __importDefault(require("fs"));
@@ -54,6 +54,7 @@ const utils_1 = require("../utils");
 const global_1 = require("../global");
 const path = __importStar(require("path"));
 const events_1 = require("./events");
+const constants_1 = require("../constants");
 var SourceKind;
 (function (SourceKind) {
     SourceKind[SourceKind["Contract"] = 0] = "Contract";
@@ -598,14 +599,18 @@ class Contract extends Artifact {
             fields: fromApiEventFields(event.fields, eventSig)
         };
     }
-    fromApiTestContractResult(methodIndex, result, txId) {
+    fromApiTestContractResult(methodName, result, txId) {
+        const methodIndex = this.functions.findIndex((sig) => sig.name === methodName);
+        const returnTypes = this.functions[`${methodIndex}`].returnTypes;
+        const rawReturn = (0, api_1.fromApiArray)(result.returns, returnTypes);
+        const returns = rawReturn.length === 0 ? null : rawReturn.length === 1 ? rawReturn[0] : rawReturn;
         const addressToCodeHash = new Map();
         addressToCodeHash.set(result.address, result.codeHash);
         result.contracts.forEach((contract) => addressToCodeHash.set(contract.address, contract.codeHash));
         return {
             contractId: (0, utils_1.binToHex)((0, utils_1.contractIdFromAddress)(result.address)),
             contractAddress: result.address,
-            returns: (0, api_1.fromApiArray)(result.returns, this.functions[`${methodIndex}`].returnTypes),
+            returns: returns,
             gasUsed: result.gasUsed,
             contracts: result.contracts.map((contract) => Contract.fromApiContractState(contract)),
             txOutputs: result.txOutputs.map(fromApiOutput),
@@ -653,10 +658,11 @@ class Contract extends Artifact {
         };
     }
     fromApiCallContractResult(result, txId, methodIndex) {
+        const returnTypes = this.functions[`${methodIndex}`].returnTypes;
+        const rawReturn = (0, api_1.fromApiArray)(result.returns, returnTypes);
+        const returns = rawReturn.length === 0 ? null : rawReturn.length === 1 ? rawReturn[0] : rawReturn;
         const addressToCodeHash = new Map();
         result.contracts.forEach((contract) => addressToCodeHash.set(contract.address, contract.codeHash));
-        const functionSig = this.functions[`${methodIndex}`];
-        const returns = (0, api_1.fromApiArray)(result.returns, functionSig.returnTypes);
         return {
             returns: returns,
             gasUsed: result.gasUsed,
@@ -856,6 +862,14 @@ class ContractFactory {
             instance: this.at(result.contractAddress)
         };
     }
+    // This is used for testing contract functions
+    stateForTest(initFields, asset, address) {
+        const newAsset = {
+            alphAmount: asset?.alphAmount ?? constants_1.ONE_ALPH,
+            tokens: asset?.tokens
+        };
+        return this.contract.toState(initFields, newAsset, address);
+    }
 }
 exports.ContractFactory = ContractFactory;
 function decodeFields(event, eventSig, eventIndex) {
@@ -904,3 +918,120 @@ function subscribeEventsFromContract(options, address, eventIndex, decodeFunc, f
     return (0, events_1.subscribeToEvents)(opt, address, fromCount);
 }
 exports.subscribeEventsFromContract = subscribeEventsFromContract;
+async function testMethod(contract, methodName, params) {
+    const txId = params?.txId ?? randomTxId();
+    const apiParams = contract.contract.toApiTestContractParams(methodName, {
+        ...params,
+        txId: txId,
+        initialFields: params.initialFields === undefined ? {} : params.initialFields,
+        testArgs: params.testArgs === undefined ? {} : params.testArgs
+    });
+    const apiResult = await (0, global_1.getCurrentNodeProvider)().contracts.postContractsTestContract(apiParams);
+    const testResult = contract.contract.fromApiTestContractResult(methodName, apiResult, txId);
+    contract.contract.printDebugMessages(methodName, testResult.debugMessages);
+    return testResult;
+}
+exports.testMethod = testMethod;
+class ContractInstance {
+    constructor(address) {
+        this.address = address;
+        this.contractId = (0, utils_1.binToHex)((0, utils_1.contractIdFromAddress)(address));
+        this.groupIndex = (0, utils_1.groupOfAddress)(address);
+    }
+}
+exports.ContractInstance = ContractInstance;
+async function fetchContractState(contract, instance) {
+    const contractState = await (0, global_1.getCurrentNodeProvider)().contracts.getContractsAddressState(instance.address, {
+        group: instance.groupIndex
+    });
+    const state = contract.contract.fromApiContractState(contractState);
+    return {
+        ...state,
+        fields: state.fields
+    };
+}
+exports.fetchContractState = fetchContractState;
+function subscribeContractCreatedEvent(instance, options, fromCount) {
+    return subscribeEventsFromContract(options, instance.address, Contract.ContractCreatedEventIndex, (event) => {
+        return {
+            ...decodeContractCreatedEvent(event),
+            contractAddress: instance.address
+        };
+    }, fromCount);
+}
+exports.subscribeContractCreatedEvent = subscribeContractCreatedEvent;
+function subscribeContractDestroyedEvent(instance, options, fromCount) {
+    return subscribeEventsFromContract(options, instance.address, Contract.ContractDestroyedEventIndex, (event) => {
+        return {
+            ...decodeContractDestroyedEvent(event),
+            contractAddress: instance.address
+        };
+    }, fromCount);
+}
+exports.subscribeContractDestroyedEvent = subscribeContractDestroyedEvent;
+function decodeEvent(contract, instance, event, targetEventIndex) {
+    if (event.eventIndex !== targetEventIndex &&
+        !(targetEventIndex >= 0 && targetEventIndex < contract.eventsSig.length)) {
+        throw new Error('Invalid event index: ' + event.eventIndex + ', expected: ' + targetEventIndex);
+    }
+    const eventSig = contract.eventsSig[`${targetEventIndex}`];
+    const fieldNames = eventSig.fieldNames;
+    const fieldTypes = eventSig.fieldTypes;
+    const fields = (0, api_1.fromApiVals)(event.fields, fieldNames, fieldTypes);
+    return {
+        contractAddress: instance.address,
+        blockHash: event.blockHash,
+        txId: event.txId,
+        eventIndex: event.eventIndex,
+        name: eventSig.name,
+        fields: fields
+    };
+}
+exports.decodeEvent = decodeEvent;
+function subscribeContractEvent(contract, instance, options, eventName, fromCount) {
+    const eventIndex = contract.eventsSig.findIndex((sig) => sig.name === eventName);
+    return subscribeEventsFromContract(options, instance.address, eventIndex, (event) => decodeEvent(contract, instance, event, eventIndex), fromCount);
+}
+exports.subscribeContractEvent = subscribeContractEvent;
+function subscribeAllEvents(contract, instance, options, fromCount) {
+    const messageCallback = (event) => {
+        switch (event.eventIndex) {
+            case Contract.ContractCreatedEventIndex: {
+                return options.messageCallback({
+                    ...decodeContractCreatedEvent(event),
+                    contractAddress: instance.address
+                });
+            }
+            case Contract.ContractDestroyedEventIndex: {
+                return options.messageCallback({
+                    ...decodeContractDestroyedEvent(event),
+                    contractAddress: instance.address
+                });
+            }
+            default:
+                return options.messageCallback({
+                    ...decodeEvent(contract, instance, event, event.eventIndex),
+                    contractAddress: instance.address
+                });
+        }
+    };
+    const errorCallback = (err, subscription) => {
+        return options.errorCallback(err, subscription);
+    };
+    const opt = {
+        pollingInterval: options.pollingInterval,
+        messageCallback: messageCallback,
+        errorCallback: errorCallback
+    };
+    return (0, events_1.subscribeToEvents)(opt, instance.address, fromCount);
+}
+exports.subscribeAllEvents = subscribeAllEvents;
+async function callMethod(contract, instance, methodName, params) {
+    const methodIndex = contract.contract.getMethodIndex(methodName);
+    const txId = params?.txId ?? randomTxId();
+    const callParams = contract.contract.toApiCallContract({ ...params, txId: txId, args: params.args === undefined ? {} : params.args }, instance.groupIndex, instance.address, methodIndex);
+    const result = await (0, global_1.getCurrentNodeProvider)().contracts.postContractsCallContract(callParams);
+    const callResult = contract.contract.fromApiCallContractResult(result, txId, methodIndex);
+    return callResult;
+}
+exports.callMethod = callMethod;

package/dist/src/utils/utils.d.ts

@@ -29,4 +29,5 @@ export declare type Eq<X, Y> = _Eq<{
     [P in keyof Y]: Y[P];
 }>;
 export declare function assertType<T extends true>(): void;
+export declare type Optional<T, K extends keyof T> = Pick<Partial<T>, K> & Omit<T, K>;
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alephium/web3",
-  "version": "0.5.0-rc.0",
+  "version": "0.5.0-rc.2",
   "description": "A JS/TS library to interact with the Alephium platform",
   "license": "GPL",
   "main": "dist/src/index.js",
@@ -27,7 +27,7 @@
   },
   "author": "Alephium dev <dev@alephium.org>",
   "config": {
-    "alephium_version": "1.7.0-rc1",
+    "alephium_version": "1.7.0",
     "explorer_backend_version": "1.12.0"
   },
   "scripts": {

package/src/constants.ts

@@ -20,3 +20,4 @@ export const TOTAL_NUMBER_OF_GROUPS = 4
 export const MIN_UTXO_SET_AMOUNT = BigInt(1000000000000)
 export const ALPH_TOKEN_ID = ''.padStart(64, '0')
 export const ONE_ALPH = 10n ** 18n
+export const DUST_AMOUNT = 10n ** 15n

package/src/contract/contract.ts

@@ -40,13 +40,25 @@ import {
   SignDeployContractTxParams,
   SignDeployContractTxResult,
   SignExecuteScriptTxParams,
-  SignerProvider
+  SignerProvider,
+  Address
 } from '../signer'
 import * as ralph from './ralph'
-import { bs58, binToHex, contractIdFromAddress, SubscribeOptions, Subscription, assertType, Eq } from '../utils'
+import {
+  bs58,
+  binToHex,
+  contractIdFromAddress,
+  SubscribeOptions,
+  Subscription,
+  assertType,
+  Eq,
+  Optional,
+  groupOfAddress
+} from '../utils'
 import { getCurrentNodeProvider } from '../global'
 import * as path from 'path'
 import { EventSubscription, subscribeToEvents } from './events'
+import { ONE_ALPH } from '../constants'
 
 export type FieldsSig = node.FieldsSig
 export type EventSig = node.EventSig
@@ -871,14 +883,23 @@ export class Contract extends Artifact {
     }
   }
 
-  fromApiTestContractResult(methodIndex: number, result: node.TestContractResult, txId: string): TestContractResult {
+  fromApiTestContractResult(
+    methodName: string,
+    result: node.TestContractResult,
+    txId: string
+  ): TestContractResult<unknown> {
+    const methodIndex = this.functions.findIndex((sig) => sig.name === methodName)
+    const returnTypes = this.functions[`${methodIndex}`].returnTypes
+    const rawReturn = fromApiArray(result.returns, returnTypes)
+    const returns = rawReturn.length === 0 ? null : rawReturn.length === 1 ? rawReturn[0] : rawReturn
+
     const addressToCodeHash = new Map<string, string>()
     addressToCodeHash.set(result.address, result.codeHash)
     result.contracts.forEach((contract) => addressToCodeHash.set(contract.address, contract.codeHash))
     return {
       contractId: binToHex(contractIdFromAddress(result.address)),
       contractAddress: result.address,
-      returns: fromApiArray(result.returns, this.functions[`${methodIndex}`].returnTypes),
+      returns: returns,
       gasUsed: result.gasUsed,
       contracts: result.contracts.map((contract) => Contract.fromApiContractState(contract)),
       txOutputs: result.txOutputs.map(fromApiOutput),
@@ -941,11 +962,17 @@ export class Contract extends Artifact {
     }
   }
 
-  fromApiCallContractResult(result: node.CallContractResult, txId: string, methodIndex: number): CallContractResult {
+  fromApiCallContractResult(
+    result: node.CallContractResult,
+    txId: string,
+    methodIndex: number
+  ): CallContractResult<unknown> {
+    const returnTypes = this.functions[`${methodIndex}`].returnTypes
+    const rawReturn = fromApiArray(result.returns, returnTypes)
+    const returns = rawReturn.length === 0 ? null : rawReturn.length === 1 ? rawReturn[0] : rawReturn
+
     const addressToCodeHash = new Map<string, string>()
     result.contracts.forEach((contract) => addressToCodeHash.set(contract.address, contract.codeHash))
-    const functionSig = this.functions[`${methodIndex}`]
-    const returns = fromApiArray(result.returns, functionSig.returnTypes)
     return {
       returns: returns,
       gasUsed: result.gasUsed,
@@ -1180,10 +1207,10 @@ export interface ContractEvent<T extends Fields = Fields> {
 
 export type DebugMessage = node.DebugMessage
 
-export interface TestContractResult {
+export interface TestContractResult<R> {
   contractId: string
   contractAddress: string
-  returns: Val[]
+  returns: R
   gasUsed: number
   contracts: ContractState[]
   txOutputs: Output[]
@@ -1250,13 +1277,16 @@ assertType<
 >
 export type DeployContractResult<T> = SignDeployContractTxResult & { instance: T }
 
-export abstract class ContractFactory<T, P extends Fields = Fields> {
+export abstract class ContractFactory<I, F extends Fields = Fields> {
   readonly contract: Contract
+
   constructor(contract: Contract) {
     this.contract = contract
   }
 
-  async deploy(signer: SignerProvider, deployParams: DeployContractParams<P>): Promise<DeployContractResult<T>> {
+  abstract at(address: string): I
+
+  async deploy(signer: SignerProvider, deployParams: DeployContractParams<F>): Promise<DeployContractResult<I>> {
     const signerParams = await this.contract.txParamsForDeployment(signer, deployParams)
     const result = await signer.signAndSubmitDeployContractTx(signerParams)
     return {
@@ -1265,7 +1295,14 @@ export abstract class ContractFactory<T, P extends Fields = Fields> {
     }
   }
 
-  abstract at(address: string): T
+  // This is used for testing contract functions
+  stateForTest(initFields: F, asset?: Asset, address?: string): ContractState<F> {
+    const newAsset = {
+      alphAmount: asset?.alphAmount ?? ONE_ALPH,
+      tokens: asset?.tokens
+    }
+    return this.contract.toState(initFields, newAsset, address)
+  }
 }
 
 export interface ExecuteScriptParams<P extends Fields = Fields> {
@@ -1293,8 +1330,8 @@ export interface CallContractParams<T extends Arguments = Arguments> {
   inputAssets?: node.TestInputAsset[]
 }
 
-export interface CallContractResult {
-  returns: Val[]
+export interface CallContractResult<R> {
+  returns: R
   gasUsed: number
   contracts: ContractState[]
   txInputs: string[]
@@ -1336,11 +1373,11 @@ export function decodeContractDestroyedEvent(
   }
 }
 
-export function subscribeEventsFromContract<T extends Fields>(
-  options: SubscribeOptions<ContractEvent<T>>,
+export function subscribeEventsFromContract<T extends Fields, M extends ContractEvent<T>>(
+  options: SubscribeOptions<M>,
   address: string,
   eventIndex: number,
-  decodeFunc: (event: node.ContractEvent) => ContractEvent<T>,
+  decodeFunc: (event: node.ContractEvent) => M,
   fromCount?: number
 ): EventSubscription {
   const messageCallback = (event: node.ContractEvent): Promise<void> => {
@@ -1351,7 +1388,7 @@ export function subscribeEventsFromContract<T extends Fields>(
   }
 
   const errorCallback = (err: any, subscription: Subscription<node.ContractEvent>): Promise<void> => {
-    return options.errorCallback(err, subscription as unknown as Subscription<ContractEvent<T>>)
+    return options.errorCallback(err, subscription as unknown as Subscription<M>)
   }
   const opt: SubscribeOptions<node.ContractEvent> = {
     pollingInterval: options.pollingInterval,
@@ -1360,3 +1397,187 @@ export function subscribeEventsFromContract<T extends Fields>(
   }
   return subscribeToEvents(opt, address, fromCount)
 }
+
+export async function testMethod<I, F extends Fields, A extends Arguments, R>(
+  contract: ContractFactory<I, F>,
+  methodName: string,
+  params: Optional<TestContractParams<F, A>, 'testArgs' | 'initialFields'>
+): Promise<TestContractResult<R>> {
+  const txId = params?.txId ?? randomTxId()
+  const apiParams = contract.contract.toApiTestContractParams(methodName, {
+    ...params,
+    txId: txId,
+    initialFields: params.initialFields === undefined ? {} : params.initialFields,
+    testArgs: params.testArgs === undefined ? {} : params.testArgs
+  })
+  const apiResult = await getCurrentNodeProvider().contracts.postContractsTestContract(apiParams)
+  const testResult = contract.contract.fromApiTestContractResult(methodName, apiResult, txId)
+  contract.contract.printDebugMessages(methodName, testResult.debugMessages)
+  return testResult as TestContractResult<R>
+}
+
+export abstract class ContractInstance {
+  readonly address: Address
+  readonly contractId: string
+  readonly groupIndex: number
+
+  constructor(address: Address) {
+    this.address = address
+    this.contractId = binToHex(contractIdFromAddress(address))
+    this.groupIndex = groupOfAddress(address)
+  }
+}
+
+export async function fetchContractState<F extends Fields, I extends ContractInstance>(
+  contract: ContractFactory<I, F>,
+  instance: ContractInstance
+): Promise<ContractState<F>> {
+  const contractState = await getCurrentNodeProvider().contracts.getContractsAddressState(instance.address, {
+    group: instance.groupIndex
+  })
+  const state = contract.contract.fromApiContractState(contractState)
+  return {
+    ...state,
+    fields: state.fields as F
+  }
+}
+
+export function subscribeContractCreatedEvent(
+  instance: ContractInstance,
+  options: SubscribeOptions<ContractCreatedEvent>,
+  fromCount?: number
+): EventSubscription {
+  return subscribeEventsFromContract(
+    options,
+    instance.address,
+    Contract.ContractCreatedEventIndex,
+    (event) => {
+      return {
+        ...decodeContractCreatedEvent(event),
+        contractAddress: instance.address
+      }
+    },
+    fromCount
+  )
+}
+
+export function subscribeContractDestroyedEvent(
+  instance: ContractInstance,
+  options: SubscribeOptions<ContractDestroyedEvent>,
+  fromCount?: number
+): EventSubscription {
+  return subscribeEventsFromContract(
+    options,
+    instance.address,
+    Contract.ContractDestroyedEventIndex,
+    (event) => {
+      return {
+        ...decodeContractDestroyedEvent(event),
+        contractAddress: instance.address
+      }
+    },
+    fromCount
+  )
+}
+
+export function decodeEvent<F extends Fields, M extends ContractEvent<F>>(
+  contract: Contract,
+  instance: ContractInstance,
+  event: node.ContractEvent,
+  targetEventIndex: number
+): M {
+  if (
+    event.eventIndex !== targetEventIndex &&
+    !(targetEventIndex >= 0 && targetEventIndex < contract.eventsSig.length)
+  ) {
+    throw new Error('Invalid event index: ' + event.eventIndex + ', expected: ' + targetEventIndex)
+  }
+  const eventSig = contract.eventsSig[`${targetEventIndex}`]
+  const fieldNames = eventSig.fieldNames
+  const fieldTypes = eventSig.fieldTypes
+  const fields = fromApiVals(event.fields, fieldNames, fieldTypes)
+  return {
+    contractAddress: instance.address,
+    blockHash: event.blockHash,
+    txId: event.txId,
+    eventIndex: event.eventIndex,
+    name: eventSig.name,
+    fields: fields
+  } as M
+}
+
+export function subscribeContractEvent<F extends Fields, M extends ContractEvent<F>>(
+  contract: Contract,
+  instance: ContractInstance,
+  options: SubscribeOptions<M>,
+  eventName: string,
+  fromCount?: number
+): EventSubscription {
+  const eventIndex = contract.eventsSig.findIndex((sig) => sig.name === eventName)
+  return subscribeEventsFromContract<F, M>(
+    options,
+    instance.address,
+    eventIndex,
+    (event) => decodeEvent(contract, instance, event, eventIndex),
+    fromCount
+  )
+}
+
+export function subscribeAllEvents(
+  contract: Contract,
+  instance: ContractInstance,
+  options: SubscribeOptions<ContractEvent<any>>,
+  fromCount?: number
+): EventSubscription {
+  const messageCallback = (event: node.ContractEvent): Promise<void> => {
+    switch (event.eventIndex) {
+      case Contract.ContractCreatedEventIndex: {
+        return options.messageCallback({
+          ...decodeContractCreatedEvent(event),
+          contractAddress: instance.address
+        })
+      }
+
+      case Contract.ContractDestroyedEventIndex: {
+        return options.messageCallback({
+          ...decodeContractDestroyedEvent(event),
+          contractAddress: instance.address
+        })
+      }
+
+      default:
+        return options.messageCallback({
+          ...decodeEvent(contract, instance, event, event.eventIndex),
+          contractAddress: instance.address
+        })
+    }
+  }
+  const errorCallback = (err: any, subscription: Subscription<node.ContractEvent>): Promise<void> => {
+    return options.errorCallback(err, subscription as unknown as Subscription<ContractEvent<any>>)
+  }
+  const opt: SubscribeOptions<node.ContractEvent> = {
+    pollingInterval: options.pollingInterval,
+    messageCallback: messageCallback,
+    errorCallback: errorCallback
+  }
+  return subscribeToEvents(opt, instance.address, fromCount)
+}
+
+export async function callMethod<I, F extends Fields, A extends Arguments, R>(
+  contract: ContractFactory<I, F>,
+  instance: ContractInstance,
+  methodName: string,
+  params: Optional<CallContractParams<A>, 'args'>
+): Promise<CallContractResult<R>> {
+  const methodIndex = contract.contract.getMethodIndex(methodName)
+  const txId = params?.txId ?? randomTxId()
+  const callParams = contract.contract.toApiCallContract(
+    { ...params, txId: txId, args: params.args === undefined ? {} : params.args },
+    instance.groupIndex,
+    instance.address,
+    methodIndex
+  )
+  const result = await getCurrentNodeProvider().contracts.postContractsCallContract(callParams)
+  const callResult = contract.contract.fromApiCallContractResult(result, txId, methodIndex)
+  return callResult as CallContractResult<R>
+}

package/src/utils/utils.ts

@@ -219,3 +219,4 @@ type _Eq<X, Y> = (<T>() => T extends X ? 1 : 2) extends <T>() => T extends Y ? 1
 export type Eq<X, Y> = _Eq<{ [P in keyof X]: X[P] }, { [P in keyof Y]: Y[P] }>
 // eslint-disable-next-line @typescript-eslint/no-empty-function, @typescript-eslint/no-unused-vars
 export function assertType<T extends true>(): void {}
+export type Optional<T, K extends keyof T> = Pick<Partial<T>, K> & Omit<T, K>