perun

type APIError ¶

type APIError string

APIError represents the errors that will be communicated via the user API.

func (e APIError) Error() string

type App ¶

type App struct {
	Def  pchannel.App
	Data pchannel.Data
}

App represents the app definition and the corresponding app data for a channel.

type BalInfo ¶

type BalInfo struct {
	Currency string   // Currency interpreter used to interpret the amounts in the balance.
	Parts    []string // List of aliases of channel participants.
	Bal      []string // Amounts held by each participant in this channel for the given currency.
}

BalInfo represents the Balance information of the channel participants. A valid BalInfo should meet the following conditions (will be validated before using the struct):

1. Lengths of Parts list and Balance list are equal.
2. All entries in Parts list are unique.
3. Parts list has an entry "self", that represents the user of the session.
4. No amount in Balance must be negative.

type ChAPI ¶ added in v0.4.0

type ChAPI interface {
	// Methods for reading the channel information is doesn't change.
	// These APIs don't use mutex lock.
	ID() string
	Currency() string
	Parts() []string
	ChallengeDurSecs() uint64

	// Methods to trasact on, close the channel and read its state.
	// These APIs use a mutex lock.
	SendChUpdate(context.Context, StateUpdater) (ChInfo, error)
	SubChUpdates(ChUpdateNotifier) error
	UnsubChUpdates() error
	RespondChUpdate(context.Context, string, bool) (ChInfo, error)
	GetChInfo() ChInfo
	Close(context.Context) (ChInfo, error)
}

ChAPI represents the APIs that can be accessed in the context of a perun channel. First a channel has to be initialized using the SessionAPI. The channel can then be used send and receive updates.

type ChClient ¶ added in v0.4.0

type ChClient interface {
	Registerer
	ProposeChannel(context.Context, pclient.ChannelProposal) (Channel, error)
	Handle(pclient.ProposalHandler, pclient.UpdateHandler)
	Channel(pchannel.ID) (Channel, error)
	Close() error

	EnablePersistence(ppersistence.PersistRestorer)
	OnNewChannel(handler func(Channel))
	Restore(context.Context) error
	RestoreChs(func(Channel)) error

	Log() pLog.Logger
}

ChClient allows the user to establish off-chain channels and transact on these channels.

It allows the user to enable persistence, where all data pertaining to the lifecycle of a channel is persisted continuously. When it is enabled, the channel client can be stopped at any point of time and resumed later.

However, the channel client is not responsible if any channel the user was participating in was closed with a wrong state when the channel client was not running. Hence it is highly recommended not to stop the channel client if there are open channels.

type ChInfo ¶ added in v0.4.0

type ChInfo struct {
	ChID string
	// Represents the amount held by each participant in the channel.
	BalInfo BalInfo
	// App used in the channel.
	App App
	// Current Version Number for the channel. This will be zero when a channel is opened and will be incremented
	// during each update. When registering the state on-chain, if different participants register states with
	// different versions, channel will be settled according to the state with highest version number.
	Version string
}

ChInfo represents the info regarding a channel that will be sent to the user.

type ChProposalNotif ¶

type ChProposalNotif struct {
	ProposalID       string
	OpeningBalInfo   BalInfo
	App              App
	ChallengeDurSecs uint64
	Expiry           int64
}

ChProposalNotif represents the parameters sent in a channel proposal notifications.

type ChProposalNotifier ¶

type ChProposalNotifier func(ChProposalNotif)

ChProposalNotifier is the notifier function that is used for sending channel proposal notifications.

type ChUpdateNotif ¶

type ChUpdateNotif struct {
	// UpdateID denotes the unique ID for this update. It is derived from the channel ID and version number.
	UpdateID       string
	CurrChInfo     ChInfo
	ProposedChInfo ChInfo

	Type ChUpdateType

	// It is with reference to the system clock on the computer running the perun-node.
	// Time (in unix timestamp) before which response to this notification should be sent.
	//
	// It is 0, when no response is expected.
	Expiry int64

	// Error represents any error encountered while processing incoming updates or
	// while a channel is closed by the watcher..
	// When this is non empty, expiry will also be zero and no response is expected
	Error string
}

ChUpdateNotif represents the parameters sent in a channel update notification. The update can be of two types 1. Regular update proposed by the peer to progress the offchain state of the channel. 2. Closing update when a channel is closed, balance is settled on the blockchain and the amount corresponding to this user is withdrawn.

The two types of updates can be differentiated using the status field, which is "open" or "final" for a regular update and "closed" for a closing update.

type ChUpdateNotifier ¶

type ChUpdateNotifier func(ChUpdateNotif)

ChUpdateNotifier is the notifier function that is used for sending channel update notifications.

type ChUpdateType ¶ added in v0.4.0

type ChUpdateType uint8

ChUpdateType is the type of channel update. It can have three values: "open", "final" and "closed".

const (
	ChUpdateTypeOpen ChUpdateType = iota
	ChUpdateTypeFinal
	ChUpdateTypeClosed
)

type ChainBackend ¶

type ChainBackend interface {
	DeployAdjudicator(onChainAddr pwallet.Address) (adjAddr pwallet.Address, _ error)
	DeployAsset(adjAddr, onChainAddr pwallet.Address) (assetAddr pwallet.Address, _ error)
	ValidateContracts(adjAddr, assetAddr pwallet.Address) error
	NewFunder(assetAddr, onChainAddr pwallet.Address) pchannel.Funder
	NewAdjudicator(adjAddr, receiverAddr pwallet.Address) pchannel.Adjudicator
}

ChainBackend wraps the methods required for instantiating and using components for making on-chain transactions and reading on-chain values on a specific blockchain platform. The timeout for on-chain transaction should be implemented by the corresponding backend. It is up to the implementation to make the value user configurable.

It defines methods for deploying contracts; validating deployed contracts and instantiating a funder, adjudicator.

type Channel ¶ added in v0.5.0

type Channel interface {
	Close() error
	ID() pchannel.ID
	Idx() pchannel.Index
	IsClosed() bool
	Params() *pchannel.Params
	Peers() []pwire.Address
	Phase() pchannel.Phase
	State() *pchannel.State
	OnUpdate(cb func(from, to *pchannel.State))
	UpdateBy(ctx context.Context, update func(*pchannel.State)) error
	Settle(ctx context.Context) error
	SettleSecondary(ctx context.Context) error
	Watch() error
}

Channel represents state channel established among the participants of the off-chain network.

type CommBackend ¶

type CommBackend interface {
	// Returns a listener that can listen for incoming messages at the specified address.
	NewListener(address string) (pnet.Listener, error)

	// Returns a dialer that can dial for new outgoing connections.
	// If timeout is zero, program will use no timeout, but standard OS timeouts may still apply.
	NewDialer() Dialer
}

CommBackend defines the set of methods required for initializing components required for off-chain communication. This can be protocols such as tcp, websockets, MQTT.

type Credential ¶

type Credential struct {
	Addr     pwallet.Address
	Wallet   pwallet.Wallet
	Keystore string
	Password string
}

Credential represents the parameters required to access the keys and make signatures for a given address.

type Currency ¶

type Currency interface {
	Parse(string) (*big.Int, error)
	Print(*big.Int) string
}

Currency represents a parser that can convert between string representation of a currency and its equivalent value in base unit represented as a big integer.

type Dialer ¶

type Dialer interface {
	pnet.Dialer
	Registerer
}

Dialer extends net.Dialer with Registerer interface.

type IDProvider ¶ added in v0.5.0

type IDProvider interface {
	IDReader
	Write(alias string, p PeerID) error
	Delete(alias string) error
	UpdateStorage() error
}

IDProvider represents the functions to read, write peer IDs from and to the local cache connected to a peer ID provider. It also includes a function to sync the changes in the cache with the ID provider backend.

type IDReader ¶ added in v0.5.0

type IDReader interface {
	ReadByAlias(alias string) (p PeerID, contains bool)
	ReadByOffChainAddr(offChainAddr pwire.Address) (p PeerID, contains bool)
}

IDReader represents the functions to read peer IDs from a cache connected to a peer ID provider.

type NodeAPI ¶

type NodeAPI interface {
	Time() int64
	GetConfig() NodeConfig
	Help() []string
	OpenSession(configFile string) (string, []ChInfo, error)

	// This function is used internally to get a SessionAPI instance.
	// Should not be exposed via user API.
	GetSession(string) (SessionAPI, error)
}

NodeAPI represents the APIs that can be accessed in the context of a perun node. Multiple sessions can be opened in a single node. Each instance will have a dedicated keystore and ID provider.

type NodeConfig ¶

type NodeConfig struct {
	// User configurable values.
	LogLevel         string        // LogLevel represents the log level for the node and all derived loggers.
	LogFile          string        // LogFile represents the file to write logs. Empty string represents stdout.
	ChainURL         string        // Address of the default blockchain node used by the perun node.
	Adjudicator      string        // Address of the default Adjudicator contract used by the perun node.
	Asset            string        // Address of the default Asset Holder contract used by the perun node.
	ChainConnTimeout time.Duration // Timeout for connecting to blockchain node.
	OnChainTxTimeout time.Duration // Timeout to wait for confirmation of on-chain tx.
	ResponseTimeout  time.Duration // Timeout to wait for a response from the peer / user.

	// Hard coded values. See cmd/perunnode/run.go.
	CommTypes            []string // Communication protocols supported by the node for off-chain communication.
	IDProviderTypes      []string // ID Provider types supported by the node.
	CurrencyInterpreters []string // Currencies Interpreters supported by the node.

}

NodeConfig represents the configurable parameters of a perun node.

type PeerID ¶ added in v0.5.0

type PeerID struct {
	// Name assigned by user for referring to this PeerID in API requests to the node.
	// It is unique within a session on the node.
	Alias string `yaml:"alias"`

	// Permanent identity used for authenticating the PeerID in the off-chain network.
	OffChainAddr pwire.Address `yaml:"-"`
	// This field holds the string value of address for easy marshaling / unmarshaling.
	OffChainAddrString string `yaml:"offchain_address"`

	// Address for off-chain communication.
	CommAddr string `yaml:"comm_address"`
	// Type of off-chain communication protocol.
	CommType string `yaml:"comm_type"`
}

PeerID represents any participant in the off-chain network that the user wants to transact with.

type Registerer ¶

type Registerer interface {
	Register(offChainAddr pwire.Address, commAddr string)
}

Registerer is used to register the commAddr corresponding to an offChainAddr to the wire.Bus in runtime.

type Session ¶

type Session struct {
	ID   string // ID uniquely identifies a session instance.
	User User

	ChClient ChClient
}

Session provides a context for the user to interact with a node. It manages user data (such as keys, peer IDs), and channel client.

Once established, a user can establish and transact on state channels. All the channels within a session will use the same type and version of communication and state channel protocol. If a user desires to use multiple types or versions of any protocol, it should request a separate session for each combination of type and version of those.

type SessionAPI ¶

type SessionAPI interface {
	ID() string
	AddPeerID(PeerID) error
	GetPeerID(alias string) (PeerID, error)
	OpenCh(context.Context, BalInfo, App, uint64) (ChInfo, error)
	GetChsInfo() []ChInfo
	SubChProposals(ChProposalNotifier) error
	UnsubChProposals() error
	RespondChProposal(context.Context, string, bool) (ChInfo, error)
	Close(force bool) ([]ChInfo, error)

	// This function is used internally to get a ChAPI instance.
	// Should not be exposed via user API.
	GetCh(string) (ChAPI, error)
}

SessionAPI represents the APIs that can be accessed in the context of a perun node. First a session has to be instantiated using the NodeAPI. The session can then be used open channels and accept channel proposals.

type StateUpdater ¶

type StateUpdater func(*pchannel.State)

StateUpdater function is the function that will be used for applying state updates.

type User ¶

type User struct {
	PeerID

	OnChain  Credential // Account for funding the channel and the on-chain transactions.
	OffChain Credential // Account (corresponding to off-chain address) used for signing authentication messages.

	// List of participant addresses for this user in each open channel.
	// OffChain credential is used for managing all these accounts.
	PartAddrs []pwallet.Address
}

User represents a participant in the off-chain network that uses a session on this node for sending transactions.

type WalletBackend ¶

type WalletBackend interface {
	ParseAddr(string) (pwallet.Address, error)
	NewWallet(keystore string, password string) (pwallet.Wallet, error)
	UnlockAccount(pwallet.Wallet, pwallet.Address) (pwallet.Account, error)
}

WalletBackend wraps the methods for instantiating wallets and accounts that are specific to a blockchain platform.

type WireBus ¶

type WireBus interface {
	pwire.Bus
	Close() error
}

WireBus is an extension of the wire.Bus interface in go-perun to include a "Close" method. pwire.Bus (in go-perun) is a central message bus over which all clients of a channel network communicate. It is used as the transport layer abstraction for the ChClient.