consensus_channel

package
v0.1.2 Latest Latest
Warning

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

 Go to latest Published: Oct 9, 2023 License: Apache-2.0, MIT Imports: 10 Imported by: 0

Documentation

Overview

Package consensus_channel manages a running ledger channel.

Index

Constants

View Source 
const (
	ErrIncorrectChannelID = types.ConstError("proposal ID and channel ID do not match")
	ErrIncorrectTurnNum   = types.ConstError("incorrect turn number")
	ErrInvalidDeposit     = types.ConstError("unable to divert to guarantee: invalid deposit")
	ErrInsufficientFunds  = types.ConstError("insufficient funds")
	ErrDuplicateGuarantee = types.ConstError("duplicate guarantee detected")
	ErrGuaranteeNotFound  = types.ConstError("guarantee not found")
	ErrInvalidAmount      = types.ConstError("left amount is greater than the guarantee amount")
)
View Source 
const (
	Leader   ledgerIndex = 0
	Follower ledgerIndex = 1
)
View Source 
const (
	ErrNotFollower                 = types.ConstError("method may only be called by channel follower")
	ErrNoProposals                 = types.ConstError("no proposals in the queue")
	ErrUnsupportedQueuedProposal   = types.ConstError("only Add proposal is supported for queued proposals")
	ErrUnsupportedExpectedProposal = types.ConstError("only Add proposal is supported for expected update")
	ErrNonMatchingProposals        = types.ConstError("expected proposal does not match first proposal in the queue")
	ErrInvalidProposalSignature    = types.ConstError("invalid signature for proposal")
	ErrInvalidTurnNum              = types.ConstError("the proposal turn number is not the next turn number")
)
View Source 
const (
	ErrNotLeader              = types.ConstError("method may only be called by the channel leader")
	ErrProposalQueueExhausted = types.ConstError("proposal queue exhausted")
	ErrWrongSigner            = types.ConstError("proposal incorrectly signed")
)

Variables

This section is empty.

Functions

This section is empty.

Types

type Add 

type Add struct {
	Guarantee
	// LeftDeposit is the portion of the Add's amount that will be deducted from left participant's ledger balance.
	//
	// The right participant's deduction is computed as the difference between the guarantee amount and LeftDeposit.
	LeftDeposit *big.Int
}

Add encodes a proposal to add a guarantee to a ConsensusChannel.

func NewAdd 

func NewAdd(g Guarantee, leftDeposit *big.Int) Add

NewAdd constructs a new Add proposal.

func (*Add) Clone 

func (a *Add) Clone() Add

Clone returns a deep copy of the receiver.

func (Add) MarshalJSON 

func (a Add) MarshalJSON() ([]byte, error)

MarshalJSON returns a JSON representation of the Add

func (Add) RightDeposit 

func (a Add) RightDeposit() *big.Int

RightDeposit computes the deposit from the right participant such that a.LeftDeposit + a.RightDeposit() fully funds a's guarantee.

func (*Add) UnmarshalJSON 

func (a *Add) UnmarshalJSON(data []byte) error

UnmarshalJSON populates the receiver with the json-encoded data

type Balance 

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

Balance is a convenient, ergonomic representation of a single-asset Allocation of type 0, ie. a simple allocation.

func NewBalance 

func NewBalance(destination types.Destination, amount *big.Int) Balance

NewBalance returns a new Balance struct with the given destination and amount.

func (Balance) AsAllocation 

func (b Balance) AsAllocation() outcome.Allocation

AsAllocation converts a Balance struct into the on-chain outcome.Allocation type.

func (*Balance) Clone 

func (b *Balance) Clone() Balance

Clone returns a deep copy of the receiver.

func (Balance) Equal 

func (b Balance) Equal(b2 Balance) bool

Equal returns true if the balances are deeply equal, false otherwise.

func (Balance) MarshalJSON 

func (b Balance) MarshalJSON() ([]byte, error)

MarshalJSON returns a JSON representation of the Balance

func (*Balance) UnmarshalJSON 

func (b *Balance) UnmarshalJSON(data []byte) error

UnmarshalJSON populates the receiver with the json-encoded data

type ConsensusChannel 

type ConsensusChannel struct {
	Id             types.Destination
	MyIndex        ledgerIndex
	OnChainFunding types.Funds
	// contains filtered or unexported fields
}

ConsensusChannel is used to manage states in a running ledger channel.

func NewFollowerChannel 

func NewFollowerChannel(fp state.FixedPart, turnNum uint64, outcome LedgerOutcome, signatures [2]state.Signature) (ConsensusChannel, error)

NewFollowerChannel constructs a new FollowerChannel

func NewLeaderChannel 

func NewLeaderChannel(fp state.FixedPart, turnNum uint64, outcome LedgerOutcome, signatures [2]state.Signature) (ConsensusChannel, error)

NewLeaderChannel constructs a new LeaderChannel

func (*ConsensusChannel) Clone 

func (c *ConsensusChannel) Clone() *ConsensusChannel

Clone returns a deep copy of the receiver.

func (*ConsensusChannel) ConsensusTurnNum 

func (c *ConsensusChannel) ConsensusTurnNum() uint64

ConsensusTurnNum returns the turn number of the current consensus state.

func (*ConsensusChannel) ConsensusVars 

func (c *ConsensusChannel) ConsensusVars() Vars

ConsensusVars returns the vars of the consensus state The consensus state is the latest state that has been signed by both parties.

func (*ConsensusChannel) FixedPart 

func (c *ConsensusChannel) FixedPart() state.FixedPart

FixedPart returns the fixed part of the channel.

func (*ConsensusChannel) Follower 

func (c *ConsensusChannel) Follower() common.Address

Follower returns the address of the participant who receives and contersigns proposals.

func (*ConsensusChannel) FundingTargets 

func (c *ConsensusChannel) FundingTargets() []types.Destination

FundingTargets returns a list of channels funded by the ConsensusChannel

func (*ConsensusChannel) HasRemovalBeenProposed 

func (c *ConsensusChannel) HasRemovalBeenProposed(target types.Destination) bool

HasRemovalBeenProposed returns whether or not a proposal exists to remove the guarantee for the target.

func (*ConsensusChannel) HasRemovalBeenProposedNext 

func (c *ConsensusChannel) HasRemovalBeenProposedNext(target types.Destination) bool

HasRemovalBeenProposedNext returns whether or not the next proposal in the queue is a remove proposal for the given target

func (*ConsensusChannel) Includes 

func (c *ConsensusChannel) Includes(g Guarantee) bool

Includes returns whether or not the consensus state includes the given guarantee.

func (*ConsensusChannel) IncludesTarget 

func (c *ConsensusChannel) IncludesTarget(target types.Destination) bool

IncludesTarget returns whether or not the consensus state includes a guarantee addressed to the given target.

func (*ConsensusChannel) IsFollower 

func (c *ConsensusChannel) IsFollower() bool

IsFollower returns true if the calling client is the follower of the channel, and false otherwise.

func (*ConsensusChannel) IsLeader 

func (c *ConsensusChannel) IsLeader() bool

IsLeader returns true if the calling client is the leader of the channel, and false otherwise.

func (*ConsensusChannel) IsProposed 

func (c *ConsensusChannel) IsProposed(g Guarantee) (bool, error)

IsProposed returns true if a proposal in the queue would lead to g being included in the receiver's outcome, and false otherwise.

Specific clarification: If the current outcome already includes g, IsProposed returns false.

func (*ConsensusChannel) IsProposedNext 

func (c *ConsensusChannel) IsProposedNext(g Guarantee) (bool, error)

IsProposedNext returns true if the next proposal in the queue would lead to g being included in the receiver's outcome, and false otherwise.

func (*ConsensusChannel) Leader 

func (c *ConsensusChannel) Leader() common.Address

Leader returns the address of the participant responsible for proposing.

func (ConsensusChannel) MarshalJSON 

func (c ConsensusChannel) MarshalJSON() ([]byte, error)

MarshalJSON returns a JSON representation of the ConsensusChannel

func (*ConsensusChannel) Participants 

func (c *ConsensusChannel) Participants() []types.Address

Participants returns the channel participants.

func (*ConsensusChannel) ProposalQueue 

func (c *ConsensusChannel) ProposalQueue() []SignedProposal

ProposalQueue returns the current queue of proposals, ordered by TurnNum.

func (*ConsensusChannel) Propose 

func (c *ConsensusChannel) Propose(proposal Proposal, sk []byte) (SignedProposal, error)

Propose is called by the Leader and receives a proposal to add or remove a guarantee, and generates and stores a SignedProposal in the queue, returning the resulting SignedProposal

func (*ConsensusChannel) Receive 

func (c *ConsensusChannel) Receive(sp SignedProposal) error

Receive accepts a proposal signed by the ConsensusChannel counterparty, validates its signature, and performs updates to the proposal queue and consensus state.

func (*ConsensusChannel) SignNextProposal 

func (c *ConsensusChannel) SignNextProposal(expectedProposal Proposal, sk []byte) (SignedProposal, error)

SignNextProposal is called by the follower and inspects whether the expected proposal matches the first proposal in the queue. If so, the proposal is removed from the queue and integrated into the channel state.

func (*ConsensusChannel) Signatures 

func (c *ConsensusChannel) Signatures() [2]state.Signature

Signatures returns the signatures on the currently supported state.

func (*ConsensusChannel) SupportedSignedState 

func (cc *ConsensusChannel) SupportedSignedState() state.SignedState

SupportedSignedState returns the latest supported signed state.

func (*ConsensusChannel) UnmarshalJSON 

func (c *ConsensusChannel) UnmarshalJSON(data []byte) error

UnmarshalJSON populates the receiver with the json-encoded data

type Guarantee 

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

Guarantee is a convenient, ergonomic representation of a single-asset Allocation of type 1, ie. a guarantee.

func NewGuarantee 

func NewGuarantee(amount *big.Int, target types.Destination, left types.Destination, right types.Destination) Guarantee

NewGuarantee constructs a new guarantee.

func (Guarantee) AsAllocation 

func (g Guarantee) AsAllocation() outcome.Allocation

AsAllocation converts a Balance struct into the on-chain outcome.Allocation type

func (*Guarantee) Clone 

func (g *Guarantee) Clone() Guarantee

Clone returns a deep copy of the receiver.

func (Guarantee) MarshalJSON 

func (g Guarantee) MarshalJSON() ([]byte, error)

MarshalJSON returns a JSON representation of the Guarantee

func (Guarantee) Target 

func (g Guarantee) Target() types.Destination

Target returns the target of the guarantee.

func (*Guarantee) UnmarshalJSON 

func (g *Guarantee) UnmarshalJSON(data []byte) error

UnmarshalJSON populates the receiver with the json-encoded data

type LedgerOutcome 

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

LedgerOutcome encodes the outcome of a ledger channel involving a "leader" and "follower" participant.

This struct does not store items in sorted order. The conventional ordering of allocation items is: [leader, follower, ...guaranteesSortedByTargetDestination]

func FromExit 

func FromExit(sae outcome.SingleAssetExit) (LedgerOutcome, error)

FromExit creates a new LedgerOutcome from the given SingleAssetExit.

It makes the following assumptions about the exit:

  • The first allocation entry is for the ledger leader
  • The second allocation entry is for the ledger follower
  • All other allocations are guarantees

func NewLedgerOutcome 

func NewLedgerOutcome(assetAddress types.Address, leader, follower Balance, guarantees []Guarantee) *LedgerOutcome

NewLedgerOutcome creates a new ledger outcome with the given asset address, balances, and guarantees.

func (*LedgerOutcome) AsOutcome 

func (o *LedgerOutcome) AsOutcome() outcome.Exit

AsOutcome converts a LedgerOutcome to an on-chain exit according to the following convention:

  • the "leader" balance is first
  • the "follower" balance is second
  • guarantees follow, sorted according to their target destinations

func (*LedgerOutcome) Clone 

func (lo *LedgerOutcome) Clone() LedgerOutcome

Clone returns a deep copy of the receiver.

func (*LedgerOutcome) Follower 

func (lo *LedgerOutcome) Follower() Balance

Follower returns the follower's balance.

func (LedgerOutcome) FundingTargets 

func (o LedgerOutcome) FundingTargets() []types.Destination

FundingTargets returns a list of channels funded by the LedgerOutcome

func (*LedgerOutcome) IncludesTarget 

func (o *LedgerOutcome) IncludesTarget(target types.Destination) bool

IncludesTarget returns true when the receiver includes a guarantee that targets the given destination.

func (*LedgerOutcome) Leader 

func (lo *LedgerOutcome) Leader() Balance

Leader returns the leader's balance.

func (LedgerOutcome) MarshalJSON 

func (l LedgerOutcome) MarshalJSON() ([]byte, error)

MarshalJSON returns a JSON representation of the LedgerOutcome

func (*LedgerOutcome) UnmarshalJSON 

func (l *LedgerOutcome) UnmarshalJSON(data []byte) error

UnmarshalJSON populates the receiver with the json-encoded data

type Proposal 

type Proposal struct {
	// LedgerID is the ChannelID of the ConsensusChannel which should receive the proposal.
	//
	// The target virtual channel ID is contained in the Add / Remove struct.
	LedgerID types.Destination
	ToAdd    Add
	ToRemove Remove
}

Proposal is a proposal either to add or to remove a guarantee.

Exactly one of {toAdd, toRemove} should be non nil.

func NewAddProposal 

func NewAddProposal(ledgerID types.Destination, g Guarantee, leftDeposit *big.Int) Proposal

NewAddProposal constructs a proposal with a valid Add proposal and empty remove proposal.

func NewRemoveProposal 

func NewRemoveProposal(ledgerID types.Destination, target types.Destination, leftAmount *big.Int) Proposal

NewRemoveProposal constructs a proposal with a valid Remove proposal and empty Add proposal.

func (*Proposal) Clone 

func (p *Proposal) Clone() Proposal

Clone returns a deep copy of the receiver.

func (*Proposal) Equal 

func (p *Proposal) Equal(q *Proposal) bool

Equal returns true if the supplied Proposal is deeply equal to the receiver, false otherwise.

func (Proposal) MarshalJSON 

func (p Proposal) MarshalJSON() ([]byte, error)

MarshalJSON returns a JSON representation of the Proposal

func (*Proposal) Target 

func (p *Proposal) Target() types.Destination

Target returns the target channel of the proposal.

func (*Proposal) Type 

func (p *Proposal) Type() ProposalType

Type returns the type of the proposal based on whether it contains an Add or a Remove proposal.

func (*Proposal) UnmarshalJSON 

func (p *Proposal) UnmarshalJSON(data []byte) error

UnmarshalJSON populates the receiver with the json-encoded data

type ProposalType 

type ProposalType string
const (
	AddProposal    ProposalType = "AddProposal"
	RemoveProposal ProposalType = "RemoveProposal"
)

type Remove 

type Remove struct {
	// Target is the address of the virtual channel being defunded
	Target types.Destination
	// LeftAmount is the amount to be credited (in the ledger channel) to the participant specified as the "left" in the guarantee.
	//
	// The amount for the "right" participant is calculated as the difference between the guarantee amount and LeftAmount.
	LeftAmount *big.Int
}

Remove is a proposal to remove a guarantee for the given virtual channel.

func NewRemove 

func NewRemove(target types.Destination, leftAmount *big.Int) Remove

NewRemove constructs a new Remove proposal.

func (*Remove) Clone 

func (r *Remove) Clone() Remove

Clone returns a deep copy of the receiver

func (Remove) MarshalJSON 

func (r Remove) MarshalJSON() ([]byte, error)

MarshalJSON returns a JSON representation of the Remove

func (*Remove) UnmarshalJSON 

func (r *Remove) UnmarshalJSON(data []byte) error

UnmarshalJSON populates the receiver with the json-encoded data

type SignedProposal 

type SignedProposal struct {
	Signature state.Signature
	Proposal  Proposal
	TurnNum   uint64
}

SignedProposal is a Proposal with a signature on it.

func (SignedProposal) ChannelID 

func (p SignedProposal) ChannelID() types.Destination

ChannelID returns the id of the ConsensusChannel which receive the proposal.

func (*SignedProposal) Clone 

func (sp *SignedProposal) Clone() SignedProposal

Clone returns a deep copy of the receiver.

func (SignedProposal) SortInfo 

func (p SignedProposal) SortInfo() (types.Destination, uint64)

SortInfo returns the channelId and turn number so the proposal can be easily sorted.

type SignedVars 

type SignedVars struct {
	Vars
	Signatures [2]state.Signature
}

SignedVars stores 0-2 signatures for some vars in a consensus channel.

type Vars 

type Vars struct {
	TurnNum uint64
	Outcome LedgerOutcome
}

Vars stores the turn number and outcome for a state in a consensus channel.

func (*Vars) Add 

func (vars *Vars) Add(p Add) error

Add mutates Vars by

  • increasing the turn number by 1
  • including the guarantee
  • adjusting balances accordingly

An error is returned if:

  • the turn number is not incremented
  • the balances are incorrectly adjusted, or the deposits are too large
  • the guarantee is already included in vars.Outcome

If an error is returned, the original vars is not mutated.

func (Vars) AsState 

func (v Vars) AsState(fp state.FixedPart) state.State

func (*Vars) Clone 

func (v *Vars) Clone() Vars

Clone returns a deep copy of the receiver.

func (*Vars) HandleProposal 

func (vars *Vars) HandleProposal(p Proposal) error

HandleProposal handles a proposal to add or remove a guarantee. It will mutate Vars by calling Add or Remove for the proposal.

func (*Vars) Remove 

func (vars *Vars) Remove(p Remove) error

Remove mutates Vars by

  • increasing the turn number by 1
  • removing the guarantee for the Target channel
  • adjusting balances accordingly based on LeftAmount and RightAmount

An error is returned if:

  • the turn number is not incremented
  • a guarantee is not found for the target
  • the amounts are too large for the guarantee amount

If an error is returned, the original vars is not mutated.

Source Files

View all Source files

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.