wtwire

package
v0.17.4-beta.rc1 Latest Latest
Warning

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

 Go to latest Published: Jan 30, 2024 License: MIT Imports: 11 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// AltruistSessionsRequired specifies that the advertising node requires
	// the remote party to understand the protocol for creating and updating
	// watchtower sessions.
	AltruistSessionsRequired lnwire.FeatureBit = 0

	// AltruistSessionsOptional specifies that the advertising node can
	// support a remote party who understand the protocol for creating and
	// updating watchtower sessions.
	AltruistSessionsOptional lnwire.FeatureBit = 1

	// AnchorCommitRequired specifies that the advertising tower requires
	// the remote party to negotiate sessions for protecting anchor
	// channels.
	AnchorCommitRequired lnwire.FeatureBit = 2

	// AnchorCommitOptional specifies that the advertising tower allows the
	// remote party to negotiate sessions for protecting anchor channels.
	AnchorCommitOptional lnwire.FeatureBit = 3
)
View Source 
const MaxCreateSessionReplyDataLength = 1024

MaxCreateSessionReplyDataLength is the maximum size of the Data payload returned in a CreateSessionReply message. This does not include the length of the Data field, which is a varint up to 3 bytes in size.

View Source 
const MaxMessagePayload = 65535 // 65KB

MaxMessagePayload is the maximum bytes a message can be regardless of other individual limits imposed by messages themselves.

Variables

View Source 
var FeatureNames = map[lnwire.FeatureBit]string{
	AltruistSessionsRequired: "altruist-sessions",
	AltruistSessionsOptional: "altruist-sessions",
	AnchorCommitRequired:     "anchor-commit",
	AnchorCommitOptional:     "anchor-commit",
}

FeatureNames holds a mapping from each feature bit understood by this implementation to its common name.

Functions

func MessageSummary 

func MessageSummary(msg Message) string

MessageSummary creates a human-readable description of a given Message. If the type is unknown, an empty string is returned.

func ReadElement 

func ReadElement(r io.Reader, element interface{}) error

ReadElement is a one-stop utility function to deserialize any datastructure encoded using the serialization format of lnwire.

func ReadElements 

func ReadElements(r io.Reader, elements ...interface{}) error

ReadElements deserializes a variable number of elements into the passed io.Reader, with each element being deserialized according to the ReadElement function.

func WriteElement 

func WriteElement(w io.Writer, element interface{}) error

WriteElement is a one-stop shop to write the big endian representation of any element which is to be serialized for the wire protocol. The passed io.Writer should be backed by an appropriately sized byte slice, or be able to dynamically expand to accommodate additional data.

func WriteElements 

func WriteElements(w io.Writer, elements ...interface{}) error

WriteElements is writes each element in the elements slice to the passed io.Writer using WriteElement.

func WriteMessage 

func WriteMessage(w io.Writer, msg Message, pver uint32) (int, error)

WriteMessage writes a lightning Message to w including the necessary header information and returns the number of bytes written.

Types

type CreateSession 

type CreateSession struct {
	// BlobType specifies the blob format that must be used by all updates sent
	// under the session key used to negotiate this session.
	BlobType blob.Type

	// MaxUpdates is the maximum number of updates the watchtower will honor
	// for this session.
	MaxUpdates uint16

	// RewardBase is the fixed amount allocated to the tower when the
	// policy's blob type specifies a reward for the tower. This is taken
	// before adding the proportional reward.
	RewardBase uint32

	// RewardRate is the fraction of the total balance of the revoked
	// commitment that the watchtower is entitled to. This value is
	// expressed in millionths of the total balance.
	RewardRate uint32

	// SweepFeeRate expresses the intended fee rate to be used when
	// constructing the justice transaction. All sweep transactions created
	// for this session must use this value during construction, and the
	// signatures must implicitly commit to the resulting output values.
	SweepFeeRate chainfee.SatPerKWeight
}

CreateSession is sent from a client to tower when to negotiate a session, which specifies the total number of updates that can be made, as well as fee rates. An update is consumed by uploading an encrypted blob that contains information required to sweep a revoked commitment transaction.

func (*CreateSession) Decode 

func (m *CreateSession) Decode(r io.Reader, pver uint32) error

Decode deserializes a serialized CreateSession message stored in the passed io.Reader observing the specified protocol version.

This is part of the wtwire.Message interface.

func (*CreateSession) Encode 

func (m *CreateSession) Encode(w io.Writer, pver uint32) error

Encode serializes the target CreateSession into the passed io.Writer observing the protocol version specified.

This is part of the wtwire.Message interface.

func (*CreateSession) MaxPayloadLength 

func (m *CreateSession) MaxPayloadLength(uint32) uint32

MaxPayloadLength returns the maximum allowed payload size for a CreateSession complete message observing the specified protocol version.

This is part of the wtwire.Message interface.

func (*CreateSession) MsgType 

func (m *CreateSession) MsgType() MessageType

MsgType returns the integer uniquely identifying this message type on the wire.

This is part of the wtwire.Message interface.

type CreateSessionCode 

type CreateSessionCode = ErrorCode

CreateSessionCode is an error code returned by a watchtower in response to a CreateSession message. The code directs the client in interpreting the payload in the reply. 

const (
	// CreateSessionCodeAlreadyExists is returned when a session is already
	// active for the public key used to connect to the watchtower. The
	// response includes the serialized reward address in case the original
	// reply was never received and/or processed by the client.
	CreateSessionCodeAlreadyExists CreateSessionCode = 60

	// CreateSessionCodeRejectMaxUpdates the tower rejected the maximum
	// number of state updates proposed by the client.
	CreateSessionCodeRejectMaxUpdates CreateSessionCode = 61

	// CreateSessionCodeRejectRewardRate the tower rejected the reward rate
	// proposed by the client.
	CreateSessionCodeRejectRewardRate CreateSessionCode = 62

	// CreateSessionCodeRejectSweepFeeRate the tower rejected the sweep fee
	// rate proposed by the client.
	CreateSessionCodeRejectSweepFeeRate CreateSessionCode = 63

	// CreateSessionCodeRejectBlobType is returned when the tower does not
	// support the proposed blob type.
	CreateSessionCodeRejectBlobType CreateSessionCode = 64
)

type CreateSessionReply 

type CreateSessionReply struct {
	// Code will be non-zero if the watchtower rejected the session init.
	Code CreateSessionCode

	// LastApplied is the tower's last accepted sequence number for the
	// session. This is useful when the session already exists but the
	// client doesn't realize it's already used the session, such as after a
	// restoration.
	LastApplied uint16

	// Data is a byte slice returned the caller of the message, and is to be
	// interpreted according to the error Code. When the response is
	// CreateSessionCodeOK, data encodes the reward address to be included in
	// any sweep transactions if the reward is not dusty. Otherwise, it may
	// encode the watchtowers configured parameters for any policy
	// rejections.
	Data []byte
}

CreateSessionReply is a message sent from watchtower to client in response to a CreateSession message, and signals either an acceptance or rejection of the proposed session parameters.

func (*CreateSessionReply) Decode 

func (m *CreateSessionReply) Decode(r io.Reader, pver uint32) error

Decode deserializes a serialized CreateSessionReply message stored in the passed io.Reader observing the specified protocol version.

This is part of the wtwire.Message interface.

func (*CreateSessionReply) Encode 

func (m *CreateSessionReply) Encode(w io.Writer, pver uint32) error

Encode serializes the target CreateSessionReply into the passed io.Writer observing the protocol version specified.

This is part of the wtwire.Message interface.

func (*CreateSessionReply) MaxPayloadLength 

func (m *CreateSessionReply) MaxPayloadLength(uint32) uint32

MaxPayloadLength returns the maximum allowed payload size for a CreateSessionReply complete message observing the specified protocol version.

This is part of the wtwire.Message interface.

func (*CreateSessionReply) MsgType 

func (m *CreateSessionReply) MsgType() MessageType

MsgType returns the integer uniquely identifying this message type on the wire.

This is part of the wtwire.Message interface.

type DeleteSession 

type DeleteSession struct{}

DeleteSession is sent from the client to the tower to signal that the tower can delete all session state for the session key used to authenticate the brontide connection. This should be done by the client once all channels that have state updates in the session have been resolved on-chain.

func (*DeleteSession) Decode 

func (m *DeleteSession) Decode(r io.Reader, pver uint32) error

Decode deserializes a serialized DeleteSession message stored in the passed io.Reader observing the specified protocol version.

This is part of the wtwire.Message interface.

func (*DeleteSession) Encode 

func (m *DeleteSession) Encode(w io.Writer, pver uint32) error

Encode serializes the target DeleteSession message into the passed io.Writer observing the specified protocol version.

This is part of the wtwire.Message interface.

func (*DeleteSession) MaxPayloadLength 

func (m *DeleteSession) MaxPayloadLength(uint32) uint32

MaxPayloadLength returns the maximum allowed payload size for a DeleteSession message observing the specified protocol version.

This is part of the wtwire.Message interface.

func (*DeleteSession) MsgType 

func (m *DeleteSession) MsgType() MessageType

MsgType returns the integer uniquely identifying this message type on the wire.

This is part of the wtwire.Message interface.

type DeleteSessionCode 

type DeleteSessionCode = ErrorCode

DeleteSessionCode is an error code returned by a watchtower in response to a DeleteSession message. 

const (
	// DeleteSessionCodeNotFound is returned when the watchtower does not
	// know of the requested session. This may indicate an error on the
	// client side, or that the tower had already deleted the session in a
	// prior request that the client may not have received.
	DeleteSessionCodeNotFound DeleteSessionCode = 80
)

type DeleteSessionReply 

type DeleteSessionReply struct {
	// Code will be non-zero if the watchtower was not able to delete the
	// requested session.
	Code DeleteSessionCode
}

DeleteSessionReply is a message sent in response to a client's DeleteSession request. The message indicates whether the deletion was a success or failure.

func (*DeleteSessionReply) Decode 

func (m *DeleteSessionReply) Decode(r io.Reader, pver uint32) error

Decode deserializes a serialized DeleteSessionReply message stored in the passed io.Reader observing the specified protocol version.

This is part of the wtwire.Message interface.

func (*DeleteSessionReply) Encode 

func (m *DeleteSessionReply) Encode(w io.Writer, pver uint32) error

Encode serializes the target DeleteSessionReply into the passed io.Writer observing the protocol version specified.

This is part of the wtwire.Message interface.

func (*DeleteSessionReply) MaxPayloadLength 

func (m *DeleteSessionReply) MaxPayloadLength(uint32) uint32

MaxPayloadLength returns the maximum allowed payload size for a DeleteSessionReply complete message observing the specified protocol version.

This is part of the wtwire.Message interface.

func (*DeleteSessionReply) MsgType 

func (m *DeleteSessionReply) MsgType() MessageType

MsgType returns the integer uniquely identifying this message type on the wire.

This is part of the wtwire.Message interface.

type ErrUnknownChainHash 

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

ErrUnknownChainHash signals that the remote Init has a different chain hash from the one we advertised.

func NewErrUnknownChainHash 

func NewErrUnknownChainHash(hash chainhash.Hash) *ErrUnknownChainHash

NewErrUnknownChainHash creates an ErrUnknownChainHash using the remote Init's chain hash.

func (*ErrUnknownChainHash) Error 

func (e *ErrUnknownChainHash) Error() string

Error returns a human-readable error displaying the unknown chain hash.

type Error 

type Error struct {
	// Code specifies the error code encountered by the server.
	Code ErrorCode

	// Data encodes a payload whose contents can be interpreted by the
	// client in response to the error code.
	Data []byte
}

Error is a generic error message that can be sent to a client if a request fails outside of prescribed protocol errors. Typically this would be followed by the server disconnecting the client, and so can be useful to transferring the exact reason.

func NewError 

func NewError() *Error

NewError returns an freshly-initialized Error message.

func (*Error) Decode 

func (e *Error) Decode(r io.Reader, pver uint32) error

Decode deserializes a serialized Error message stored in the passed io.Reader observing the specified protocol version.

This is part of the wtwire.Message interface.

func (*Error) Encode 

func (e *Error) Encode(w io.Writer, prver uint32) error

Encode serializes the target Error into the passed io.Writer observing the protocol version specified.

This is part of the wtwire.Message interface.

func (*Error) MaxPayloadLength 

func (e *Error) MaxPayloadLength(uint32) uint32

MaxPayloadLength returns the maximum allowed payload size for a Error complete message observing the specified protocol version.

This is part of the wtwire.Message interface.

func (*Error) MsgType 

func (e *Error) MsgType() MessageType

MsgType returns the integer uniquely identifying this message type on the wire.

This is part of the wtwire.Message interface.

type ErrorCode 

type ErrorCode uint16

ErrorCode represents a generic error code used when replying to watchtower clients. Specific reply messages may extend the ErrorCode primitive and add custom codes, so long as they don't collide with the generic error codes.. 

const (
	// CodeOK signals that the request was successfully processed by the
	// watchtower.
	CodeOK ErrorCode = 0

	// CodeTemporaryFailure alerts the client that the watchtower is
	// temporarily unavailable, but that it may try again at a later time.
	CodeTemporaryFailure ErrorCode = 40

	// CodePermanentFailure alerts the client that the watchtower has
	// permanently failed, and further communication should be avoided.
	CodePermanentFailure ErrorCode = 50
)

func (ErrorCode) String 

func (c ErrorCode) String() string

String returns a human-readable description of an ErrorCode.

type Init 

type Init struct {
	// ConnFeatures are the feature bits being advertised for the duration
	// of a single connection with a peer.
	ConnFeatures *lnwire.RawFeatureVector

	// ChainHash is the genesis hash of the chain that the advertiser claims
	// to be on.
	ChainHash chainhash.Hash
}

Init is the first message sent over the watchtower wire protocol, and specifies connection features bits and level of requiredness maintained by the sending node. The Init message also sends the chain hash identifying the network that the sender is on.

func NewInitMessage 

func NewInitMessage(connFeatures *lnwire.RawFeatureVector,
	chainHash chainhash.Hash) *Init

NewInitMessage generates a new Init message from a raw connection feature vector and chain hash.

func (*Init) CheckRemoteInit 

func (msg *Init) CheckRemoteInit(remoteInit *Init,
	featureNames map[lnwire.FeatureBit]string) error

CheckRemoteInit performs basic validation of the remote party's Init message. This method checks that the remote Init's chain hash matches our advertised chain hash and that the remote Init does not contain any required feature bits that we don't understand.

func (*Init) Decode 

func (msg *Init) Decode(r io.Reader, pver uint32) error

Decode deserializes a serialized Init message stored in the passed io.Reader observing the specified protocol version.

This is part of the wtwire.Message interface.

func (*Init) Encode 

func (msg *Init) Encode(w io.Writer, pver uint32) error

Encode serializes the target Init into the passed io.Writer observing the protocol version specified.

This is part of the wtwire.Message interface.

func (*Init) MaxPayloadLength 

func (msg *Init) MaxPayloadLength(uint32) uint32

MaxPayloadLength returns the maximum allowed payload size for an Init complete message observing the specified protocol version.

This is part of the wtwire.Message interface.

func (*Init) MsgType 

func (msg *Init) MsgType() MessageType

MsgType returns the integer uniquely identifying this message type on the wire.

This is part of the wtwire.Message interface.

type Message 

type Message interface {
	Serializable

	// MsgType returns a MessageType that uniquely identifies the message to
	// be encoded.
	MsgType() MessageType

	// MaxMessagePayload is the maximum serialized length that a particular
	// message type can take.
	MaxPayloadLength(uint32) uint32
}

Message is an interface that defines a lightning wire protocol message. The interface is general in order to allow implementing types full control over the representation of its data.

func ReadMessage 

func ReadMessage(r io.Reader, pver uint32) (Message, error)

ReadMessage reads, validates, and parses the next Watchtower message from r for the provided protocol version.

type MessageType 

type MessageType uint16

MessageType is the unique 2 byte big-endian integer that indicates the type of message on the wire. All messages have a very simple header which consists simply of 2-byte message type. We omit a length field, and checksum as the Watchtower Protocol is intended to be encapsulated within a confidential+authenticated cryptographic messaging protocol. 

const (
	// MsgInit identifies an encoded Init message.
	MsgInit MessageType = 600

	// MsgError identifies an encoded Error message.
	MsgError MessageType = 601

	// MsgCreateSession identifies an encoded CreateSession message.
	MsgCreateSession MessageType = 602

	// MsgCreateSessionReply identifies an encoded CreateSessionReply message.
	MsgCreateSessionReply MessageType = 603

	// MsgStateUpdate identifies an encoded StateUpdate message.
	MsgStateUpdate MessageType = 604

	// MsgStateUpdateReply identifies an encoded StateUpdateReply message.
	MsgStateUpdateReply MessageType = 605

	// MsgDeleteSession identifies an encoded DeleteSession message.
	MsgDeleteSession MessageType = 606

	// MsgDeleteSessionReply identifies an encoded DeleteSessionReply
	// message.
	MsgDeleteSessionReply MessageType = 607
)

The currently defined message types within this current version of the Watchtower protocol.

func (MessageType) String 

func (m MessageType) String() string

String returns a human readable description of the message type.

type Serializable 

type Serializable interface {
	// Decode reads the bytes stream and converts it to the object.
	Decode(io.Reader, uint32) error

	// Encode converts object to the bytes stream and write it into the
	// write buffer.
	Encode(io.Writer, uint32) error
}

Serializable is an interface which defines a lightning wire serializable object.

type StateUpdate 

type StateUpdate struct {
	// SeqNum is a 1-indexed, monotonically incrementing sequence number.
	// This number represents to the client's expected sequence number when
	// sending updates sent to the watchtower. This value must always be
	// less or equal than the negotiated MaxUpdates for the session, and
	// greater than the LastApplied sent in the same message.
	SeqNum uint16

	// LastApplied echos the LastApplied value returned from watchtower,
	// allowing the tower to detect faulty clients. This allow provides a
	// feedback mechanism for the tower if updates are allowed to stream in
	// an async fashion.
	LastApplied uint16

	// IsComplete is 1 if the watchtower should close the connection after
	// responding, and 0 otherwise.
	IsComplete uint8

	// Hint is the 16-byte prefix of the revoked commitment transaction ID
	// for which the encrypted blob can exact justice.
	Hint [16]byte

	// EncryptedBlob is the serialized ciphertext containing all necessary
	// information to sweep the commitment transaction corresponding to the
	// Hint. The ciphertext is to be encrypted using the full transaction ID
	// of the revoked commitment transaction.
	//
	// The plaintext MUST be encoded using the negotiated Version for
	// this session. In addition, the signatures must be computed over a
	// sweep transaction honoring the decided SweepFeeRate, RewardRate, and
	// (possibly) reward address returned in the SessionInitReply.
	EncryptedBlob []byte
}

StateUpdate transmits an encrypted state update from the client to the watchtower. Each state update is tied to particular session, identified by the client's brontide key used to make the request.

func (*StateUpdate) Decode 

func (m *StateUpdate) Decode(r io.Reader, pver uint32) error

Decode deserializes a serialized StateUpdate message stored in the passed io.Reader observing the specified protocol version.

This is part of the wtwire.Message interface.

func (*StateUpdate) Encode 

func (m *StateUpdate) Encode(w io.Writer, pver uint32) error

Encode serializes the target StateUpdate into the passed io.Writer observing the protocol version specified.

This is part of the wtwire.Message interface.

func (*StateUpdate) MaxPayloadLength 

func (m *StateUpdate) MaxPayloadLength(uint32) uint32

MaxPayloadLength returns the maximum allowed payload size for a StateUpdate complete message observing the specified protocol version.

This is part of the wtwire.Message interface.

func (*StateUpdate) MsgType 

func (m *StateUpdate) MsgType() MessageType

MsgType returns the integer uniquely identifying this message type on the wire.

This is part of the wtwire.Message interface.

type StateUpdateCode 

type StateUpdateCode = ErrorCode

StateUpdateCode is an error code returned by a watchtower in response to a StateUpdate message. 

const (
	// StateUpdateCodeClientBehind signals that the client's sequence number
	// is behind what the watchtower expects based on its LastApplied. This
	// error should cause the client to record the LastApplied field in the
	// response, and initiate another attempt with the proper sequence
	// number.
	//
	// NOTE: Repeated occurrences of this could be interpreted as an attempt
	// to siphon state updates from the client. If the client believes it
	// is not violating the protocol, this could be grounds to blacklist
	// this tower from future session negotiation.
	StateUpdateCodeClientBehind StateUpdateCode = 70

	// StateUpdateCodeMaxUpdatesExceeded signals that the client tried to
	// send a sequence number beyond the negotiated MaxUpdates of the
	// session.
	StateUpdateCodeMaxUpdatesExceeded StateUpdateCode = 71

	// StateUpdateCodeSeqNumOutOfOrder signals the client sent an update
	// that does not follow the required incremental monotonicity required
	// by the tower.
	StateUpdateCodeSeqNumOutOfOrder StateUpdateCode = 72
)

type StateUpdateReply 

type StateUpdateReply struct {
	// Code will be non-zero if the watchtower rejected the state update.
	Code StateUpdateCode

	// LastApplied returns the sequence number of the last accepted update
	// known to the watchtower. If the update was successful, this value
	// should be the sequence number of the last update sent.
	LastApplied uint16
}

StateUpdateReply is a message sent from watchtower to client in response to a StateUpdate message, and signals either an acceptance or rejection of the proposed state update.

func (*StateUpdateReply) Decode 

func (t *StateUpdateReply) Decode(r io.Reader, pver uint32) error

Decode deserializes a serialized StateUpdateReply message stored in the passed io.Reader observing the specified protocol version.

This is part of the wtwire.Message interface.

func (*StateUpdateReply) Encode 

func (t *StateUpdateReply) Encode(w io.Writer, pver uint32) error

Encode serializes the target StateUpdateReply into the passed io.Writer observing the protocol version specified.

This is part of the wtwire.Message interface.

func (*StateUpdateReply) MaxPayloadLength 

func (t *StateUpdateReply) MaxPayloadLength(uint32) uint32

MaxPayloadLength returns the maximum allowed payload size for a StateUpdateReply complete message observing the specified protocol version.

This is part of the wtwire.Message interface.

func (*StateUpdateReply) MsgType 

func (t *StateUpdateReply) MsgType() MessageType

MsgType returns the integer uniquely identifying this message type on the wire.

This is part of the wtwire.Message interface.

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.