wtdb

package
v0.18.2-beta Latest Latest
Warning

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

 Go to latest Published: Jul 8, 2024 License: MIT Imports: 31 Imported by: 0

Documentation

Index

Constants

View Source 
const SessionIDSize = 33

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

View Source 
const (
	// TowerStatusTLVType is the TLV type number that will be used to store
	// the tower's status.
	TowerStatusTLVType = tlv.Type(0)
)

Variables

View Source 
var (

	// ErrTowerNotFound signals that the target tower was not found in the
	// database.
	ErrTowerNotFound = errors.New("tower not found")

	// ErrTowerUnackedUpdates is an error returned when we attempt to mark a
	// tower's sessions as inactive, but one of its sessions has unacked
	// updates.
	ErrTowerUnackedUpdates = errors.New("tower has unacked updates")

	// ErrCorruptClientSession signals that the client session's on-disk
	// structure deviates from what is expected.
	ErrCorruptClientSession = errors.New("client session corrupted")

	// ErrCorruptChanDetails signals that the clients channel detail's
	// on-disk structure deviates from what is expected.
	ErrCorruptChanDetails = errors.New("channel details corrupted")

	// ErrClientSessionAlreadyExists signals an attempt to reinsert a client
	// session that has already been created.
	ErrClientSessionAlreadyExists = errors.New(
		"client session already exists",
	)

	// ErrChannelAlreadyRegistered signals a duplicate attempt to register a
	// channel with the client database.
	ErrChannelAlreadyRegistered = errors.New("channel already registered")

	// ErrChannelNotRegistered signals a channel has not yet been registered
	// in the client database.
	ErrChannelNotRegistered = errors.New("channel not registered")

	// ErrClientSessionNotFound signals that the requested client session
	// was not found in the database.
	ErrClientSessionNotFound = errors.New("client session not found")

	// ErrUpdateAlreadyCommitted signals that the chosen sequence number has
	// already been committed to an update with a different breach hint.
	ErrUpdateAlreadyCommitted = errors.New("update already committed")

	// ErrCommitUnorderedUpdate signals the client tried to commit a
	// sequence number other than the next unallocated sequence number.
	ErrCommitUnorderedUpdate = errors.New("update seqnum not monotonic")

	// ErrCommittedUpdateNotFound signals that the tower tried to ACK a
	// sequence number that has not yet been allocated by the client.
	ErrCommittedUpdateNotFound = errors.New("committed update not found")

	// ErrUnallocatedLastApplied signals that the tower tried to provide a
	// LastApplied value greater than any allocated sequence number.
	ErrUnallocatedLastApplied = errors.New("tower echoed last appiled " +
		"greater than allocated seqnum")

	// ErrNoReservedKeyIndex signals that a client session could not be
	// created because no session key index was reserved.
	ErrNoReservedKeyIndex = errors.New("key index not reserved")

	// ErrIncorrectKeyIndex signals that the client session could not be
	// created because session key index differs from the reserved key
	// index.
	ErrIncorrectKeyIndex = errors.New("incorrect key index")

	// ErrLastTowerAddr is an error returned when the last address of a
	// watchtower is attempted to be removed.
	ErrLastTowerAddr = errors.New("cannot remove last tower address")

	// ErrNoRangeIndexFound is returned when there is no persisted
	// range-index found for the given session ID to channel ID pair.
	ErrNoRangeIndexFound = errors.New("no range index found for the " +
		"given session-channel pair")

	// ErrSessionFailedFilterFn indicates that a particular session did
	// not pass the filter func provided by the caller.
	ErrSessionFailedFilterFn = errors.New("session failed filter func")

	// ErrSessionNotClosable is returned when a session is not found in the
	// closable list.
	ErrSessionNotClosable = errors.New("session is not closable")

	// ErrSessionHasUnackedUpdates is an error used to indicate that a
	// session has un-acked updates.
	ErrSessionHasUnackedUpdates = errors.New("session has un-acked updates")
)
View Source 
var (

	// ErrUninitializedDB signals that top-level buckets for the database
	// have not been initialized.
	ErrUninitializedDB = errors.New("db not initialized")

	// ErrNoDBVersion signals that the database contains no version info.
	ErrNoDBVersion = errors.New("db has no version")
)
View Source 
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")
)
View Source 
var (

	// ErrNoSessionHintIndex signals that an active session does not have an
	// initialized index for tracking its own state updates.
	ErrNoSessionHintIndex = errors.New("session hint index missing")

	// ErrInvalidBlobSize indicates that the encrypted blob provided by the
	// client is not valid according to the blob type of the session.
	ErrInvalidBlobSize = errors.New("invalid blob size")
)
View Source 
var (

	// ErrEmptyQueue is returned from Pop if there are no items left in
	// the queue.
	ErrEmptyQueue = errors.New("queue is empty")
)

Functions

func DisableLog 

func DisableLog()

DisableLog disables all library log output. Logging output is disabled by default until UseLogger is called.

func NewBoltBackendCreator 

func NewBoltBackendCreator(active bool, dbPath,
	dbFileName string) func(boltCfg *kvdb.BoltConfig) (kvdb.Backend,
	error)

NewBoltBackendCreator returns a function that creates a new bbolt backend for the watchtower database.

func ReadElement 

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

ReadElement deserializes a single element from the provided io.Reader.

func ReadElements 

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

ReadElements deserializes the provided io.Reader into a variadic list of target elements.

func UseLogger 

func UseLogger(logger btclog.Logger)

UseLogger uses a specified Logger to output package logging info. This should be used in preference to SetLogWriter if the caller is also using btclog.

func WriteElement 

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

WriteElement serializes a single element into the provided io.Writer.

func WriteElements 

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

WriteElements serializes a variadic list of elements into the given io.Writer.

Types

type BackupID 

type BackupID struct {
	// ChanID is the channel id of the revoked commitment.
	ChanID lnwire.ChannelID

	// CommitHeight is the commitment height of the revoked commitment.
	CommitHeight uint64
}

BackupID identifies a particular revoked, remote commitment by channel id and commitment height.

func (*BackupID) Decode 

func (b *BackupID) Decode(r io.Reader) error

Decode reads a BackupID from the passed io.Reader.

func (*BackupID) Encode 

func (b *BackupID) Encode(w io.Writer) error

Encode writes the BackupID from the passed io.Writer.

func (BackupID) String 

func (b BackupID) String() string

String returns a human-readable encoding of a BackupID.

type CSessionStatus 

type CSessionStatus uint8

CSessionStatus is a bit-field representing the possible statuses of ClientSessions. 

const (
	// CSessionActive indicates that the ClientSession is active and can be
	// used for backups.
	CSessionActive CSessionStatus = 0

	// CSessionTerminal indicates that the ClientSession is in a terminal
	// state and cannot be used for backups.
	CSessionTerminal CSessionStatus = 1
)

type ChannelInfo 

type ChannelInfo struct {
	ClientChanSummary

	// MaxHeight is the highest commitment height that the tower has been
	// handed for this channel. An Option type is used to store this since
	// a commitment height of zero is valid, and we need a way of knowing if
	// we have seen a new height yet or not.
	MaxHeight fn.Option[uint64]
}

ChannelInfo contains various useful things about a registered channel.

NOTE: the reason for adding this struct which wraps ClientChanSummary instead of extending ClientChanSummary is for faster look-up of added fields. If we were to extend ClientChanSummary instead then we would need to decode the entire struct each time we want to read the new fields and then re-encode the struct each time we want to write to a new field.

type ChannelInfos 

type ChannelInfos map[lnwire.ChannelID]*ChannelInfo

ChannelInfos is a map for a given channel id to it's ChannelInfo.

type ClientChanSummary 

type ClientChanSummary struct {
	// SweepPkScript is the pkscript to which all justice transactions will
	// deposit recovered funds for this particular channel.
	SweepPkScript []byte
}

ClientChanSummary tracks channel-specific information. A new ClientChanSummary is inserted in the database the first time the client encounters a particular channel.

func (*ClientChanSummary) Decode 

func (s *ClientChanSummary) Decode(r io.Reader) error

Decode reads a ClientChanSummary form the passed io.Reader.

func (*ClientChanSummary) Encode 

func (s *ClientChanSummary) Encode(w io.Writer) error

Encode writes the ClientChanSummary to the passed io.Writer.

type ClientDB 

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

ClientDB is single database providing a persistent storage engine for the wtclient.

func OpenClientDB 

func OpenClientDB(db kvdb.Backend) (*ClientDB, error)

OpenClientDB opens the client database given the path to the database's directory. If no such database exists, this method will initialize a fresh one using the latest version number and bucket structure. If a database exists but has a lower version number than the current version, any necessary migrations will be applied before returning. Any attempt to open a database with a version number higher that the latest version will fail to prevent accidental reversion.

func (*ClientDB) AckUpdate 

func (c *ClientDB) AckUpdate(id *SessionID, seqNum uint16,
	lastApplied uint16) error

AckUpdate persists an acknowledgment for a given (session, seqnum) pair. This removes the update from the set of committed updates, and validates the lastApplied value returned from the tower.

func (*ClientDB) Close 

func (c *ClientDB) Close() error

Close closes the underlying database.

func (*ClientDB) CommitUpdate 

func (c *ClientDB) CommitUpdate(id *SessionID,
	update *CommittedUpdate) (uint16, error)

CommitUpdate persists the CommittedUpdate provided in the slot for (session, seqNum). This allows the client to retransmit this update on startup.

func (*ClientDB) CreateClientSession 

func (c *ClientDB) CreateClientSession(session *ClientSession) error

CreateClientSession records a newly negotiated client session in the set of active sessions. The session can be identified by its SessionID.

func (*ClientDB) CreateTower 

func (c *ClientDB) CreateTower(lnAddr *lnwire.NetAddress) (*Tower, error)

CreateTower initialize an address record used to communicate with a watchtower. Each Tower is assigned a unique ID, that is used to amortize storage costs of the public key when used by multiple sessions. If the tower already exists, the address is appended to the list of all addresses used to that tower previously and its corresponding sessions are marked as active.

func (*ClientDB) DeactivateTower 

func (c *ClientDB) DeactivateTower(pubKey *btcec.PublicKey) error

DeactivateTower sets the given tower's status to inactive. This means that this tower's sessions won't be loaded and used for backups. CreateTower can be used to reactivate the tower again.

func (*ClientDB) DeleteCommittedUpdates 

func (c *ClientDB) DeleteCommittedUpdates(id *SessionID) error

DeleteCommittedUpdates deletes all the committed updates for the given session.

func (*ClientDB) DeleteSession 

func (c *ClientDB) DeleteSession(id SessionID) error

DeleteSession can be called when a session should be deleted from the DB. All references to the session will also be deleted from the DB. Note that a session will only be deleted if was previously marked as closable.

func (*ClientDB) FetchChanInfos 

func (c *ClientDB) FetchChanInfos() (ChannelInfos, error)

FetchChanInfos loads a mapping from all registered channels to their ChannelInfo. Only the channels that have not yet been marked as closed will be loaded.

func (*ClientDB) FetchSessionCommittedUpdates 

func (c *ClientDB) FetchSessionCommittedUpdates(id *SessionID) (
	[]CommittedUpdate, error)

FetchSessionCommittedUpdates retrieves the current set of un-acked updates of the given session.

func (*ClientDB) GetClientSession 

func (c *ClientDB) GetClientSession(id SessionID,
	opts ...ClientSessionListOption) (*ClientSession, error)

GetClientSession loads the ClientSession with the given ID from the DB.

func (*ClientDB) GetDBQueue 

func (c *ClientDB) GetDBQueue(namespace []byte) Queue[*BackupID]

GetDBQueue returns a BackupID Queue instance under the given namespace.

func (*ClientDB) IsAcked 

func (c *ClientDB) IsAcked(id *SessionID, backupID *BackupID) (bool, error)

IsAcked returns true if the given backup has been backed up using the given session.

func (*ClientDB) ListClientSessions 

func (c *ClientDB) ListClientSessions(id *TowerID,
	opts ...ClientSessionListOption) (map[SessionID]*ClientSession, error)

ListClientSessions returns the set of all client sessions known to the db. An optional tower ID can be used to filter out any client sessions in the response that do not correspond to this tower.

func (*ClientDB) ListClosableSessions 

func (c *ClientDB) ListClosableSessions() (map[SessionID]uint32, error)

ListClosableSessions fetches and returns the IDs for all sessions marked as closable.

func (*ClientDB) ListTowers 

func (c *ClientDB) ListTowers(filter TowerFilterFn) ([]*Tower, error)

ListTowers retrieves the list of towers available within the database that have a status matching the given status. The filter function may be set in order to filter out the towers to be returned.

func (*ClientDB) LoadTower 

func (c *ClientDB) LoadTower(pubKey *btcec.PublicKey) (*Tower, error)

LoadTower retrieves a tower by its public key.

func (*ClientDB) LoadTowerByID 

func (c *ClientDB) LoadTowerByID(towerID TowerID) (*Tower, error)

LoadTowerByID retrieves a tower by its tower ID.

func (*ClientDB) MarkBackupIneligible 

func (c *ClientDB) MarkBackupIneligible(chanID lnwire.ChannelID,
	commitHeight uint64) error

MarkBackupIneligible records that the state identified by the (channel id, commit height) tuple was ineligible for being backed up under the current policy. This state can be retried later under a different policy.

func (*ClientDB) MarkChannelClosed 

func (c *ClientDB) MarkChannelClosed(chanID lnwire.ChannelID,
	blockHeight uint32) ([]SessionID, error)

MarkChannelClosed will mark a registered channel as closed by setting its closed-height as the given block height. It returns a list of session IDs for sessions that are now considered closable due to the close of this channel. The details for this channel will be deleted from the DB if there are no more sessions in the DB that contain updates for this channel.

func (*ClientDB) NextSessionKeyIndex 

func (c *ClientDB) NextSessionKeyIndex(towerID TowerID,
	blobType blob.Type, forceNext bool) (uint32, error)

NextSessionKeyIndex reserves a new session key derivation index for a particular tower id. The index is reserved for that tower until CreateClientSession is invoked for that tower and index, at which point a new index for that tower can be reserved. Multiple calls to this method before CreateClientSession is invoked should return the same index unless forceNext is true.

func (*ClientDB) NumAckedUpdates 

func (c *ClientDB) NumAckedUpdates(id *SessionID) (uint64, error)

NumAckedUpdates returns the number of backups that have been successfully backed up using the given session.

func (*ClientDB) RegisterChannel 

func (c *ClientDB) RegisterChannel(chanID lnwire.ChannelID,
	sweepPkScript []byte) error

RegisterChannel registers a channel for use within the client database. For now, all that is stored in the channel summary is the sweep pkscript that we'd like any tower sweeps to pay into. In the future, this will be extended to contain more info to allow the client efficiently request historical states to be backed up under the client's active policy.

func (*ClientDB) RemoveTower 

func (c *ClientDB) RemoveTower(pubKey *btcec.PublicKey, addr net.Addr) error

RemoveTower modifies a tower's record within the database. If an address is provided, then _only_ the address record should be removed from the tower's persisted state. Otherwise, we'll attempt to mark the tower as inactive. If any of its sessions has unacked updates, then ErrTowerUnackedUpdates is returned. If the tower doesn't have any sessions at all, it'll be completely removed from the database.

NOTE: An error is not returned if the tower doesn't exist.

func (*ClientDB) TerminateSession 

func (c *ClientDB) TerminateSession(id SessionID) error

TerminateSession sets the given session's status to CSessionTerminal meaning that it will not be usable again. An error will be returned if the given session still has un-acked updates that should be attended to.

func (*ClientDB) Version 

func (c *ClientDB) Version() (uint32, error)

Version returns the database's current version number.

NOTE: Part of the versionedDB interface.

type ClientSessWithNumCommittedUpdatesFilterFn 

type ClientSessWithNumCommittedUpdatesFilterFn func(*ClientSession, uint16) bool

ClientSessWithNumCommittedUpdatesFilterFn describes the signature of a callback function that can be used to filter out a session based on the contents of ClientSession along with the number of un-acked committed updates that the session has.

type ClientSession 

type ClientSession struct {
	// ID is the client's public key used when authenticating with the
	// tower.
	//
	// NOTE: This value is not serialized with the body of the struct, it
	// should be set and recovered as the ClientSession's key.
	ID SessionID

	ClientSessionBody
}

ClientSession encapsulates a SessionInfo returned from a successful session negotiation, and also records the tower and ephemeral secret used for communicating with the tower.

type ClientSessionBody 

type ClientSessionBody struct {
	// SeqNum is the next unallocated sequence number that can be sent to
	// the tower.
	SeqNum uint16

	// TowerLastApplied the last last-applied the tower has echoed back.
	TowerLastApplied uint16

	// TowerID is the unique, db-assigned identifier that references the
	// Tower with which the session is negotiated.
	TowerID TowerID

	// KeyIndex is the index of key locator used to derive the client's
	// session key so that it can authenticate with the tower to update its
	// session. In order to rederive the private key, the key locator should
	// use the keychain.KeyFamilyTowerSession key family.
	KeyIndex uint32

	// Policy holds the negotiated session parameters.
	Policy wtpolicy.Policy

	// Status indicates the current state of the ClientSession.
	Status CSessionStatus

	// RewardPkScript is the pkscript that the tower's reward will be
	// deposited to if a sweep transaction confirms and the sessions
	// specifies a reward output.
	RewardPkScript []byte
}

ClientSessionBody represents the primary components of a ClientSession that are serialized together within the database. The CommittedUpdates and AckedUpdates are serialized in buckets separate from the body.

func (*ClientSessionBody) Decode 

func (s *ClientSessionBody) Decode(r io.Reader) error

Decode reads a ClientSessionBody from the passed io.Reader.

func (*ClientSessionBody) Encode 

func (s *ClientSessionBody) Encode(w io.Writer) error

Encode writes a ClientSessionBody to the passed io.Writer.

type ClientSessionFilterFn 

type ClientSessionFilterFn func(*ClientSession) bool

ClientSessionFilterFn describes the signature of a callback function that can be used to filter the sessions that are returned in any of the DB methods that read sessions from the DB.

type ClientSessionListCfg 

type ClientSessionListCfg struct {
	// PerNumAckedUpdates will, if set, be called for each of the session's
	// channels to communicate the number of updates stored for that
	// channel.
	PerNumAckedUpdates PerNumAckedUpdatesCB

	// PerRogueUpdateCount will, if set, be called with the number of rogue
	// updates that the session has backed up.
	PerRogueUpdateCount PerRogueUpdateCountCB

	// PerMaxHeight will, if set, be called for each of the session's
	// channels to communicate the highest commit height of updates stored
	// for that channel.
	PerMaxHeight PerMaxHeightCB

	// PerCommittedUpdate will, if set, be called for each of the session's
	// committed (un-acked) updates.
	PerCommittedUpdate PerCommittedUpdateCB

	// PreEvaluateFilterFn will be run after loading a session from the DB
	// and _before_ any of the other call-back functions in
	// ClientSessionListCfg. Therefore, if a session fails this filter
	// function, then it will not be passed to any of the other call backs
	// and won't be included in the return list.
	PreEvaluateFilterFn ClientSessionFilterFn

	// PostEvaluateFilterFn will be run _after_ all the other call-back
	// functions in ClientSessionListCfg. If a session fails this filter
	// function then all it means is that it won't be included in the list
	// of sessions to return.
	PostEvaluateFilterFn ClientSessWithNumCommittedUpdatesFilterFn
}

ClientSessionListCfg defines various query parameters that will be used when querying the DB for client sessions.

func NewClientSessionCfg 

func NewClientSessionCfg() *ClientSessionListCfg

NewClientSessionCfg constructs a new ClientSessionListCfg.

type ClientSessionListOption 

type ClientSessionListOption func(cfg *ClientSessionListCfg)

ClientSessionListOption describes the signature of a functional option that can be used when listing client sessions in order to provide any extra instruction to the query.

func WithPerCommittedUpdate 

func WithPerCommittedUpdate(cb PerCommittedUpdateCB) ClientSessionListOption

WithPerCommittedUpdate constructs a functional option that will set a call-back function to be called for each of a client's un-acked updates.

func WithPerMaxHeight 

func WithPerMaxHeight(cb PerMaxHeightCB) ClientSessionListOption

WithPerMaxHeight constructs a functional option that will set a call-back function to be called for each of a session's channels to communicate the maximum commitment height that the session has stored for the channel.

func WithPerNumAckedUpdates 

func WithPerNumAckedUpdates(cb PerNumAckedUpdatesCB) ClientSessionListOption

WithPerNumAckedUpdates constructs a functional option that will set a call-back function to be called for each of a session's channels to communicate the number of updates that the session has stored for the channel.

func WithPerRogueUpdateCount 

func WithPerRogueUpdateCount(cb PerRogueUpdateCountCB) ClientSessionListOption

WithPerRogueUpdateCount constructs a functional option that will set a call-back function to be called with the number of rogue updates that the session has backed up.

func WithPostEvalFilterFn 

func WithPostEvalFilterFn(
	fn ClientSessWithNumCommittedUpdatesFilterFn) ClientSessionListOption

WithPostEvalFilterFn constructs a functional option that will set a call-back function that will be used to determine if a session should be included in the returned list. This differs from WithPreEvalFilterFn since that call-back is used to determine if the session should be evaluated at all (and thus run against the other ClientSessionListCfg call-backs) whereas the session will only reach the PostEvalFilterFn call-back once it has already been evaluated by all the other call-backs.

func WithPreEvalFilterFn 

func WithPreEvalFilterFn(fn ClientSessionFilterFn) ClientSessionListOption

WithPreEvalFilterFn constructs a functional option that will set a call-back function that will be called immediately after loading a session. If the session fails this filter function, then it will not be passed to any of the other evaluation call-back functions.

type CommittedUpdate 

type CommittedUpdate struct {
	// SeqNum is the unique sequence number allocated by the session to this
	// update.
	SeqNum uint16

	CommittedUpdateBody
}

CommittedUpdate holds a state update sent by a client along with its allocated sequence number and the exact remote commitment the encrypted justice transaction can rectify.

type CommittedUpdateBody 

type CommittedUpdateBody struct {
	// BackupID identifies the breached commitment that the encrypted blob
	// can spend from.
	BackupID BackupID

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

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

CommittedUpdateBody represents the primary components of a CommittedUpdate. On disk, this is stored under the sequence number, which acts as its key.

func (*CommittedUpdateBody) Decode 

func (u *CommittedUpdateBody) Decode(r io.Reader) error

Decode reads a CommittedUpdateBody from the passed io.Reader.

func (*CommittedUpdateBody) Encode 

func (u *CommittedUpdateBody) Encode(w io.Writer) error

Encode writes the CommittedUpdateBody to the passed io.Writer.

type DiskQueueDB 

type DiskQueueDB[T Serializable] struct {
	// contains filtered or unexported fields
}

DiskQueueDB is a generic Bolt DB implementation of the Queue interface.

func (*DiskQueueDB[T]) Len 

func (d *DiskQueueDB[T]) Len() (uint64, error)

Len returns the number of tasks in the queue.

NOTE: This is part of the Queue interface.

func (*DiskQueueDB[T]) PopUpTo 

func (d *DiskQueueDB[T]) PopUpTo(n int) ([]T, error)

PopUpTo attempts to pop up to n items from the queue. If the queue is empty, then ErrEmptyQueue is returned.

NOTE: This is part of the Queue interface.

func (*DiskQueueDB[T]) Push 

func (d *DiskQueueDB[T]) Push(items ...T) error

Push adds a T to the tail of the queue.

NOTE: This is part of the Queue interface.

func (*DiskQueueDB[T]) PushHead 

func (d *DiskQueueDB[T]) PushHead(items ...T) error

PushHead pushes new T items to the head of the queue. For this implementation of the Queue interface, this will require popping all items currently in the head queue and adding them after first adding the given list of items. Care should thus be taken to never have an unbounded number of items in the head queue.

NOTE: This is part of the Queue interface.

type KVStore 

type KVStore interface {
	// Put saves the specified key/value pair to the store. Keys that do not
	// already exist are added and keys that already exist are overwritten.
	Put(key, value []byte) error

	// Delete removes the specified key from the bucket. Deleting a key that
	// does not exist does not return an error.
	Delete(key []byte) error
}

KVStore is an interface representing a key-value store.

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 blob.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 PerAckedUpdateCB 

type PerAckedUpdateCB func(*ClientSession, uint16, BackupID)

PerAckedUpdateCB describes the signature of a callback function that can be called for each of a session's acked updates.

type PerCommittedUpdateCB 

type PerCommittedUpdateCB func(*ClientSession, *CommittedUpdate)

PerCommittedUpdateCB describes the signature of a callback function that can be called for each of a session's committed updates (updates that the client has not yet received an ACK for).

type PerMaxHeightCB 

type PerMaxHeightCB func(*ClientSession, lnwire.ChannelID, uint64)

PerMaxHeightCB describes the signature of a callback function that can be called for each channel that a session has updates for to communicate the maximum commitment height that the session has backed up for the channel.

type PerNumAckedUpdatesCB 

type PerNumAckedUpdatesCB func(*ClientSession, lnwire.ChannelID, uint16)

PerNumAckedUpdatesCB describes the signature of a callback function that can be called for each channel that a session has updates for to communicate the number of updates that the session has for the channel.

type PerRogueUpdateCountCB 

type PerRogueUpdateCountCB func(*ClientSession, uint16)

PerRogueUpdateCountCB describes the signature of a callback function that can be called for each session with the number of rogue updates that the session has.

type Queue 

type Queue[T any] interface {
	// Len returns the number of tasks in the queue.
	Len() (uint64, error)

	// Push pushes new T items to the tail of the queue.
	Push(items ...T) error

	// PopUpTo attempts to pop up to n items from the head of the queue. If
	// no more items are in the queue then ErrEmptyQueue is returned.
	PopUpTo(n int) ([]T, error)

	// PushHead pushes new T items to the head of the queue.
	PushHead(items ...T) error
}

Queue is an interface describing a FIFO queue for any generic type T.

func NewQueueDB 

func NewQueueDB[T Serializable](db kvdb.Backend, queueBktName []byte,
	constructor func() T,
	onItemWrite func(tx kvdb.RwTx, item T) error) Queue[T]

NewQueueDB constructs a new DiskQueueDB. A queueBktName must be provided so that the DiskQueueDB can create its own namespace in the bolt db.

type RangeIndex 

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

RangeIndex can be used to keep track of which numbers have been added to a set. It does so by keeping track of a sorted list of rangeItems. Each rangeItem has a start and end value of a range where all values in-between have been added to the set. It works well in situations where it is expected numbers in the set are not sparse.

func NewRangeIndex 

func NewRangeIndex(ranges map[uint64]uint64,
	opts ...RangeIndexOption) (*RangeIndex, error)

NewRangeIndex constructs a new RangeIndex. An initial set of ranges may be passed to the function in the form of a map.

func (*RangeIndex) Add 

func (a *RangeIndex) Add(newHeight uint64, kv KVStore) error

Add adds a single number to the range set. It first attempts to apply the necessary changes to the passed KV store and then only if this succeeds, will the changes be applied to the in-memory structure.

func (*RangeIndex) GetAllRanges 

func (a *RangeIndex) GetAllRanges() map[uint64]uint64

GetAllRanges returns a copy of the range set in the form of a map.

func (*RangeIndex) IsInIndex 

func (a *RangeIndex) IsInIndex(n uint64) bool

IsInIndex returns true if the given number is in the range set.

func (*RangeIndex) MaxHeight 

func (a *RangeIndex) MaxHeight() uint64

MaxHeight returns the highest number covered in the range.

func (*RangeIndex) NumInSet 

func (a *RangeIndex) NumInSet() uint64

NumInSet returns the number of items covered by the range set.

type RangeIndexOption 

type RangeIndexOption func(*RangeIndex)

RangeIndexOption describes the signature of a functional option that can be used to modify the behaviour of a RangeIndex.

func WithSerializeUint64Fn 

func WithSerializeUint64Fn(fn func(uint64) ([]byte, error)) RangeIndexOption

WithSerializeUint64Fn is a functional option that can be used to set the function to be used to do the serialization of a uint64 into a byte slice.

type Serializable 

type Serializable interface {
	Encode(w io.Writer) error
	Decode(r io.Reader) error
}

Serializable is an interface must be satisfied for any type that the DiskQueueDB should handle.

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

	// Policy holds the negotiated session parameters.
	Policy wtpolicy.Policy

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

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

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

func (s *SessionInfo) Decode(r io.Reader) error

Decode deserializes the session info from the given io.Reader.

func (*SessionInfo) Encode 

func (s *SessionInfo) Encode(w io.Writer) error

Encode serializes the session info to the given io.Writer.

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 blob.BreachHint

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

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

func (*SessionStateUpdate) Decode 

func (u *SessionStateUpdate) Decode(r io.Reader) error

Decode deserializes the target state update from the provided io.Reader.

func (*SessionStateUpdate) Encode 

func (u *SessionStateUpdate) Encode(w io.Writer) error

Encode serializes the state update into the provided io.Writer.

type Tower 

type Tower struct {
	// ID is a unique ID for this record assigned by the database.
	ID TowerID

	// IdentityKey is the public key of the remote node, used to
	// authenticate the brontide transport.
	IdentityKey *btcec.PublicKey

	// Addresses is a list of possible addresses to reach the tower.
	Addresses []net.Addr

	// Status is the status of this tower as set by the client.
	Status TowerStatus
}

Tower holds the necessary components required to connect to a remote tower. Communication is handled by brontide, and requires both a public key and an address.

func (*Tower) AddAddress 

func (t *Tower) AddAddress(addr net.Addr)

AddAddress adds the given address to the tower's in-memory list of addresses. If the address's string is already present, the Tower will be left unmodified. Otherwise, the address is prepended to the beginning of the Tower's addresses, on the assumption that it is fresher than the others.

NOTE: This method is NOT safe for concurrent use.

func (*Tower) Decode 

func (t *Tower) Decode(r io.Reader) error

Decode reads a Tower from the passed io.Reader. The TowerID is meant to be decoded from the key.

func (*Tower) Encode 

func (t *Tower) Encode(w io.Writer) error

Encode writes the Tower to the passed io.Writer. The TowerID is not serialized, since it acts as the key.

func (*Tower) RemoveAddress 

func (t *Tower) RemoveAddress(addr net.Addr)

RemoveAddress removes the given address from the tower's in-memory list of addresses. If the address doesn't exist, then this will act as a NOP.

func (*Tower) String 

func (t *Tower) String() string

String returns a user-friendly identifier of the tower.

type TowerDB 

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

TowerDB is single database providing a persistent storage engine for the wtserver and lookout subsystems.

func OpenTowerDB 

func OpenTowerDB(db kvdb.Backend) (*TowerDB, error)

OpenTowerDB opens the tower database given the path to the database's directory. If no such database exists, this method will initialize a fresh one using the latest version number and bucket structure. If a database exists but has a lower version number than the current version, any necessary migrations will be applied before returning. Any attempt to open a database with a version number higher that the latest version will fail to prevent accidental reversion.

func (*TowerDB) Close 

func (t *TowerDB) Close() error

Close closes the underlying database.

func (*TowerDB) DeleteSession 

func (t *TowerDB) DeleteSession(target SessionID) error

DeleteSession removes all data associated with a particular session id from the tower's database.

func (*TowerDB) GetLookoutTip 

func (t *TowerDB) GetLookoutTip() (*chainntnfs.BlockEpoch, error)

GetLookoutTip retrieves the current lookout tip block epoch from the tower database.

func (*TowerDB) GetSessionInfo 

func (t *TowerDB) GetSessionInfo(id *SessionID) (*SessionInfo, error)

GetSessionInfo retrieves the session for the passed session id. An error is returned if the session could not be found.

func (*TowerDB) InsertSessionInfo 

func (t *TowerDB) InsertSessionInfo(session *SessionInfo) error

InsertSessionInfo records a negotiated session in the tower database. An error is returned if the session already exists.

func (*TowerDB) InsertStateUpdate 

func (t *TowerDB) InsertStateUpdate(update *SessionStateUpdate) (uint16, error)

InsertStateUpdate stores an update sent by the client after validating that the update is well-formed in the context of other updates sent for the same session. This include verifying that the sequence number is incremented properly and the last applied values echoed by the client are sane.

func (*TowerDB) QueryMatches 

func (t *TowerDB) QueryMatches(breachHints []blob.BreachHint) ([]Match, error)

QueryMatches searches against all known state updates for any that match the passed breachHints. More than one Match will be returned for a given hint if they exist in the database.

func (*TowerDB) SetLookoutTip 

func (t *TowerDB) SetLookoutTip(epoch *chainntnfs.BlockEpoch) error

SetLookoutTip stores the provided epoch as the latest lookout tip epoch in the tower database.

func (*TowerDB) Version 

func (t *TowerDB) Version() (uint32, error)

Version returns the database's current version number.

NOTE: Part of the versionedDB interface.

type TowerFilterFn 

type TowerFilterFn func(*Tower) bool

TowerFilterFn is the signature of a call-back function that can be used to skip certain towers in the ListTowers method.

type TowerID 

type TowerID uint64

TowerID is a unique 64-bit identifier allocated to each unique watchtower. This allows the client to conserve on-disk space by not needing to always reference towers by their pubkey.

func TowerIDFromBytes 

func TowerIDFromBytes(towerIDBytes []byte) TowerID

TowerIDFromBytes constructs a TowerID from the provided byte slice. The argument must have at least 8 bytes, and should contain the TowerID in big-endian byte order.

func (TowerID) Bytes 

func (id TowerID) Bytes() []byte

Bytes encodes a TowerID into an 8-byte slice in big-endian byte order.

type TowerStatus 

type TowerStatus uint8

TowerStatus represents the state of the tower as set by the tower client. 

const (
	// TowerStatusActive is the default state of the tower, and it indicates
	// that this tower should be used to attempt session creation.
	TowerStatusActive TowerStatus = 0

	// TowerStatusInactive indicates that the tower should not be used to
	// attempt session creation.
	TowerStatusInactive TowerStatus = 1
)

type UnknownElementType 

type UnknownElementType = channeldb.UnknownElementType

UnknownElementType is an alias for channeldb.UnknownElementType.

Source Files

View all Source files

Directories

Path Synopsis

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.