Documentation
¶
Index ¶
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") )
Functions ¶
This section is empty.
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 ¶
NewSessionIDFromPubKey creates a new SessionID from a public key.
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.
Source Files