perun

type APIError ¶

type APIError interface {
	Category() ErrorCategory
	Code() ErrorCode
	Message() string
	AddInfo() interface{}
	Error() string
}

APIError represents the newer version of error returned by node, session and channel APIs.

Along with the error message, this error type assigns to each error an error category that describes how the error should be handled, an error code that identifies specific types of error and additional info that contains data related to the error as key value pairs.

func NewAPIErr(category ErrorCategory, code ErrorCode, err error, addInfo interface{}) APIError

func NewAPIErrChainNotReachable(err error, chainURL string) APIError

func NewAPIErrFailedPreCondition(err error) APIError

func NewAPIErrFailedPreConditionUnclosedChs(err error, chs []ChInfo) APIError

func NewAPIErrInvalidArgument(err error, name ArgumentName, value string) APIError

func NewAPIErrInvalidConfig(err error, name, value string) APIError

func NewAPIErrInvalidContracts(contractErrInfos ...ContractErrInfo) APIError

func NewAPIErrPeerNotFunded(err error, peerAlias string) APIError

func NewAPIErrPeerRejected(err error, peerAlias, reason string) APIError

func NewAPIErrPeerRequestTimedOut(err error, peerAlias, timeout string) APIError

func NewAPIErrResourceExists(resourceType ResourceType, resourceID string) APIError

func NewAPIErrResourceNotFound(resourceType ResourceType, resourceID string) APIError

func NewAPIErrTxTimedOut(err error, txType, txID, txTimeout string) APIError

func NewAPIErrUnknownInternal(err error) APIError

func NewAPIErrUserResponseTimedOut(expiry, receivedAt int64) APIError

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 ArgumentName ¶ added in v0.6.0

type ArgumentName string

ArgumentName type is used enumerate valid argument names for use InvalidArgument error.

The enumeration of valid constants should be defined in the package using the error constructors.

type BalInfo ¶

type BalInfo struct {
	Currencies []string   // List of currencies for the specifying amounts in the balance.
	Parts      []string   // List of aliases of channel participants.
	Bals       [][]string // Amounts held by each participant in this channel for the each currency.
}

BalInfo represents the Balance information of the channel participants. Bal[0] represents the balance of the channel for asset Currency[0] for the all the channel participants as mentioned in Parts; Bal[1] specifies for asset Currency[1] and so on.

A valid BalInfo should meet the following conditions (will be validated before using the struct):

1. Length of Currencies and outer length of Bal are equal.
1. Lengths of Parts and inner length of Bal are equal.
2. All entries in Parts list are unique 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(symbol string) (int, Currency, bool)
	Parts() []string
	ChallengeDurSecs() uint64

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

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 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 APIError
}

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 off-chain 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 {
	ROChainBackend

	DeployAdjudicator(txSender pwallet.Address) (pwallet.Address, error)
	DeployAssetETH(adjudicator, txSender pwallet.Address) (pwallet.Address, error)
	DeployAssetERC20(adjudicator, tokenERC20, txSender pwallet.Address) (pwallet.Address, error)
	DeployPerunToken(initAccs []pwallet.Address, initBal *big.Int, txSender pwallet.Address) (pwallet.Address, error)

	NewFunder(assetETH, txSender pwallet.Address) Funder
	NewAdjudicator(adjudicator, txSender pwallet.Address) pchannel.Adjudicator
}

ChainBackend wraps the methods required for deploy contracts, validating them and instantiating funde, adjudicator instances.

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.

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 ContractErrInfo ¶ added in v0.6.0

type ContractErrInfo struct {
	Name    string
	Address string
	Error   string
}

ContractErrInfo is used to pass the contract information (name, address, error message) encountered when validating a contract.

type ContractRegistry ¶ added in v0.6.0

type ContractRegistry interface {
	ROContractRegistry
	RegisterAssetERC20(token, asset pwallet.Address) (symbol string, maxDecimals uint8, _ error)
}

ContractRegistry provides an interface to register and retrieve adjudicator and asset contracts.

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
	Symbol() 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 CurrencyRegistry ¶ added in v0.6.0

type CurrencyRegistry interface {
	ROCurrencyRegistry
	Register(symbol string, maxDecimals uint8) (Currency, error)
}

CurrencyRegistry provides an interface to register and retrieve currency parsers.

type Dialer ¶

type Dialer interface {
	pnet.Dialer
	Registerer
}

Dialer extends net.Dialer with Registerer interface.

type ErrInfoChainNotReachable ¶ added in v0.6.0

type ErrInfoChainNotReachable struct {
	ChainURL string
}

ErrInfoChainNotReachable represents the fields in the additional info for ErrChainNotReachable.

type ErrInfoFailedPreCondUnclosedChs ¶ added in v0.6.0

type ErrInfoFailedPreCondUnclosedChs struct {
	ChInfos []ChInfo
}

ErrInfoFailedPreCondUnclosedChs represents the fields in the additional info for the ErrFailedPreCondition when session closed is called without force option and the session has unclosed channels.

This additional info should not be used in any other context.

type ErrInfoInvalidArgument ¶ added in v0.6.0

type ErrInfoInvalidArgument struct {
	Name        string
	Value       string
	Requirement string
}

ErrInfoInvalidArgument represents the fields in the additional info for ErrInvalidArgument.

type ErrInfoInvalidConfig ¶ added in v0.6.0

type ErrInfoInvalidConfig struct {
	Name  string
	Value string
}

ErrInfoInvalidConfig represents the fields in the additional info for ErrInfoInvalidConfig.

type ErrInfoInvalidContracts ¶ added in v0.6.0

type ErrInfoInvalidContracts struct {
	ContractErrInfos []ContractErrInfo
}

ErrInfoInvalidContracts represents the fields in the additional info for ErrInvalidContracts.

type ErrInfoPeerNotFunded ¶ added in v0.6.0

type ErrInfoPeerNotFunded struct {
	PeerAlias string
}

ErrInfoPeerNotFunded represents the fields in the additional info for ErrPeerNotFunded.

type ErrInfoPeerRejected ¶ added in v0.6.0

type ErrInfoPeerRejected struct {
	PeerAlias string
	Reason    string
}

ErrInfoPeerRejected represents the fields in the additional info for ErrRejectedByPeer.

type ErrInfoPeerRequestTimedOut ¶ added in v0.6.0

type ErrInfoPeerRequestTimedOut struct {
	PeerAlias string
	Timeout   string
}

ErrInfoPeerRequestTimedOut represents the fields in the additional info for ErrPeerRequestTimedOut.

type ErrInfoResourceExists ¶ added in v0.6.0

type ErrInfoResourceExists struct {
	Type string
	ID   string
}

ErrInfoResourceExists represents the fields in the additional info for ErrResourceExists.

type ErrInfoResourceNotFound ¶ added in v0.6.0

type ErrInfoResourceNotFound struct {
	Type string
	ID   string
}

ErrInfoResourceNotFound represents the fields in the additional info for ErrResourceNotFound.

type ErrInfoTxTimedOut ¶ added in v0.6.0

type ErrInfoTxTimedOut struct {
	TxType    string
	TxID      string
	TxTimeout string
}

ErrInfoTxTimedOut represents the fields in the additional info for ErrTxTimedOut.

type ErrInfoUserResponseTimedOut ¶ added in v0.6.0

type ErrInfoUserResponseTimedOut struct {
	Expiry     int64
	ReceivedAt int64
}

ErrInfoUserResponseTimedOut represents the fields in the additional info for ErrUserResponseTimedOut.

type ErrorCategory ¶ added in v0.6.0

type ErrorCategory int

ErrorCategory represents the category of the error, which describes how the error should be handled by the client.

const (
	// ParticipantError is caused by one of the channel participants not acting
	// as per the perun protocol.
	//
	// To resolve this, the client should negotiate with the peer outside of
	// this system to act in accordance with the perun protocol.
	ParticipantError ErrorCategory = iota

	// ClientError is caused by the errors in the request from the client. It
	// could be errors in arguments or errors in configuration provided by the
	// client to access the external systems or errors in the state of external
	// systems not managed by the node.
	//
	// To resolve this, the client should provide valid arguments, provide
	// correct configuration to access the external systems or fix the external
	// systems; and then retry.
	ClientError

	// ProtocolFatalError is caused when the protocol aborts due to unexpected
	// failure in external system during execution. It could also result in loss
	// of funds.
	//
	// To resolve this, user should manually inspect the error message and
	// handle it.
	ProtocolFatalError
	// InternalError is caused due to unintended behavior in the node software.
	//
	// To resolve this, user should manually inspect the error message and
	// handle it.
	InternalError
)

func (c ErrorCategory) String() string

type ErrorCode ¶ added in v0.6.0

type ErrorCode int

ErrorCode is a numeric code assigned to identify the specific type of error. The keys in the additional field is fixed for each error code.

const (
	ErrPeerRequestTimedOut  ErrorCode = 101
	ErrPeerRejected         ErrorCode = 102
	ErrPeerNotFunded        ErrorCode = 103
	ErrUserResponseTimedOut ErrorCode = 104
	ErrResourceNotFound     ErrorCode = 201
	ErrResourceExists       ErrorCode = 202
	ErrInvalidArgument      ErrorCode = 203
	ErrFailedPreCondition   ErrorCode = 204
	ErrInvalidConfig        ErrorCode = 205
	ErrInvalidContracts     ErrorCode = 206
	ErrTxTimedOut           ErrorCode = 301
	ErrChainNotReachable    ErrorCode = 302
	ErrUnknownInternal      ErrorCode = 401
)

type Funder ¶ added in v0.6.0

type Funder interface {
	pchannel.Funder
	RegisterAssetERC20(asset, token, acc pwallet.Address) bool
	IsAssetRegistered(asset pwallet.Address) bool
}

Funder wraps the methods required on ETH funder.

ETH funder implements helper methods for registering assets and checking if assets are registered. But these methods use types that are defined in ethereum backend packages.

This wrapper wraps those types with only those types defined in go-perun core abstraction.

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, APIError)

	RegisterCurrency(tokenAddr, assetAddr string) (symbol string, _ APIError)

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

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            // URL of the blockchain node.
	ChainID          int               // See session.chainconfig.
	Adjudicator      string            // Address of the Adjudicator contract.
	AssetETH         string            // Address of the ETH Asset holder contract.
	AssetERC20s      map[string]string // Address of ERC20 token contracts and corresponding asset contracts.
	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 ROChainBackend ¶ added in v0.6.0

type ROChainBackend interface {
	ValidateAdjudicator(adjudicator pwallet.Address) error
	ValidateAssetETH(adjudicator, assetETH pwallet.Address) error
	ValidateAssetERC20(adjudicator, tokenERC20, assetERC20 pwallet.Address) (symbol string, maxDecimals uint8, _ error)
	ERC20Info(token pwallet.Address) (symbol string, decimal uint8, _ error)
}

ROChainBackend wraps the methods required for validating contracts.

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.

type ROContractRegistry ¶ added in v0.6.0

type ROContractRegistry interface {
	Adjudicator() pwallet.Address
	AssetETH() pwallet.Address
	Asset(symbol string) (asset pwallet.Address, found bool)
	Token(symbol string) (token pwallet.Address, found bool)
	Symbol(asset pwallet.Address) (symbol string, found bool)
	Assets() map[string]string
}

ROContractRegistry provides an interface to retrieve contracts.

type ROCurrencyRegistry ¶ added in v0.6.0

type ROCurrencyRegistry interface {
	IsRegistered(symbol string) bool
	Currency(symbol string) Currency
	Symbols() []string
}

ROCurrencyRegistry provides an interface to retrieve currency parsers.

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 ResourceType ¶ added in v0.6.0

type ResourceType string

ResourceType is used to enumerate valid resource types in ResourceNotFound and ResourceExists errors.

The enumeration of valid constants should be defined in the package using the error constructors.

type SessionAPI ¶

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

	DeployAssetERC20(tokenERC20 string) (asset string, _ APIError)

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

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) error

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

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.