sidecar

Documentation

Index

• Variables
• func CheckOfferParams(capacity, pushAmt, baseSupplyUnit btcutil.Amount) error
• func CheckOfferParamsForOrder(offer Offer, bidAmt, bidMinUnitsMatch, baseSupplyUnit btcutil.Amount) error
• func DBytes8(r io.Reader, val interface{}, _ *[8]byte, l uint64) error
• func DSig(r io.Reader, val interface{}, buf *[8]byte, l uint64) error
• func EBytes8(w io.Writer, val interface{}, _ *[8]byte) error
• func ESig(w io.Writer, val interface{}, buf *[8]byte) error
• func EncodeToString(t *Ticket) (string, error)
• func SerializeTicket(w io.Writer, ticket *Ticket) error
• func SignOffer(ctx context.Context, ticket *Ticket, signingKeyLoc keychain.KeyLocator, ...) error
• func SignOrder(ctx context.Context, ticket *Ticket, bidNonce [32]byte, ...) error
• func VerifyOffer(ctx context.Context, ticket *Ticket, signer lndclient.SignerClient) error
• func VerifyOrder(ctx context.Context, ticket *Ticket, signer lndclient.SignerClient) error
• type Execution
• type Offer
• type Order
• type Recipient
• type State
  • func (s State) IsTerminal() bool
  • func (s State) String() string
• type Store
• type Ticket
  • func DecodeString(s string) (*Ticket, error)
  • func DeserializeTicket(r io.Reader) (*Ticket, error)
  • func NewTicket(version Version, capacity, pushAmt btcutil.Amount, duration uint32, ...) (*Ticket, error)
  • func (t *Ticket) OfferDigest() ([32]byte, error)
  • func (t *Ticket) OrderDigest() ([32]byte, error)
• type Version

Variables

var (
	// ZeroSignature is an empty signature with all bits set to zero.
	ZeroSignature = [64]byte{}
)

Functions

func CheckOfferParams

func CheckOfferParams(capacity, pushAmt, baseSupplyUnit btcutil.Amount) error

CheckOfferParams makes sure the offer parameters of a sidecar ticket are valid and sane.

func CheckOfferParamsForOrder

func CheckOfferParamsForOrder(offer Offer, bidAmt, bidMinUnitsMatch,
	baseSupplyUnit btcutil.Amount) error

CheckOfferParamsForOrder makes sure that the order parameters in a sidecar offer are formally valid, sane and match the order parameters.

func DBytes8

func DBytes8(r io.Reader, val interface{}, _ *[8]byte, l uint64) error

DBytes8 is a Decoder for 8-byte arrays. An error is returned if val is not a *[8]byte.

func DSig

func DSig(r io.Reader, val interface{}, buf *[8]byte, l uint64) error

DSig is a Decoder for the btcec.Signature type. An error is returned if val is not a **btcec.Signature.

func EBytes8

func EBytes8(w io.Writer, val interface{}, _ *[8]byte) error

EBytes8 is an Encoder for 8-byte arrays. An error is returned if val is not a *[8]byte.

func ESig

func ESig(w io.Writer, val interface{}, buf *[8]byte) error

ESig is an Encoder for the btcec.Signature type. An error is returned if val is not a **btcec.Signature.

func EncodeToString

func EncodeToString(t *Ticket) (string, error)

EncodeToString serializes and encodes the ticket as an URL safe string that contains a human readable prefix and a checksum.

func SerializeTicket

func SerializeTicket(w io.Writer, ticket *Ticket) error

SerializeTicket binary serializes the given ticket to the writer using the tlv format.

func SignOffer

func SignOffer(ctx context.Context, ticket *Ticket,
	signingKeyLoc keychain.KeyLocator, signer lndclient.SignerClient) error

SignOffer adds a signature over the offer digest to the given ticket.

func SignOrder

func SignOrder(ctx context.Context, ticket *Ticket, bidNonce [32]byte,
	signingKeyLoc keychain.KeyLocator, signer lndclient.SignerClient) error

SignOrder adds the order part to a ticket and signs it, adding the signature as well.

func VerifyOffer

func VerifyOffer(ctx context.Context, ticket *Ticket,
	signer lndclient.SignerClient) error

VerifyOffer verifies the state of a ticket to be in the offered state and also makes sure the offer signature is valid.

func VerifyOrder

func VerifyOrder(ctx context.Context, ticket *Ticket,
	signer lndclient.SignerClient) error

VerifyOrder verifies the state of a ticket to be in the ordered state and also makes sure the order signature is valid.

Types

type Execution

type Execution struct {
	// PendingChannelID is the pending channel ID of the currently
	// registered funding shim that was added by the recipient node to
	// receive the channel.
	PendingChannelID [32]byte
}

Execution is a struct holding information about the sidecar bid order during its execution.

type Offer

type Offer struct {
	// Capacity is the channel capacity of the sidecar channel in satoshis.
	Capacity btcutil.Amount

	// PushAmt is the amount in satoshis that will be pushed to the
	// recipient of the channel to kick start them with inbound capacity.
	// If this is non-zero then the provider must pay for the push amount as
	// well as all other costs from their Pool account. Makers can opt out
	// of supporting push amounts when submitting ask orders so this will
	// reduce the matching chances somewhat.
	PushAmt btcutil.Amount

	// LeaseDurationBlocks is the number of blocks the offered channel in
	// this offer would be leased for.
	LeaseDurationBlocks uint32

	// SignPubKey is the public key for corresponding to the private key
	// that signed the SigOfferDigest below and, in a later state, the
	// SigOrderDigest of the Order struct.
	SignPubKey *btcec.PublicKey

	// SigOfferDigest is a signature over the offer digest, signed with the
	// private key that corresponds to the SignPubKey above.
	SigOfferDigest *btcec.Signature

	// Auto determines if the provider requires that the ticket be
	// completed using an automated negotiation sequence.
	Auto bool
}

Offer is a struct holding the information that a sidecar channel provider is committing to when offering to buy a channel for the recipient. The sidecar channel flow is initiated by the provider creating a ticket and adding its signed offer to it.

type Order

type Order struct {
	// BidNonce is the order nonce of the bid order that was submitted for
	// purchasing the sidecar channel.
	BidNonce [32]byte

	// SigOrderDigest is a signature over the order digest, signed with the
	// private key that corresponds to the SignPubKey in the Offer struct.
	SigOrderDigest *btcec.Signature
}

Order is a struct holding the information about the sidecar bid order after it's been submitted by the provider.

type Recipient

type Recipient struct {
	// NodePubKey is the recipient nodes' identity public key that is
	// advertised in the bid order.
	NodePubKey *btcec.PublicKey

	// MultiSigPubKey is a public key to which the recipient node has the
	// private key to. It is the key that will be used as one of the 2-of-2
	// multisig keys of the channel funding transaction output and is
	// advertised in the bid order.
	MultiSigPubKey *btcec.PublicKey

	// MultiSigKeyIndex is the derivation index of the MultiSigPubKey.
	MultiSigKeyIndex uint32
}

Recipient is a struct holding the information about the recipient of the sidecar channel in question.

type State

type State uint8

State is the state a sidecar ticket currently is in. Each updater of the ticket is responsible for also setting the state correctly after adding their data according to their role.

const (
	// StateCreated is the state a ticket is in after it's been first
	// created and the offer information was added but not signed yet.
	StateCreated State = 0

	// StateOffered is the state a ticket is in after the offer data was
	// signed by the sidecar provider.
	StateOffered State = 1

	// StateRegistered is the state a ticket is in after the recipient has
	// registered it in their system and added their information.
	StateRegistered State = 2

	// StateOrdered is the state a ticket is in after the bid order for the
	// sidecar channel was submitted and the order information was added to
	// the ticket. The ticket now also contains a signature of the provider
	// over the order digest.
	StateOrdered State = 3

	// StateExpectingChannel is the state a ticket is in after it's been
	// returned to the channel recipient and their node was instructed to
	// start listening for batch events for it.
	StateExpectingChannel State = 4

	// StateCompleted is the state a ticket is in after the sidecar channel
	// was successfully opened and the bid order completed.
	StateCompleted State = 5

	// StateCanceled is the state a ticket is in after the sidecar channel
	// bid order was canceled by the taker.
	StateCanceled State = 6
)

func (State) IsTerminal

func (s State) IsTerminal() bool

IsTerminal returns true if the ticket is in a final state and will not be updated ever again.

func (State) String

func (s State) String() string

String returns the string representation of a sidecar ticket state.

type Store

type Store interface {
	// AddSidecar adds a record for the sidecar order to the database.
	AddSidecar(sidecar *Ticket) error

	// UpdateSidecar updates a sidecar order in the database.
	UpdateSidecar(sidecar *Ticket) error

	// Sidecar retrieves a specific sidecar by its ID and provider signing
	// key (offer signature pubkey) or returns ErrNoSidecar if it's not
	// found.
	Sidecar(id [8]byte, offerSignPubKey *btcec.PublicKey) (*Ticket, error)

	// Sidecars retrieves all known sidecar orders from the database.
	Sidecars() ([]*Ticket, error)
}

Store is the interface a persistent storage must implement for storing and retrieving sidecar tickets.

type Ticket

type Ticket struct {
	// ID is a pseudorandom identifier of the ticket.
	ID [8]byte

	// Version is the version of the ticket serialization format.
	Version Version

	// State is the current state of the ticket. The state is updated by
	// each participant and is therefore not covered in any of the signature
	// digests.
	State State

	// Offer contains the initial conditions offered by the sidecar channel
	// provider. Every ticket must start with an offer and therefore this
	// member can never be empty or nil.
	Offer Offer

	// Recipient contains the information about the receiver node of the
	// sidecar channel. This field must be set for all states greater or
	// equal to StateRegistered.
	Recipient *Recipient

	// Order contains the information about the order that was submitted for
	// leasing the sidecar channel represented by this ticket. This field
	// must be set for all states greater or equal to StateOrdered.
	Order *Order

	// Execution contains the information about the execution part of the
	// sidecar channel. This information is not meant to be exchanged
	// between the participating parties but is included in the ticket to
	// make it easy to serialize/deserialize a ticket state within the local
	// database.
	Execution *Execution
}

Ticket is a struct holding all the information for establishing/buying a sidecar channel. It is meant to be used in a PSBT like manner where each participant incrementally adds their information according to their role and the current step.

func DecodeString

func DecodeString(s string) (*Ticket, error)

DecodeString decodes and then deserializes the given sidecar ticket string.

func DeserializeTicket

func DeserializeTicket(r io.Reader) (*Ticket, error)

DeserializeTicket deserializes a ticket from the given reader, expecting the data to be encoded in the tlv format.

func NewTicket

func NewTicket(version Version, capacity, pushAmt btcutil.Amount,
	duration uint32, offerPubKey *btcec.PublicKey,
	auto bool) (*Ticket, error)

NewTicket creates a new sidecar ticket with the given version and offer information.

func (*Ticket) OfferDigest

func (t *Ticket) OfferDigest() ([32]byte, error)

OfferDigest returns a message digest over the offer fields.

func (*Ticket) OrderDigest

func (t *Ticket) OrderDigest() ([32]byte, error)

OrderDigest returns a message digest over the order fields.

type Version

type Version uint8

Version is the version of the sidecar ticket format.

const (
	// VersionDefault is the initial version of the ticket format.
	VersionDefault Version = 0
)