fsm

package
v0.1.0-alpha.0...-0b1224c Latest Latest
Warning

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

 Go to latest Published: Apr 5, 2019 License: Apache-2.0, Apache-2.0 Imports: 16 Imported by: 0

Documentation

Overview

Package fsm implements the state transition logic in the Starlight spec.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// Command errors
	ErrInsufficientFunds = errors.New("insufficient funds")

	// Message errors
	ErrChannelExists            = errors.New("received channel propose message for channel that already exists")
	ErrInvalidVersion           = errors.New("invalid version number")
	ErrUnusedSettleWithGuestSig = errors.New("unused settle with guest sig")

	ErrUnexpectedState = errors.New("unexpected state")
)

Defines the FSM package errors

Functions

func Close 

func Close(u *Updater) error

Close transitions the channel in the given Updater to Closed.

func MatchesFundingTx 

func MatchesFundingTx(c *Channel, tx *worizon.Tx) bool

MatchesFundingTx reports whether a transaction is the funding transaction for the channel.

Types

type AccountID 

type AccountID xdr.AccountId

AccountID is a Stellar account ID.

func (*AccountID) Address 

func (id *AccountID) Address() string

Address produces the Stellar address string for id.

func (*AccountID) Equals 

func (id *AccountID) Equals(other AccountID) bool

Equals tells whether two Stellar account IDs are the same.

func (*AccountID) MarshalBinary 

func (id *AccountID) MarshalBinary() ([]byte, error)

MarshalBinary satisfies interface BinaryMarshaler.

func (*AccountID) MarshalText 

func (id *AccountID) MarshalText() ([]byte, error)

MarshalText implements the TextMarshaler interface for the accountID type, allowing us to serialize the account IDs to their string addresses, rather than the default xdr Uint256 slice.

func (*AccountID) SetAddress 

func (id *AccountID) SetAddress(address string) error

SetAddress sets *id to the account ID corresponding to the given Stellar address.

func (*AccountID) UnmarshalBinary 

func (id *AccountID) UnmarshalBinary(data []byte) error

UnmarshalBinary satisfies interface BinaryUnmarshaler.

func (*AccountID) UnmarshalText 

func (id *AccountID) UnmarshalText(data []byte) error

UnmarshalText implements the TextMarshaler interface, taking our custom-serialized JSON for Channel objects and converting the string addresses back into xdr.AccountId types.

func (*AccountID) XDR 

func (id *AccountID) XDR() *xdr.AccountId

XDR produces the XDR form of a Stellar account ID.

type Balance 

type Balance struct {
	Asset      xdr.Asset
	Amount     uint64
	Pending    bool
	Authorized bool
}

Balance represents the point-in-time state of a non-XLM Asset in the WalletAcct.

type Channel 

type Channel struct {
	ID                     string
	Role                   Role
	State, PrevState       State
	CounterpartyAddress    string // either the Guest's federation address, or the Host's public key address
	RemoteURL              string
	Passphrase             string
	Cursor                 string // where we are in watching escrowacct txs on the ledger
	BaseSequenceNumber     xdr.SequenceNumber
	RoundNumber            uint64
	CounterpartyMsgIndex   uint64
	LastMsgIndex           uint64
	MaxRoundDuration       time.Duration
	FinalityDelay          time.Duration
	ChannelFeerate         xlm.Amount
	HostFeerate            xlm.Amount
	FundingTime            time.Time
	FundingTimedOut        bool
	FundingTxSeqnum        xdr.SequenceNumber
	HostAmount             xlm.Amount
	GuestAmount            xlm.Amount
	TopUpAmount            xlm.Amount
	PendingAmountSent      xlm.Amount
	PendingAmountReceived  xlm.Amount
	PaymentTime            time.Time
	PendingPaymentTime     time.Time
	HostAcct               AccountID
	GuestAcct              AccountID
	EscrowAcct             AccountID
	HostRatchetAcct        AccountID
	GuestRatchetAcct       AccountID
	KeyIndex               uint32
	HostRatchetAcctSeqNum  xdr.SequenceNumber
	GuestRatchetAcctSeqNum xdr.SequenceNumber

	// Ratchet transaction from the last completed round, including the
	// counterparty's signature.
	CurrentRatchetTx xdr.TransactionEnvelope

	// Latest settlement txes for which the counterparty has a valid
	// ratchet transaction and has provided their signature.
	// TODO(debnil): Convert SettleWithHostTx to a pointer, as it is
	// only set in some channel states, both here and below.
	CounterpartyLatestSettleWithGuestTx *xdr.TransactionEnvelope
	CounterpartyLatestSettleWithHostTx  xdr.TransactionEnvelope

	// Settlement transaction from the latest completed round, including
	// the counterparty's signature. This only differs from
	// CounterPartyLatestSettlementTxes when the channel has transitioned
	// into the PaymentAccepted state, but has yet to receive the
	// PaymentCompleteMsg from the counterparty.
	CurrentSettleWithGuestTx *xdr.TransactionEnvelope
	CurrentSettleWithHostTx  xdr.TransactionEnvelope

	// In a cooperative close, the counterparty's signature
	// is included in the Channel state so a Transaction Envelope
	// containing the transaction signed by each party can be submitted.
	CounterpartyCoopCloseSig xdr.DecoratedSignature
}

Channel represents the point-in-time state of a single Starlight channel. It is pure data, and designed to be serializable to and from JSON.

func (*Channel) MarshalJSON 

func (ch *Channel) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler. Required for genbolt.

func (*Channel) SetupAndFundingReserveAmount 

func (ch *Channel) SetupAndFundingReserveAmount() xlm.Amount

SetupAndFundingReserveAmount reports the amount in lumens needed to set up and fund the channel.

func (*Channel) TimerTime 

func (ch *Channel) TimerTime() (*time.Time, error)

TimerTime returns the time at which a timer for the current state should fire, or nil if there is no timer associated with this state.

func (*Channel) UnmarshalJSON 

func (ch *Channel) UnmarshalJSON(b []byte) error

UnmarshalJSON implements json.Unmarshaler. Required for genbolt.

type ChannelAcceptMsg 

type ChannelAcceptMsg struct {
	GuestRatchetRound1Sig      xdr.DecoratedSignature
	GuestSettleOnlyWithHostSig xdr.DecoratedSignature
}

ChannelAcceptMsg contains Signatures for Guest accepting a proposal.

type ChannelProposeMsg 

type ChannelProposeMsg struct {
	HostAcct           AccountID
	GuestAcct          AccountID
	HostRatchetAcct    AccountID
	GuestRatchetAcct   AccountID
	MaxRoundDuration   time.Duration
	FinalityDelay      time.Duration
	BaseSequenceNumber xdr.SequenceNumber
	HostAmount         xlm.Amount
	Feerate            xlm.Amount
	FundingTime        time.Time
}

ChannelProposeMsg defines a JSON schema for proposal over a Channel.

type CloseMsg 

type CloseMsg struct {
	CooperativeCloseSig xdr.DecoratedSignature
}

CloseMsg is the protocol message proposing a cooperative closure of the channel.

type Command 

type Command struct {
	Name      CommandName
	Amount    xlm.Amount // for TopUp, ChannelPay, or Pay
	Time      time.Time
	Recipient string // for Pay
	AssetCode string // for AddAsset, RemoveAsset
	Issuer    string // for AddAsset, RemoveAsset
}

Command contains a command name and its required arguments.

type CommandName 

type CommandName string

CommandName is the type of a user-command constant. 

const (
	CreateChannel CommandName = "CreateChannel"
	CleanUp       CommandName = "CleanUp"
	CloseChannel  CommandName = "CloseChannel"
	TopUp         CommandName = "TopUp"
	ChannelPay    CommandName = "ChannelPay"
	ForceClose    CommandName = "ForceClose"
	Pay           CommandName = "Pay"
	AddAsset      CommandName = "AddAsset"
	RemoveAsset   CommandName = "RemoveAsset"
)

User commands.

type Message 

type Message struct {
	ChannelID string
	MsgNum    uint64
	Version   int

	ChannelProposeMsg  *ChannelProposeMsg  `json:",omitempty"`
	ChannelAcceptMsg   *ChannelAcceptMsg   `json:",omitempty"`
	PaymentProposeMsg  *PaymentProposeMsg  `json:",omitempty"`
	PaymentAcceptMsg   *PaymentAcceptMsg   `json:",omitempty"`
	PaymentCompleteMsg *PaymentCompleteMsg `json:",omitempty"`
	CloseMsg           *CloseMsg           `json:",omitempty"`

	// Signature is a signature over the JSON representation of the message
	// (minus the Signature field itself), made with the sender's key.
	Signature []byte `json:",omitempty"`
}

Message defines a JSON schema for Starlight messages.

func (*Message) MarshalJSON 

func (m *Message) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler. Required for genbolt.

func (*Message) UnmarshalJSON 

func (m *Message) UnmarshalJSON(b []byte) error

UnmarshalJSON implements json.Unmarshaler. Required for genbolt.

type Outputter 

type Outputter interface {
	// OutputMsg sends a message to the remote endpoint.
	OutputMsg(*Message)

	// OutputTx publishes a transaction to the ledger.
	OutputTx(xdr.TransactionEnvelope)
}

Outputter accumulates side effects to be emitted to the outside world. This consists of zero or more messages to send to the peer, transactions to publish to the Stellar network, and timers to schedule.

type PaymentAcceptMsg 

type PaymentAcceptMsg struct {
	RoundNumber                 uint64
	RecipientRatchetSig         xdr.DecoratedSignature
	RecipientSettleWithGuestSig *xdr.DecoratedSignature
	RecipientSettleWithHostSig  xdr.DecoratedSignature
}

PaymentAcceptMsg is the protocol message accepting a proposed channel payment.

type PaymentCompleteMsg 

type PaymentCompleteMsg struct {
	RoundNumber      uint64
	SenderRatchetSig xdr.DecoratedSignature
}

PaymentCompleteMsg is the protocol message acknowledging a PaymentAcceptMsg.

type PaymentProposeMsg 

type PaymentProposeMsg struct {
	RoundNumber              uint64
	PaymentTime              time.Time
	PaymentAmount            xlm.Amount
	SenderSettleWithGuestSig xdr.DecoratedSignature
	SenderSettleWithHostSig  xdr.DecoratedSignature
}

PaymentProposeMsg is the protocol message proposing a channel payment.

type Role 

type Role string

Role is the type of a role constant. 

const (
	Host  Role = "Host"
	Guest Role = "Guest"
)

Roles. A participant in a channel is either the channel's host, if they created the channel, or the guest, if they accepted a channel proposal.

type State 

type State string

State is the type of a channel-state constant. 

const (
	// Start indicates a channel that does not (yet) exist.
	//
	// Note that no state transition enters the state Start,
	// so if a Channel has this state after running an Update
	// function in this package, the channel is invalid.
	Start State = ""

	Closed State = "Closed"

	AwaitingCleanup           State = "AwaitingCleanup"
	AwaitingClose             State = "AwaitingClose"
	AwaitingFunding           State = "AwaitingFunding"
	AwaitingPaymentMerge      State = "AwaitingPaymentMerge"
	AwaitingRatchet           State = "AwaitingRatchet"
	AwaitingSettlement        State = "AwaitingSettlement"
	AwaitingSettlementMintime State = "AwaitingSettlementMintime"
	ChannelProposed           State = "ChannelProposed"
	Open                      State = "Open"
	PaymentAccepted           State = "PaymentAccepted"
	PaymentProposed           State = "PaymentProposed"
	SettingUp                 State = "SettingUp"
)

Channel-state constants.

type Updater 

type Updater struct {
	C          *Channel
	O          Outputter
	H          *WalletAcct
	Seed       []byte
	LedgerTime time.Time
	Passphrase string
	// contains filtered or unexported fields
}

Updater contains the state necessary to effect a state transition in a channel.

func (*Updater) Cmd 

func (u *Updater) Cmd(c *Command) error

Cmd causes the updater to update its channel in response to a user command.

func (*Updater) Msg 

func (u *Updater) Msg(m *Message) error

Msg causes the updater to update its channel in response to a protocol message received from a peer Agent.

func (*Updater) SetDebug 

func (u *Updater) SetDebug(debug bool)

func (*Updater) Time 

func (u *Updater) Time() error

Time causes the updater to update its channel in response to a deadline arriving.

func (*Updater) Tx 

func (u *Updater) Tx(tx *worizon.Tx) error

Tx causes the updater to update its channel in response to a transaction appearing in a Stellar ledger.

type WalletAcct 

type WalletAcct struct {
	NativeBalance xlm.Amount
	Reserve       xlm.Amount
	Seqnum        xdr.SequenceNumber
	Address       string // Stellar federation address
	Cursor        string
	Balances      map[string]Balance
}

WalletAcct represents the point-in-time state of the channel's wallet account, passed to the FSM for state transitions that access or update host-level data.

func (*WalletAcct) MarshalJSON 

func (w *WalletAcct) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler. Required for genbolt.

func (*WalletAcct) UnmarshalJSON 

func (w *WalletAcct) UnmarshalJSON(b []byte) error

UnmarshalJSON implements json.Unmarshaler. Required for genbolt.

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.