ForceMove.sol

View Source: contracts/ForceMove.sol

โ†— Extends: IForceMove โ†˜ Derived Contracts: NitroAdjudicator, TESTForceMove

An implementation of ForceMove protocol, which allows state channels to be adjudicated and finalized.


Contract Members

Constants & Variables

//public members
mapping(bytes32 => bytes32) public channelStorageHashes;
//internal members
bytes internal constant prefix;

Events

event ChallengeRegistered(bytes32 indexed channelId, uint48 turnNumRecord, uint48 finalizesAt, address challenger, bool isFinal, struct IForceMove.FixedPart fixedPart, struct ForceMoveApp.VariablePart[] variableParts, struct IForceMove.Signature[] sigs, uint8[] whoSignedWhat);
event ChallengeCleared(bytes32 indexed channelId, uint48 newTurnNumRecord);
event Concluded(bytes32 indexed channelId);

Functions


getChannelStorage

Unpacks turnNumRecord, finalizesAt and fingerprint from the channelStorageHash of a particular channel.

function getChannelStorage(bytes32 channelId) public view
returns(turnNumRecord uint48, finalizesAt uint48, fingerprint uint160)

Returns

turnNumRecord A turnNum that (the adjudicator knows) is supported by a signature from each participant.

Arguments

NameTypeDescription
channelIdbytes32Unique identifier for a state channel.

forceMove

Registers a challenge against a state channel. A challenge will either prompt another participant into clearing the challenge (via one of the other methods), or cause the channel to finalize at a specific time.

function forceMove(struct IForceMove.FixedPart fixedPart, uint48 largestTurnNum, struct ForceMoveApp.VariablePart[] variableParts, uint8 isFinalCount, struct IForceMove.Signature[] sigs, uint8[] whoSignedWhat, struct IForceMove.Signature challengerSig) public nonpayable

Arguments

NameTypeDescription
fixedPartstruct IForceMove.FixedPartData describing properties of the state channel that do not change with state updates.
largestTurnNumuint48The largest turn number of the submitted states; will overwrite the stored value of turnNumRecord.
variablePartsstruct ForceMoveApp.VariablePart[]An ordered array of structs, each decribing the properties of the state channel that may change with each state update. Length is from 1 to the number of participants (inclusive).
isFinalCountuint8Describes how many of the submitted states have the isFinal property set to true. It is implied that the rightmost isFinalCount states are final, and the rest are not final.
sigsstruct IForceMove.Signature[]An array of signatures that support the state with the largestTurnNum. There must be one for each participant, e.g.: [sig-from-p0, sig-from-p1, ...]
whoSignedWhatuint8[]An array denoting which participant has signed which state: participant[i] signed the state with index whoSignedWhat[i].
challengerSigstruct IForceMove.SignatureThe signature of a participant on the keccak256 of the abi.encode of (supportedStateHash, 'forceMove').

respond

Repsonds to an ongoing challenge registered against a state channel.

function respond(address challenger, bool[2] isFinalAB, struct IForceMove.FixedPart fixedPart, struct ForceMoveApp.VariablePart[2] variablePartAB, struct IForceMove.Signature sig) public nonpayable

Arguments

NameTypeDescription
challengeraddressThe address of the participant whom registered the challenge.
isFinalABbool[2]An pair of booleans describing if the challenge state and/or the response state have the isFinal property set to true.
fixedPartstruct IForceMove.FixedPartData describing properties of the state channel that do not change with state updates.
variablePartABstruct ForceMoveApp.VariablePart[2]An pair of structs, each decribing the properties of the state channel that may change with each state update (for the challenge state and for the response state).
sigstruct IForceMove.SignatureThe responder's signature on the responseStateHash.

checkpoint

Overwrites the turnNumRecord stored against a channel by providing a state with higher turn number, supported by a signature from each participant.

function checkpoint(struct IForceMove.FixedPart fixedPart, uint48 largestTurnNum, struct ForceMoveApp.VariablePart[] variableParts, uint8 isFinalCount, struct IForceMove.Signature[] sigs, uint8[] whoSignedWhat) public nonpayable

Arguments

NameTypeDescription
fixedPartstruct IForceMove.FixedPartData describing properties of the state channel that do not change with state updates.
largestTurnNumuint48The largest turn number of the submitted states; will overwrite the stored value of turnNumRecord.
variablePartsstruct ForceMoveApp.VariablePart[]An ordered array of structs, each decribing the properties of the state channel that may change with each state update.
isFinalCountuint8Describes how many of the submitted states have the isFinal property set to true. It is implied that the rightmost isFinalCount states are final, and the rest are not final.
sigsstruct IForceMove.Signature[]An array of signatures that support the state with the largestTurnNum.
whoSignedWhatuint8[]An array denoting which participant has signed which state: participant[i] signed the state with index whoSignedWhat[i].

conclude

Finalizes a channel by providing a finalization proof.

function conclude(uint48 largestTurnNum, struct IForceMove.FixedPart fixedPart, bytes32 appPartHash, bytes32 outcomeHash, uint8 numStates, uint8[] whoSignedWhat, struct IForceMove.Signature[] sigs) public nonpayable

Arguments

NameTypeDescription
largestTurnNumuint48The largest turn number of the submitted states; will overwrite the stored value of turnNumRecord.
fixedPartstruct IForceMove.FixedPartData describing properties of the state channel that do not change with state updates.
appPartHashbytes32The keccak256 of the abi.encode of (challengeDuration, appDefinition, appData). Applies to all states in the finalization proof.
outcomeHashbytes32The keccak256 of the abi.encode of the outcome. Applies to all stats in the finalization proof.
numStatesuint8The number of states in the finalization proof.
whoSignedWhatuint8[]An array denoting which participant has signed which state: participant[i] signed the state with index whoSignedWhat[i].
sigsstruct IForceMove.Signature[]An array of signatures that support the state with the largestTurnNum.

_requireChallengerIsParticipant

Checks that the challengerSignature was created by one of the supplied participants.

function _requireChallengerIsParticipant(bytes32 supportedStateHash, address[] participants, struct IForceMove.Signature challengerSignature) internal pure
returns(challenger address)

Arguments

NameTypeDescription
supportedStateHashbytes32Forms part of the digest to be signed, along with the string 'forceMove'.
participantsaddress[]A list of addresses representing the participants of a channel.
challengerSignaturestruct IForceMove.SignatureThe signature of a participant on the keccak256 of the abi.encode of (supportedStateHash, 'forceMove').

_isAddressInArray

Tests whether a given address is in a given array of addresses.

function _isAddressInArray(address suspect, address[] addresses) internal pure
returns(bool)

Returns

true if the address is in the array, false otherwise

Arguments

NameTypeDescription
suspectaddressA single address of interest.
addressesaddress[]A line-up of possible perpetrators.

_validSignatures

Given an array of state hashes, checks the validity of the supplied signatures. Valid means there is a signature for each participant, either on the hash of the state for which they are a mover, or on the hash of a state that appears after that state in the array.

function _validSignatures(uint48 largestTurnNum, address[] participants, bytes32[] stateHashes, struct IForceMove.Signature[] sigs, uint8[] whoSignedWhat) internal pure
returns(bool)

Returns

true if the signatures are valid, false otherwise

Arguments

NameTypeDescription
largestTurnNumuint48The largest turn number of the submitted states; will overwrite the stored value of turnNumRecord.
participantsaddress[]A list of addresses representing the participants of a channel.
stateHashesbytes32[]Array of keccak256(State) submitted in support of a state,
sigsstruct IForceMove.Signature[]Array of Signatures, one for each participant
whoSignedWhatuint8[]participant[i] signed stateHashes[whoSignedWhat[i]]

_acceptableWhoSignedWhat

Given a declaration of which state in the support proof was signed by which participant, check if this declaration is acceptable. Acceptable means there is a signature for each participant, either on the hash of the state for which they are a mover, or on the hash of a state that appears after that state in the array.

function _acceptableWhoSignedWhat(uint8[] whoSignedWhat, uint48 largestTurnNum, uint256 nParticipants, uint256 nStates) internal pure
returns(bool)

Returns

true if whoSignedWhat is acceptable, false otherwise

Arguments

NameTypeDescription
whoSignedWhatuint8[]participant[i] signed stateHashes[whoSignedWhat[i]]
largestTurnNumuint48Largest turnNum of the support proof
nParticipantsuint256Number of participants in the channel
nStatesuint256Number of states in the support proof

_recoverSigner

Given a digest and ethereum digital signature, recover the signer

function _recoverSigner(bytes32 _d, struct IForceMove.Signature sig) internal pure
returns(address)

Returns

signer

Arguments

NameTypeDescription
_dbytes32message digest
sigstruct IForceMove.Signatureethereum digital signature

_requireStateSupportedBy

Check that the submitted data constitute a support proof.

function _requireStateSupportedBy(uint48 largestTurnNum, struct ForceMoveApp.VariablePart[] variableParts, uint8 isFinalCount, bytes32 channelId, struct IForceMove.FixedPart fixedPart, struct IForceMove.Signature[] sigs, uint8[] whoSignedWhat) internal pure
returns(bytes32)

Returns

The hash of the latest state in the proof, if supported, else reverts.

Arguments

NameTypeDescription
largestTurnNumuint48Largest turnNum of the support proof
variablePartsstruct ForceMoveApp.VariablePart[]Variable parts of the states in the support proof
isFinalCountuint8How many of the states are final? The final isFinalCount states are implied final, the remainder are implied not final.
channelIdbytes32Unique identifier for a channel.
fixedPartstruct IForceMove.FixedPartFixed Part of the states in the support proof
sigsstruct IForceMove.Signature[]A signature from each participant.
whoSignedWhatuint8[]participant[i] signed stateHashes[whoSignedWhat[i]]

_requireValidTransitionChain

Check that the submitted states form a chain of valid transitions

function _requireValidTransitionChain(uint48 largestTurnNum, struct ForceMoveApp.VariablePart[] variableParts, uint8 isFinalCount, bytes32 channelId, struct IForceMove.FixedPart fixedPart) internal pure
returns(bytes32[])

Returns

true if every state is a validTransition from its predecessor, false otherwise.

Arguments

NameTypeDescription
largestTurnNumuint48Largest turnNum of the support proof
variablePartsstruct ForceMoveApp.VariablePart[]Variable parts of the states in the support proof
isFinalCountuint8How many of the states are final? The final isFinalCount states are implied final, the remainder are implied not final.
channelIdbytes32Unique identifier for a channel.
fixedPartstruct IForceMove.FixedPartFixed Part of the states in the support proof

_requireValidTransition

Check that the submitted pair of states form a valid transition

function _requireValidTransition(uint256 nParticipants, bool[2] isFinalAB, struct ForceMoveApp.VariablePart[2] ab, uint48 turnNumB, address appDefinition) internal pure
returns(bool)

Returns

true if the later state is a validTransition from its predecessor, false otherwise.

Arguments

NameTypeDescription
nParticipantsuint256Number of participants in the channel.
transition
isFinalABbool[2]Pair of booleans denoting whether the first and second state (resp.) are final.
abstruct ForceMoveApp.VariablePart[2]Variable parts of each of the pair of states
turnNumBuint48turnNum of the later state of the pair.
appDefinitionaddressAddress of deployed contract containing application-specific validTransition function.

_bytesEqual

Check for equality of two byte strings

function _bytesEqual(bytes left, bytes right) internal pure
returns(bool)

Returns

true if the bytes are identical, false otherwise.

Arguments

NameTypeDescription
leftbytesOne bytes string
rightbytesThe other bytes string

_clearChallenge

Clears a challenge by updating the turnNumRecord and resetting the remaining channel storage fields, and emits a ChallengeCleared event.

function _clearChallenge(bytes32 channelId, uint48 newTurnNumRecord) internal nonpayable

Arguments

NameTypeDescription
channelIdbytes32Unique identifier for a channel.
newTurnNumRecorduint48New turnNumRecord to overwrite existing value

_requireIncreasedTurnNumber

Checks that the submitted turnNumRecord is strictly greater than the turnNumRecord stored on chain.

function _requireIncreasedTurnNumber(bytes32 channelId, uint48 newTurnNumRecord) internal view

Arguments

NameTypeDescription
channelIdbytes32Unique identifier for a channel.
newTurnNumRecorduint48New turnNumRecord intended to overwrite existing value

_requireNonDecreasedTurnNumber

Checks that the submitted turnNumRecord is greater than or equal to the turnNumRecord stored on chain.

function _requireNonDecreasedTurnNumber(bytes32 channelId, uint48 newTurnNumRecord) internal view

Arguments

NameTypeDescription
channelIdbytes32Unique identifier for a channel.
newTurnNumRecorduint48New turnNumRecord intended to overwrite existing value

_requireSpecificChallenge

Checks that a given ChannelData struct matches the challenge stored on chain, and that the channel is in Challenge mode.

function _requireSpecificChallenge(struct IForceMove.ChannelData data, bytes32 channelId) internal view

Arguments

NameTypeDescription
datastruct IForceMove.ChannelDataA given ChannelData data structure.
channelIdbytes32Unique identifier for a channel.

_requireOngoingChallenge

Checks that a given channel is in the Challenge mode.

function _requireOngoingChallenge(bytes32 channelId) internal view

Arguments

NameTypeDescription
channelIdbytes32Unique identifier for a channel.

_requireChannelNotFinalized

Checks that a given channel is NOT in the Finalized mode.

function _requireChannelNotFinalized(bytes32 channelId) internal view

Arguments

NameTypeDescription
channelIdbytes32Unique identifier for a channel.

_requireChannelFinalized

Checks that a given channel is in the Finalized mode.

function _requireChannelFinalized(bytes32 channelId) internal view

Arguments

NameTypeDescription
channelIdbytes32Unique identifier for a channel.

_requireChannelOpen

Checks that a given channel is in the Open mode.

function _requireChannelOpen(bytes32 channelId) internal view

Arguments

NameTypeDescription
channelIdbytes32Unique identifier for a channel.

_requireMatchingStorage

Checks that a given ChannelData struct matches the challenge stored on chain.

function _requireMatchingStorage(struct IForceMove.ChannelData data, bytes32 channelId) internal view

Arguments

NameTypeDescription
datastruct IForceMove.ChannelDataA given ChannelData data structure.
channelIdbytes32Unique identifier for a channel.

_mode

Computes the ChannelMode for a given channelId.

function _mode(bytes32 channelId) internal view
returns(enum IForceMove.ChannelMode)

Arguments

NameTypeDescription
channelIdbytes32Unique identifier for a channel.

_hashChannelData

Hashes the input data and formats it for on chain storage.

function _hashChannelData(struct IForceMove.ChannelData channelData) internal pure
returns(newHash bytes32)

Arguments

NameTypeDescription
channelDatastruct IForceMove.ChannelDataChannelData data.

_getChannelStorage

Unpacks turnNumRecord, finalizesAt and fingerprint from the channelStorageHash of a particular channel.

function _getChannelStorage(bytes32 channelId) internal view
returns(turnNumRecord uint48, finalizesAt uint48, fingerprint uint160)

Returns

turnNumRecord A turnNum that (the adjudicator knows) is supported by a signature from each participant.

Arguments

NameTypeDescription
channelIdbytes32Unique identifier for a state channel.

_matchesHash

Checks that a given ChannelData struct matches a supplied bytes32 when formatted for storage.

function _matchesHash(struct IForceMove.ChannelData data, bytes32 h) internal pure
returns(bool)

Arguments

NameTypeDescription
datastruct IForceMove.ChannelDataA given ChannelData data structure.
hbytes32Some data in on-chain storage format.

_hashState

Computes the hash of the state corresponding to the input data.

function _hashState(uint48 turnNum, bool isFinal, bytes32 channelId, struct IForceMove.FixedPart fixedPart, bytes appData, bytes32 outcomeHash) internal pure
returns(bytes32)

Returns

The stateHash

Arguments

NameTypeDescription
turnNumuint48Turn number
isFinalboolIs the state final?
channelIdbytes32Unique identifier for the channel
fixedPartstruct IForceMove.FixedPartPart of the state that does not change
appDatabytesApplication specific date
outcomeHashbytes32Hash of the outcome.

_hashOutcome

Computes the hash of a given outcome.

function _hashOutcome(bytes outcome) internal pure
returns(bytes32)

Returns

The outcomeHash

Arguments

NameTypeDescription
outcomebytesAn outcome

_getChannelId

Computes the unique id of a channel.

function _getChannelId(struct IForceMove.FixedPart fixedPart) internal pure
returns(channelId bytes32)

Returns

channelId

Arguments

NameTypeDescription
fixedPartstruct IForceMove.FixedPartPart of the state that does not change
Last updated on by geoknee