import Executor from 'fincontracts-lib/src/fincontract-executor.js'

public class | source

Executor

Executor class is used for executing deployed contracts in FincontractMarketplace. By executing, we mean 'joining' the contract, which is equivalent to first owning it and then executing. Those two cannot be done separetly. It also allows for choosing OR contract (see FincOrNode).

Example:

import Executor from './fincontract-executor';
const exec = new Executor(marketplace, gateway, web3);
try {
  const executed = await exec.join(id);
  console.log(JSON.stringify(executed));
} catch (err) {
  console.log(err);
}

Static Member Summary

Static Public Members
public static get	Timeout: Number Time in seconds to trigger timeout error if nothing has happened.

Constructor Summary

Public Constructor
public	constructor(marketplace: FincontractMarketplace, gateway: Gateway, web3: Web3) Constructs the Executor object with Fincontracts smart contract instance, a Gateway smart contract instance not connected to any address and a web3 instance connected to an Ethereum node

Method Summary

Public Methods
public	async choose(fctID: String, choice: Boolean): Promise<ExecutionResult, Error> Chooses a sub-fincontract if the root (top-level) node is an OR node (see FincOrNode) and then executes it.
public	async join(fctID: String): Promise<ExecutionResult, Error> Joins the contract (owns and then executes) as defined in FincontractMarketplace given the 32-byte address of the blockchain deployed Fincontract.
public	processDeferredExecution(deleted: String): Promise<ExecutionResult, Error> Processes the deferred execution by fetching all `CreateBy` events (see FincontractMarketplace), which yield the newly created Fincontracts.
public	async pullThenUpdateGateways(fctID: String): Fincontract Pulls a Fincontract from the blockchain given its 32-byte address, then updates all its Gateways, if there are any.
public	async watchExecution(sentTransaction: Transaction): Promise<ExecutionResult, Error> Begins to watch for events associated with Fincontract execution.

Static Public Members

public static get Timeout: Number source

Time in seconds to trigger timeout error if nothing has happened. By default it's 90 seconds.

Public Constructors

public constructor(marketplace: FincontractMarketplace, gateway: Gateway, web3: Web3) source

Constructs the Executor object with Fincontracts smart contract instance, a Gateway smart contract instance not connected to any address and a web3 instance connected to an Ethereum node

Params:

Name	Type	Attribute	Description
marketplace	FincontractMarketplace		a Fincontracts smart contract instance
gateway	Gateway		a gateway instance not connected to any address
web3	Web3		a web3 instance connected to an Ethereum node

Public Methods

public async choose(fctID: String, choice: Boolean): Promise<ExecutionResult, Error> source

Chooses a sub-fincontract if the root (top-level) node is an OR node (see FincOrNode) and then executes it. Similarly to Executor#join it updates the gateways before proceeding with the actual execution

Params:

Name	Type	Attribute	Description
fctID	String		a 32-byte address of the deployed Fincontract
choice	Boolean		a choice for the sub-fincontract (1 signifies selection of the first sub-fincontract, 0 selection of the second sub-fincontract)

Return:

Promise<ExecutionResult, Error>

promise returned by Executor#watchExecution

Throw:

Error	If current user cannot own this contract
Error	If the root of the fincontract is not an OR node

public async join(fctID: String): Promise<ExecutionResult, Error> source

Joins the contract (owns and then executes) as defined in FincontractMarketplace given the 32-byte address of the blockchain deployed Fincontract. It first updates any gateways contained in the Fincontract and then sends the join transaction. For more details see Executor#pullThenUpdateGateways and GatewayUpdater#updateAllGateways

Params:

Name	Type	Attribute	Description
fctID	String		a 32-byte address of the deployed Fincontract

Return:

Promise<ExecutionResult, Error>

promise returned by Executor#watchExecution

Throw:

Error

If current user cannot own this contract

public processDeferredExecution(deleted: String): Promise<ExecutionResult, Error> source

Processes the deferred execution by fetching all CreateBy events (see FincontractMarketplace), which yield the newly created Fincontracts.

Params:

Name	Type	Attribute	Description
deleted	String		the address of recently deleted Fincontract

Return:

Promise<ExecutionResult, Error>

promise that resolve to the results of execution with ExecutionResult.newFincontracts containing a list of newly created Fincontract ids or rejects with an Error if it could not get the ids

public async pullThenUpdateGateways(fctID: String): Fincontract source

Pulls a Fincontract from the blockchain given its 32-byte address, then updates all its Gateways, if there are any.

Params:

Name	Type	Attribute	Description
fctID	String		32-byte address of a deployed Fincontract

Return:

Fincontract

pulled Fincontract from the blockchain

public async watchExecution(sentTransaction: Transaction): Promise<ExecutionResult, Error> source

Begins to watch for events associated with Fincontract execution. The Fincontract's execution can finish successfully (Executed), be postponed (Deferred) or it can timeout (Timeout).

Executed - happens only if the Fincontract does not contain any OR nodes and all Timebound nodes have starting time later than now. (see FincTimeboundNode.lowerBound)
Deferred - if the above condition is not met, then the Fincontract's execution will be deferred in time, resulting in new Fincontracts being created, while the sub-tree which was able to execute completely is executed and the its payments are enforced.
Timeout - if the transaction throws any error, the timeout will be triggered after Executor.Timeout seconds. Errors can throw, because the gateways have incorrect address, they were incorrectly updated or the transaction ran out of gas (OOG) due to recursion.

The original Fincontract is always deleted, unless the transaction threw for some reason, then all state changes are reverted as defined by the Ethereum protocol.

Params:

Name	Type	Attribute	Description
sentTransaction	Transaction		a sent Transaction object, either 'join' or 'executeOr' (see FincontractMarketplace)

Return:

Promise<ExecutionResult, Error>

an object containing the result of the execution or an Error if it timed out.