channel

package
v0.9.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 25, 2022 License: Apache-2.0 Imports: 34 Imported by: 0

Documentation

Overview

Package channel contains the Ethereum channel backend implementation.

Index

Constants

View Source 
const ERC20DepositorTXGasLimit = 100000

ERC20DepositorTXGasLimit is the limit of Gas that an `ERC20Depositor` will spend per transaction when depositing funds. An `IncreaseAllowance` uses ~45kGas and a `Deposit` call ~84kGas on average.

View Source 
const ETHDepositorGasLimit = 50000

ETHDepositorGasLimit is the limit of Gas that an `ETHDepositor` will spend when depositing funds. A `Deposit` call uses ~47kGas on average.

View Source 
const (
	// GasLimit is the max amount of gas we want to send per transaction.
	GasLimit = 1000000
)

Variables

View Source 
var ErrInvalidContractCode = stderrors.New("invalid bytecode at address")

ErrInvalidContractCode signals invalid bytecode at given address, such as incorrect or no code.

View Source 
var ErrTxFailed = stderrors.New("transaction failed")

ErrTxFailed signals a failed, i.e., reverted, transaction.

Functions

func CalcID added in v0.2.0 

func CalcID(p *channel.Params) (id channel.ID)

CalcID calculates the channelID as needed by the ethereum smart contracts.

func DeployAdjudicator 

func DeployAdjudicator(ctx context.Context, backend ContractBackend, deployer accounts.Account) (common.Address, error)

DeployAdjudicator deploys a new Adjudicator contract. Returns txTimedOutError if the context is cancelled or if the context deadline is exceeded when waiting for the transaction to be mined.

func DeployERC20Assetholder added in v0.5.2 

func DeployERC20Assetholder(ctx context.Context, backend ContractBackend, adjudicatorAddr common.Address, tokenAddr common.Address, deployer accounts.Account) (common.Address, error)

DeployERC20Assetholder deploys a new ERC20AssetHolder contract. Returns txTimedOutError if the context is cancelled or if the context deadline is exceeded when waiting for the transaction to be mined.

func DeployETHAssetholder 

func DeployETHAssetholder(ctx context.Context, backend ContractBackend, adjudicatorAddr common.Address, deployer accounts.Account) (common.Address, error)

DeployETHAssetholder deploys a new ETHAssetHolder contract. Returns txTimedOutError if the context is cancelled or if the context deadline is exceeded when waiting for the transaction to be mined.

func DeployPerunToken added in v0.5.2 

func DeployPerunToken(ctx context.Context, backend ContractBackend, deployer accounts.Account, initAccs []common.Address, initBals *big.Int) (common.Address, error)

DeployPerunToken deploys a new PerunToken contract. Returns txTimedOutError if the context is cancelled or if the context deadline is exceeded when waiting for the transaction to be mined.

func DeployTrivialApp added in v0.6.0 

func DeployTrivialApp(ctx context.Context, backend ContractBackend, deployer accounts.Account) (common.Address, error)

DeployTrivialApp deploys a new TrivialApp contract. Returns txTimedOutError if the context is cancelled or if the context deadline is exceeded when waiting for the transaction to be mined.

func EncodeParams added in v0.5.0 

func EncodeParams(params *adjudicator.ChannelParams) ([]byte, error)

EncodeParams encodes the parameters as with abi.encode() in the smart contracts.

func EncodeState added in v0.5.0 

func EncodeState(state *adjudicator.ChannelState) ([]byte, error)

EncodeState encodes the state as with abi.encode() in the smart contracts.

func FromEthState added in v0.6.0 

func FromEthState(app channel.App, s *adjudicator.ChannelState) channel.State

FromEthState converts a ChannelState to a channel.State struct.

func FundingIDs added in v0.2.0 

func FundingIDs(channelID channel.ID, participants ...perunwallet.Address) [][32]byte

FundingIDs returns a slice the same size as the number of passed participants where each entry contains the hash Keccak256(channel id || participant address).

func HashState added in v0.5.0 

func HashState(s *channel.State) (id channel.ID)

HashState calculates the hash of a state as needed by the ethereum smart contracts.

func IsErrInvalidContractCode added in v0.6.0 

func IsErrInvalidContractCode(err error) bool

IsErrInvalidContractCode returns whether the cause of the error was a invalid bytecode.

func IsErrTxFailed added in v0.6.0 

func IsErrTxFailed(err error) bool

IsErrTxFailed returns whether the cause of the error was a failed transaction.

func NewAsset added in v0.9.0 

func NewAsset() channel.Asset

NewAsset returns a variable of type Asset, which can be used for unmarshalling an asset from its binary representation.

func Sign 

func Sign(acc wallet.Account, s *channel.State) (wallet.Sig, error)

Sign signs the channel state as needed by the ethereum smart contracts.

func ToEthParams added in v0.5.0 

func ToEthParams(p *channel.Params) adjudicator.ChannelParams

ToEthParams converts a channel.Params to a ChannelParams struct.

func ToEthState added in v0.5.0 

func ToEthState(s *channel.State) adjudicator.ChannelState

ToEthState converts a channel.State to a ChannelState struct.

func ValidateAdjudicator added in v0.4.0 

func ValidateAdjudicator(ctx context.Context,
	backend bind.ContractCaller, adjudicatorAddr common.Address) error

ValidateAdjudicator checks if the bytecode at given address is correct. Returns a ContractBytecodeError if the bytecode at given address is invalid. This error can be checked with function IsErrInvalidContractCode.

func ValidateAssetHolderERC20 added in v0.6.0 

func ValidateAssetHolderERC20(ctx context.Context,
	backend bind.ContractBackend, assetHolderERC20, adjudicator, token common.Address) error

ValidateAssetHolderERC20 checks if the bytecode at the given asset holder ERC20 address is correct and if the adjudicator address is correctly set in the asset holder contract. The contract code at the adjudicator address is not validated, it is the user's responsibility to provide a valid adjudicator address.

Returns a ContractBytecodeError if the bytecode is invalid. This error can be checked with function IsErrInvalidContractCode.

func ValidateAssetHolderETH added in v0.4.0 

func ValidateAssetHolderETH(ctx context.Context,
	backend bind.ContractBackend, assetHolderETH, adjudicator common.Address) error

ValidateAssetHolderETH checks if the bytecode at the given asset holder ETH address is correct and if the adjudicator address is correctly set in the asset holder contract. The contract code at the adjudicator address is not validated, it is the user's responsibility to provide a valid adjudicator address.

Returns a ContractBytecodeError if the bytecode is invalid. This error can be checked with function IsErrInvalidContractCode.

func Verify 

func Verify(addr wallet.Address, s *channel.State, sig wallet.Sig) (bool, error)

Verify verifies that a state was signed correctly.

Types

type Adjudicator added in v0.2.0 

type Adjudicator struct {
	ContractBackend

	// The address to which we send all funds.
	Receiver common.Address
	// contains filtered or unexported fields
}

The Adjudicator struct implements the channel.Adjudicator interface It provides all functionality to close a channel.

func NewAdjudicator added in v0.2.0 

func NewAdjudicator(backend ContractBackend, contract common.Address, receiver common.Address, txSender accounts.Account) *Adjudicator

NewAdjudicator creates a new ethereum adjudicator. The receiver is the on-chain address that receives withdrawals.

func (*Adjudicator) Progress added in v0.6.0 

func (a *Adjudicator) Progress(ctx context.Context, req channel.ProgressReq) error

Progress progresses a channel state on-chain.

func (*Adjudicator) Register added in v0.2.0 

func (a *Adjudicator) Register(ctx context.Context, req channel.AdjudicatorReq, subChannels []channel.SignedState) error

Register registers a state on-chain. If the state is a final state, register becomes a no-op.

func (*Adjudicator) Subscribe added in v0.6.0 

func (a *Adjudicator) Subscribe(ctx context.Context, chID channel.ID) (channel.AdjudicatorSubscription, error)

Subscribe returns a new AdjudicatorSubscription to adjudicator events.

func (*Adjudicator) Withdraw added in v0.2.0 

func (a *Adjudicator) Withdraw(ctx context.Context, req channel.AdjudicatorReq, subStates channel.StateMap) error

Withdraw ensures that a channel has been concluded and the final outcome withdrawn from the asset holders.

type Asset 

type Asset struct {
	wallet.Address
}

Asset is an Ethereum asset.

func NewAssetFromAddress added in v0.9.0 

func NewAssetFromAddress(a common.Address) *Asset

NewAssetFromAddress creates a new asset from an Ethereum address.

func (Asset) Equal added in v0.9.0 

func (a Asset) Equal(b channel.Asset) bool

Equal returns true iff the asset equals the given asset.

func (Asset) EthAddress added in v0.9.0 

func (a Asset) EthAddress() common.Address

EthAddress returns the Ethereum address representation of the asset.

type Backend 

type Backend struct{}

Backend implements the interface defined in channel/Backend.go.

func (*Backend) CalcID added in v0.2.0 

func (*Backend) CalcID(p *channel.Params) (id channel.ID)

CalcID calculates the channelID as needed by the ethereum smart contracts.

func (*Backend) NewAsset added in v0.9.0 

func (b *Backend) NewAsset() channel.Asset

NewAsset returns a variable of type Asset, which can be used for unmarshalling an asset from its binary representation.

func (*Backend) Sign 

func (*Backend) Sign(acc wallet.Account, s *channel.State) (wallet.Sig, error)

Sign signs the channel state as needed by the ethereum smart contracts.

func (*Backend) Verify 

func (*Backend) Verify(addr wallet.Address, s *channel.State, sig wallet.Sig) (bool, error)

Verify verifies that a state was signed correctly.

type BlockTimeout added in v0.2.1 

type BlockTimeout struct {
	Time uint64
	// contains filtered or unexported fields
}

BlockTimeout is a timeout on an Ethereum blockchain. A ChainReader is used to wait for the timeout to pass.

This is much better than a channel.TimeTimeout because the local clock might not match the blockchain's timestamp at the point in time when the timeout has passed locally.

func NewBlockTimeout added in v0.2.1 

func NewBlockTimeout(cr ethereum.ChainReader, ts uint64) *BlockTimeout

NewBlockTimeout creates a new BlockTimeout bound to the provided ChainReader and ts as the absolute block.timestamp timeout.

func NewBlockTimeoutDuration added in v0.2.1 

func NewBlockTimeoutDuration(
	ctx context.Context, cr ethereum.ChainReader, duration uint64) (*BlockTimeout, error)

NewBlockTimeoutDuration creates a new BlockTimeout that elapses duration blockchain seconds added to the current block timestamp in the future.

func (*BlockTimeout) IsElapsed added in v0.2.1 

func (t *BlockTimeout) IsElapsed(ctx context.Context) bool

IsElapsed reads the timestamp from the current blockchain header to check whether the timeout has passed yet.

func (*BlockTimeout) String added in v0.2.1 

func (t *BlockTimeout) String() string

String returns a string stating the block timeout as a unix timestamp.

func (*BlockTimeout) Wait added in v0.2.1 

func (t *BlockTimeout) Wait(ctx context.Context) error

Wait subscribes to new blocks until the timeout is reached. It returns the context error if it is canceled before the timeout is reached.

type ContractBackend 

type ContractBackend struct {
	ContractInterface
	// contains filtered or unexported fields
}

ContractBackend adds a keystore and an on-chain account to the ContractInterface. This is needed to send on-chain transaction to interact with the smart contracts.

func NewContractBackend 

func NewContractBackend(cf ContractInterface, tr Transactor, txFinalityDepth uint64) ContractBackend

NewContractBackend creates a new ContractBackend with the given parameters. txFinalityDepth defines in how many consecutive blocks a TX has to be included to be considered final. Must be at least 1.

func (*ContractBackend) ConfirmTransaction added in v0.5.2 

func (c *ContractBackend) ConfirmTransaction(ctx context.Context, tx *types.Transaction, acc accounts.Account) (*types.Receipt, error)

ConfirmTransaction returns the receipt of the transaction if it was included in at least `TxFinalityDepth` many blocks at one point in time. Returns `txTimedOutError` on context timeout or cancel.

func (*ContractBackend) NewFilterOpts added in v0.2.0 

func (c *ContractBackend) NewFilterOpts(ctx context.Context) (*bind.FilterOpts, error)

NewFilterOpts returns bind.FilterOpts with the field Start set to the block number 100 blocks ago (or 1) and the field End set to nil and the ctx field set to the passed context.

func (*ContractBackend) NewTransactor added in v0.2.0 

func (c *ContractBackend) NewTransactor(ctx context.Context, gasLimit uint64,
	acc accounts.Account) (*bind.TransactOpts, error)

NewTransactor returns bind.TransactOpts with the context, gas limit and account set as specified, using the ContractBackend's Transactor.

The gas price and nonce are not set and will be set by go-ethereum automatically when not manually specified by the caller. The caller must also set the value manually afterwards if it should be different from 0.

func (*ContractBackend) NewWatchOpts added in v0.2.0 

func (c *ContractBackend) NewWatchOpts(ctx context.Context) (*bind.WatchOpts, error)

NewWatchOpts returns bind.WatchOpts with the field Start set to the current block number and the ctx field set to the passed context.

type ContractInterface 

type ContractInterface interface {
	bind.ContractBackend
	ethereum.ChainReader
	ethereum.TransactionReader
}

ContractInterface provides all functions needed by an ethereum backend. Both test.SimulatedBackend and ethclient.Client implement this interface.

type DepositReq added in v0.4.1 

type DepositReq struct {
	Balance   channel.Bal      // How much should be deposited.
	CB        ContractBackend  // Used to bind contracts and send TX.
	Account   accounts.Account // Depositor's account.
	Asset     Asset            // Address of the AssetHolder.
	FundingID [32]byte         // Needed by the AssetHolder.
}

DepositReq contains all necessary data for a `Depositor` to deposit funds. It is much smaller than a `FundingReq` and only holds the information for one Funding-ID.

func NewDepositReq added in v0.4.1 

func NewDepositReq(balance channel.Bal, cb ContractBackend, asset Asset, account accounts.Account, fundingID [32]byte) *DepositReq

NewDepositReq returns a new `DepositReq`.

type Depositor added in v0.4.1 

type Depositor interface {
	// Deposit returns the transactions needed for the deposit or an error.
	// The transactions should already be sent to the chain, such that
	// `abi/bind.WaitMined` can be used to await their success.
	// When one of the TX fails, the status of the following ones is ignored.
	Deposit(context.Context, DepositReq) (types.Transactions, error)

	// NumTX returns how many transactions a `Deposit` call needs.
	NumTX() uint32
}

Depositor is used by the `Funder` to deposit funds for ledger channel funding. Depositor are reusable such that one Depositor per asset is enough.

type ERC20Depositor added in v0.5.2 

type ERC20Depositor struct {
	Token common.Address
}

ERC20Depositor deposits tokens into the `AssetHolderERC20` contract. It is bound to a token but can be reused to deposit multiple times.

func NewERC20Depositor added in v0.7.0 

func NewERC20Depositor(token common.Address) *ERC20Depositor

NewERC20Depositor creates a new ERC20Depositor.

func (*ERC20Depositor) Deposit added in v0.5.2 

func (d *ERC20Depositor) Deposit(ctx context.Context, req DepositReq) (types.Transactions, error)

Deposit deposits ERC20 tokens into the ERC20 AssetHolder specified at the requests's asset address.

func (*ERC20Depositor) NumTX added in v0.5.2 

func (*ERC20Depositor) NumTX() uint32

NumTX returns 2 since it does IncreaseAllowance and Deposit.

type ETHDepositor added in v0.4.1 

type ETHDepositor struct{}

ETHDepositor deposits funds into the `AssetHolderETH` contract. It has no state and is therefore completely reusable.

func NewETHDepositor added in v0.7.0 

func NewETHDepositor() *ETHDepositor

NewETHDepositor creates a new ETHDepositor.

func (*ETHDepositor) Deposit added in v0.4.1 

func (d *ETHDepositor) Deposit(ctx context.Context, req DepositReq) (types.Transactions, error)

Deposit deposits ether into the ETH AssetHolder specified at the requests's asset address.

func (*ETHDepositor) NumTX added in v0.5.2 

func (*ETHDepositor) NumTX() uint32

NumTX returns 1 since it only does Deposit.

type Funder 

type Funder struct {
	ContractBackend
	// contains filtered or unexported fields
}

Funder implements the channel.Funder interface for Ethereum.

In addition to the `Fund` method required by the `Funder` interface, it also provides additional functions for convenience.

All the exported methods are thread-safe and can be invoked concurrently.

func NewFunder added in v0.4.1 

func NewFunder(backend ContractBackend) *Funder

NewFunder creates a new ethereum funder.

func (*Funder) Fund 

func (f *Funder) Fund(ctx context.Context, request channel.FundingReq) error

Fund implements the channel.Funder interface. It funds all assets in parallel. If not all participants successfully fund within a timeframe of ChallengeDuration seconds, Fund returns a FundingTimeoutError.

If funding on a real blockchain, make sure that the passed context doesn't cancel before the funding period of length ChallengeDuration elapses, or funding will be canceled prematurely.

func (*Funder) IsAssetRegistered added in v0.7.0 

func (f *Funder) IsAssetRegistered(asset Asset) (Depositor, accounts.Account, bool)

IsAssetRegistered returns if the specified asset is registered in the funder or not. If is registered, then the corresponding depositor and account will also be returned.

func (*Funder) NumTX added in v0.5.2 

func (f *Funder) NumTX(req channel.FundingReq) (sum uint32, err error)

NumTX returns how many Transactions are needed for the funding request.

func (*Funder) RegisterAsset added in v0.7.0 

func (f *Funder) RegisterAsset(asset Asset, d Depositor, acc accounts.Account) bool

RegisterAsset registers the depositor and account for the specified asset in the funder.

Deposits for this asset will be sent using the depositors from the specified account when funding. Hence, it is the responsibility of the caller to ensure, the account has sufficient balance in the asset.

It returns true if the asset was successfully registered, false if it was already present.

type OnChainTxType added in v0.7.0 

type OnChainTxType int

OnChainTxType defines the type of on-chain transaction function names that can be returned in TxTimeoutError. 

const (
	Fund OnChainTxType = iota
	Register
	Progress
	Conclude
	ConcludeFinal
	Withdraw
)

Enumeration of valid transaction types.

Fund funds the channel for a given user. Register registers a state of the channel. The state be concluded after the challenge duration has passed. Progress progresses the state of the channel directly on the blockchain. Conclude concludes the state of a channel after it had been registered and the challenge duration has passed. ConcludeFinal directly concludes the finalized state of the channel without registering it. Withdraw withdraws the funds for a given user after the channel was concluded.

func (OnChainTxType) String added in v0.7.0 

func (t OnChainTxType) String() string

type RegisteredSub added in v0.2.0 

type RegisteredSub struct {
	// contains filtered or unexported fields
}

RegisteredSub implements the channel.AdjudicatorSubscription interface.

func (*RegisteredSub) Close added in v0.2.0 

func (r *RegisteredSub) Close() error

Close closes this subscription. Any pending calls to Next will return nil.

func (*RegisteredSub) Err added in v0.2.0 

func (r *RegisteredSub) Err() error

Err returns the error of the event subscription. Should only be called after Next returned nil.

func (*RegisteredSub) Next added in v0.2.0 

func (r *RegisteredSub) Next() channel.AdjudicatorEvent

Next returns the newest past or next blockchain event. It blocks until an event is returned from the blockchain or the subscription is closed. If the subscription is closed, Next immediately returns nil. If there was a past event when the subscription was set up, the first call to Next will return it.

type Transactor added in v0.4.1 

type Transactor interface {
	NewTransactor(account accounts.Account) (*bind.TransactOpts, error)
}

Transactor can be used to make transactOpts for a given account.

Source Files

View all Source files

Directories

Path Synopsis
Package errors contains error checking and wrapping functions.
 Package errors contains error checking and wrapping functions.
Package test contains utilities for testing the Ethereum channel backend, such as a simulated blockchain backend and a custom Adjudicator.
 Package test contains utilities for testing the Ethereum channel backend, such as a simulated blockchain backend and a custom Adjudicator.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.