state

package
v0.0.0-...-9190965 Latest Latest
Warning

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

 Go to latest Published: Jun 16, 2022 License: Apache-2.0 Imports: 10 Imported by: 1

Documentation

Overview

Package state contains a state machine, contained in the Channel type, for managing a Starlight payment channel.

The Channel type once constructed contains functions for three categories of operations: - Open: Opening the payment channel. - Payment: Making a payment from either participant to the other participant. - Close: Coordinating an immediate close the payment channel.

The Channel type also provides functions for ingesting data from the network into the state machine. This is necessary to progress the state of the channel through states that are based on network activity, such as open and close.

The Open, Payment, and Close operations are broken up into three steps: - Propose: Called by the payer to create the agreement. - Confirm: Called by the payee to confirm the agreement. - Finalize*: Called by the payer to finalize the agreement with the payees signatures. 

+-----------+      +-----------+
|   Payer   |      |   Payee   |
+-----+-----+      +-----+-----+
      |                  |
   Propose               |
      +----------------->+
      |               Confirm
      +<-----------------+
  Finalize*              |
      |                  |

* Note that the Open and Close processes do not have a Finalize operation, and the Confirm is used in its place at this time. A Finalize operation is likely to be added in the future.

None of the primitives in this package are threadsafe and synchronization must be provided by the caller if the package is used in a concurrent context.

Index

Constants

View Source 
const NativeAsset = Asset("native")

Variables

View Source 
var ErrUnderfunded = fmt.Errorf("account is underfunded to make payment")

ErrUnderfunded indicates that the account has insufficient funds to make a specific payment amount.

Functions

This section is empty.

Types

type Asset 

type Asset string

Asset is a Stellar asset.

func (Asset) Asset 

func (a Asset) Asset() txnbuild.Asset

Asset returns an asset from the stellar/go/txnbuild package with the same asset code and issuer, or a native asset if a native asset.

func (Asset) Code 

func (a Asset) Code() string

Code returns the asset code of credit assets.

func (Asset) EqualTrustLineAsset 

func (a Asset) EqualTrustLineAsset(ta xdr.TrustLineAsset) bool

EqualTrustLineAsset returns true if the canonical strings of this asset and a given trustline asset are equal, else false.

func (Asset) IsNative 

func (a Asset) IsNative() bool

IsNative returns true if the asset is the native asset of the stellar network.

func (Asset) Issuer 

func (a Asset) Issuer() string

Issuer returns the issuer of credit assets.

func (Asset) StringCanonical 

func (a Asset) StringCanonical() string

StringCanonical returns a string friendly representation of the asset in canonical form.

type Channel 

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

Channel holds the state of a single Starlight payment channel.

func NewChannel 

func NewChannel(c Config) *Channel

NewChannel constructs a new channel with the given config.

func NewChannelFromSnapshot 

func NewChannelFromSnapshot(c Config, s Snapshot) *Channel

NewChannelFromSnapshot creates the channel with the given config, and restores the internal state of the channel using the snapshot. To restore the channel to its identical state the same config should be provided that was in use when the snapshot was created.

func (*Channel) Balance 

func (c *Channel) Balance() int64

Balance returns the amount owing from the initiator to the responder, if positive, or the amount owing from the responder to the initiator, if negative.

func (*Channel) CloseTxs 

func (c *Channel) CloseTxs() (declTx *txnbuild.Transaction, closeTx *txnbuild.Transaction, err error)

CloseTxs builds the declaration and close transactions used for closing the channel using the latest close agreement. The transactions are signed and ready to submit.

func (*Channel) ConfirmClose 

func (c *Channel) ConfirmClose(ce CloseEnvelope) (closeAgreement CloseAgreement, err error)

ConfirmClose agrees to a close agreement to be submitted without waiting the observation period. The agreement will always be accepted if it is identical to the latest authorized close agreement, and it is signed by the participant proposing the close.

func (*Channel) ConfirmOpen 

func (c *Channel) ConfirmOpen(m OpenEnvelope) (open OpenAgreement, err error)

ConfirmOpen confirms an open that was proposed. ConfirmPayment confirms the agreement. The responder to the open process calls this once to sign and store the agreement. The initiator of the open process calls this once with a copy of the agreement signed by the destination to store the destination's signatures.

func (*Channel) ConfirmPayment 

func (c *Channel) ConfirmPayment(ce CloseEnvelope) (closeAgreement CloseAgreement, err error)

ConfirmPayment confirms an agreement. The destination of a payment calls this once to sign and store the agreement.

func (*Channel) FinalizePayment 

func (c *Channel) FinalizePayment(cs CloseSignatures) (closeAgreement CloseAgreement, err error)

FinalizePayment finalizes a payment, making it authorized, by attaching the close signatures to the agreement as the confirmers signatures. The proposer of a payment calls this once with the confirmers signatures when the confirmer provides them. This can only be used to finalize the most recent unauthorized payment.

func (*Channel) IngestTx 

func (c *Channel) IngestTx(txOrderID int64, txXDR, resultXDR, resultMetaXDR string) error

IngestTx accepts any transaction that has been seen as successful or unsuccessful on the network. The function updates the internal state of the channel if the transaction relates to one of the channel's channel accounts.

The txOrderID is an identifier that orders transactions as they were executed on the Stellar network.

The function may be called with transactions for each channel account out of order. For example, transactions for the initiator channel account can be processed in order, and transactions for the responder channel account can be processed in order, but relative to each other they may be out of order. If transactions for a single account are processed out of order some state transition may be skipped.

The function maybe called with duplicate transactions and duplicates will not change the state of the channel.

func (*Channel) IsInitiator 

func (c *Channel) IsInitiator() bool

IsInitiator returns true if this channel initiated the process of opening a channel, else false.

func (*Channel) LatestCloseAgreement 

func (c *Channel) LatestCloseAgreement() CloseAgreement

LatestCloseAgreement returns the latest close agreement signed by both channel participants.

func (*Channel) LatestUnauthorizedCloseAgreement 

func (c *Channel) LatestUnauthorizedCloseAgreement() (CloseAgreement, bool)

LatestUnauthorizedCloseAgreement returns the latest unauthorized close agreement yet to be signed by both participants.

func (*Channel) LocalChannelAccount 

func (c *Channel) LocalChannelAccount() ChannelAccount

LocalChannelAccount returns the local channel account.

func (*Channel) OpenAgreement 

func (c *Channel) OpenAgreement() OpenAgreement

OpenAgreement returns the open agreement used to open the channel.

func (*Channel) OpenTx 

func (c *Channel) OpenTx() (openTx *txnbuild.Transaction, err error)

OpenTx builds the open transaction used for opening the channel. The transaction is signed and ready to submit. ProposeOpen and ConfirmOpen must be used prior to prepare an open agreement with the other participant.

func (*Channel) ProposeClose 

func (c *Channel) ProposeClose() (CloseAgreement, error)

ProposeClose proposes that the latest authorized close agreement be submitted without waiting the observation period. This should be used when participants are in agreement on the final close state, but would like to submit earlier than the original observation time.

func (*Channel) ProposeOpen 

func (c *Channel) ProposeOpen(p OpenParams) (OpenAgreement, error)

ProposeOpen proposes the open of the channel, it is called by the participant initiating the channel.

func (*Channel) ProposePayment 

func (c *Channel) ProposePayment(amount int64) (CloseAgreement, error)

ProposePayment proposes a new payment from the local, the caller of the function, to the remote. ProposePayment is the first step in the process that the paricipants use to make a payment from a payer to a payee.

func (*Channel) ProposePaymentWithMemo 

func (c *Channel) ProposePaymentWithMemo(amount int64, memo []byte) (CloseAgreement, error)

ProposePaymentWithMemo proposes a new payment that has a byte memo attached to it. The memo can be used to store an identifier or any amount of information about the payment. See the ProposePayment function for more information.

func (*Channel) RemoteChannelAccount 

func (c *Channel) RemoteChannelAccount() ChannelAccount

RemoteChannelAccount returns the remote channel account.

func (*Channel) Snapshot 

func (c *Channel) Snapshot() Snapshot

Snapshot returns a snapshot of the channel's internal state that if combined with it's initialization config can be used to create a new Channel that has the same state.

func (*Channel) State 

func (c *Channel) State() (State, error)

State returns a single value representing the overall state of the channel. If there was an error finding the state, or internal values are unexpected, then a failed channel state is returned, indicating something is wrong.

func (*Channel) UpdateLocalChannelAccountBalance 

func (c *Channel) UpdateLocalChannelAccountBalance(balance int64)

UpdateLocalChannelAccountBalance updates the local channel account balance.

func (*Channel) UpdateRemoteChannelAccountBalance 

func (c *Channel) UpdateRemoteChannelAccountBalance(balance int64)

UpdateRemoteChannelAccountBalance updates the remote channel account balance.

type ChannelAccount 

type ChannelAccount struct {
	Address                    *keypair.FromAddress
	SequenceNumber             int64
	Balance                    int64
	LastSeenTransactionOrderID int64
}

ChannelAccount holds the details that a Channel tracks for a Stellar account. A Channel tracks the details of two Stellar accounts, one for each participant in the channel.

The channel accounts hold the assets that are used for payments and will be re-distributed at close.

type CloseAgreement 

type CloseAgreement struct {
	Envelope     CloseEnvelope
	Transactions CloseTransactions
}

CloseAgreement contains all the information known for an agreement proposed or confirmed by the channel.

func (CloseAgreement) SignedTransactions 

func (ca CloseAgreement) SignedTransactions() CloseTransactions

SignedTransactions adds signatures from the CloseAgreement's Envelope to its Transactions.

type CloseDetails 

type CloseDetails struct {
	ObservationPeriodTime      time.Duration
	ObservationPeriodLedgerGap uint32
	IterationNumber            int64
	Balance                    int64
	ProposingSigner            *keypair.FromAddress
	ConfirmingSigner           *keypair.FromAddress

	// The following fields are not captured in the signatures produced by
	// signers because the information is not embedded into the agreement's
	// transactions.
	PaymentAmount int64
	Memo          []byte
}

CloseDetails contains the details that the participants agree on.

func (CloseDetails) Equal 

func (d CloseDetails) Equal(d2 CloseDetails) bool

Equal returns true if two CloseDetails are equal, else false.

type CloseEnvelope 

type CloseEnvelope struct {
	Details             CloseDetails
	ProposerSignatures  CloseSignatures
	ConfirmerSignatures CloseSignatures
}

CloseEnvelope contains everything a participant needs to execute the close agreement on the Stellar network.

func (CloseEnvelope) Empty 

func (ca CloseEnvelope) Empty() bool

Empty returns true if the CloseEnvelope has no data, else false.

func (CloseEnvelope) Equal 

func (ca CloseEnvelope) Equal(ca2 CloseEnvelope) bool

Equal returns true if two CloseEnvelope are equal, else false.

func (CloseEnvelope) SignaturesFor 

func (ca CloseEnvelope) SignaturesFor(signer *keypair.FromAddress) *CloseSignatures

SignaturesFor returns the signatures currently held for the given signer, if any.

type CloseSignatures 

type CloseSignatures struct {
	Close       xdr.Signature
	Declaration xdr.Signature
}

CloseSignatures holds the signatures for a close agreement.

func (CloseSignatures) Empty 

func (cas CloseSignatures) Empty() bool

Empty returns true if there are not any signatures present, else false.

func (CloseSignatures) Equal 

func (cas CloseSignatures) Equal(cas2 CloseSignatures) bool

Equal returns true if two CloseSignatures are equal, else false.

func (CloseSignatures) HasAllSignatures 

func (cas CloseSignatures) HasAllSignatures() bool

HasAllSignatures returns true if there is a signature for each transaction type present, else false.

type CloseTransactions 

type CloseTransactions struct {
	CloseHash       TransactionHash
	Close           *txnbuild.Transaction
	DeclarationHash TransactionHash
	Declaration     *txnbuild.Transaction
}

CloseTransactions contain all the transaction hashes and transactions for the transactions that make up the close agreement.

type Config 

type Config struct {
	NetworkPassphrase string
	MaxOpenExpiry     time.Duration

	Initiator bool

	LocalChannelAccount  *keypair.FromAddress
	RemoteChannelAccount *keypair.FromAddress

	LocalSigner  *keypair.Full
	RemoteSigner *keypair.FromAddress
}

Config contains the information for setting up a new channel.

type OpenAgreement 

type OpenAgreement struct {
	Envelope          OpenEnvelope
	Transactions      OpenTransactions
	CloseTransactions CloseTransactions
}

OpenAgreement contains all the information known for an agreement proposed or confirmed by the channel.

func (OpenAgreement) CloseAgreement 

func (oa OpenAgreement) CloseAgreement() CloseAgreement

CloseAgreement returns the initial close agreement created at the channel open.

func (OpenAgreement) SignedTransactions 

func (oa OpenAgreement) SignedTransactions() OpenTransactions

SignedTransactions returns the OpenTransactions with added signatures from the OpenAgreement's Envelope.

type OpenDetails 

type OpenDetails struct {
	ObservationPeriodTime      time.Duration
	ObservationPeriodLedgerGap uint32
	Asset                      Asset
	ExpiresAt                  time.Time
	StartingSequence           int64
	ProposingSigner            *keypair.FromAddress
	ConfirmingSigner           *keypair.FromAddress
}

OpenDetails contain the details participants agree on for opening a channel.

func (OpenDetails) Equal 

func (d OpenDetails) Equal(d2 OpenDetails) bool

Equal returns true if two OpenDetails are equal, else false.

type OpenEnvelope 

type OpenEnvelope struct {
	Details             OpenDetails
	ProposerSignatures  OpenSignatures
	ConfirmerSignatures OpenSignatures
}

OpenEnvelope contains everything a participant needs to execute the open agreement on the Stellar network.

func (OpenEnvelope) CloseEnvelope 

func (oe OpenEnvelope) CloseEnvelope() CloseEnvelope

CloseEnvelope gets the equivalent CloseEnvelope for this OpenEnvelope.

func (OpenEnvelope) Empty 

func (oa OpenEnvelope) Empty() bool

Empty returns true if the OpenEnvelope has no data, else false.

func (OpenEnvelope) Equal 

func (oa OpenEnvelope) Equal(oa2 OpenEnvelope) bool

Equal returns true if two OpenEnvelope are equal, else false.

func (OpenEnvelope) HasAllSignatures 

func (oa OpenEnvelope) HasAllSignatures() bool

HasAllSignatures checks if the open agreement has the max amount of signatures, indicating it is fully signed by all parties.

func (OpenEnvelope) SignaturesFor 

func (oa OpenEnvelope) SignaturesFor(signer *keypair.FromAddress) *OpenSignatures

SignaturesFor returns the signatures currently held for the given signer, if any.

type OpenParams 

type OpenParams struct {
	ObservationPeriodTime      time.Duration
	ObservationPeriodLedgerGap uint32
	Asset                      Asset
	ExpiresAt                  time.Time
	StartingSequence           int64
}

OpenParams are the parameters selected by the participant proposing an open channel.

type OpenSignatures 

type OpenSignatures struct {
	Close       xdr.Signature
	Declaration xdr.Signature
	Open        xdr.Signature
}

OpenSignatures holds the signatures for an open agreement.

func (OpenSignatures) Empty 

func (oas OpenSignatures) Empty() bool

Empty returns true if there are not any signatures present, else false.

func (OpenSignatures) Equal 

func (oas OpenSignatures) Equal(oas2 OpenSignatures) bool

Equal returns true if two OpenSignatures are equal, else false.

func (OpenSignatures) HasAllSignatures 

func (oas OpenSignatures) HasAllSignatures() bool

HasAllSignatures returns true if there is a signature for each transaction type present, else false.

func (OpenSignatures) Verify 

func (s OpenSignatures) Verify(txs OpenTransactions, closeTxs CloseTransactions, signer *keypair.FromAddress) error

Verify returns true if the given open and close transactions, signed by the given signer, resulted in these OpenSignatures, else false.

type OpenTransactions 

type OpenTransactions struct {
	OpenHash TransactionHash
	Open     *txnbuild.Transaction
}

OpenTransactions contain all the transaction hashes and transactions that make up the open agreement.

type Snapshot 

type Snapshot struct {
	LocalChannelAccountSequence                    int64
	LocalChannelAccountBalance                     int64
	LocalChannelAccountLastSeenTransactionOrderID  int64
	RemoteChannelAccountSequence                   int64
	RemoteChannelAccountBalance                    int64
	RemoteChannelAccountLastSeenTransactionOrderID int64

	OpenAgreement            OpenAgreement
	OpenExecutedAndValidated bool
	OpenExecutedWithError    bool

	LatestAuthorizedCloseAgreement   CloseAgreement
	LatestUnauthorizedCloseAgreement CloseAgreement
}

Snapshot is a snapshot of a Channel's internal state. If a Snapshot is combined with a Channel's initialization config they can be used to create a new Channel that has the same state.

type State 

type State int
const (
	StateError State = iota - 1
	StateNone
	StateOpen
	StateClosingWithOutdatedState
	StateClosedWithOutdatedState
	StateClosing
	StateClosed
)

type TransactionHash 

type TransactionHash [32]byte

func (TransactionHash) MarshalText 

func (h TransactionHash) MarshalText() ([]byte, error)

func (TransactionHash) String 

func (h TransactionHash) String() string

func (*TransactionHash) UnmarshalText 

func (h *TransactionHash) UnmarshalText(text []byte) error

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.