@graphprotocol/statechannels
v0.3.0
Published
Contracts for the Gateway-Indexer statechannels interaction
Downloads
8
Maintainers
Keywords
Readme
Conditional Graph payments
What is a ForceMove
app?
Short answer
https://docs.statechannels.org/contract-api/natspec/forcemoveapp/
Medium answer
It's a smart contract that implements a validTransition
function with the following signature.
struct VariablePart {
bytes outcome,
bytes appData
}
function validTransition(
struct ForceMoveApp.VariablePart a,
struct ForceMoveApp.VariablePart b,
uint48 turnNumB,
uint256 nParticipants
) external pure returns(bool)
The outcome
is an encoding (using the ethereum ABI encoder) of a non-simple type OutcomItem[]
where OutcomeItem
is defined here.
The appData
is an encoding of an arbitrary solidity data type, designed specifically for the channel's application.
It is entirely possible for appData
to always be the null 0x
bytes value.
Example
This is a payment channel where any participant can send any of its peers any amount of its remaining funds, on their turn.
This particular app uses no appData
.
This is a more complicated example, implementing the rules of Rock Paper Scissors. Thus, it makes use of app data to store game state, such as the current player's move.
What is the AttestationApp
?
It is a ForceMove
app with the following intended properties:
- On the gateway's turn, it embeds a query ID (
queryCID
) and an allocation id (allocationId
) in the app data. - On the indexer's turn, it embeds an attestation in the app data
- It deducts the
paymentAmount
from the gateway's total in the outcome, and adds it to the indexer's total for that allocation. If the indexer hasn't been payed yet through that allocation, a new outcome item is created - It signs the attestation
- It deducts the
Reminder: Peers take turns in Nitro state channels. In these channels, the gateway takes even turns, and the indexer takes odd turns. For example, if the current turn number is 7, then it is the gateway's turn to update the channel on turn 8, because it is even.
The outcome in the AttestationApp should be a single AssetOutcome
where the asset holder address is the GRTAssetHolder
.
The app data in the AttestationApp contains at most one of:
- A "Query request", which is a
bytes32 requestCID
as well as auint256 paymentAmount
- An "Attestation", which is a
bytes32 responseCID
as well as a signature.
It is possible for the app data to contain neither of (1) or (2). This is allowed in two cases:
- In the "starting state"
- When the indexer declines a query.
Security
An honest indexer would
- execute the query
- compute the query result's
responseCID
from the query result - constructs the attestation, which is composed of the
requestCID
, theresponseCID
, and thesubgraphDeploymentID
- signs the attestation
A malicious indexer can skip (1), and put a random value for the responseCID
.
Thus, signing the attestation does not guarantee that the query result is correct.
The gateway can, in this case, penalize the indexer's stake by challenging the result. The penalty is very severe, providing an incentive for indexers to be honest.
Testing
There is one positive test case for each possible (state, event) pair in the happy path.
In addition, there are some test cases of invalid transitions.
These are tested against contracts deployed to a local ganache network.