wtwire

package
v0.5.1-beta-rc1 Latest Latest
Warning

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

 Go to latest Published: Nov 15, 2018 License: MIT Imports: 8 Imported by: 0

Documentation

Index

Constants

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

	// WtSessionsOptional specifies that the advertising node can support
	// a remote party who understand the protocol for creating and updating
	// watchtower sessions.
	WtSessionsOptional lnwire.FeatureBit = 9
)
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 GlobalFeatures map[lnwire.FeatureBit]string

GlobalFeatures holds the globally advertised feature bits understood by watchtower implementations.

View Source 
var LocalFeatures = map[lnwire.FeatureBit]string{
	WtSessionsRequired: "wt-sessions-required",
	WtSessionsOptional: "wt-sessions-optional",
}

LocalFeatures holds the locally advertised feature bits understood by watchtower implementations.

Functions

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 {
	// BlobVersion specifies the blob format that must be used by all
	// updates sent under the session key used to negotiate this session.
	BlobVersion uint16

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

	// 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 lnwallet.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

	// CreateSessionCodeRejectRejectMaxUpdates the tower rejected the maximum
	// number of state updates proposed by the client.
	CreateSessionCodeRejectRejectMaxUpdates 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
)

type CreateSessionReply 

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

	// 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 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 transfering 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
)

type Init 

type Init struct {
	*lnwire.Init
}

Init is the first message sent over the watchtower wire protocol, and specifies features and level of requiredness maintained by the sending node. The watchtower Init message is identical to the LN Init message, except it uses a different message type to ensure the two are not conflated.

func NewInitMessage 

func NewInitMessage(gf, lf *lnwire.RawFeatureVector) *Init

NewInitMessage generates a new Init message from raw global and local feature vectors.

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 = 300

	// MsgError identifies an encoded Error message.
	MsgError = 301

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

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

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

	// MsgStateUpdateReply identifies an encoded StateUpdateReply message.
	MsgStateUpdateReply MessageType = 305
)

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 = lnwire.Serializable

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 brontine 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.