@statechannels/nitro-protocol

nitro-protocol package

Smart contracts that implement nitro protocol for state channel networks on ethereum. Includes javascript and typescript support.

Remarks

Building your state channel application contract against our interface:

pragma solidity ^0.7.0;
pragma experimental ABIEncoderV2;
import '@statechannels/nitro-protocol/contracts/interfaces/IForceMoveApp.sol';
import '@statechannels/nitro-protocol/contracts/Outcome.sol';
contract MyStateChannelApp is IForceMoveApp {
function validTransition(
VariablePart memory a,
VariablePart memory b,
uint256 turnNumB,
uint256 nParticipants
) public override pure returns (bool) {
// Your logic ...
return true;
}
}

Import precompiled artifacts for deployment/testing

const {
NitroAdjudicatorArtifact,
TrivialAppArtifact,
TokenArtifact,
} = require('@statechannels/nitro-protocol').ContractArtifacts;

Import typescript types

import {Channel} from '@statechannels/nitro-protocol';
const channel: Channel = {
chainId: '0x1',
channelNonce: 0,
participants: ['0xalice...', '0xbob...'],
};

Import javascript helper functions

import {getChannelId} from '@statechannels/nitro-protocol';
const channelId = getChannelId(channel);

Enumerations

EnumerationDescription
ValidTransitionStatusIsValidTransition can be True (0) (no further checks required) NeedToCheckApp (1) (clears protocol checks, overall validity depends on App.validTransition)

Functions

FunctionDescription
channelDataToStatus(channelData)Computes the on chain status from the supplied channelData
convertAddressToBytes32(address)Left pads a 20 byte address hex string with zeros until it is a 32 byte hex string e.g., 0x9546E319878D2ca7a21b481F873681DF344E0Df8 becomes 0x0000000000000000000000009546E319878D2ca7a21b481F873681DF344E0Df8
convertBytes32ToAddress(bytes32)Extracts a 20 byte address hex string from a 32 byte hex string by slicing
createChallengeTransaction(signedStates, challengePrivateKey)Marshalls the supplied signedStates into an ethereum transaction for the checkpoint method. Automatically computes whosignedWhat, sigs, etc.
createCheckpointTransaction(signedStates)Marshalls the supplied signedStates into an ethereum transaction for the checkpoint method. Automatically computes whosignedWhat, sigs, etc.
createConcludeAndTransferAllAssetsTransaction(signedStates)Marshalls the supplied signedStates into an ethereum transaction for the checkpoint method. Automatically computes whosignedWhat, sigs, etc.
createConcludeTransaction(conclusionProof)Marshalls the supplied signedStates into an ethereum transaction for the checkpoint method. Automatically computes whosignedWhat, sigs, etc.
createERC20DepositTransaction(tokenAddress, destination, expectedHeld, amount)Crafts an ethers TransactionRequest targeting the adjudicator's deposit method, specifically for ERC20 deposits
createETHDepositTransaction(destination, expectedHeld, amount)Crafts an ethers TransactionRequest targeting the adjudicator's deposit method, specifically for ETH deposits
createRespondTransaction(challengeState, response)Marshalls the supplied signedStates into an ethereum transaction for the checkpoint method. Automatically computes whosignedWhat, sigs, etc.
createSignatureArguments(signedStates)Marshalls the supplied signedStates into the signature arguments used in most on chain methods.] Currently we assume each signedState is a unique combination of state/signature So if multiple participants sign a state we expect a SignedState for each participant
createTransferAllAssetsTransaction(state)Marshalls the supplied signedStates into an ethereum transaction for the checkpoint method. Automatically computes whosignedWhat, sigs, etc.
createValidTransitionTransaction(fromState, toState)Encodes a validTransition method call as the data on an ethereum transaction. Useful for testing gas consumption of a ForceMoveApp.
getChallengeClearedEvent(tx, eventResult)Extracts a ChallengeClearedEvent (containing a new signedState) from the logs of a respond or checkpoint transaction
getChallengeRegisteredEvent(eventResult)Extracts a ChallengeRegisteredEvent (containing challengeStates) from the supplied eventResult.
getChannelId(channel)Computes the unique id for the supplied channel
getChannelMode(finalizesAt, now)Takes in when the channel finalizes and the current timestamp and determines the ChannelMode
getDepositedEvent(eventResult)Extracts a DepositedEvent from a suitable eventResult
getFixedPart(state)Extracts the FixedPart of a state
getStateSignerAddress(signedState)
getVariablePart(state)Extracts the VariablePart of a state
hashAppPart(state)Encodes and hashes the AppPart of a state
hashOutcome(outcome)Encodes and hashes an Outcome
hashState(state)Encodes and hashes a state
isExternalDestination(bytes32)Determines if the supplied 32 byte hex string represents an external destination (meaning funds will be paid _out_ of the adjudicator on chain)
replaceAddressesAndBigNumberify(object, addresses)Recursively replaces any key in a copy of the supplied object with the value of that key in the supplied addresses object. Also BigNumberifies all numbers. Used in testing only.
requireValidProtocolTransition(fromState, toState)Port of ForceMove#_requireValidProtocolTransition solidity code either: - returns Status.True (no further checks required) - returns Status.NeedToCheckApp (clears protocol checks, overall validity requires App.validTransition) - throws an error
sign(wallet, msgHash)
signChallengeMessage(signedStates, privateKey)Signs a challenge message (necessary for submitting a challenge) using the last of the supplied signedStates and privateKey
signData(hashedData, privateKey)
signState(state, privateKey)Encodes, hashes and signs a State using the supplied privateKey
signStates(states, wallets, whoSignedWhat)Maps the supplied wallets array to (a Promise of) an array of signatures by those wallets on the supplied states, using whoSignedWhat to map from wallet to state.
validTransition(fromState, toState, appContract)Calls the valiTransition method on the supplied ForceMoveApp using eth_call

Interfaces

InterfaceDescription
AssetOutcomeShortHandA mapping from destination to BigNumberish. E.g. {ALICE:2, BOB:3}. Only used in testing.
ChallengeRegisteredEventHolds information from a ChallengeRegistered event in a convenient form
ChannelHolds the parameters that define a channel (in particular, its id)
DepositedEventHolds rich information about a Deposited event emitted on chain
OutcomeShortHandA mapping from asset to AssetOutcomeShorthand. E.g. {ETH: {ALICE:2, BOB:3}, DAI: {ALICE:1, BOB:4}}. Only used in testing.
SignedStateA State along with a on it
StateHolds all of the data defining the state of a channel
VariablePartThe part of a State which usually changes during state channel updates

Variables

VariableDescription
ContractArtifacts
decodeOutcome
encodeOutcome
ForceMoveAppContractInterface
getTestProvider
MAGIC_ADDRESS_INDICATING_ETH
MAX_TX_DATA_SIZE
NITRO_MAX_GAS
randomChannelId
randomExternalDestination
TestContractArtifacts

Type Aliases

Type AliasDescription
AssetOutcome
Bytes32
ChannelModehttps://docs.statechannels.org/docs/protocol-tutorial/understand-channel-storage/\#channel-modes
OutcomeThe part of a State which dictates how assets are redistributed when the channel closes
Uint256