Class: Engine

Engine(address, signatureService, blockchainService)

GoNetworks Engine encapsualtes off chain interactions between clients and propogation onto the blockchain. The Engine is platform agnostic and adaptble to different blockchains by providing appropriate blockchainService adapters Overriding the send callback also allows for custom transport layers and methods (not neccessarily IP network based)

Constructor

new Engine(address, signatureService, blockchainService)

Parameters:
Name Type Description
address Buffer your ethereum address; ETH Address is merely the last 20 bytes of the keccak256 hash of the public key given the public private key pair.
signatureService function the callback that requests the privatekey for signing of messages. This allows the user to store the private key in a secure store or other means
blockchainService BlockchainService a class extending the BlockchainService class to monitor and propogate transactions on chain. Override for different Blockchains
Properties:
Name Type Default Description
msgID BN 0
currentBlock BN 0 the current block which is synchronized to the onchain mined block value via blockchainService handler callbacks
publicKey Buffer Future Use: ElGamal Elliptic Curve Asymmetric Encryption public key to be sent to channel partners
initiatorStateMachine InitiatorFactory stateMachine.IntiatorFactory creates a new state machine for mediated transfers you initiate
targeStateMachine TargetFactory stateMachine.TargetFactory creates a new state machine for mediated transfers that are intended for you
messageState object {} tracks the state of mediated transfer messages using msgID as the key i.e. this.messageState[msgID] = stateMachine.*
channelByPeer object {} channels by peers ethereum address as hex string no 0x prefix
channels object {} channels by on-chain contract address hex string no 0x prefix
pendingChannels object {} used to track newChannel requests initiated by the engine
signatureService function
blockchain object
Source:

Extends

  • events.EventEmitter

Methods

approveChannel(channelAddress, amount) → {Promise}

approve the channel to take ERC20 deposits. This must be called before a deposit can be made successfully. This utlimately creates and allowance for the channel on the ERC20 contract.
Parameters:
Name Type Description
channelAddress Buffer the on-chain nettingchannel address of the channel
amount BN the maximum amount of the ERC20 token to allow the channel to transfer when making a deposit.
Source:
Returns:
- the promise is settled when the channel close request is mined. If there is an error during any point of execution in the mining the onApprovalError(channelAddress) is called
Type
Promise

approveChannelManager(amount) → {Promise}

Approve the channelManager to take the flat fee in GOT ERC20 tokens when a channel is created. This only needs to be called once when the engine is initialized
Parameters:
Name Type Description
amount BN the maximum allowance of GOT ERC20 tokens to allow the channelManager to transfer.
Source:
Returns:
- the promise is settled when the channel close request is mined. If there is an error during any point of execution in the mining the onApprovalError() is called
Type
Promise

closeChannel(channelAddress) → {Promise}

close a channel given the peer ethereum address. The close proof in the state is transferred during the call to close.
Parameters:
Name Type Description
channelAddress Buffer the on-chain nettingchannel address of the channel
Source:
Returns:
- the promise is settled when the channel close request is mined. If there is an error during any point of execution in the mining the onChannelCloseError(channelAddress) is called
Type
Promise

depositChannel(channelAddress, amount) → {Promise}

Deposit an amount of the ERC20 token into the channel on-chain. After the transaction is mined successfully, that amount will be available for net transfer in the channel. This is effectively the collateral locked up during the channel lifetime and cannot be freed until the channel is closed and settled.
Parameters:
Name Type Description
channelAddress Buffer the on-chain nettingchannel address of the channel
amount BN the amount of the ERC20 token to deposit. The maxium amount of the cumulative deposits is determined by the allowance setup for the channel.
Source:
See:
  • Engine.approveChannel
Returns:
- the promise is settled when the channel close request is mined. If there is an error during any point of execution in the mining the onChannelNewBalanceError(channelAddress) is called
Type
Promise

handleEvent(event, state)

Internal event handlers triggered by state-machine workflows and blockchain events
Parameters:
Name Type Description
event string the GOT.* namespaced event triggered asynchronously by external engine components i.e. stateMachine, on-chain event handlers,etc.
state object the accompanying object state
Source:

newChannel(peerAddress) → {Promise}

Create a new channel given the peer ethereum address
Parameters:
Name Type Description
peerAddress Buffer eth address
Source:
Returns:
- the promise is settled when the channel is mined. If there is an error during any point of execution in the mining the onChannelNewError(peerAddress) is called
Type
Promise

onApproval(owner, spender, value)

Callback when a ERC20 token approves someone for an allowance
Parameters:
Name Type Description
owner String ethereum address hexString
spender String ethereum address hexString
value BN the allowance that was set
Source:

onChannelClose(channelAddress, closingAddress)

Callback when a channel is closed on chain identifying which of the partners initiated the close
Parameters:
Name Type Description
channelAddress String ethereum address hexString
closingAddress String ethereum address hexString
Source:

onChannelNew(channelAddress, addressOne, addressTwo, settleTimeout-)

Callback when a new channel is created by the channel manager
Parameters:
Name Type Description
channelAddress String ethereum address hexString
addressOne String ethereum address hexString
addressTwo String ethereum address hexString
settleTimeout- BN the settle_timeout for the channel
Source:

onChannelNewBalance(channelAddress, address, balance)

Callback when a channel has tokens deposited into it on-chain
Parameters:
Name Type Description
channelAddress String ethereum address hexString
address String the particpants ethereum address in hexString who deposited the funds
balance String the new deposited balance for the participant in the channel
Source:

onChannelSecretRevealed(channelAddress, secret, receiverAddress)

Callback when a lock has been withdrawn on-chain. If a user was withholding the secret in a mediate transfer, the party can now unlock the pending locks in the other channels. This is why it is essential in a mediated transfer setting that each hop decrements the expiration by a safe margin such that they may claim a lock off chain in case of byzantine faults
Parameters:
Name Type Description
channelAddress String ethereum address hexString
secret String the 32 byte secret in hexString
receiverAddress String ethereum address hexString which unlocked the lock on-chain
Source:

onChannelSettled(channelAddress)

Callback when a channel is settled on-chain
Parameters:
Name Type Description
channelAddress String ethereum address hexString
Source:

onMessage(message) → {message.Ack}

Handle an incoming message after it has been deserialized
Parameters:
Name Type Description
message message.SignedMessage
Source:
Throws:
  • "Invalid Message: no signature found"
  • "Invalid Message: uknown message received"
Returns:
Type
message.Ack

onRefund(channelAddress, receiverAddress, amount-)

Callback when a channel has been closed and the channel lifetime exceeds the refund interval. i.e. channel.closedBlock - channel.openedBlock > refundInterval. This is in hopes to incentives longer lived state channels by reducing the cost of their deployment for longer periods.
Parameters:
Name Type Description
channelAddress String ethereum address hexString
receiverAddress String ethereum address hexString of the party that received the refund
amount- BN the amount of GOT refunded
Source:

onTransferUpdated(channelAddress, nodeAddress)

Callback when a the counterpary has updated their transfer proof on-chain
Parameters:
Name Type Description
channelAddress String ethereum address hexString
nodeAddress String the party who submitted the proof
Source:

send(msg)

Send the message. Override this function to define different transport channels e.g integrate this with TELEGRAMS Api and securely transfer funds between users on telegram. Generate qrcodes for revelSecret message or implement webRTC p2p protocol for transport etc.
Parameters:
Name Type Description
msg message A message implementation in the message namespace
Source:

sendDirectTransfer(to, transferredAmount)

Send a direct transfer to your channel partner. This method calls send(directTransfer) and applies the directTransfer to the local channel state.
Parameters:
Name Type Description
to Buffer eth address who this message will be sent to. Only differs from target if mediating a transfer
transferredAmount Buffer the monotonically increasing amount to send. This value is set by taking the previous transferredAmount + amount you want to transfer.
Source:
Throws:
  • "Invalid MediatedTransfer: unknown to address"
  • 'Invalid DirectTransfer:state channel is not open'

sendMediatedTransfer(to, target, amount, expiration, secret, hashLock)

Send a locked transfer to your channel partner. This method intiatlizes a initator state machine which will queue the message for send via handleEvent
Parameters:
Name Type Description
to Buffer eth address who this message will be sent to. Only differs from target if mediating a transfer
target Buffer eth address of the target.
amount BN amount to lock and send.
expiration BN the absolute block number this locked transfer expires at.
secret Buffer Bytes32 cryptographic secret
hashLock Buffer Bytes32 keccak256(secret) value.
Source:
Throws:
  • "Invalid MediatedTransfer: channel does not exist"
  • 'Invalid Channel State:state channel is not open'

settleChannel(channelAddress) → {Promise}

Settle the channel on-chain after settle_timeout time has passed since closing, unlocking the on-chain collateral and distributing the funds according to the proofs and lock withdrawals on chain.
Parameters:
Name Type Description
channelAddress Buffer the on-chain nettingchannel address of the channel
Source:
Returns:
- the promise is settled when the channel close request is mined. If there is an error during any point of execution in the mining the onChannelSettledError(channelAddress) is called
Type
Promise

transferUpdate(channelAddress) → {Promise}

Update the proof after you learn a channel has been closed by the channel counter party
Parameters:
Name Type Description
channelAddress Buffer the on-chain nettingchannel address of the channel
Source:
Returns:
- the promise is settled when the channel close request is mined. If there is an error during any point of execution in the mining the onTransferUpdatedError(channelAddress) is called
Type
Promise

withdrawPeerOpenLocks(channelAddress) → {Promise}

Issue withdraw proofs on-chain for locks that have had their corresponding secret revealed. Locks can be settled on chain once a proof has been sent on-chain. Locks can only be withdrawn once.
Parameters:
Name Type Description
channelAddress Buffer the on-chain nettingchannel address of the channel
Source:
Returns:
- the promise is settled when the channel close request is mined. If there is an error during any point of execution in the mining the onChannelSecretRevealedError(channelAddress) is called for each lock that was not successfully withdrawn on-chain and must be reissued
Type
Promise