client

package
v0.12.0 Latest Latest
Warning

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

 Go to latest Published: Nov 18, 2024 License: Apache-2.0 Imports: 27 Imported by: 14

Documentation

Overview

Package client contains the Perun State Channel network protocol implementation. It provides a Client that exposes the central API to communicate with a channel network. The Client provides Channel controllers to interact with individual channels.

Index

Constants

View Source 
const (
	// ProposerIdx is the index of the channel proposer.
	ProposerIdx = 0
	// ProposeeIdx is the index of the channel proposal receiver.
	ProposeeIdx = 1
)

Variables

This section is empty.

Functions

func NewChainNotReachableError added in v0.7.0 

func NewChainNotReachableError(actualErr error) error

NewChainNotReachableError constructs a ChainNotReachableError and wraps it with the actual error message.

func NewTxTimedoutError added in v0.7.0 

func NewTxTimedoutError(txType, txID, actualErrMsg string) error

NewTxTimedoutError constructs a TxTimedoutError and wraps it with the actual error message.

txID is the ID required for tracking the transaction on the blockchain and txType is the type of on-chain transaction. Valid types should be defined by each of the blockchain backend.

Types

type AdjudicatorEventHandler added in v0.6.0 

type AdjudicatorEventHandler interface {
	HandleAdjudicatorEvent(channel.AdjudicatorEvent)
}

AdjudicatorEventHandler represents an interface for handling adjudicator events.

type BaseChannelProposal added in v0.4.1 

type BaseChannelProposal struct {
	ProposalID        ProposalID          // Unique ID for the proposal.
	ChallengeDuration uint64              // Dispute challenge duration.
	NonceShare        NonceShare          // Proposer's channel nonce share.
	App               channel.App         // App definition, or nil.
	InitData          channel.Data        // Initial App data.
	InitBals          *channel.Allocation // Initial balances.
	FundingAgreement  channel.Balances    // Possibly different funding agreement from initial state's balances.
}

BaseChannelProposal contains all data necessary to propose a new channel to a given set of peers. It is also sent over the wire.

BaseChannelProposal implements the channel proposal messages from the Multi-Party Channel Proposal Protocol (MPCPP).

func (*BaseChannelProposal) Base added in v0.5.0 

func (p *BaseChannelProposal) Base() *BaseChannelProposal

Base returns the channel proposal's common values.

func (*BaseChannelProposal) Decode added in v0.4.1 

func (p *BaseChannelProposal) Decode(r io.Reader) (err error)

Decode decodes a BaseChannelProposal from an io.Reader.

func (BaseChannelProposal) Encode added in v0.4.1 

func (p BaseChannelProposal) Encode(w io.Writer) error

Encode encodes the BaseChannelProposal into an io.Writer.

func (BaseChannelProposal) NumPeers added in v0.5.2 

func (p BaseChannelProposal) NumPeers() int

NumPeers returns the number of peers in a channel.

func (*BaseChannelProposal) Valid added in v0.4.1 

func (p *BaseChannelProposal) Valid() error

Valid checks that the channel proposal is valid: * InitBals must not be nil * ValidateProposalParameters returns nil * InitBals are valid * No locked sub-allocations * non-zero ChallengeDuration.

type BaseChannelProposalAcc added in v0.5.2 

type BaseChannelProposalAcc struct {
	ProposalID ProposalID // Proposal session ID we're answering.
	NonceShare NonceShare // Responder's channel nonce share.
}

BaseChannelProposalAcc contains all data for a response to a channel proposal message. The ProposalID must correspond to the channel proposal request one wishes to respond to. Participant should be a participant address just for this channel instantiation.

The type implements the channel proposal response messages from the Multi-Party Channel Proposal Protocol (MPCPP).

func (*BaseChannelProposalAcc) Decode added in v0.5.2 

func (acc *BaseChannelProposalAcc) Decode(r io.Reader) error

Decode decodes a BaseChannelProposalAcc.

func (BaseChannelProposalAcc) Encode added in v0.5.2 

func (acc BaseChannelProposalAcc) Encode(w io.Writer) error

Encode encodes a BaseChannelProposalAcc.

type ChainNotReachableError added in v0.7.0 

type ChainNotReachableError struct{}

ChainNotReachableError indicates problems in connecting to the blockchain network when trying to do on-chain transactions or reading from the blockchain.

func (ChainNotReachableError) Error added in v0.7.0 

func (e ChainNotReachableError) Error() string

Error implements the error interface.

type Channel 

type Channel struct {
	perunsync.OnCloser
	log.Embedding
	// contains filtered or unexported fields
}

Channel is the channel controller, progressing the channel state machine and executing the channel update and dispute protocols.

Currently, only the two-party protocol is fully implemented.

func (*Channel) Close 

func (c *Channel) Close() error

Close closes the channel and all associated peer subscriptions.

func (*Channel) Ctx added in v0.3.0 

func (c *Channel) Ctx() context.Context

Ctx returns a context that is active for the channel's lifetime.

func (*Channel) ForceUpdate added in v0.8.0 

func (c *Channel) ForceUpdate(ctx context.Context, updater func(*channel.State)) error

ForceUpdate enforces a state update through the adjudicator as specified by the `updater` function.

The updater function must adhere to the following rules: - The version must not be changed. It is incremented automatically. - The assets must not be changed. - The locked allocation must not be changed.

Returns TxTimedoutError when the program times out waiting for a transaction to be mined. Returns ChainNotReachableError if the connection to the blockchain network fails when sending a transaction to / reading from the blockchain.

func (*Channel) HasApp added in v0.6.0 

func (c *Channel) HasApp() bool

HasApp returns whether the channel has an app.

func (*Channel) ID 

func (c *Channel) ID() channel.ID

ID returns the channel ID.

func (*Channel) Idx 

func (c *Channel) Idx() channel.Index

Idx returns our index in the channel.

func (*Channel) IsClosed added in v0.3.0 

func (c *Channel) IsClosed() bool

IsClosed returns whether the channel is closed.

func (*Channel) IsLedgerChannel added in v0.6.0 

func (c *Channel) IsLedgerChannel() bool

IsLedgerChannel returns whether the channel is a ledger channel.

func (*Channel) IsSubChannel added in v0.5.0 

func (c *Channel) IsSubChannel() bool

IsSubChannel returns whether the channel is a sub-channel.

func (*Channel) IsVirtualChannel added in v0.7.0 

func (c *Channel) IsVirtualChannel() bool

IsVirtualChannel returns whether the channel is a virtual channel. A virtual channel is a channel that has a parent channel with different participants.

func (*Channel) OnUpdate added in v0.4.1 

func (c *Channel) OnUpdate(cb func(from, to *channel.State))

OnUpdate sets up a callback to state updates for the channel. The subscription cannot be canceled, but it can be replaced. The States that are passed to the callback are not clones but pointers to the State in the channel machine, so they must not be modified. If you need to modify the State, .Clone() them first.

func (*Channel) Params 

func (c *Channel) Params() *channel.Params

Params returns the channel parameters.

func (*Channel) Parent added in v0.5.0 

func (c *Channel) Parent() *Channel

Parent returns the parent channel. Can be nil.

func (*Channel) Peers added in v0.4.0 

func (c *Channel) Peers() []wire.Address

Peers returns the Perun network addresses of all peers, in the order of the channel participants.

func (*Channel) Phase 

func (c *Channel) Phase() channel.Phase

Phase returns the current phase of the channel state machine. Can not be called from an update handler.

func (*Channel) Settle 

func (c *Channel) Settle(ctx context.Context, secondary bool) (err error)

Settle concludes the channel and withdraws the funds.

This only works if the channel is concludable. - A ledger channel is concludable, if it is final or if it has been disputed before and the dispute timeout has passed. - Sub-channels and virtual channels are only concludable if they are final and do not have any sub-channels. Otherwise, this means a dispute has occurred and the corresponding ledger channel must be disputed.

Returns TxTimedoutError when the program times out waiting for a transaction to be mined. Returns ChainNotReachableError if the connection to the blockchain network fails when sending a transaction to / reading from the blockchain.

func (*Channel) State 

func (c *Channel) State() *channel.State

State returns a pointer to the current state. Clone it if you want to modify it. Can not be called from an update handler.

func (*Channel) Update 

func (c *Channel) Update(ctx context.Context, updater func(*channel.State)) error

Update proposes a state update to the channel participants as specified by the `updater` function.

The updater function must adhere to the following rules: - The version must not be changed. It is incremented automatically. - The assets must not be changed. - The locked allocation must not be changed.

Returns nil if all peers accept the update. Returns RequestTimedOutError if any peer did not respond before the context expires or is cancelled. Returns an error if any runtime error occurs or any peer rejects the update.

func (*Channel) Watch added in v0.2.0 

func (c *Channel) Watch(h AdjudicatorEventHandler) error

Watch registers the channel with the watcher, which watches for channel events and responds accordingly. The handler is notified about the corresponding events.

The watcher takes care that if an old state is registered, the on-chain state is refuted by registering the channel tree with the most recent states available to the watcher. In such a case, the handler may receive multiple registered events in short succession.

It should be started as a go-routine and returns when the channel is closed.

type ChannelFundingError added in v0.10.1 

type ChannelFundingError struct {
	Err error
}

ChannelFundingError indicates an error during channel funding.

func (ChannelFundingError) Error added in v0.10.1 

func (e ChannelFundingError) Error() string

type ChannelMsg 

type ChannelMsg interface {
	wire.Msg
	ID() channel.ID
}

ChannelMsg are all messages that can be routed to a particular channel controller.

type ChannelProposal 

type ChannelProposal interface {
	wire.Msg
	perunio.Decoder

	// Base returns the channel proposal's common values.
	Base() *BaseChannelProposal

	// Matches checks whether an accept message is of the correct type. This
	// does not check any contents of the accept message, only its type.
	Matches(ChannelProposalAccept) bool

	// Valid checks whether a channel proposal is valid.
	Valid() error
}

ChannelProposal is the interface that describes all channel proposal message types.

type ChannelProposalAccept added in v0.5.2 

type ChannelProposalAccept interface {
	wire.Msg
	Base() *BaseChannelProposalAcc
}

ChannelProposalAccept is the generic interface for channel proposal accept messages.

type ChannelProposalRejMsg added in v0.9.0 

type ChannelProposalRejMsg struct {
	ProposalID ProposalID // The channel proposal to reject.
	Reason     string     // The rejection reason.
}

ChannelProposalRejMsg is used to reject a ChannelProposalReq. An optional reason for the rejection can be set.

The message is one of two possible responses in the Multi-Party Channel Proposal Protocol (MPCPP).

Reason should be a UTF-8 encodable string.

func (*ChannelProposalRejMsg) Decode added in v0.9.0 

func (rej *ChannelProposalRejMsg) Decode(r io.Reader) error

Decode decodes a ChannelProposalRej from an io.Reader.

func (ChannelProposalRejMsg) Encode added in v0.9.0 

func (rej ChannelProposalRejMsg) Encode(w io.Writer) error

Encode encodes a ChannelProposalRej into an io.Writer.

func (ChannelProposalRejMsg) Type added in v0.9.0 

func (ChannelProposalRejMsg) Type() wire.Type

Type returns wire.ChannelProposalRej.

type ChannelSyncMsg added in v0.9.0 

type ChannelSyncMsg struct {
	Phase     channel.Phase       // Phase is the phase of the sender.
	CurrentTX channel.Transaction // CurrentTX is the sender's current transaction.
}

ChannelSyncMsg is the wire message for syncing channel states across multiple clients.

func (*ChannelSyncMsg) Decode added in v0.9.0 

func (m *ChannelSyncMsg) Decode(r io.Reader) error

Decode implements perunio.Decode.

func (*ChannelSyncMsg) Encode added in v0.9.0 

func (m *ChannelSyncMsg) Encode(w io.Writer) error

Encode implements perunio.Encode.

func (*ChannelSyncMsg) ID added in v0.9.0 

func (m *ChannelSyncMsg) ID() channel.ID

ID returns the channel's ID.

func (*ChannelSyncMsg) Type added in v0.9.0 

func (m *ChannelSyncMsg) Type() wire.Type

Type implements wire.Type.

type ChannelUpdate 

type ChannelUpdate struct {
	// State is the proposed new state.
	State *channel.State
	// ActorIdx is the actor causing the new state. It does not need to
	// coincide with the sender of the request.
	ActorIdx channel.Index
}

ChannelUpdate is a channel update proposal.

type ChannelUpdateAccMsg added in v0.9.0 

type ChannelUpdateAccMsg struct {
	// ChannelID is the channel ID.
	ChannelID channel.ID
	// Version of the state that is accepted.
	Version uint64
	// Sig is the signature on the proposed new state by the sender.
	Sig wallet.Sig
}

ChannelUpdateAccMsg is the wire message sent as a positive reply to a ChannelUpdate. It references the channel ID and version and contains the signature on the accepted new state by the sender.

func (*ChannelUpdateAccMsg) Decode added in v0.9.0 

func (c *ChannelUpdateAccMsg) Decode(r io.Reader) (err error)

Decode decodes the ChannelUpdateAccMsg from the io.Reader.

func (ChannelUpdateAccMsg) Encode added in v0.9.0 

func (c ChannelUpdateAccMsg) Encode(w io.Writer) error

Encode encodes the ChannelUpdateAccMsg into the io.Writer.

func (*ChannelUpdateAccMsg) ID added in v0.9.0 

func (c *ChannelUpdateAccMsg) ID() channel.ID

ID returns the id of the channel this update acceptance refers to.

func (*ChannelUpdateAccMsg) Type added in v0.9.0 

func (*ChannelUpdateAccMsg) Type() wire.Type

Type returns this message's type: ChannelUpdateAcc.

func (*ChannelUpdateAccMsg) Ver added in v0.9.0 

func (c *ChannelUpdateAccMsg) Ver() uint64

Ver returns the version of the state this update acceptance refers to.

type ChannelUpdateMsg added in v0.9.0 

type ChannelUpdateMsg struct {
	ChannelUpdate
	// Sig is the signature on the proposed state by the peer sending the
	// ChannelUpdate.
	Sig wallet.Sig
}

ChannelUpdateMsg is the wire message of a channel update proposal. It additionally holds the signature on the proposed state.

func (*ChannelUpdateMsg) Base added in v0.9.0 

func (c *ChannelUpdateMsg) Base() *ChannelUpdateMsg

Base returns the core channel update message.

func (*ChannelUpdateMsg) Decode added in v0.9.0 

func (c *ChannelUpdateMsg) Decode(r io.Reader) (err error)

Decode decodes the ChannelUpdateMsg from the io.Reader.

func (ChannelUpdateMsg) Encode added in v0.9.0 

func (c ChannelUpdateMsg) Encode(w io.Writer) error

Encode encodes the ChannelUpdateMsg into the io.Writer.

func (*ChannelUpdateMsg) ID added in v0.9.0 

func (c *ChannelUpdateMsg) ID() channel.ID

ID returns the id of the channel this update refers to.

func (*ChannelUpdateMsg) Type added in v0.9.0 

func (*ChannelUpdateMsg) Type() wire.Type

Type returns this message's type: ChannelUpdate.

type ChannelUpdateProposal added in v0.7.0 

type ChannelUpdateProposal interface {
	wire.Msg
	perunio.Decoder
	Base() *ChannelUpdateMsg
}

ChannelUpdateProposal represents an abstract update proposal message.

type ChannelUpdateRejMsg added in v0.9.0 

type ChannelUpdateRejMsg struct {
	// ChannelID is the channel ID.
	ChannelID channel.ID
	// Version of the state that is accepted.
	Version uint64
	// Reason states why the sender rejectes the proposed new state.
	Reason string
}

ChannelUpdateRejMsg is the wire message sent as a negative reply to a ChannelUpdate. It references the channel ID and version and states a reason for the rejection.

Reason should be a UTF-8 encodable string.

func (*ChannelUpdateRejMsg) Decode added in v0.9.0 

func (c *ChannelUpdateRejMsg) Decode(r io.Reader) (err error)

Decode decodes the ChannelUpdateRejMsg from the io.Reader.

func (ChannelUpdateRejMsg) Encode added in v0.9.0 

func (c ChannelUpdateRejMsg) Encode(w io.Writer) error

Encode encodes the ChannelUpdateRejMsg into the io.Writer.

func (*ChannelUpdateRejMsg) ID added in v0.9.0 

func (c *ChannelUpdateRejMsg) ID() channel.ID

ID returns the id of the channel this update rejection refers to.

func (*ChannelUpdateRejMsg) Type added in v0.9.0 

func (*ChannelUpdateRejMsg) Type() wire.Type

Type returns this message's type: ChannelUpdateRej.

func (*ChannelUpdateRejMsg) Ver added in v0.9.0 

func (c *ChannelUpdateRejMsg) Ver() uint64

Ver returns the version of the state this update rejection refers to.

type Client 

type Client struct {
	sync.Closer
	// contains filtered or unexported fields
}

Client is a state channel client. It is the central controller to interact with a state channel network. It can be used to propose channels to other channel network peers.

Currently, only the two-party protocol is fully implemented.

func New 

func New(
	address wire.Address,
	bus wire.Bus,
	funder channel.Funder,
	adjudicator channel.Adjudicator,
	wallet wallet.Wallet,
	watcher watcher.Watcher,
) (c *Client, err error)

New creates a new State Channel Client.

address is the channel network address of this client. It is the persistend identifier in the network and not necessarily related to any on-chain identity or channel participant address.

bus is the wire protocol bus over which messages to other network clients are sent and received from.

The funder and adjudicator are used to fund and dispute or settle a ledger channel, respectively.

The wallet is used to resolve addresses to accounts when creating or restoring channels.

If any argument is nil, New panics.

func (*Client) Channel added in v0.2.0 

func (c *Client) Channel(id channel.ID) (*Channel, error)

Channel queries a channel by its ID.

func (*Client) Close 

func (c *Client) Close() error

Close closes this state channel client. It also closes the peer registry.

func (*Client) EnablePersistence added in v0.3.0 

func (c *Client) EnablePersistence(pr persistence.PersistRestorer)

EnablePersistence sets the PersistRestorer that the client is going to use for channel persistence. This methods is expected to be called once during the setup of the client and is hence not thread-safe.

The PersistRestorer is not closed when the Client is closed.

func (*Client) Handle added in v0.3.0 

func (c *Client) Handle(ph ProposalHandler, uh UpdateHandler)

Handle is the incoming request handler routine. It handles channel proposals and channel update requests. It must be started exactly once by the user, during the setup of the Client. Incoming requests are handled by the passed respecive handlers.

func (*Client) Log 

func (c *Client) Log() log.Logger

Log returns the logger used by the client. It is not thread-safe.

func (*Client) OnNewChannel added in v0.3.0 

func (c *Client) OnNewChannel(handler func(*Channel))

OnNewChannel sets a callback to be called whenever a new channel is created or restored. Only one such handler can be set at a time, and repeated calls to this function will overwrite the currently existing handler. This function may be safely called at any time.

func (*Client) ProposeChannel 

func (c *Client) ProposeChannel(ctx context.Context, prop ChannelProposal) (*Channel, error)

ProposeChannel attempts to open a channel with the parameters and peers from ChannelProposal prop: - the proposal is sent to the peers and if all peers accept, - the channel is funded. If successful, - the channel controller is returned.

After the channel controller got successfully set up, it is passed to the callback registered with Client.OnNewChannel. Accept returns after this callback has run.

It is important that the passed context does not cancel before the ChallengeDuration has passed. Otherwise funding may not complete.

If funding fails, ChannelFundingError is thrown and an unfunded channel object is returned, which can be used for withdrawing the funds.

After the channel got successfully created, the user is required to start the channel watcher with Channel.Watch() on the returned channel controller.

Returns PeerRejectedProposalError if the channel is rejected by the peer. Returns RequestTimedOutError if the peer did not respond before the context expires or is cancelled. Returns ChannelFundingError if an error happened during funding. The internal error gives more information. - Contains FundingTimeoutError if any of the participants do not fund the channel in time. - Contains TxTimedoutError when the program times out waiting for a transaction to be mined. - Contains ChainNotReachableError if the connection to the blockchain network fails when sending a transaction to / reading from the blockchain.

func (*Client) Restore added in v0.4.0 

func (c *Client) Restore(ctx context.Context) error

Restore restores all channels from persistence. Channels are restored in parallel. Newly restored channels should be acquired through the OnNewChannel callback.

func (*Client) SetLog added in v0.4.0 

func (c *Client) SetLog(l log.Logger)

SetLog sets the logger used by the client. It is not thread-safe.

type LedgerChannelProposalAccMsg added in v0.9.0 

type LedgerChannelProposalAccMsg struct {
	BaseChannelProposalAcc
	Participant wallet.Address // Responder's participant address.
}

LedgerChannelProposalAccMsg is the accept message type corresponding to ledger channel proposals. ParticipantAdd is recommended to be unique for each channel instantiation.

func (*LedgerChannelProposalAccMsg) Base added in v0.9.0 

func (acc *LedgerChannelProposalAccMsg) Base() *BaseChannelProposalAcc

Base returns the common proposal accept values.

func (*LedgerChannelProposalAccMsg) Decode added in v0.9.0 

func (acc *LedgerChannelProposalAccMsg) Decode(r io.Reader) error

Decode decodes a LedgerChannelProposalAcc from an io.Reader.

func (LedgerChannelProposalAccMsg) Encode added in v0.9.0 

func (acc LedgerChannelProposalAccMsg) Encode(w io.Writer) error

Encode encodes the LedgerChannelProposalAcc into an io.Writer.

func (LedgerChannelProposalAccMsg) Type added in v0.9.0 

func (LedgerChannelProposalAccMsg) Type() wire.Type

Type returns wire.ChannelProposalAcc.

type LedgerChannelProposalMsg added in v0.9.0 

type LedgerChannelProposalMsg struct {
	BaseChannelProposal
	Participant wallet.Address // Proposer's address in the channel.
	Peers       []wire.Address // Participants' wire addresses.
}

LedgerChannelProposalMsg is a channel proposal for ledger channels.

func NewLedgerChannelProposal added in v0.4.1 

func NewLedgerChannelProposal(
	challengeDuration uint64,
	participant wallet.Address,
	initBals *channel.Allocation,
	peers []wire.Address,
	opts ...ProposalOpts,
) (prop *LedgerChannelProposalMsg, err error)

NewLedgerChannelProposal creates a ledger channel proposal and applies the supplied options. challengeDuration is the on-chain challenge duration in seconds. participant is our wallet address. initBals are the initial balances. peers are the wire addresses of the channel participants. For more information, see ProposalOpts.

func (LedgerChannelProposalMsg) Accept added in v0.9.0 

func (p LedgerChannelProposalMsg) Accept(
	participant wallet.Address,
	nonceShare ProposalOpts,
) *LedgerChannelProposalAccMsg

Accept constructs an accept message that belongs to a proposal message. It should be used instead of manually constructing an accept message.

func (*LedgerChannelProposalMsg) Decode added in v0.9.0 

func (p *LedgerChannelProposalMsg) Decode(r io.Reader) error

Decode decodes a ledger channel proposal.

func (LedgerChannelProposalMsg) Encode added in v0.9.0 

func (p LedgerChannelProposalMsg) Encode(w io.Writer) error

Encode encodes a ledger channel proposal.

func (LedgerChannelProposalMsg) Matches added in v0.9.0 

func (LedgerChannelProposalMsg) Matches(acc ChannelProposalAccept) bool

Matches requires that the accept message is a LedgerChannelAcc message.

func (LedgerChannelProposalMsg) Type added in v0.9.0 

func (LedgerChannelProposalMsg) Type() wire.Type

Type returns wire.LedgerChannelProposal.

func (LedgerChannelProposalMsg) Valid added in v0.9.0 

func (p LedgerChannelProposalMsg) Valid() error

Valid checks whether the participant address is nil.

type NonceShare added in v0.4.1 

type NonceShare = [32]byte

NonceShare is used to cooperatively calculate a channel's nonce.

type PeerRejectedError added in v0.7.0 

type PeerRejectedError struct {
	ItemType string // ItemType indicates the type of item rejected (channel proposal or channel update).
	Reason   string // Reason sent by the peer for the rejection.
}

PeerRejectedError indicates the channel proposal or channel update was rejected by the peer.

Reason should be a UTF-8 encodable string.

func (PeerRejectedError) Error added in v0.7.0 

func (e PeerRejectedError) Error() string

Error implements the error interface.

type ProposalHandler 

type ProposalHandler interface {
	// HandleProposal is the user callback called by the Client on an incoming channel
	// proposal.
	// The response on the proposal responder must be called within the same go routine.
	HandleProposal(ChannelProposal, *ProposalResponder)
}

A ProposalHandler decides how to handle incoming channel proposals from other channel network peers.

type ProposalHandlerFunc added in v0.3.0 

type ProposalHandlerFunc func(ChannelProposal, *ProposalResponder)

ProposalHandlerFunc is an adapter type to allow the use of functions as proposal handlers. ProposalHandlerFunc(f) is a ProposalHandler that calls f when HandleProposal is called.

func (ProposalHandlerFunc) HandleProposal added in v0.4.0 

func (f ProposalHandlerFunc) HandleProposal(p ChannelProposal, r *ProposalResponder)

HandleProposal calls the proposal handler function.

type ProposalID added in v0.4.1 

type ProposalID = [32]byte

ProposalID uniquely identifies the channel proposal as specified by the Channel Proposal Protocol (CPP).

type ProposalOpts added in v0.4.1 

type ProposalOpts map[string]interface{}

ProposalOpts contains optional configuration instructions for channel proposals and channel proposal acceptance messages. Per default, NoApp and NoData is set, and a random nonce share is generated.

func WithApp added in v0.4.1 

func WithApp(app channel.App, initData channel.Data) ProposalOpts

WithApp configures an app and initial data.

func WithFundingAgreement added in v0.5.2 

func WithFundingAgreement(alloc channel.Balances) ProposalOpts

WithFundingAgreement configures a fixed funding agreement.

func WithNonce added in v0.4.1 

func WithNonce(share NonceShare) ProposalOpts

WithNonce configures a fixed nonce share.

func WithNonceFrom added in v0.4.1 

func WithNonceFrom(r io.Reader) ProposalOpts

WithNonceFrom reads a nonce share from a reader (should be random stream).

func WithRandomNonce added in v0.4.1 

func WithRandomNonce() ProposalOpts

WithRandomNonce creates a nonce from crypto/rand.Reader.

func WithoutApp added in v0.4.1 

func WithoutApp() ProposalOpts

WithoutApp configures a NoApp and NoData.

func (ProposalOpts) App added in v0.4.1 

func (o ProposalOpts) App() channel.App

App returns the option's configured app.

func (ProposalOpts) AppData added in v0.4.1 

func (o ProposalOpts) AppData() channel.Data

AppData returns the option's configured app data.

func (ProposalOpts) SetsApp added in v0.4.1 

func (o ProposalOpts) SetsApp() bool

SetsApp returns whether an app and data have been explicitly set.

type ProposalResponder 

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

ProposalResponder lets the user respond to a channel proposal. If the user wants to accept the proposal, they should call Accept(), otherwise Reject(). Only a single function must be called and every further call causes a panic.

func (*ProposalResponder) Accept 

func (r *ProposalResponder) Accept(ctx context.Context, acc ChannelProposalAccept) (*Channel, error)

Accept lets the user signal that they want to accept the channel proposal. The ChannelProposalAcc message has to be created using ChannelProposal.Proposal().NewChannelProposalAcc on the proposal that was passed to the handler.

Accept returns the newly created channel controller if the channel was successfully created and funded. Panics if the proposal was already accepted or rejected.

After the channel controller got successfully set up, it is passed to the callback registered with Client.OnNewChannel. Accept returns after this callback has run.

It is important that the passed context does not cancel before the ChallengeDuration has passed. Otherwise funding may not complete.

If funding fails, ChannelFundingError is thrown and an unfunded channel object is returned, which can be used for withdrawing the funds.

After the channel got successfully created, the user is required to start the channel watcher with Channel.Watch() on the returned channel controller.

Returns ChannelFundingError if an error happened during funding. The internal error gives more information. - Contains FundingTimeoutError if any of the participants do not fund the channel in time. - Contains TxTimedoutError when the program times out waiting for a transaction to be mined. - Contains ChainNotReachableError if the connection to the blockchain network fails when sending a transaction to / reading from the blockchain.

func (*ProposalResponder) Reject 

func (r *ProposalResponder) Reject(ctx context.Context, reason string) error

Reject lets the user signal that they reject the channel proposal. Returns whether the rejection message was successfully sent. Panics if the proposal was already accepted or rejected.

func (*ProposalResponder) RemoveEgoisticChain added in v0.12.0 

func (r *ProposalResponder) RemoveEgoisticChain(egoistic multi.LedgerID)

RemoveEgoisticChain removes the egoistic chain flag for a given ledger.

func (*ProposalResponder) SetEgoisticChain added in v0.12.0 

func (r *ProposalResponder) SetEgoisticChain(egoistic multi.LedgerID)

SetEgoisticChain sets the egoistic chain flag for a given ledger.

type RequestTimedOutError added in v0.7.0 

type RequestTimedOutError string

RequestTimedOutError indicates that a peer has not responded within the expected time period.

func (RequestTimedOutError) Error added in v0.7.0 

func (e RequestTimedOutError) Error() string

Error implements error interface for RequestTimedOutError.

type SubChannelProposalAccMsg added in v0.9.0 

type SubChannelProposalAccMsg struct {
	BaseChannelProposalAcc
}

SubChannelProposalAccMsg is the accept message type corresponding to sub channel proposals.

func (*SubChannelProposalAccMsg) Base added in v0.9.0 

func (acc *SubChannelProposalAccMsg) Base() *BaseChannelProposalAcc

Base returns the common proposal accept values.

func (*SubChannelProposalAccMsg) Decode added in v0.9.0 

func (acc *SubChannelProposalAccMsg) Decode(r io.Reader) error

Decode decodes a SubChannelProposalAcc from an io.Reader.

func (SubChannelProposalAccMsg) Encode added in v0.9.0 

func (acc SubChannelProposalAccMsg) Encode(w io.Writer) error

Encode encodes the SubChannelProposalAcc into an io.Writer.

func (SubChannelProposalAccMsg) Type added in v0.9.0 

func (SubChannelProposalAccMsg) Type() wire.Type

Type returns wire.SubChannelProposalAcc.

type SubChannelProposalMsg added in v0.9.0 

type SubChannelProposalMsg struct {
	BaseChannelProposal
	Parent channel.ID
}

SubChannelProposalMsg is a channel proposal for subchannels.

func NewSubChannelProposal added in v0.5.0 

func NewSubChannelProposal(
	parent channel.ID,
	challengeDuration uint64,
	initBals *channel.Allocation,
	opts ...ProposalOpts,
) (prop *SubChannelProposalMsg, err error)

NewSubChannelProposal creates a subchannel proposal and applies the supplied options. For more information, see ProposalOpts.

func (SubChannelProposalMsg) Accept added in v0.9.0 

func (p SubChannelProposalMsg) Accept(
	nonceShare ProposalOpts,
) *SubChannelProposalAccMsg

Accept constructs an accept message that belongs to a proposal message. It should be used instead of manually constructing an accept message.

func (*SubChannelProposalMsg) Decode added in v0.9.0 

func (p *SubChannelProposalMsg) Decode(r io.Reader) error

Decode decodes a SubChannelProposal from an io.Reader.

func (SubChannelProposalMsg) Encode added in v0.9.0 

func (p SubChannelProposalMsg) Encode(w io.Writer) error

Encode encodes the SubChannelProposal into an io.Writer.

func (SubChannelProposalMsg) Matches added in v0.9.0 

func (SubChannelProposalMsg) Matches(acc ChannelProposalAccept) bool

Matches requires that the accept message is a sub channel proposal accept message.

func (SubChannelProposalMsg) Type added in v0.9.0 

func (SubChannelProposalMsg) Type() wire.Type

Type returns wire.SubChannelProposal.

type TestChannel added in v0.2.0 

type TestChannel struct {
	*Channel
}

TestChannel grants access to the `AdjudicatorRequest` which is otherwise hidden by `Channel`. Behaves like a `Channel` in all other cases.

Only used for testing.

func NewTestChannel added in v0.2.0 

func NewTestChannel(c *Channel) *TestChannel

NewTestChannel creates a new `TestChannel` from a `Channel`.

func (*TestChannel) AdjudicatorReq added in v0.2.0 

func (c *TestChannel) AdjudicatorReq() channel.AdjudicatorReq

AdjudicatorReq returns the `AdjudicatorReq` of the underlying machine.

func (*TestChannel) Register added in v0.8.0 

func (c *TestChannel) Register(ctx context.Context) error

Register exposes dispute registration.

type TransparentChannel added in v0.11.0 

type TransparentChannel struct {
	*Channel
}

TransparentChannel grants access to the `SignedState` of the underlying channel, which is otherwise hidden by `Channel`. Behaves like a normal channel in all other cases.

func NewTransparentChannel added in v0.11.0 

func NewTransparentChannel(c *Channel) *TransparentChannel

NewTransparentChannel returns a new `TransparentChannel` from a `Channel`.

func (*TransparentChannel) SignedState added in v0.11.0 

func (c *TransparentChannel) SignedState() channel.SignedState

SignedState returns the current signed state of the channel.

type TxTimedoutError added in v0.7.0 

type TxTimedoutError struct {
	TxType string // Type of the transaction.
	TxID   string // Transaction ID to track it on the blockchain.
}

TxTimedoutError indicates that we have timed out waiting for a transaction to be mined.

It can happen that this transaction can be eventually mined. So the user should of the framework should be watching for the transaction to be mined and decide on what to do.

func (TxTimedoutError) Error added in v0.7.0 

func (e TxTimedoutError) Error() string

Error implements the error interface.

type UpdateHandler 

type UpdateHandler interface {
	// HandleUpdate is the user callback called by the channel controller on an
	// incoming update request. The first argument contains the current state
	// of the channel before the update is applied. Clone it if you want to
	// modify it.
	HandleUpdate(*channel.State, ChannelUpdate, *UpdateResponder)
}

An UpdateHandler decides how to handle incoming channel update requests from other channel participants.

type UpdateHandlerFunc added in v0.3.0 

type UpdateHandlerFunc func(*channel.State, ChannelUpdate, *UpdateResponder)

UpdateHandlerFunc is an adapter type to allow the use of functions as update handlers. UpdateHandlerFunc(f) is an UpdateHandler that calls f when HandleUpdate is called.

func (UpdateHandlerFunc) HandleUpdate added in v0.4.0 

func (f UpdateHandlerFunc) HandleUpdate(s *channel.State, u ChannelUpdate, r *UpdateResponder)

HandleUpdate calls the update handler function.

type UpdateResponder 

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

The UpdateResponder allows the user to react to the incoming channel update request. If the user wants to accept the update, Accept() should be called, otherwise Reject(), possibly giving a reason for the rejection. Only a single function must be called and every further call causes a panic.

func (*UpdateResponder) Accept 

func (r *UpdateResponder) Accept(ctx context.Context) error

Accept accepts the channel update.

func (*UpdateResponder) Reject 

func (r *UpdateResponder) Reject(ctx context.Context, reason string) error

Reject rejects the channel update.

type VirtualChannelFundingProposalMsg added in v0.9.0 

type VirtualChannelFundingProposalMsg struct {
	ChannelUpdateMsg
	Initial  channel.SignedState
	IndexMap []channel.Index
}

VirtualChannelFundingProposalMsg is a channel update that proposes the funding of a virtual channel.

func (*VirtualChannelFundingProposalMsg) Decode added in v0.9.0 

func (m *VirtualChannelFundingProposalMsg) Decode(r io.Reader) (err error)

Decode decodes the VirtualChannelFundingProposalMsg from the io.Reader.

func (VirtualChannelFundingProposalMsg) Encode added in v0.9.0 

func (m VirtualChannelFundingProposalMsg) Encode(w io.Writer) (err error)

Encode encodes the VirtualChannelFundingProposalMsg into the io.Writer.

func (*VirtualChannelFundingProposalMsg) Type added in v0.9.0 

func (*VirtualChannelFundingProposalMsg) Type() wire.Type

Type returns the message type.

type VirtualChannelProposalAccMsg added in v0.9.0 

type VirtualChannelProposalAccMsg struct {
	BaseChannelProposalAcc
	Responder wallet.Address // Responder's participant address.
}

VirtualChannelProposalAccMsg is the accept message type corresponding to virtual channel proposals.

func (*VirtualChannelProposalAccMsg) Base added in v0.9.0 

func (acc *VirtualChannelProposalAccMsg) Base() *BaseChannelProposalAcc

Base returns the common proposal accept values.

func (*VirtualChannelProposalAccMsg) Decode added in v0.9.0 

func (acc *VirtualChannelProposalAccMsg) Decode(r io.Reader) error

Decode decodes a message from an io.Reader.

func (VirtualChannelProposalAccMsg) Encode added in v0.9.0 

func (acc VirtualChannelProposalAccMsg) Encode(w io.Writer) error

Encode encodes the message into an io.Writer.

func (VirtualChannelProposalAccMsg) Type added in v0.9.0 

func (VirtualChannelProposalAccMsg) Type() wire.Type

Type returns the message type.

type VirtualChannelProposalMsg added in v0.9.0 

type VirtualChannelProposalMsg struct {
	BaseChannelProposal
	Proposer  wallet.Address    // Proposer's address in the channel.
	Peers     []wire.Address    // Participants' wire addresses.
	Parents   []channel.ID      // Parent channels for each participant.
	IndexMaps [][]channel.Index // Index mapping for each participant in relation to the root channel.
}

VirtualChannelProposalMsg is a channel proposal for virtual channels.

func NewVirtualChannelProposal added in v0.7.0 

func NewVirtualChannelProposal(
	challengeDuration uint64,
	participant wallet.Address,
	initBals *channel.Allocation,
	peers []wire.Address,
	parents []channel.ID,
	indexMaps [][]channel.Index,
	opts ...ProposalOpts,
) (prop *VirtualChannelProposalMsg, err error)

NewVirtualChannelProposal creates a virtual channel proposal.

func (VirtualChannelProposalMsg) Accept added in v0.9.0 

func (p VirtualChannelProposalMsg) Accept(
	responder wallet.Address,
	opts ...ProposalOpts,
) *VirtualChannelProposalAccMsg

Accept constructs an accept message that belongs to a proposal message.

func (*VirtualChannelProposalMsg) Decode added in v0.9.0 

func (p *VirtualChannelProposalMsg) Decode(r io.Reader) error

Decode decodes a proposal from an io.Reader.

func (VirtualChannelProposalMsg) Encode added in v0.9.0 

func (p VirtualChannelProposalMsg) Encode(w io.Writer) error

Encode encodes the proposal into an io.Writer.

func (VirtualChannelProposalMsg) Matches added in v0.9.0 

func (VirtualChannelProposalMsg) Matches(acc ChannelProposalAccept) bool

Matches requires that the accept message has the correct type.

func (VirtualChannelProposalMsg) Type added in v0.9.0 

func (VirtualChannelProposalMsg) Type() wire.Type

Type returns the message type.

type VirtualChannelSettlementProposalMsg added in v0.9.0 

type VirtualChannelSettlementProposalMsg struct {
	ChannelUpdateMsg
	Final channel.SignedState
}

VirtualChannelSettlementProposalMsg is a channel update that proposes the settlement of a virtual channel.

func (*VirtualChannelSettlementProposalMsg) Decode added in v0.9.0 

func (m *VirtualChannelSettlementProposalMsg) Decode(r io.Reader) (err error)

Decode decodes the VirtualChannelSettlementProposalMsg from the io.Reader.

func (VirtualChannelSettlementProposalMsg) Encode added in v0.9.0 

func (m VirtualChannelSettlementProposalMsg) Encode(w io.Writer) (err error)

Encode encodes the VirtualChannelSettlementProposalMsg into the io.Writer.

func (*VirtualChannelSettlementProposalMsg) Type added in v0.9.0 

func (*VirtualChannelSettlementProposalMsg) Type() wire.Type

Type returns the message type.

Source Files

View all Source files

Directories

Path Synopsis
Package test contains testing setup types and functions for package client.
 Package test contains testing setup types and functions for package client.

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.