Class: Channel

Channel(peerState, myState, channelAddress, currentBlock)

Channel represents the states between two participants. State synchronization occurs against channel endpoints. Channels rely on monotonically increasing simplex channels to track net value transfer flux. Rather then leveraging Poon-Dryja style channels for value transfer with off-chain hashed time lock contracts, we prefer the Raiden Network style simplex channels. The advantage of Raiden style channels is the counterparties are not punished for providing invalid or out of date lock proofs to the block-chain. From a game theoretic perspective, since the value is monotonically increasing, a rational actor will attempt to send the most up to date and relevant proof to the blockchain. However; this is only effective for monotonically increasing value transfers. For general state transfers where the value may vary wildly, we will subclass our LockedTransfer class towards Poon-Dryja implementation. This scheme requires a deposit from both parties (i.e a COMMIT transaction) which is used as punishment for publishing invalidated hashLocks on the blockchain. This is enforced simply as with every new state transfer, a new secret is generated and the old secret is revealed by the party creating the updates. Much care must be given to the order of the operations and the counterparties actions in any of the implementations. Our design decision relies on mass consumer adoption; i.e. it is likely users will lose proof messages (lost phones, forgotten passwords, hardware failures), and they shouldn't be further punished by the blockchain as they already have lost value due to a stale proof.

Constructor

new Channel(peerState, myState, channelAddress, currentBlock)

Parameters:
Name Type Description
peerState ChannelState The initialized ChannelState object representing a peer.
myState ChannelState The initialized ChannelState object representing my state.
channelAddress Bytes The on chain netting channel ethereum contract address.
currentBlock BN The current block number on ethereum.
Properties:
Name Type Default Description
peerState ChannelState peer endpoint state
myState ChannelState my endpoint state
channelAddress Buffer the Ethereum NettingChannel Contract Address for this channel
openedBlock BN the block the channel was opened
closedBlock BN null
settledBlock BN null
issuedCloseBlock BN null the block the channel issuedCloseBlock, null if you never issue
issuedTransferUpdateBlock BN null
issuedSettleBlock BN null
updatedProofBlock BN null the block you sent your proof message to the on-chain netting channel, null if your partner never send you value transfers
withdrawnLocks Object.<string, int> the state of the on-chain withdraw proof
Source:
See:

Members

state

Properties:
Type Description
string return the current channel state
Source:

Methods

_withdrawPeerOpenLocks() → {channel.OpenLock}

Internal
Source:
Returns:
Type
channel.OpenLock

canIssueSettle(currentBlock) → {bool}

Parameters:
Name Type Description
currentBlock BN
Source:
Returns:
Type
bool

createDirectTransfer(msgID, amount)

create a direct transfer from myState to peerState
Parameters:
Name Type Description
msgID BN
amount BN
Source:
Throws:
"Insufficient funds: direct transfer cannot be completed:..."
Returns:
message.DirectTransfer

createLockedTransfer(msgID, hashLock, amount, expirationBlock, currentBlock)

create a locked transfer from myState for peerState
Parameters:
Name Type Description
msgID BN
hashLock Buffer the keccak256 hash of the secret
amount BN
expirationBlock BN
currentBlock BN
Source:
Throws:
"Insufficient funds: lock amount must be less than or equal to transferrable amount"
Returns:
message.LockedTransfer

createMediatedTransfer(msgID, hashLock, amount, expirationBlock, expirationBlock, target, initiator, currentBlock)

create a mediated transfer from myState to target using the peerState as a mediator and is set as the to address. This holds if there exists a route in the state channel network between myState and target through the peer
Parameters:
Name Type Description
msgID BN
hashLock Buffer the keccak256 hash of the secret
amount BN
expirationBlock BN
expirationBlock BN
target Buffer the intended recipient of the locked transfer. This target node will make the RevealSecret request direction to the initiator
initiator Buffer myState ethereum address
currentBlock BN
Source:
Returns:
message.MediatedTransfer

createSecretToProof(msgID, secret) → {message.SecretToProof}

Move an openLocks amount to the transferredAmount and remove from merkletree, this can increase channel longevity as openLocks will require on-chain withdrawals without this mechanism.
Parameters:
Name Type Description
msgID BN
secret Buffer
Source:
Returns:
Type
message.SecretToProof

getChannelExpirationBlock(currentBlock) → {BN}

determine which absolute block number the settlement period ends
Parameters:
Name Type Description
currentBlock BN
Source:
Returns:
Type
BN

handleRevealSecret(revealSecret) → {bool}

Parameters:
Name Type Description
revealSecret message.RevealSecret
Source:
Throws:
  • "Invalid Message: Expected RevealSecret"
  • "Invalid Secret: Unknown secret revealed"
Returns:
- true if applied
Type
bool

handleTransfer(transfer, currentBlock)

Parameters:
Name Type Description
transfer message.DirectTransfer | message.LockedTransfer
currentBlock BN
Source:
Throws:
  • "Invalid transfer: cannot update a closing channel"
  • "Invalid Transfer: unknown from"

handleTransferFromTo(from, to, transfer, currentBlock) → {bool}

process a transfer in the direction of from > to channelState
Parameters:
Name Type Description
from ChannelState transfer originator
to ChannelState transfer recipient
transfer message.DirectTransfer | message.LockedTransfer
currentBlock BN
Source:
Throws:
  • "Invalid Transfer Type"
  • "Invalid Channel Address: channel address mismatch"
  • "Invalid nonce: Nonce must be incremented by 1"
  • "Invalid Lock: Lock registered previously"
  • "Invalid LocksRoot for LockedTransfer"
  • "Invalid Lock: Lock amount must be greater than 0"
  • "Invalid SecretToProof: unknown secret"
  • "Invalid LocksRoot for SecretToProof:..."
  • "Invalid transferredAmount: must be monotonically increasing value"
  • "Invalid transferredAmount: SecretToProof does not provide expected lock amount"
  • "Invalid transferredAmount: Insufficient Balance:..."
Returns:
- true if transfer applied to channelState
Type
bool

incrementedNonce() → {BN}

Source:
Returns:
incremented nonce
Type
BN

isOpen() → {bool}

Source:
Returns:
returns true iff the channel is open
Type
bool

onBlock(currentBlock) → {Array.<string>}

handle a block update
Parameters:
Name Type Description
currentBlock BN
Source:
See:
  • Engine.handleEvent
Returns:
- GOT.* events to be processed
Type
Array.<string>

transferrableFromTo(from, to, currentBlock) → {BN}

The amount of funds that can be sent from -> to in the payment channel at a particular block. The block is important as locks expire those funds are made available again
Parameters:
Name Type Description
from ChannelState
to ChannelState
currentBlock BN The current block number
Source:
Returns:
Type
BN