ForceMove.sol
View Source: contracts/ForceMove.sol
โ Extends: IForceMove, StatusManager โ Derived Contracts: NitroAdjudicator, TESTForceMove
An implementation of ForceMove protocol, which allows state channels to be adjudicated and finalized.
Enums
IsValidTransition
Functions
- unpackStatus
- challenge
- respond
- checkpoint
- conclude
- _conclude
- getChainID
- requireValidInput
- _requireChallengerIsParticipant
- _isAddressInArray
- _validSignatures
- _acceptableWhoSignedWhat
- _recoverSigner
- _requireStateSupportedBy
- _requireValidTransitionChain
- _requireValidProtocolTransition
- _requireValidTransition
- _bytesEqual
- _clearChallenge
- _requireIncreasedTurnNumber
- _requireNonDecreasedTurnNumber
- _requireSpecificChallenge
- _requireOngoingChallenge
- _requireChannelNotFinalized
- _requireChannelOpen
- _requireMatchingStorage
- _matchesStatus
- _hashState
- _getChannelId
unpackStatus
Unpacks turnNumRecord, finalizesAt and fingerprint from the status of a particular channel.
Returns
turnNumRecord A turnNum that (the adjudicator knows) is supported by a signature from each participant.
Arguments
Name | Type | Description |
---|---|---|
channelId | bytes32 | Unique 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.
Arguments
Name | Type | Description |
---|---|---|
fixedPart | struct IForceMove.FixedPart | Data describing properties of the state channel that do not change with state updates. |
largestTurnNum | uint48 | The largest turn number of the submitted states; will overwrite the stored value of turnNumRecord . |
variableParts | struct 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). |
isFinalCount | uint8 | Describes 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. |
sigs | struct 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, ...] |
whoSignedWhat | uint8[] | An array denoting which participant has signed which state: participant[i] signed the state with index whoSignedWhat[i] . |
challengerSig | struct IForceMove.Signature | The 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.
Arguments
Name | Type | Description |
---|---|---|
isFinalAB | bool[2] | An pair of booleans describing if the challenge state and/or the response state have the isFinal property set to true . |
fixedPart | struct IForceMove.FixedPart | Data describing properties of the state channel that do not change with state updates. |
variablePartAB | struct 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). |
sig | struct IForceMove.Signature | The 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.
Arguments
Name | Type | Description |
---|---|---|
fixedPart | struct IForceMove.FixedPart | Data describing properties of the state channel that do not change with state updates. |
largestTurnNum | uint48 | The largest turn number of the submitted states; will overwrite the stored value of turnNumRecord . |
variableParts | struct IForceMoveApp.VariablePart[] | An ordered array of structs, each decribing the properties of the state channel that may change with each state update. |
isFinalCount | uint8 | Describes 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. |
sigs | struct IForceMove.Signature[] | An array of signatures that support the state with the largestTurnNum : one for each participant, in participant order (e.g. [sig of participant[0], sig of participant[1], ...]). |
whoSignedWhat | uint8[] | 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.
Arguments
Name | Type | Description |
---|---|---|
largestTurnNum | uint48 | The largest turn number of the submitted states; will overwrite the stored value of turnNumRecord . |
fixedPart | struct IForceMove.FixedPart | Data describing properties of the state channel that do not change with state updates. |
appPartHash | bytes32 | The keccak256 of the abi.encode of (challengeDuration, appDefinition, appData) . Applies to all states in the finalization proof. |
outcomeHash | bytes32 | The keccak256 of the abi.encode of the outcome . Applies to all states in the finalization proof. |
numStates | uint8 | The number of states in the finalization proof. |
whoSignedWhat | uint8[] | An array denoting which participant has signed which state: participant[i] signed the state with index whoSignedWhat[i] . |
sigs | struct IForceMove.Signature[] | An array of signatures that support the state with the largestTurnNum : one for each participant, in participant order (e.g. [sig of participant[0], sig of participant[1], ...]). |
_conclude
Finalizes a channel by providing a finalization proof. Internal method.
Arguments
Name | Type | Description |
---|---|---|
largestTurnNum | uint48 | The largest turn number of the submitted states; will overwrite the stored value of turnNumRecord . |
fixedPart | struct IForceMove.FixedPart | Data describing properties of the state channel that do not change with state updates. |
appPartHash | bytes32 | The keccak256 of the abi.encode of (challengeDuration, appDefinition, appData) . Applies to all states in the finalization proof. |
outcomeHash | bytes32 | The keccak256 of the outcome . Applies to all stats in the finalization proof. |
numStates | uint8 | The number of states in the finalization proof. |
whoSignedWhat | uint8[] | An array denoting which participant has signed which state: participant[i] signed the state with index whoSignedWhat[i] . |
sigs | struct IForceMove.Signature[] | An array of signatures that support the state with the largestTurnNum :: one for each participant, in participant order (e.g. [sig of participant[0], sig of participant[1], ...]). |
getChainID
Arguments
Name | Type | Description |
---|
requireValidInput
Validates input for several external methods.
Arguments
Name | Type | Description |
---|---|---|
numParticipants | uint256 | Length of the participants array |
numStates | uint256 | Number of states submitted |
numSigs | uint256 | Number of signatures submitted |
numWhoSignedWhats | uint256 | whoSignedWhat.length |
_requireChallengerIsParticipant
Checks that the challengerSignature was created by one of the supplied participants.
Arguments
Name | Type | Description |
---|---|---|
supportedStateHash | bytes32 | Forms part of the digest to be signed, along with the string 'forceMove'. |
participants | address[] | A list of addresses representing the participants of a channel. |
challengerSignature | struct IForceMove.Signature | The 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.
Returns
true if the address is in the array, false otherwise
Arguments
Name | Type | Description |
---|---|---|
suspect | address | A single address of interest. |
addresses | address[] | 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.
Returns
true if the signatures are valid, false otherwise
Arguments
Name | Type | Description |
---|---|---|
largestTurnNum | uint48 | The largest turn number of the submitted states; will overwrite the stored value of turnNumRecord . |
participants | address[] | A list of addresses representing the participants of a channel. |
stateHashes | bytes32[] | Array of keccak256(State) submitted in support of a state, |
sigs | struct IForceMove.Signature[] | Array of Signatures, one for each participant, in participant order (e.g. [sig of participant[0], sig of participant[1], ...]). |
whoSignedWhat | uint8[] | 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.
Returns
true if whoSignedWhat is acceptable, false otherwise
Arguments
Name | Type | Description |
---|---|---|
whoSignedWhat | uint8[] | participant[i] signed stateHashes[whoSignedWhat[i]] |
largestTurnNum | uint48 | Largest turnNum of the support proof |
nParticipants | uint256 | Number of participants in the channel |
nStates | uint256 | Number of states in the support proof |
_recoverSigner
Given a digest and ethereum digital signature, recover the signer
Returns
signer
Arguments
Name | Type | Description |
---|---|---|
_d | bytes32 | message digest |
sig | struct IForceMove.Signature | ethereum digital signature |
_requireStateSupportedBy
Check that the submitted data constitute a support proof.
Returns
The hash of the latest state in the proof, if supported, else reverts.
Arguments
Name | Type | Description |
---|---|---|
largestTurnNum | uint48 | Largest turnNum of the support proof |
variableParts | struct IForceMoveApp.VariablePart[] | Variable parts of the states in the support proof |
isFinalCount | uint8 | How many of the states are final? The final isFinalCount states are implied final, the remainder are implied not final. |
channelId | bytes32 | Unique identifier for a channel. |
fixedPart | struct IForceMove.FixedPart | Fixed Part of the states in the support proof |
sigs | struct IForceMove.Signature[] | A signature from each participant, in participant order (e.g. [sig of participant[0], sig of participant[1], ...]). |
whoSignedWhat | uint8[] | participant[i] signed stateHashes[whoSignedWhat[i]] |
_requireValidTransitionChain
Check that the submitted states form a chain of valid transitions
Returns
true if every state is a validTransition from its predecessor, false otherwise.
Arguments
Name | Type | Description |
---|---|---|
largestTurnNum | uint48 | Largest turnNum of the support proof |
variableParts | struct IForceMoveApp.VariablePart[] | Variable parts of the states in the support proof |
isFinalCount | uint8 | How many of the states are final? The final isFinalCount states are implied final, the remainder are implied not final. |
channelId | bytes32 | Unique identifier for a channel. |
fixedPart | struct IForceMove.FixedPart | Fixed Part of the states in the support proof |
_requireValidProtocolTransition
Check that the submitted pair of states form a valid transition
Returns
true if the later state is a validTransition from its predecessor, false otherwise.
Arguments
Name | Type | Description |
---|---|---|
nParticipants | uint256 | Number of participants in the channel. |
transition | ||
isFinalAB | bool[2] | Pair of booleans denoting whether the first and second state (resp.) are final. |
ab | struct IForceMoveApp.VariablePart[2] | Variable parts of each of the pair of states |
turnNumB | uint48 | turnNum of the later state of the pair |
_requireValidTransition
Check that the submitted pair of states form a valid transition
Returns
true if the later state is a validTransition from its predecessor, false otherwise.
Arguments
Name | Type | Description |
---|---|---|
nParticipants | uint256 | Number of participants in the channel. |
transition | ||
isFinalAB | bool[2] | Pair of booleans denoting whether the first and second state (resp.) are final. |
ab | struct IForceMoveApp.VariablePart[2] | Variable parts of each of the pair of states |
turnNumB | uint48 | turnNum of the later state of the pair. |
appDefinition | address | Address of deployed contract containing application-specific validTransition function. |
_bytesEqual
Check for equality of two byte strings
Returns
true if the bytes are identical, false otherwise.
Arguments
Name | Type | Description |
---|---|---|
_preBytes | bytes | One bytes string |
_postBytes | bytes | The other bytes string |
_clearChallenge
Clears a challenge by updating the turnNumRecord and resetting the remaining channel storage fields, and emits a ChallengeCleared event.
Arguments
Name | Type | Description |
---|---|---|
channelId | bytes32 | Unique identifier for a channel. |
newTurnNumRecord | uint48 | New turnNumRecord to overwrite existing value |
_requireIncreasedTurnNumber
Checks that the submitted turnNumRecord is strictly greater than the turnNumRecord stored on chain.
Arguments
Name | Type | Description |
---|---|---|
channelId | bytes32 | Unique identifier for a channel. |
newTurnNumRecord | uint48 | New turnNumRecord intended to overwrite existing value |
_requireNonDecreasedTurnNumber
Checks that the submitted turnNumRecord is greater than or equal to the turnNumRecord stored on chain.
Arguments
Name | Type | Description |
---|---|---|
channelId | bytes32 | Unique identifier for a channel. |
newTurnNumRecord | uint48 | New 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.
Arguments
Name | Type | Description |
---|---|---|
data | struct IStatusManager.ChannelData | A given ChannelData data structure. |
channelId | bytes32 | Unique identifier for a channel. |
_requireOngoingChallenge
Checks that a given channel is in the Challenge mode.
Arguments
Name | Type | Description |
---|---|---|
channelId | bytes32 | Unique identifier for a channel. |
_requireChannelNotFinalized
Checks that a given channel is NOT in the Finalized mode.
Arguments
Name | Type | Description |
---|---|---|
channelId | bytes32 | Unique identifier for a channel. |
_requireChannelOpen
Checks that a given channel is in the Open mode.
Arguments
Name | Type | Description |
---|---|---|
channelId | bytes32 | Unique identifier for a channel. |
_requireMatchingStorage
Checks that a given ChannelData struct matches the challenge stored on chain.
Arguments
Name | Type | Description |
---|---|---|
data | struct IStatusManager.ChannelData | A given ChannelData data structure. |
channelId | bytes32 | Unique identifier for a channel. |
_matchesStatus
Checks that a given ChannelData struct matches a supplied bytes32 when formatted for storage.
Arguments
Name | Type | Description |
---|---|---|
data | struct IStatusManager.ChannelData | A given ChannelData data structure. |
s | bytes32 | Some data in on-chain storage format. |
_hashState
Computes the hash of the state corresponding to the input data.
Returns
The stateHash
Arguments
Name | Type | Description |
---|---|---|
turnNum | uint48 | Turn number |
isFinal | bool | Is the state final? |
channelId | bytes32 | Unique identifier for the channel |
fixedPart | struct IForceMove.FixedPart | Part of the state that does not change |
appData | bytes | Application specific date |
outcomeHash | bytes32 | Hash of the outcome. |
_getChannelId
Computes the unique id of a channel.
Returns
channelId
Arguments
Name | Type | Description |
---|---|---|
fixedPart | struct IForceMove.FixedPart | Part of the state that does not change |