wtdb

Documentation

Index

• Constants
• Variables
• type BreachHint
  • func NewBreachHintFromHash(hash *chainhash.Hash) BreachHint
  • func (h BreachHint) String() string
• type Match
• type SessionID
  • func NewSessionIDFromPubKey(pubKey *btcec.PublicKey) SessionID
  • func (s SessionID) String() string
• type SessionInfo
  • func (s *SessionInfo) AcceptUpdateSequence(seqNum, lastApplied uint16) error
  • func (s *SessionInfo) ComputeSweepOutputs(totalAmt btcutil.Amount, txVSize int64) (btcutil.Amount, btcutil.Amount, error)
• type SessionStateUpdate

Constants

const BreachHintSize = 16

BreachHintSize is the length of the txid prefix used to identify remote commitment broadcasts.

const SessionIDSize = 33

SessionIDSize is 33-bytes; it is a serialized, compressed public key.

Variables

var (
	// ErrSessionNotFound is returned when querying by session id for a
	// session that does not exist.
	ErrSessionNotFound = errors.New("session not found in db")

	// ErrSessionAlreadyExists signals that a session creation failed
	// because a session with the same session id already exists.
	ErrSessionAlreadyExists = errors.New("session already exists")

	// ErrUpdateOutOfOrder is returned when the sequence number is not equal
	// to the server's LastApplied+1.
	ErrUpdateOutOfOrder = errors.New("update sequence number is not " +
		"sequential")

	// ErrLastAppliedReversion is returned when the client echos a
	// last-applied value that is less than it claimed in a prior update.
	ErrLastAppliedReversion = errors.New("update last applied must be " +
		"non-decreasing")

	// ErrSeqNumAlreadyApplied is returned when the client sends a sequence
	// number for which they already claim to have an ACK.
	ErrSeqNumAlreadyApplied = errors.New("update sequence number has " +
		"already been applied")

	// ErrSessionConsumed is returned if the client tries to send a sequence
	// number larger than the session's max number of updates.
	ErrSessionConsumed = errors.New("all session updates have been " +
		"consumed")

	// ErrFeeExceedsInputs signals that the total input value of breaching
	// commitment txn is insufficient to cover the fees required to sweep
	// it.
	ErrFeeExceedsInputs = errors.New("sweep fee exceeds input values")
)

Types

type BreachHint

type BreachHint [BreachHintSize]byte

BreachHint is the first 16-bytes of the txid belonging to a revoked commitment transaction.

func NewBreachHintFromHash

func NewBreachHintFromHash(hash *chainhash.Hash) BreachHint

NewBreachHintFromHash creates a breach hint from a transaction ID.

func (BreachHint) String

func (h BreachHint) String() string

String returns a hex encoding of the breach hint.

type Match

type Match struct {
	// ID is the session id of the client who uploaded the state update.
	ID SessionID

	// SeqNum is the session sequence number occupied by the client's state
	// update. Together with ID, this allows the tower to derive the
	// appropriate nonce for decryption.
	SeqNum uint16

	// Hint is the breach hint that triggered the match.
	Hint BreachHint

	// EncryptedBlob is the encrypted payload containing the justice kit
	// uploaded by the client.
	EncryptedBlob []byte

	// SessionInfo is the contract negotiated between tower and client, that
	// provides input parameters such as fee rate, reward rate, and reward
	// address when attempting to reconstruct the justice transaction.
	SessionInfo *SessionInfo
}

Match is returned in response to a database query for a breach hints contained in a particular block. The match encapsulates all data required to properly decrypt a client's encrypted blob, and pursue action on behalf of the victim by reconstructing the justice transaction and broadcasting it to the network.

NOTE: It is possible for a match to cause a false positive, since they are matched on a prefix of the txid. In such an event, the likely behavior is that the payload will fail to decrypt.

type SessionID

type SessionID [SessionIDSize]byte

SessionID is created from the remote public key of a client, and serves as a unique identifier and authentication for sending state updates.

func NewSessionIDFromPubKey

func NewSessionIDFromPubKey(pubKey *btcec.PublicKey) SessionID

NewSessionIDFromPubKey creates a new SessionID from a public key.

func (SessionID) String

func (s SessionID) String() string

String returns a hex encoding of the session id.

type SessionInfo

type SessionInfo struct {
	// ID is the remote public key of the watchtower client.
	ID SessionID

	// Version specifies the plaintext blob encoding of all state updates.
	Version uint16

	// MaxUpdates is the total number of updates the client can send for
	// this session.
	MaxUpdates uint16

	// LastApplied the sequence number of the last successful state update.
	LastApplied uint16

	// ClientLastApplied the last last-applied the client has echoed back.
	ClientLastApplied uint16

	// RewardRate the fraction of the swept amount that goes to the tower,
	// expressed in millionths of the swept balance.
	RewardRate uint32

	// SweepFeeRate is the agreed upon fee rate used to sign any sweep
	// transactions.
	SweepFeeRate lnwallet.SatPerKWeight

	// RewardAddress the address that the tower's reward will be deposited
	// to if a sweep transaction confirms.
	RewardAddress []byte
}

SessionInfo holds the negotiated session parameters for single session id, and handles the acceptance and validation of state updates sent by the client.

func (*SessionInfo) AcceptUpdateSequence

func (s *SessionInfo) AcceptUpdateSequence(seqNum, lastApplied uint16) error

AcceptUpdateSequence validates that a state update's sequence number and last applied are valid given our past history with the client. These checks ensure that clients are properly in sync and following the update protocol properly. If validation is successful, the receiver's LastApplied and ClientLastApplied are updated with the latest values presented by the client. Any errors returned from this method are converted into an appropriate wtwire.StateUpdateCode.

func (*SessionInfo) ComputeSweepOutputs

func (s *SessionInfo) ComputeSweepOutputs(totalAmt btcutil.Amount,
	txVSize int64) (btcutil.Amount, btcutil.Amount, error)

ComputeSweepOutputs splits the total funds in a breaching commitment transaction between the victim and the tower, according to the sweep fee rate and reward rate. The fees are first subtracted from the overall total, before splitting the remaining balance amongst the victim and tower.

type SessionStateUpdate

type SessionStateUpdate struct {
	// ID the session id of the client who sent the state update.
	ID SessionID

	// SeqNum the sequence number of the update within the session.
	SeqNum uint16

	// LastApplied the highest index that client has acknowledged is
	// committed
	LastApplied uint16

	// Hint is the 16-byte prefix of the revoked commitment transaction.
	Hint BreachHint

	// EncryptedBlob is a ciphertext containing the sweep information for
	// exacting justice if the commitment transaction matching the breach
	// hint is braodcast.
	EncryptedBlob []byte
}

SessionStateUpdate holds a state update sent by a client along with its SessionID.