blob

Documentation

Index

• Constants
• Variables
• func PlaintextSize(ver uint16) int
• func Size(ver uint16) int
• type JusticeKit
  • func Decrypt(key, ciphertext []byte, version uint16) (*JusticeKit, error)
  • func (b *JusticeKit) CommitToLocalRevokeWitnessStack() ([][]byte, error)
  • func (b *JusticeKit) CommitToLocalWitnessScript() ([]byte, error)
  • func (b *JusticeKit) CommitToRemoteWitnessScript() ([]byte, error)
  • func (b *JusticeKit) CommitToRemoteWitnessStack() ([][]byte, error)
  • func (b *JusticeKit) Encrypt(key []byte, version uint16) ([]byte, error)
  • func (b *JusticeKit) HasCommitToRemoteOutput() bool
• type PubKey

Constants

const (
	// MinVersion is the minimum blob version supported by this package.
	MinVersion = 0

	// MaxVersion is the maximumm blob version supported by this package.
	MaxVersion = 0

	// NonceSize is the length of a chacha20poly1305 nonce, 24 bytes.
	NonceSize = chacha20poly1305.NonceSizeX

	// KeySize is the length of a chacha20poly1305 key, 32 bytes.
	KeySize = chacha20poly1305.KeySize

	// CiphertextExpansion is the number of bytes padded to a plaintext
	// encrypted with chacha20poly1305, which comes from a 16-byte MAC.
	CiphertextExpansion = 16

	// V0PlaintextSize is the plaintext size of a version 0 encoded blob.
	//    sweep address length:            1 byte
	//    padded sweep address:           42 bytes
	//    revocation pubkey:              33 bytes
	//    local delay pubkey:             33 bytes
	//    csv delay:                       4 bytes
	//    commit to-local revocation sig: 64 bytes
	//    commit to-remote pubkey:        33 bytes, maybe blank
	//    commit to-remote sig:           64 bytes, maybe blank
	V0PlaintextSize = 274

	// MaxSweepAddrSize defines the maximum sweep address size that can be
	// encoded in a blob.
	MaxSweepAddrSize = 42
)

Variables

var (

	// ErrUnknownBlobVersion signals that we don't understand the requested
	// blob encoding scheme.
	ErrUnknownBlobVersion = errors.New("unknown blob version")

	// ErrCiphertextTooSmall is a decryption error signaling that the
	// ciphertext is smaller than the ciphertext expansion factor.
	ErrCiphertextTooSmall = errors.New(
		"ciphertext is too small for chacha20poly1305",
	)

	// ErrKeySize signals that the provided key is improperly sized.
	ErrKeySize = fmt.Errorf(
		"chacha20poly1305 key size must be %d bytes", KeySize,
	)

	// ErrNoCommitToRemoteOutput is returned when trying to retrieve the
	// commit to-remote output from the blob, though none exists.
	ErrNoCommitToRemoteOutput = errors.New(
		"cannot obtain commit to-remote p2wkh output script from blob",
	)

	// ErrSweepAddressToLong is returned when trying to encode or decode a
	// sweep address with length greater than the maximum length of 42
	// bytes, which supports p2wkh and p2sh addresses.
	ErrSweepAddressToLong = fmt.Errorf(
		"sweep address must be less than or equal to %d bytes long",
		MaxSweepAddrSize,
	)
)

Functions

func PlaintextSize

func PlaintextSize(ver uint16) int

PlaintextSize returns the size of the encoded-but-unencrypted blob in bytes.

func Size

func Size(ver uint16) int

Size returns the size of the encoded-and-encrypted blob in bytes.

nonce:                24 bytes
enciphered plaintext:  n bytes
MAC:                  16 bytes

Types

type JusticeKit

type JusticeKit struct {
	// SweepAddress is the witness program of the output where the client's
	// fund will be deposited. This value is included in the blobs, as
	// opposed to the session info, such that the sweep addresses can't be
	// correlated across sessions and/or towers.
	//
	// NOTE: This is chosen to be the length of a maximally sized witness
	// program.
	SweepAddress []byte

	// RevocationPubKey is the compressed pubkey that guards the revocation
	// clause of the remote party's to-local output.
	RevocationPubKey PubKey

	// LocalDelayPubKey is the compressed pubkey in the to-local script of
	// the remote party, which guards the path where the remote party
	// claims their commitment output.
	LocalDelayPubKey PubKey

	// CSVDelay is the relative timelock in the remote party's to-local
	// output, which the remote party must wait out before sweeping their
	// commitment output.
	CSVDelay uint32

	// CommitToLocalSig is a signature under RevocationPubKey using
	// SIGHASH_ALL.
	CommitToLocalSig lnwire.Sig

	// CommitToRemotePubKey is the public key in the to-remote output of the revoked
	// commitment transaction.
	//
	// NOTE: This value is only used if it contains a valid compressed
	// public key.
	CommitToRemotePubKey PubKey

	// CommitToRemoteSig is a signature under CommitToRemotePubKey using SIGHASH_ALL.
	//
	// NOTE: This value is only used if CommitToRemotePubKey contains a valid
	// compressed public key.
	CommitToRemoteSig lnwire.Sig
}

JusticeKit is lé Blob of Justice. The JusticeKit contains information required to construct a justice transaction, that sweeps a remote party's revoked commitment transaction. It supports encryption and decryption using chacha20poly1305, allowing the client to encrypt the contents of the blob, and for a watchtower to later decrypt if action must be taken. The encoding format is versioned to allow future extensions.

func Decrypt

func Decrypt(key, ciphertext []byte, version uint16) (*JusticeKit, error)

Decrypt unenciphers a blob of justice by decrypting the ciphertext using chacha20poly1305 with the chosen (nonce, key) pair. The internal plaintext is then deserialized using the given encoding version.

func (*JusticeKit) CommitToLocalRevokeWitnessStack

func (b *JusticeKit) CommitToLocalRevokeWitnessStack() ([][]byte, error)

CommitToLocalRevokeWitnessStack constructs a witness stack spending the revocation clause of the commitment to-local output.

<revocation-sig> 1

func (*JusticeKit) CommitToLocalWitnessScript

func (b *JusticeKit) CommitToLocalWitnessScript() ([]byte, error)

CommitToLocalWitnessScript returns the serialized witness script for the commitment to-local output.

func (*JusticeKit) CommitToRemoteWitnessScript

func (b *JusticeKit) CommitToRemoteWitnessScript() ([]byte, error)

CommitToRemoteWitnessScript returns the witness script for the commitment to-remote p2wkh output, which is the pubkey itself.

func (*JusticeKit) CommitToRemoteWitnessStack

func (b *JusticeKit) CommitToRemoteWitnessStack() ([][]byte, error)

CommitToRemoteWitnessStack returns a witness stack spending the commitment to-remote output, which is a regular p2wkh.

<to-remote-sig>

func (*JusticeKit) Encrypt

func (b *JusticeKit) Encrypt(key []byte, version uint16) ([]byte, error)

Encrypt encodes the blob of justice using encoding version, and then creates a ciphertext using chacha20poly1305 under the chosen (nonce, key) pair.

NOTE: It is the caller's responsibility to ensure that this method is only called once for a given (nonce, key) pair.

func (*JusticeKit) HasCommitToRemoteOutput

func (b *JusticeKit) HasCommitToRemoteOutput() bool

HasCommitToRemoteOutput returns true if the blob contains a to-remote p2wkh pubkey.

type PubKey

type PubKey [33]byte

PubKey is a 33-byte, serialized compressed public key.