lightningdevkit/structs/Offer.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 { Nonce } from '../structs/Nonce.mjs';
import { Option_AmountZ } from '../structs/Option_AmountZ.mjs';
import { Quantity } from '../structs/Quantity.mjs';
import { OfferId } from '../structs/OfferId.mjs';
import { Result_InvoiceRequestWithDerivedPayerSigningPubkeyBuilderBolt12SemanticErrorZ } from '../structs/Result_InvoiceRequestWithDerivedPayerSigningPubkeyBuilderBolt12SemanticErrorZ.mjs';
import { Result_OfferDecodeErrorZ } from '../structs/Result_OfferDecodeErrorZ.mjs';
import { Result_OfferBolt12ParseErrorZ } from '../structs/Result_OfferBolt12ParseErrorZ.mjs';
import { ExpandedKey } from '../structs/ExpandedKey.mjs';
import { PrintableString } from '../structs/PrintableString.mjs';
import { OfferFeatures } from '../structs/OfferFeatures.mjs';
import { CommonBase } from './CommonBase.mjs';
/**
 * An `Offer` is a potentially long-lived proposal for payment of a good or service.
 *
 * An offer is a precursor to an [`InvoiceRequest`]. A merchant publishes an offer from which a
 * customer may request an [`Bolt12Invoice`] for a specific quantity and using an amount sufficient
 * to cover that quantity (i.e., at least `quantity * amount`). See [`Offer::amount`].
 *
 * Offers may be denominated in currency other than bitcoin but are ultimately paid using the
 * latter.
 *
 * Through the use of [`BlindedMessagePath`]s, offers provide recipient privacy.
 *
 * [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest
 * [`Bolt12Invoice`]: crate::offers::invoice::Bolt12Invoice
 */
export declare class Offer extends CommonBase {
    clone_ptr(): bigint;
    /**
     * Creates a copy of the Offer
     */
    clone(): Offer;
    /**
     * 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;
    /**
     * Returns the id of the offer.
     */
    id(): OfferId;
    /**
     * Returns whether the given chain is supported by the offer.
     */
    supports_chain(chain: Uint8Array): boolean;
    /**
     * Whether the offer has expired given the duration since the Unix epoch.
     */
    is_expired_no_std(duration_since_epoch: bigint): boolean;
    /**
     * Returns whether the given quantity is valid for the offer.
     */
    is_valid_quantity(quantity: bigint): boolean;
    /**
     * Returns whether a quantity is expected in an [`InvoiceRequest`] for the offer.
     *
     * [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest
     */
    expects_quantity(): boolean;
    /**
     * Creates an [`InvoiceRequestBuilder`] for the offer, which
     * - derives the [`InvoiceRequest::payer_signing_pubkey`] such that a different key can be used
     * for each request in order to protect the sender's privacy,
     * - sets [`InvoiceRequest::payer_metadata`] when [`InvoiceRequestBuilder::build_and_sign`] is
     * called such that it can be used by [`Bolt12Invoice::verify_using_metadata`] to determine
     * if the invoice was requested using a base [`ExpandedKey`] from which the payer id was
     * derived, and
     * - includes the [`PaymentId`] encrypted in [`InvoiceRequest::payer_metadata`] so that it can
     * be used when sending the payment for the requested invoice.
     *
     * Errors if the offer contains unknown required features.
     *
     * [`InvoiceRequest::payer_signing_pubkey`]: crate::offers::invoice_request::InvoiceRequest::payer_signing_pubkey
     * [`InvoiceRequest::payer_metadata`]: crate::offers::invoice_request::InvoiceRequest::payer_metadata
     * [`Bolt12Invoice::verify_using_metadata`]: crate::offers::invoice::Bolt12Invoice::verify_using_metadata
     * [`ExpandedKey`]: crate::ln::inbound_payment::ExpandedKey
     */
    request_invoice(expanded_key: ExpandedKey, nonce: Nonce, payment_id: Uint8Array): Result_InvoiceRequestWithDerivedPayerSigningPubkeyBuilderBolt12SemanticErrorZ;
    /**
     * Generates a non-cryptographic 64-bit hash of the Offer.
     */
    hash(): bigint;
    /**
     * Read a Offer from a byte array, created by Offer_write
     */
    static constructor_read(ser: Uint8Array): Result_OfferDecodeErrorZ;
    /**
     * Serialize the Offer object into a byte array which can be read by Offer_read
     */
    write(): Uint8Array;
    /**
     * Read a Offer object from a string
     */
    static constructor_from_str(s: string): Result_OfferBolt12ParseErrorZ;
    /**
     * Get the string representation of a Offer object
     */
    to_str(): string;
}