protocols

README

Off-chain protocols

This package defines the off-chain protocols for managing channels. These protocols are abstract rules which nodes should follow in order to reach a desired goal.

To implement the protocols, we make use of an abstraction we call the Objective. Objectives are named for the goal which the off-chain protocol aspires to achieve.

The following table shows some example objectives and their implemetation status:

Objective type	Implemented
direct-fund	x
direct-defund	x
virtual-fund	x
virtual-defund	x
challenge

The set of objectives comprises the functional core of a go-nitro node. They expose only pure functions -- but otherwise take on as much responsibility as possible, leaving only a small amount of responsibility to an imperative shell.

Each Objective type is implemented by a Go struct implementing the Objective interface. Each instance of an Objective type will hold its own data.

The imperative shell will typically be responsible for:

• spawning new objective instances of one type or another
• reading and persisting objectives to and from a store.
• listening to peers and the blockchain for events relevant to the objective
• "updating" objectives by passing events to their Update(event) function (an updated copy is returned)
• "cranking" objectives by calling Crank() (side effects are returned)
• executing side effects

Documentation

Overview

Package protocols defines the off-chain protocols for managing channels. It is the functional core of a go-nitro node.

Index

• Variables
• type AdjudicationStatus
• type ChainTransaction
• type ChainTransactionBase
  • func (cct ChainTransactionBase) ChannelId() types.Destination
• type ChallengeTransaction
  • func NewChallengeTransaction(channelId types.Destination, candidate state.SignedState, ...) ChallengeTransaction
• type DepositTransaction
  • func NewDepositTransaction(channelId types.Destination, deposit types.Funds) DepositTransaction
• type Message
  • func CreateObjectivePayloadMessage(id ObjectiveId, p interface{}, payloadType PayloadType, ...) ([]Message, error)
  • func CreateRejectionNoticeMessage(oId ObjectiveId, recipients ...types.Address) []Message
  • func CreateSignedProposalMessage(recipient types.Address, proposals ...consensus_channel.SignedProposal) Message
  • func CreateVoucherMessage(voucher payments.Voucher, recipients ...types.Address) []Message
  • func DeserializeMessage(s string) (Message, error)
  • func (m Message) Serialize() (string, error)
  • func (m Message) Summarize() MessageSummary
• type MessageSummary
• type Objective
• type ObjectiveId
  • func GetProposalObjectiveId(p consensus_channel.Proposal) (ObjectiveId, error)
• type ObjectivePayload
  • func CreateObjectivePayload(id ObjectiveId, payloadType PayloadType, p interface{}) (ObjectivePayload, error)
• type ObjectivePayloadSummary
• type ObjectiveRequest
• type ObjectiveStatus
• type PayloadType
• type PaymentSummary
• type ProposalReceiver
• type ProposalSummary
• type SideEffects
  • func (se *SideEffects) Merge(other SideEffects)
• type Storable
• type Summary
• type WaitingFor
• type WithdrawAllTransaction
  • func NewWithdrawAllTransaction(channelId types.Destination, signedState state.SignedState) WithdrawAllTransaction

Variables

var ErrNotApproved = errors.New("objective not approved")

Types

type AdjudicationStatus

type AdjudicationStatus struct {
	TurnNumRecord uint
}

AdjudicationStatus mirrors the on chain adjudication status of a particular channel. Everything that is stored on chain, other than holdings.

type ChainTransaction

type ChainTransaction interface {
	ChannelId() types.Destination
}

ChainTransaction defines the interface that every transaction must implement

type ChainTransactionBase

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

ChainTransactionBase is a convenience struct that is embedded in other transaction structs. It is exported only to allow cmp.Diff to compare transactions

func (ChainTransactionBase) ChannelId

func (cct ChainTransactionBase) ChannelId() types.Destination

type ChallengeTransaction

type ChallengeTransaction struct {
	ChainTransaction
	Candidate     state.SignedState
	Proof         []state.SignedState
	ChallengerSig crypto.Signature
}

func NewChallengeTransaction

func NewChallengeTransaction(
	channelId types.Destination,
	candidate state.SignedState,
	proof []state.SignedState,
	challengerSig crypto.Signature,
) ChallengeTransaction

type DepositTransaction

type DepositTransaction struct {
	ChainTransaction
	Deposit types.Funds
}

func NewDepositTransaction

func NewDepositTransaction(channelId types.Destination, deposit types.Funds) DepositTransaction

type Message

type Message struct {
	To   types.Address
	From types.Address
	// ObjectivePayloads contains a collection of payloads for various objectives.
	// Protocols are responsible for parsing the payload.
	ObjectivePayloads []ObjectivePayload
	// LedgerProposals contains a collection of signed proposals.
	// Since proposals need to be handled in order they need to be an explicit part of the message format.
	LedgerProposals []consensus_channel.SignedProposal
	// Payments contains a collection of signed vouchers representing payments.
	// Payments are handled outside of any objective.
	Payments []payments.Voucher
	// RejectedObjectives is a collection of objectives that have been rejected.
	RejectedObjectives []ObjectiveId
}

Message is an object to be sent across the wire.

func CreateObjectivePayloadMessage

func CreateObjectivePayloadMessage(id ObjectiveId, p interface{}, payloadType PayloadType, recipients ...types.Address) ([]Message, error)

CreateObjectivePayloadMessage returns a message for each recipient tht contains an objective payload.

func CreateRejectionNoticeMessage

func CreateRejectionNoticeMessage(oId ObjectiveId, recipients ...types.Address) []Message

CreateSignedProposalMessage returns a signed proposal message addressed to the counterparty in the given ledger It contains the provided signed proposals and any proposals in the proposal queue.

func CreateSignedProposalMessage

func CreateSignedProposalMessage(recipient types.Address, proposals ...consensus_channel.SignedProposal) Message

CreateSignedProposalMessage returns a signed proposal message addressed to the counterparty in the given ledger channel. The proposals MUST be sorted by turnNum since the ledger protocol relies on the message receipient processing the proposals in that order. See ADR 4.

func CreateVoucherMessage

func CreateVoucherMessage(voucher payments.Voucher, recipients ...types.Address) []Message

CreateVoucherMessage returns a signed voucher message for each of the recipients provided.

func DeserializeMessage

func DeserializeMessage(s string) (Message, error)

DeserializeMessage deserializes the passed string into a protocols.Message.

func (Message) Serialize

func (m Message) Serialize() (string, error)

Serialize serializes the message into a string.

func (Message) Summarize

func (m Message) Summarize() MessageSummary

Summarize returns a MessageSummary for the message that is suitable for logging

type MessageSummary

type MessageSummary struct {
	To               string
	From             string
	PayloadSummaries []ObjectivePayloadSummary

	ProposalSummaries []ProposalSummary

	Payments []PaymentSummary
	// RejectedObjectives is a collection of objectives that have been rejected.
	RejectedObjectives []string
}

MessageSummary is a summary of a message suitable for logging.

type Objective

type Objective interface {
	Id() ObjectiveId

	Approve() Objective                                                  // returns an updated Objective (a copy, no mutation allowed), does not declare effects
	Reject() (Objective, SideEffects)                                    // returns an updated Objective (a copy, no mutation allowed), does not declare effects
	Update(payload ObjectivePayload) (Objective, error)                  // returns an updated Objective (a copy, no mutation allowed), does not declare effects
	Crank(secretKey *[]byte) (Objective, SideEffects, WaitingFor, error) // does *not* accept an event, but *does* accept a pointer to a signing key; declare side effects; return an updated Objective

	// Related returns a slice of related objects that need to be stored along with the objective
	Related() []Storable
	Storable

	// OwnsChannel returns the channel the objective exclusively owns.
	OwnsChannel() types.Destination
	// GetStatus returns the status of the objective.
	GetStatus() ObjectiveStatus
}

Objective is the interface for off-chain protocols. The lifecycle of an objective is as follows:

• It is initialized by a single client (passing in various parameters). It is implicitly approved by that client. It is communicated to the other clients.
• It is stored and then approved or rejected by the other clients
• It is updated with external information arriving to the client
• After each update, it is cranked. This generates side effects and other metadata
• The metadata will eventually indicate that the Objective has stalled OR the Objective has completed successfully

type ObjectiveId

type ObjectiveId string

ObjectiveId is a unique identifier for an Objective.

func GetProposalObjectiveId

func GetProposalObjectiveId(p consensus_channel.Proposal) (ObjectiveId, error)

GetProposalObjectiveId returns the objectiveId for a proposal.

type ObjectivePayload

type ObjectivePayload struct {
	// PayloadData is the serialized json payload
	PayloadData []byte
	// ObjectiveId is the id of the objective that is responsible for decoding and handling the payload
	ObjectiveId ObjectiveId
	// Type is the type of the payload the message contains.
	// This is useful when a protocol wants to handle different types of payloads.
	Type PayloadType
}

ObjectivePayload is a message containing a payload of []byte that an objective is responsible for decoding.

func CreateObjectivePayload

func CreateObjectivePayload(id ObjectiveId, payloadType PayloadType, p interface{}) (ObjectivePayload, error)

CreateObjectivePayload generates an objective message from the given objective id and payload. CreateObjectivePayload handles serializing `p` into json.

type ObjectivePayloadSummary

type ObjectivePayloadSummary struct {
	ObjectiveId     string
	Type            string
	PayloadDataSize int
}

ObjectivePayloadSummary is a summary of an objective payload suitable for logging.

type ObjectiveRequest

type ObjectiveRequest interface {
	Id(types.Address, *big.Int) ObjectiveId
	WaitForObjectiveToStart()
	SignalObjectiveStarted()
}

ObjectiveRequest is a request to create a new objective.

type ObjectiveStatus

type ObjectiveStatus int8

const (
	Unapproved ObjectiveStatus = iota
	Approved
	Rejected
	Completed
)

type PayloadType

type PayloadType string

type PaymentSummary

type PaymentSummary struct {
	Amount    uint64
	ChannelId string
}

PaymentSummary is a summary of a payment voucher suitable for logging.

type ProposalReceiver

type ProposalReceiver interface {
	Objective
	// ReceiveProposal receives a signed proposal and returns an updated VirtualObjective.
	// It is used to update the objective with a proposal received from a peer.
	ReceiveProposal(signedProposal consensus_channel.SignedProposal) (ProposalReceiver, error)
}

ProposalReceiver is an Objective that receives proposals.

type ProposalSummary

type ProposalSummary struct {
	ObjectiveId  string
	LedgerId     string
	ProposalType string
	TurnNum      uint64
}

ProposalSummary is a summary of a proposal suitable for logging.

type SideEffects

type SideEffects struct {
	MessagesToSend       []Message
	TransactionsToSubmit []ChainTransaction
	ProposalsToProcess   []consensus_channel.Proposal
}

SideEffects are effects to be executed by an imperative shell

func (*SideEffects) Merge

func (se *SideEffects) Merge(other SideEffects)

Merge accepts a SideEffects struct that is merged into the the existing SideEffects.

type Storable

type Storable interface {
	json.Marshaler
	json.Unmarshaler
}

Storable is an object that can be stored by the store.

type Summary

type Summary interface {
	ObjectivePayloadSummary | ProposalSummary | PaymentSummary | string
}

type WaitingFor

type WaitingFor string

WaitingFor is an enumerable "pause-point" computed from an Objective. It describes how the objective is blocked on actions by third parties (i.e. co-participants or the blockchain).

type WithdrawAllTransaction

type WithdrawAllTransaction struct {
	ChainTransaction
	SignedState state.SignedState
}

func NewWithdrawAllTransaction

func NewWithdrawAllTransaction(channelId types.Destination, signedState state.SignedState) WithdrawAllTransaction