lightningdevkit/structs/VerifiedInvoiceRequest.d.mts

Lightning Development Kit

import { Option_u64Z } from '../structs/Option_u64Z.mjs';
import { BlindedMessagePath } from '../structs/BlindedMessagePath.mjs';
import { Option_CVec_u8ZZ } from '../structs/Option_CVec_u8ZZ.mjs';
import { HumanReadableName } from '../structs/HumanReadableName.mjs';
import { BlindedPaymentPath } from '../structs/BlindedPaymentPath.mjs';
import { Option_AmountZ } from '../structs/Option_AmountZ.mjs';
import { Quantity } from '../structs/Quantity.mjs';
import { OfferId } from '../structs/OfferId.mjs';
import { Result_InvoiceWithExplicitSigningPubkeyBuilderBolt12SemanticErrorZ } from '../structs/Result_InvoiceWithExplicitSigningPubkeyBuilderBolt12SemanticErrorZ.mjs';
import { Result_InvoiceWithDerivedSigningPubkeyBuilderBolt12SemanticErrorZ } from '../structs/Result_InvoiceWithDerivedSigningPubkeyBuilderBolt12SemanticErrorZ.mjs';
import { InvoiceRequestFields } from '../structs/InvoiceRequestFields.mjs';
import { PrintableString } from '../structs/PrintableString.mjs';
import { OfferFeatures } from '../structs/OfferFeatures.mjs';
import { InvoiceRequestFeatures } from '../structs/InvoiceRequestFeatures.mjs';
import { CommonBase } from './CommonBase.mjs';
/**
 * An [`InvoiceRequest`] that has been verified by [`InvoiceRequest::verify_using_metadata`] or
 * [`InvoiceRequest::verify_using_recipient_data`] and exposes different ways to respond depending
 * on whether the signing keys were derived.
 */
export declare class VerifiedInvoiceRequest extends CommonBase {
    /**
     * The identifier of the [`Offer`] for which the [`InvoiceRequest`] was made.
     */
    get_offer_id(): OfferId;
    /**
     * The identifier of the [`Offer`] for which the [`InvoiceRequest`] was made.
     */
    set_offer_id(val: OfferId): void;
    clone_ptr(): bigint;
    /**
     * Creates a copy of the VerifiedInvoiceRequest
     */
    clone(): VerifiedInvoiceRequest;
    /**
     * The chains that may be used when paying a requested invoice (e.g., bitcoin mainnet).
     * Payments must be denominated in units of the minimal lightning-payable unit (e.g., msats)
     * for the selected chain.
     */
    chains(): Uint8Array[];
    /**
     * Opaque bytes set by the originator. Useful for authentication and validating fields since it
     * is reflected in `invoice_request` messages along with all the other fields from the `offer`.
     */
    metadata(): Option_CVec_u8ZZ;
    /**
     * The minimum amount required for a successful payment of a single item.
     */
    amount(): Option_AmountZ;
    /**
     * A complete description of the purpose of the payment. Intended to be displayed to the user
     * but with the caveat that it has not been verified in any way.
     *
     * Note that the return value (or a relevant inner pointer) may be NULL or all-0s to represent None
     */
    description(): PrintableString;
    /**
     * Features pertaining to the offer.
     */
    offer_features(): OfferFeatures;
    /**
     * Duration since the Unix epoch when an invoice should no longer be requested.
     *
     * If `None`, the offer does not expire.
     */
    absolute_expiry(): Option_u64Z;
    /**
     * The issuer of the offer, possibly beginning with `user@domain` or `domain`. Intended to be
     * displayed to the user but with the caveat that it has not been verified in any way.
     *
     * Note that the return value (or a relevant inner pointer) may be NULL or all-0s to represent None
     */
    issuer(): PrintableString;
    /**
     * Paths to the recipient originating from publicly reachable nodes. Blinded paths provide
     * recipient privacy by obfuscating its node id.
     */
    paths(): BlindedMessagePath[];
    /**
     * The quantity of items supported.
     */
    supported_quantity(): Quantity;
    /**
     * The public key corresponding to the key used by the recipient to sign invoices.
     * - If [`Offer::paths`] is empty, MUST be `Some` and contain the recipient's node id for
     * sending an [`InvoiceRequest`].
     * - If [`Offer::paths`] is not empty, MAY be `Some` and contain a transient id.
     * - If `None`, the signing pubkey will be the final blinded node id from the
     * [`BlindedMessagePath`] in [`Offer::paths`] used to send the [`InvoiceRequest`].
     *
     * See also [`Bolt12Invoice::signing_pubkey`].
     *
     * [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest
     * [`Bolt12Invoice::signing_pubkey`]: crate::offers::invoice::Bolt12Invoice::signing_pubkey
     *
     * Note that the return value (or a relevant inner pointer) may be NULL or all-0s to represent None
     */
    issuer_signing_pubkey(): Uint8Array;
    /**
     * An unpredictable series of bytes, typically containing information about the derivation of
     * [`payer_signing_pubkey`].
     *
     * [`payer_signing_pubkey`]: Self::payer_signing_pubkey
     */
    payer_metadata(): Uint8Array;
    /**
     * A chain from [`Offer::chains`] that the offer is valid for.
     */
    chain(): Uint8Array;
    /**
     * The amount to pay in msats (i.e., the minimum lightning-payable unit for [`chain`]), which
     * must be greater than or equal to [`Offer::amount`], converted if necessary.
     *
     * [`chain`]: Self::chain
     */
    amount_msats(): Option_u64Z;
    /**
     * Returns whether an amount was set in the request; otherwise, if [`amount_msats`] is `Some`
     * then it was inferred from the [`Offer::amount`] and [`quantity`].
     *
     * [`amount_msats`]: Self::amount_msats
     * [`quantity`]: Self::quantity
     */
    has_amount_msats(): boolean;
    /**
     * Features pertaining to requesting an invoice.
     */
    invoice_request_features(): InvoiceRequestFeatures;
    /**
     * The quantity of the offer's item conforming to [`Offer::is_valid_quantity`].
     */
    quantity(): Option_u64Z;
    /**
     * A possibly transient pubkey used to sign the invoice request.
     */
    payer_signing_pubkey(): Uint8Array;
    /**
     * A payer-provided note which will be seen by the recipient and reflected back in the invoice
     * response.
     *
     * Note that the return value (or a relevant inner pointer) may be NULL or all-0s to represent None
     */
    payer_note(): PrintableString;
    /**
     * If the [`Offer`] was sourced from a BIP 353 Human Readable Name, this should be set by the
     * builder to indicate the original [`HumanReadableName`] which was resolved.
     *
     * Note that the return value (or a relevant inner pointer) may be NULL or all-0s to represent None
     */
    offer_from_hrn(): HumanReadableName;
    /**
     * Creates an [`InvoiceBuilder`] for the request with the given required fields.
     *
     * Unless [`InvoiceBuilder::relative_expiry`] is set, the invoice will expire two hours after
     * `created_at`, which is used to set [`Bolt12Invoice::created_at`].
     *
     * The caller is expected to remember the preimage of `payment_hash` in order to claim a payment
     * for the invoice.
     *
     * The `payment_paths` parameter is useful for maintaining the payment recipient's privacy. It
     * must contain one or more elements ordered from most-preferred to least-preferred, if there's
     * a preference. Note, however, that any privacy is lost if a public node id was used for
     * [`Offer::issuer_signing_pubkey`].
     *
     * Errors if the request contains unknown required features.
     *
     * # Note
     *
     * If the originating [`Offer`] was created using [`OfferBuilder::deriving_signing_pubkey`],
     * then first use [`InvoiceRequest::verify_using_metadata`] or
     * [`InvoiceRequest::verify_using_recipient_data`] and then [`VerifiedInvoiceRequest`] methods
     * instead.
     *
     * [`Bolt12Invoice::created_at`]: crate::offers::invoice::Bolt12Invoice::created_at
     * [`OfferBuilder::deriving_signing_pubkey`]: crate::offers::offer::OfferBuilder::deriving_signing_pubkey
     */
    respond_with_no_std(payment_paths: BlindedPaymentPath[], payment_hash: Uint8Array, created_at: bigint): Result_InvoiceWithExplicitSigningPubkeyBuilderBolt12SemanticErrorZ;
    /**
     * Creates an [`InvoiceBuilder`] for the request using the given required fields and that uses
     * derived signing keys from the originating [`Offer`] to sign the [`Bolt12Invoice`]. Must use
     * the same [`ExpandedKey`] as the one used to create the offer.
     *
     * See [`InvoiceRequest::respond_with_no_std`] for further details.
     *
     * [`Bolt12Invoice`]: crate::offers::invoice::Bolt12Invoice
     */
    respond_using_derived_keys_no_std(payment_paths: BlindedPaymentPath[], payment_hash: Uint8Array, created_at: bigint): Result_InvoiceWithDerivedSigningPubkeyBuilderBolt12SemanticErrorZ;
    /**
     * Fetch the [`InvoiceRequestFields`] for this verified invoice.
     *
     * These are fields which we expect to be useful when receiving a payment for this invoice
     * request, and include the returned [`InvoiceRequestFields`] in the
     * [`PaymentContext::Bolt12Offer`].
     *
     * [`PaymentContext::Bolt12Offer`]: crate::blinded_path::payment::PaymentContext::Bolt12Offer
     */
    fields(): InvoiceRequestFields;
}