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.


Enums

IsValidTransition

enum IsValidTransition {
True,
NeedToCheckApp
}

Contract Members

Constants & Variables

mapping(bytes32 => bytes32) public statusOf;

Functions


unpackStatus

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

function unpackStatus(bytes32 channelId) external 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.

challenge

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 challenge(struct IForceMove.FixedPart fixedPart, uint48 largestTurnNum, struct IForceMoveApp.VariablePart[] variableParts, uint8 isFinalCount, struct IForceMove.Signature[] sigs, uint8[] whoSignedWhat, struct IForceMove.Signature challengerSig) external 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 IForceMoveApp.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 IForceMoveApp.VariablePart[2] variablePartAB, struct IForceMove.Signature sig) external 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 IForceMoveApp.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 IForceMoveApp.VariablePart[] variableParts, uint8 isFinalCount, struct IForceMove.Signature[] sigs, uint8[] whoSignedWhat) external 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 IForceMoveApp.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. External wrapper for _conclude.

function conclude(uint48 largestTurnNum, struct IForceMove.FixedPart fixedPart, bytes32 appPartHash, bytes32 outcomeHash, uint8 numStates, uint8[] whoSignedWhat, struct IForceMove.Signature[] sigs) external 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 states 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.

_conclude

Finalizes a channel by providing a finalization proof. Internal method.

function _conclude(uint48 largestTurnNum, struct IForceMove.FixedPart fixedPart, bytes32 appPartHash, bytes32 outcomeHash, uint8 numStates, uint8[] whoSignedWhat, struct IForceMove.Signature[] sigs) internal nonpayable
returns(channelId bytes32)

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 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 IForceMoveApp.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 IForceMoveApp.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 IForceMoveApp.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 IForceMoveApp.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

_requireValidProtocolTransition

Check that the submitted pair of states form a valid transition

function _requireValidProtocolTransition(uint256 nParticipants, bool[2] isFinalAB, struct IForceMoveApp.VariablePart[2] ab, uint48 turnNumB) internal pure
returns(enum ForceMove.IsValidTransition)

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 IForceMoveApp.VariablePart[2]Variable parts of each of the pair of states
turnNumBuint48turnNum of the later state of the pair

_requireValidTransition

Check that the submitted pair of states form a valid transition

function _requireValidTransition(uint256 nParticipants, bool[2] isFinalAB, struct IForceMoveApp.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 IForceMoveApp.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 _preBytes, bytes _postBytes) internal pure
returns(bool)

Returns

true if the bytes are identical, false otherwise.

Arguments

NameTypeDescription
_preBytesbytesOne bytes string
_postBytesbytesThe 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.

_generateStatus

Formats the input data for on chain storage.

function _generateStatus(struct IForceMove.ChannelData channelData) internal pure
returns(status bytes32)

Arguments

NameTypeDescription
channelDatastruct IForceMove.ChannelDataChannelData data.

_unpackStatus

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

function _unpackStatus(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.

_matchesStatus

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

function _matchesStatus(struct IForceMove.ChannelData data, bytes32 s) internal pure
returns(bool)

Arguments

NameTypeDescription
datastruct IForceMove.ChannelDataA given ChannelData data structure.
sbytes32Some 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.

getChainID

function getChainID() public pure
returns(uint256)

Arguments

NameTypeDescription

_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

requireValidInput

Validates input for several external methods.

function requireValidInput(uint256 numParticipants, uint256 numStates, uint256 numSigs, uint256 numWhoSignedWhats) public pure
returns(bool)

Arguments

NameTypeDescription
numParticipantsuint256Length of the participants array
numStatesuint256Number of states submitted
numSigsuint256Number of signatures submitted
numWhoSignedWhatsuint256whoSignedWhat.length
Last updated on by geoknee