Struct RecipientOnionFields

pub struct RecipientOnionFields {
    pub payment_secret: Option<PaymentSecret>,
    pub payment_metadata: Option<Vec<u8>>,
    /* private fields */
}

Information which is provided, encrypted, to the payment recipient when sending HTLCs.

This should generally be constructed with data communicated to us from the recipient (via a BOLT11 or BOLT12 invoice).

Fields

payment_secret: Option<PaymentSecret>

The PaymentSecret is an arbitrary 32 bytes provided by the recipient for us to repeat in the onion. It is unrelated to payment_hash (or PaymentPreimage) and exists to authenticate the sender to the recipient and prevent payment-probing (deanonymization) attacks.

If you do not have one, the Route you pay over must not contain multiple paths as multi-path payments require a recipient-provided secret.

Some implementations may reject spontaneous payments with payment secrets, so you may only want to provide a secret for a spontaneous payment if MPP is needed and you know your recipient will not reject it.

payment_metadata: Option<Vec<u8>>

The payment metadata serves a similar purpose as Self::payment_secret but is of arbitrary length. This gives recipients substantially more flexibility to receive additional data.

In LDK, while the Self::payment_secret is fixed based on an internal authentication scheme to authenticate received payments against expected payments and invoices, this field is not used in LDK for received payments, and can be used to store arbitrary data in invoices which will be received with the payment.

Note that this field was added to the lightning specification more recently than Self::payment_secret and while nearly all lightning senders support secrets, metadata may not be supported as universally.

Implementations

impl RecipientOnionFields

pub fn secret_only(payment_secret: PaymentSecret) -> RecipientOnionFields

Creates a RecipientOnionFields from only a PaymentSecret. This is the most common set of onion fields for today’s BOLT11 invoices - most nodes require a PaymentSecret but do not require or provide any further data.

pub fn spontaneous_empty() -> RecipientOnionFields

Creates a new RecipientOnionFields with no fields. This generally does not create payable HTLCs except for single-path spontaneous payments, i.e. this should generally only be used for calls to ChannelManager::send_spontaneous_payment. If you are sending a spontaneous MPP this will not work as all MPP require payment secrets; you may instead want to use RecipientOnionFields::secret_only.

pub fn with_custom_tlvs( self, custom_tlvs: Vec<(u64, Vec<u8>)>, ) -> Result<RecipientOnionFields, ()>

Creates a new RecipientOnionFields from an existing one, adding custom TLVs. Each TLV is provided as a (u64, Vec<u8>) for the type number and serialized value respectively. TLV type numbers must be unique and within the range reserved for custom types, i.e. >= 2^16, otherwise this method will return Err(()).

This method will also error for types in the experimental range which have been standardized within the protocol, which only includes 5482373484 (keysend) for now.

See Self::custom_tlvs for more info.

pub fn custom_tlvs(&self) -> &Vec<(u64, Vec<u8>)>

Gets the custom TLVs that will be sent or have been received.

Custom TLVs allow sending extra application-specific data with a payment. They provide additional flexibility on top of payment metadata, as while other implementations may require payment_metadata to reflect metadata provided in an invoice, custom TLVs do not have this restriction.

Note that if this field is non-empty, it will contain strictly increasing TLVs, each represented by a (u64, Vec<u8>) for its type number and serialized value respectively. This is validated when setting this field using Self::with_custom_tlvs.

Trait Implementations

impl Clone for RecipientOnionFields

fn clone(&self) -> RecipientOnionFields

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for RecipientOnionFields

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl PartialEq for RecipientOnionFields

fn eq(&self, other: &RecipientOnionFields) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Readable for RecipientOnionFields

fn read<R>(reader: &mut R) -> Result<RecipientOnionFields, DecodeError>

where R: Read,

Reads a Self in from the given Read.

impl Writeable for RecipientOnionFields

fn write<W>(&self, writer: &mut W) -> Result<(), Error>

where W: Writer,

Writes self out to the given Writer.

fn serialized_length(&self) -> usize

Gets the length of this object after it has been serialized. This can be overridden to optimize cases where we prepend an object with its length.

fn encode(&self) -> Vec<u8>

Writes self out to a Vec<u8>.

impl Eq for RecipientOnionFields

impl StructuralPartialEq for RecipientOnionFields