wtpolicy

Documentation

Index

• Constants
• Variables
• func ComputeRewardAmount(total btcutil.Amount, base, rate uint32) btcutil.Amount
• type Policy
  • func DefaultPolicy() Policy
  • func (p *Policy) ComputeAltruistOutput(totalAmt btcutil.Amount, txWeight int64) (btcutil.Amount, error)
  • func (p *Policy) ComputeJusticeTxOuts(totalAmt btcutil.Amount, txWeight int64, sweepPkScript, rewardPkScript []byte) ([]*wire.TxOut, error)
  • func (p *Policy) ComputeRewardOutputs(totalAmt btcutil.Amount, txWeight int64) (btcutil.Amount, btcutil.Amount, error)
  • func (p Policy) String() string

Constants

const (
	// RewardScale is the denominator applied when computing the
	// proportional component for a tower's reward output. The current scale
	// is in millionths.
	RewardScale = 1000000

	// DefaultMaxUpdates specifies the number of encrypted blobs a client
	// can send to the tower in a single session.
	DefaultMaxUpdates = 1024

	// DefaultRewardRate specifies the fraction of the channel that the
	// tower takes if it successfully sweeps a breach. The value is
	// expressed in millionths of the channel capacity.
	DefaultRewardRate = 10000

	// DefaultSweepFeeRate specifies the fee rate used to construct justice
	// transactions. The value is expressed in satoshis per kilo-weight.
	DefaultSweepFeeRate = 3000
)

Variables

var (
	// 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 value")

	// ErrRewardExceedsInputs signals that the reward given to the tower (in
	// addition to the transaction fees) is more than the input amount.
	ErrRewardExceedsInputs = errors.New("reward amount exceeds input value")

	// ErrCreatesDust signals that the session's policy would create a dust
	// output for the victim.
	ErrCreatesDust = errors.New("justice transaction creates dust at fee rate")
)

Functions

func ComputeRewardAmount

func ComputeRewardAmount(total btcutil.Amount, base, rate uint32) btcutil.Amount

ComputeRewardAmount computes the amount rewarded to the tower using the proportional rate expressed in millionths, e.g. one million is equivalent to one hundred percent of the total amount. The amount is rounded up to the nearest whole satoshi.

Types

type Policy

type Policy 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 lnwallet.SatPerKWeight
}

Policy defines the negotiated parameters for a session between a client and server. The parameters specify the format of encrypted blobs sent to the tower, the reward schedule for the tower, and the number of encrypted blobs a client can send in one session.

func DefaultPolicy

func DefaultPolicy() Policy

DefaultPolicy returns a Policy containing the default parameters that can be used by clients or servers.

func (*Policy) ComputeAltruistOutput

func (p *Policy) ComputeAltruistOutput(totalAmt btcutil.Amount,
	txWeight int64) (btcutil.Amount, error)

ComputeAltruistOutput computes the lone output value of a justice transaction that pays no reward to the tower. The value is computed using the weight of of the justice transaction and subtracting an amount that satisfies the policy's fee rate.

func (*Policy) ComputeJusticeTxOuts

func (p *Policy) ComputeJusticeTxOuts(totalAmt btcutil.Amount, txWeight int64,
	sweepPkScript, rewardPkScript []byte) ([]*wire.TxOut, error)

ComputeJusticeTxOuts constructs the justice transaction outputs for the given policy. If the policy specifies a reward for the tower, there will be two outputs paying to the victim and the tower. Otherwise there will be a single output sweeping funds back to the victim. The totalAmt should be the sum of any inputs used in the transaction. The passed txWeight should include the weight of the outputs for the justice transaction, which is dependent on whether the justice transaction has a reward. The sweepPkScript should be the pkScript of the victim to which funds will be recovered. The rewardPkScript is the pkScript of the tower where its reward will be deposited, and will be ignored if the blob type does not specify a reward.

func (*Policy) ComputeRewardOutputs

func (p *Policy) ComputeRewardOutputs(totalAmt btcutil.Amount,
	txWeight int64) (btcutil.Amount, btcutil.Amount, error)

ComputeRewardOutputs 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 reward to he tower is substracted first, before splitting the remaining balance amongst the victim and fees.

func (Policy) String

func (p Policy) String() string

String returns a human-readable description of the current policy.