@alephium/web3 0.4.0 → 0.5.0-rc.1

package/src/contract/contract.ts

@@ -33,26 +33,39 @@ import {
   Token,
   Val,
   fromApiTokens,
-  fromApiVals
+  fromApiVals,
+  typeLength
 } from '../api'
 import {
   SignDeployContractTxParams,
+  SignDeployContractTxResult,
   SignExecuteScriptTxParams,
   SignerProvider,
-  SignExecuteScriptTxResult,
-  SignDeployContractTxResult
+  Address
 } from '../signer'
 import * as ralph from './ralph'
-import { bs58, binToHex, contractIdFromAddress, assertType, Eq } from '../utils'
+import {
+  bs58,
+  binToHex,
+  contractIdFromAddress,
+  SubscribeOptions,
+  Subscription,
+  assertType,
+  Eq,
+  Optional,
+  groupOfAddress
+} from '../utils'
 import { getCurrentNodeProvider } from '../global'
-import { web3 } from '..'
 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
 export type FunctionSig = node.FunctionSig
 export type Fields = NamedVals
 export type Arguments = NamedVals
+export type HexString = string
 
 enum SourceKind {
   Contract = 0,
@@ -354,7 +367,7 @@ export class Project {
     return script.artifact
   }
 
-  private async saveArtifactsToFile(): Promise<void> {
+  private async saveArtifactsToFile(projectRootDir: string): Promise<void> {
     const artifactsRootDir = this.artifactsRootDir
     const saveToFile = async function (compiled: Compiled<Artifact>): Promise<void> {
       const artifactPath = compiled.sourceInfo.getArtifactPath(artifactsRootDir)
@@ -366,7 +379,7 @@ export class Project {
     }
     this.contracts.forEach((contract) => saveToFile(contract))
     this.scripts.forEach((script) => saveToFile(script))
-    await this.projectArtifact.saveToFile(this.artifactsRootDir)
+    await this.projectArtifact.saveToFile(projectRootDir)
   }
 
   contractByCodeHash(codeHash: string): Contract {
@@ -382,6 +395,7 @@ export class Project {
   private static async compile(
     provider: NodeProvider,
     sourceInfos: SourceInfo[],
+    projectRootDir: string,
     contractsRootDir: string,
     artifactsRootDir: string,
     errorOnWarnings: boolean,
@@ -414,7 +428,7 @@ export class Project {
       errorOnWarnings,
       projectArtifact
     )
-    await project.saveArtifactsToFile()
+    await project.saveArtifactsToFile(projectRootDir)
     return project
   }
 
@@ -422,6 +436,7 @@ export class Project {
     provider: NodeProvider,
     sourceInfos: SourceInfo[],
     projectArtifact: ProjectArtifact,
+    projectRootDir: string,
     contractsRootDir: string,
     artifactsRootDir: string,
     errorOnWarnings: boolean,
@@ -460,6 +475,7 @@ export class Project {
       return Project.compile(
         provider,
         sourceInfos,
+        projectRootDir,
         contractsRootDir,
         artifactsRootDir,
         errorOnWarnings,
@@ -590,12 +606,13 @@ export class Project {
     const provider = getCurrentNodeProvider()
     const sourceFiles = await Project.loadSourceFiles(projectRootDir, contractsRootDir)
     const { errorOnWarnings, ...nodeCompilerOptions } = { ...DEFAULT_COMPILER_OPTIONS, ...compilerOptionsPartial }
-    const projectArtifact = await ProjectArtifact.from(artifactsRootDir)
+    const projectArtifact = await ProjectArtifact.from(projectRootDir)
     if (typeof projectArtifact === 'undefined' || projectArtifact.needToReCompile(nodeCompilerOptions, sourceFiles)) {
       console.log(`Compiling contracts in folder "${contractsRootDir}"`)
       Project.currentProject = await Project.compile(
         provider,
         sourceFiles,
+        projectRootDir,
         contractsRootDir,
         artifactsRootDir,
         errorOnWarnings,
@@ -607,6 +624,7 @@ export class Project {
         provider,
         sourceFiles,
         projectArtifact,
+        projectRootDir,
         contractsRootDir,
         artifactsRootDir,
         errorOnWarnings,
@@ -722,13 +740,6 @@ export class Contract extends Artifact {
     return Contract.fromJson(artifact, bytecodeDebugPatch, codeHashDebug)
   }
 
-  async fetchState(address: string, group: number): Promise<ContractState> {
-    const state = await web3.getCurrentNodeProvider().contracts.getContractsAddressState(address, {
-      group: group
-    })
-    return this.fromApiContractState(state)
-  }
-
   override toString(): string {
     const object = {
       version: this.version,
@@ -742,7 +753,7 @@ export class Contract extends Artifact {
     return JSON.stringify(object, null, 2)
   }
 
-  toState(fields: Fields, asset: Asset, address?: string): ContractState {
+  toState<T extends Fields>(fields: T, asset: Asset, address?: string): ContractState<T> {
     const addressDef = typeof address !== 'undefined' ? address : Contract.randomAddress()
     return {
       address: addressDef,
@@ -763,53 +774,13 @@ export class Contract extends Artifact {
     return bs58.encode(bytes)
   }
 
-  private _printDebugMessages(funcName: string, messages: DebugMessage[]) {
+  printDebugMessages(funcName: string, messages: DebugMessage[]) {
     if (messages.length != 0) {
       console.log(`Testing ${this.name}.${funcName}:`)
       messages.forEach((m) => console.log(`Debug - ${m.contractAddress} - ${m.message}`))
     }
   }
 
-  private async _test(
-    funcName: string,
-    params: TestContractParams,
-    expectPublic: boolean,
-    accessType: string,
-    printDebugMessages: boolean
-  ): Promise<TestContractResult> {
-    const apiParams: node.TestContract = this.toTestContract(funcName, params)
-    const apiResult = await web3.getCurrentNodeProvider().contracts.postContractsTestContract(apiParams)
-
-    const methodIndex =
-      typeof params.testMethodIndex !== 'undefined' ? params.testMethodIndex : this.getMethodIndex(funcName)
-    const isPublic = this.functions[`${methodIndex}`].isPublic
-    if (printDebugMessages) {
-      this._printDebugMessages(funcName, apiResult.debugMessages)
-    }
-    if (isPublic === expectPublic) {
-      const result = await this.fromTestContractResult(methodIndex, apiResult)
-      return result
-    } else {
-      throw new Error(`The test method ${funcName} is not ${accessType}`)
-    }
-  }
-
-  async testPublicMethod(
-    funcName: string,
-    params: TestContractParams,
-    printDebugMessages = true
-  ): Promise<TestContractResult> {
-    return this._test(funcName, params, true, 'public', printDebugMessages)
-  }
-
-  async testPrivateMethod(
-    funcName: string,
-    params: TestContractParams,
-    printDebugMessages = true
-  ): Promise<TestContractResult> {
-    return this._test(funcName, params, false, 'private', printDebugMessages)
-  }
-
   toApiFields(fields?: Fields): node.Val[] {
     if (typeof fields === 'undefined') {
       return []
@@ -839,12 +810,17 @@ export class Contract extends Artifact {
     return typeof states != 'undefined' ? states.map((state) => toApiContractState(state)) : undefined
   }
 
-  toTestContract(funcName: string, params: TestContractParams): node.TestContract {
+  toApiTestContractParams(funcName: string, params: TestContractParams): node.TestContract {
+    const immFields =
+      params.initialFields === undefined ? [] : extractFields(params.initialFields, this.fieldsSig, false)
+    const mutFields =
+      params.initialFields === undefined ? [] : extractFields(params.initialFields, this.fieldsSig, true)
     return {
       group: params.group,
       address: params.address,
       bytecode: this.bytecodeDebug,
-      initialFields: this.toApiFields(params.initialFields),
+      initialImmFields: immFields,
+      initialMutFields: mutFields,
       initialAsset: typeof params.initialAsset !== 'undefined' ? toApiAsset(params.initialAsset) : undefined,
       methodIndex: this.getMethodIndex(funcName),
       args: this.toApiArgs(funcName, params.testArgs),
@@ -853,14 +829,14 @@ export class Contract extends Artifact {
     }
   }
 
-  fromApiContractState(state: node.ContractState): ContractState {
+  fromApiContractState(state: node.ContractState): ContractState<Fields> {
     return {
       address: state.address,
       contractId: binToHex(contractIdFromAddress(state.address)),
       bytecode: state.bytecode,
       initialStateHash: state.initialStateHash,
       codeHash: state.codeHash,
-      fields: fromApiFields(state.fields, this.fieldsSig),
+      fields: fromApiFields(state.immFields, state.mutFields, this.fieldsSig),
       fieldsSig: this.fieldsSig,
       asset: fromApiAsset(state.asset)
     }
@@ -871,24 +847,26 @@ export class Contract extends Artifact {
     return contract.fromApiContractState(state)
   }
 
+  static ContractCreatedEventIndex = -1
   static ContractCreatedEvent: EventSig = {
     name: 'ContractCreated',
     fieldNames: ['address'],
     fieldTypes: ['Address']
   }
 
+  static ContractDestroyedEventIndex = -2
   static ContractDestroyedEvent: EventSig = {
     name: 'ContractDestroyed',
     fieldNames: ['address'],
     fieldTypes: ['Address']
   }
 
-  static fromApiEvent(event: node.ContractEventByTxId, codeHash: string | undefined): ContractEventByTxId {
+  static fromApiEvent(event: node.ContractEventByTxId, codeHash: string | undefined, txId: string): ContractEvent {
     let eventSig: EventSig
 
-    if (event.eventIndex == -1) {
+    if (event.eventIndex == Contract.ContractCreatedEventIndex) {
       eventSig = this.ContractCreatedEvent
-    } else if (event.eventIndex == -2) {
+    } else if (event.eventIndex == Contract.ContractDestroyedEventIndex) {
       eventSig = this.ContractDestroyedEvent
     } else {
       const contract = Project.currentProject.contractByCodeHash(codeHash!)
@@ -896,65 +874,114 @@ export class Contract extends Artifact {
     }
 
     return {
+      txId: txId,
       blockHash: event.blockHash,
       contractAddress: event.contractAddress,
       name: eventSig.name,
+      eventIndex: event.eventIndex,
       fields: fromApiEventFields(event.fields, eventSig)
     }
   }
 
-  fromTestContractResult(methodIndex: number, result: node.TestContractResult): 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),
-      events: result.events.map((event) => {
-        const contractAddress = event.contractAddress
-        const codeHash = addressToCodeHash.get(contractAddress)
-        if (typeof codeHash !== 'undefined' || event.eventIndex < 0) {
-          return Contract.fromApiEvent(event, codeHash)
-        } else {
-          throw Error(`Cannot find codeHash for the contract address: ${contractAddress}`)
-        }
-      }),
+      events: Contract.fromApiEvents(result.events, addressToCodeHash, txId),
       debugMessages: result.debugMessages
     }
   }
 
-  async txParamsForDeployment(
+  async txParamsForDeployment<P extends Fields>(
     signer: SignerProvider,
-    params: Omit<BuildDeployContractTx, 'signerAddress'>
+    params: DeployContractParams<P>
   ): Promise<SignDeployContractTxParams> {
-    const bytecode = this.buildByteCodeToDeploy(params.initialFields ? params.initialFields : {})
+    const bytecode = this.buildByteCodeToDeploy(params.initialFields ?? {})
     const signerParams: SignDeployContractTxParams = {
       signerAddress: await signer.getSelectedAddress(),
       bytecode: bytecode,
-      initialAttoAlphAmount: params.initialAttoAlphAmount,
-      issueTokenAmount: params.issueTokenAmount,
-      initialTokenAmounts: params.initialTokenAmounts,
-      gasAmount: params.gasAmount,
-      gasPrice: params.gasPrice
+      initialAttoAlphAmount: params?.initialAttoAlphAmount,
+      issueTokenAmount: params?.issueTokenAmount,
+      initialTokenAmounts: params?.initialTokenAmounts,
+      gasAmount: params?.gasAmount,
+      gasPrice: params?.gasPrice
     }
     return signerParams
   }
 
-  async deploy(
-    signer: SignerProvider,
-    params: Omit<BuildDeployContractTx, 'signerAddress'>
-  ): Promise<SignDeployContractTxResult> {
-    const signerParams = await this.txParamsForDeployment(signer, params)
-    return signer.signAndSubmitDeployContractTx(signerParams)
-  }
-
   buildByteCodeToDeploy(initialFields: Fields): string {
     return ralph.buildContractByteCode(this.bytecode, initialFields, this.fieldsSig)
   }
+
+  static fromApiEvents(
+    events: node.ContractEventByTxId[],
+    addressToCodeHash: Map<string, string>,
+    txId: string
+  ): ContractEvent[] {
+    return events.map((event) => {
+      const contractAddress = event.contractAddress
+      const codeHash = addressToCodeHash.get(contractAddress)
+      if (typeof codeHash !== 'undefined' || event.eventIndex < 0) {
+        return Contract.fromApiEvent(event, codeHash, txId)
+      } else {
+        throw Error(`Cannot find codeHash for the contract address: ${contractAddress}`)
+      }
+    })
+  }
+
+  toApiCallContract<T extends Arguments>(
+    params: CallContractParams<T>,
+    groupIndex: number,
+    contractAddress: string,
+    methodIndex: number
+  ): node.CallContract {
+    const functionSig = this.functions[`${methodIndex}`]
+    const args = toApiVals(params.args ?? {}, functionSig.paramNames, functionSig.paramTypes)
+    return {
+      ...params,
+      group: groupIndex,
+      address: contractAddress,
+      methodIndex: methodIndex,
+      args: args
+    }
+  }
+
+  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))
+    return {
+      returns: returns,
+      gasUsed: result.gasUsed,
+      contracts: result.contracts.map((state) => Contract.fromApiContractState(state)),
+      txInputs: result.txInputs,
+      txOutputs: result.txOutputs.map((output) => fromApiOutput(output)),
+      events: Contract.fromApiEvents(result.events, addressToCodeHash, txId)
+    }
+  }
 }
 
 export class Script extends Artifact {
@@ -1025,13 +1052,13 @@ export class Script extends Artifact {
     return JSON.stringify(object, null, 2)
   }
 
-  async txParamsForExecution(
+  async txParamsForExecution<P extends Fields>(
     signer: SignerProvider,
-    params: Omit<BuildExecuteScriptTx, 'signerAddress'>
+    params: ExecuteScriptParams<P>
   ): Promise<SignExecuteScriptTxParams> {
     const signerParams: SignExecuteScriptTxParams = {
       signerAddress: await signer.getSelectedAddress(),
-      bytecode: this.buildByteCodeToDeploy(params.initialFields ? params.initialFields : {}),
+      bytecode: this.buildByteCodeToDeploy(params.initialFields ?? {}),
       attoAlphAmount: params.attoAlphAmount,
       tokens: params.tokens,
       gasAmount: params.gasAmount,
@@ -1040,20 +1067,27 @@ export class Script extends Artifact {
     return signerParams
   }
 
-  async execute(
-    signer: SignerProvider,
-    params: Omit<BuildExecuteScriptTx, 'signerAddress'>
-  ): Promise<SignExecuteScriptTxResult> {
-    const signerParams = await this.txParamsForExecution(signer, params)
-    return await signer.signAndSubmitExecuteScriptTx(signerParams)
-  }
-
   buildByteCodeToDeploy(initialFields: Fields): string {
     return ralph.buildScriptByteCode(this.bytecodeTemplate, initialFields, this.fieldsSig)
   }
 }
 
-function fromApiFields(vals: node.Val[], fieldsSig: node.FieldsSig): Fields {
+function fromApiFields(immFields: node.Val[], mutFields: node.Val[], fieldsSig: node.FieldsSig): Fields {
+  const vals: node.Val[] = []
+  let immIndex = 0
+  let mutIndex = 0
+  const isMutable = fieldsSig.types.flatMap((tpe, index) =>
+    Array(typeLength(tpe)).fill(fieldsSig.isMutable[`${index}`])
+  )
+  isMutable.forEach((mutable) => {
+    if (mutable) {
+      vals.push(mutFields[`${mutIndex}`])
+      mutIndex += 1
+    } else {
+      vals.push(immFields[`${immIndex}`])
+      immIndex += 1
+    }
+  })
   return fromApiVals(vals, fieldsSig.names, fieldsSig.types)
 }
 
@@ -1085,13 +1119,13 @@ export interface InputAsset {
   asset: Asset
 }
 
-export interface ContractState {
+export interface ContractState<T extends Fields = Fields> {
   address: string
   contractId: string
   bytecode: string
   initialStateHash?: string
   codeHash: string
-  fields: Fields
+  fields: T
   fieldsSig: FieldsSig
   asset: Asset
 }
@@ -1104,13 +1138,24 @@ function getVal(vals: NamedVals, name: string): Val {
   }
 }
 
+function extractFields(fields: NamedVals, fieldsSig: FieldsSig, mutable: boolean) {
+  const fieldIndexes = fieldsSig.names
+    .map((_, index) => index)
+    .filter((index) => fieldsSig.isMutable[`${index}`] === mutable)
+  const fieldNames = fieldIndexes.map((index) => fieldsSig.names[`${index}`])
+  const fieldTypes = fieldIndexes.map((index) => fieldsSig.types[`${index}`])
+  return toApiVals(fields, fieldNames, fieldTypes)
+}
+
 function toApiContractState(state: ContractState): node.ContractState {
+  const stateFields = state.fields ?? {}
   return {
     address: state.address,
     bytecode: state.bytecode,
     codeHash: state.codeHash,
     initialStateHash: state.initialStateHash,
-    fields: toApiFields(state.fields, state.fieldsSig),
+    immFields: extractFields(stateFields, state.fieldsSig, false),
+    mutFields: extractFields(stateFields, state.fieldsSig, true),
     asset: toApiAsset(state.asset)
   }
 }
@@ -1123,7 +1168,7 @@ function toApiArgs(args: Arguments, funcSig: FunctionSig): node.Val[] {
   return toApiVals(args, funcSig.paramNames, funcSig.paramTypes)
 }
 
-function toApiVals(fields: Fields, names: string[], types: string[]): node.Val[] {
+export function toApiVals(fields: Fields, names: string[], types: string[]): node.Val[] {
   return names.map((name, index) => {
     const val = getVal(fields, name)
     const tpe = types[`${index}`]
@@ -1139,41 +1184,37 @@ function toApiInputAssets(inputAssets?: InputAsset[]): node.TestInputAsset[] | u
   return typeof inputAssets !== 'undefined' ? inputAssets.map(toApiInputAsset) : undefined
 }
 
-export interface TestContractParams {
+export interface TestContractParams<F extends Fields = Fields, A extends Arguments = Arguments> {
   group?: number // default 0
   address?: string
-  initialFields?: Fields // default no fields
+  blockHash?: string
+  txId?: string
+  initialFields: F
   initialAsset?: Asset // default 1 ALPH
-  testMethodIndex?: number // default 0
-  testArgs?: Arguments // default no arguments
+  testArgs: A
   existingContracts?: ContractState[] // default no existing contracts
   inputAssets?: InputAsset[] // default no input asserts
 }
 
-export interface ContractEvent {
-  blockHash: string
+export interface ContractEvent<T extends Fields = Fields> {
   txId: string
-  name: string
-  fields: Fields
-}
-
-export interface ContractEventByTxId {
   blockHash: string
   contractAddress: string
+  eventIndex: number
   name: string
-  fields: Fields
+  fields: T
 }
 
 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[]
-  events: ContractEventByTxId[]
+  events: ContractEvent[]
   debugMessages: DebugMessage[]
 }
 export declare type Output = AssetOutput | ContractOutput
@@ -1214,41 +1255,329 @@ function fromApiOutput(output: node.Output): Output {
   }
 }
 
-export interface DeployContractTransaction {
-  fromGroup: number
-  toGroup: number
-  unsignedTx: string
-  txId: string
-  contractAddress: string
-  contractId: string
+export function randomTxId(): string {
+  const bytes = new Uint8Array(32)
+  crypto.getRandomValues(bytes)
+  return binToHex(bytes)
 }
 
-type BuildTxParams<T> = Omit<T, 'bytecode'> & { initialFields?: Val[] }
-
-export interface BuildDeployContractTx {
-  signerAddress: string
-  initialFields?: Fields
+export interface DeployContractParams<P extends Fields = Fields> {
+  initialFields: P
   initialAttoAlphAmount?: Number256
   initialTokenAmounts?: Token[]
   issueTokenAmount?: Number256
   gasAmount?: number
   gasPrice?: Number256
 }
-assertType<Eq<keyof BuildDeployContractTx, keyof BuildTxParams<SignDeployContractTxParams>>>()
+assertType<
+  Eq<
+    Omit<DeployContractParams<undefined>, 'initialFields'>,
+    Omit<SignDeployContractTxParams, 'signerAddress' | 'bytecode'>
+  >
+>
+export type DeployContractResult<T> = SignDeployContractTxResult & { instance: T }
+
+export abstract class ContractFactory<I, F extends Fields = Fields> {
+  readonly contract: Contract
+
+  constructor(contract: Contract) {
+    this.contract = contract
+  }
 
-export interface BuildExecuteScriptTx {
-  signerAddress: string
-  initialFields?: Fields
+  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 {
+      ...result,
+      instance: this.at(result.contractAddress)
+    }
+  }
+
+  // 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> {
+  initialFields: P
   attoAlphAmount?: Number256
   tokens?: Token[]
   gasAmount?: number
   gasPrice?: Number256
 }
-assertType<Eq<keyof BuildExecuteScriptTx, keyof BuildTxParams<SignExecuteScriptTxParams>>>()
 
-export interface BuildScriptTxResult {
-  fromGroup: number
-  toGroup: number
+export interface ExecuteScriptResult {
+  groupIndex: number
   unsignedTx: string
   txId: string
+  signature: string
+  gasAmount: number
+  gasPrice: Number256
+}
+
+export interface CallContractParams<T extends Arguments = Arguments> {
+  args: T
+  worldStateBlockHash?: string
+  txId?: string
+  existingContracts?: string[]
+  inputAssets?: node.TestInputAsset[]
+}
+
+export interface CallContractResult<R> {
+  returns: R
+  gasUsed: number
+  contracts: ContractState[]
+  txInputs: string[]
+  txOutputs: Output[]
+  events: ContractEvent[]
+}
+
+export type ContractCreatedEvent = ContractEvent<{ address: HexString }>
+export type ContractDestroyedEvent = ContractEvent<{ address: HexString }>
+
+function decodeFields(event: node.ContractEvent, eventSig: EventSig, eventIndex: number): Fields {
+  if (event.eventIndex !== eventIndex) {
+    throw new Error(`Invalid event index: ${event.eventIndex}, expected: ${eventIndex}`)
+  }
+  return fromApiVals(event.fields, eventSig.fieldNames, eventSig.fieldTypes)
+}
+
+export function decodeContractCreatedEvent(event: node.ContractEvent): Omit<ContractCreatedEvent, 'contractAddress'> {
+  const fields = decodeFields(event, Contract.ContractCreatedEvent, Contract.ContractCreatedEventIndex)
+  return {
+    blockHash: event.blockHash,
+    txId: event.txId,
+    eventIndex: event.eventIndex,
+    name: Contract.ContractCreatedEvent.name,
+    fields: { address: fields['address'] as HexString }
+  }
+}
+
+export function decodeContractDestroyedEvent(
+  event: node.ContractEvent
+): Omit<ContractDestroyedEvent, 'contractAddress'> {
+  const fields = decodeFields(event, Contract.ContractDestroyedEvent, Contract.ContractDestroyedEventIndex)
+  return {
+    blockHash: event.blockHash,
+    txId: event.txId,
+    eventIndex: event.eventIndex,
+    name: Contract.ContractDestroyedEvent.name,
+    fields: { address: fields['address'] as HexString }
+  }
+}
+
+export function subscribeEventsFromContract<T extends Fields, M extends ContractEvent<T>>(
+  options: SubscribeOptions<M>,
+  address: string,
+  eventIndex: number,
+  decodeFunc: (event: node.ContractEvent) => M,
+  fromCount?: number
+): EventSubscription {
+  const messageCallback = (event: node.ContractEvent): Promise<void> => {
+    if (event.eventIndex !== eventIndex) {
+      return Promise.resolve()
+    }
+    return options.messageCallback(decodeFunc(event))
+  }
+
+  const errorCallback = (err: any, subscription: Subscription<node.ContractEvent>): Promise<void> => {
+    return options.errorCallback(err, subscription as unknown as Subscription<M>)
+  }
+  const opt: SubscribeOptions<node.ContractEvent> = {
+    pollingInterval: options.pollingInterval,
+    messageCallback: messageCallback,
+    errorCallback: errorCallback
+  }
+  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>
 }