Struct LexeWallet

pub struct LexeWallet { /* private fields */ }

Top-level handle to a Lexe wallet.

Implementations

impl LexeWallet

pub fn fresh( env_config: WalletEnvConfig, credentials: CredentialsRef<'_>, lexe_data_dir: Option<PathBuf>, ) -> Result<Self>

Create a fresh LexeWallet, deleting any existing database state for this user. Data for other users and environments is not affected.

It is recommended to always pass the same lexe_data_dir, regardless of which environment we’re in (dev/staging/prod) and which user this LexeWallet is for. Users and environments will not interfere with each other as all data is namespaced internally. Defaults to ~/.lexe if not specified.

pub fn load( env_config: WalletEnvConfig, credentials: CredentialsRef<'_>, lexe_data_dir: Option<PathBuf>, ) -> Result<Option<Self>>

Load an existing LexeWallet with persistence from lexe_data_dir. Returns None if no local data exists, in which case you should use fresh to create the wallet and local data cache.

If you are authenticating with RootSeeds and this returns None, you should call signup after creating the wallet if you’re not sure whether the user has been signed up with Lexe.

It is recommended to always pass the same lexe_data_dir, regardless of which environment we’re in (dev/staging/prod) and which user this LexeWallet is for. Users and environments will not interfere with each other as all data is namespaced internally. Defaults to ~/.lexe if not specified.

pub fn load_or_fresh( env_config: WalletEnvConfig, credentials: CredentialsRef<'_>, lexe_data_dir: Option<PathBuf>, ) -> Result<Self>

Load an existing LexeWallet with persistence from lexe_data_dir, or create a fresh one if no local data exists. If you are authenticating with client credentials, this is generally what you want to use.

It is recommended to always pass the same lexe_data_dir, regardless of which environment we’re in (dev/staging/prod) and which user this LexeWallet is for. Users and environments will not interfere with each other as all data is namespaced internally. Defaults to ~/.lexe if not specified.

pub fn without_db( env_config: WalletEnvConfig, credentials: CredentialsRef<'_>, ) -> Result<Self>

Create a LexeWallet without any persistence. It is recommended to use fresh or load instead, to initialize with persistence.

Node operations (invoices, payments, node info) work normally. Local payment cache operations (sync_payments, list_payments, clear_payments) are not available and will return an error.

pub fn persistence_enabled(&self) -> bool

Returns true if local persistence is enabled for this wallet.

pub async fn sync_payments(&self) -> Result<PaymentSyncSummary>

Sync payments from the user node to the local payments cache.

Returns an error if local persistence is disabled for this wallet.

pub fn list_payments( &self, filter: &PaymentFilter, order: Option<Order>, limit: Option<usize>, after: Option<&PaymentCreatedIndex>, ) -> Result<ListPaymentsResponse>

List payments from local storage with cursor-based pagination.

Defaults to descending order (newest first) with a limit of 100.

To continue paginating, set after to the next_index from the previous response. after is an exclusive index.

If needed, use sync_payments to fetch the latest data from the node before calling this method.

Returns an error if local persistence is disabled for this wallet.

pub fn clear_payments(&self) -> Result<()>

Clear all locally cached payment data for this wallet.

Clears the local payment cache only. Remote data on the node is not affected. Call sync_payments to re-populate.

Returns an error if local persistence is disabled for this wallet.

pub async fn wait_for_payment( &self, index: PaymentCreatedIndex, timeout: Option<Duration>, ) -> Result<Payment>

Wait for a payment to reach a terminal state (completed or failed).

Polls the node with exponential backoff until the payment finalizes or the timeout is reached. Defaults to 600 seconds (10 minutes). Maximum timeout is 86,400 seconds (24 hours).

pub async fn signup( &self, root_seed: &RootSeed, partner_pk: Option<UserPk>, ) -> Result<()>

Registers this user with Lexe, then provisions the node. This method must be called after the user’s LexeWallet has been created for the first time, otherwise subsequent requests will fail.

It is only necessary to call this method once, ever, per user, but it is also okay to call this method even if the user has already been signed up; in other words, this method is idempotent.

After a successful signup, make sure the user’s root seed has been persisted somewhere! Without access to their root seed, your user will lose their funds forever. If adding Lexe to a broader wallet, a good strategy is to derive Lexe’s RootSeed from your own root seed.

• partner_pk: Set to your company’s UserPk to earn a share of this wallet’s fees.

pub async fn provision(&self, credentials: CredentialsRef<'_>) -> Result<()>

Ensures the wallet is provisioned to all recent trusted releases. This should be called every time the wallet is loaded, to ensure the node is running the most up-to-date enclave software.

This fetches the current enclaves from the gateway, computes which releases need to be provisioned, and provisions them.

pub fn user_config(&self) -> &WalletUserConfig

Get a reference to the user’s wallet configuration.

pub async fn node_info(&self) -> Result<NodeInfo>

Get information about this Lexe node, including balance and channels.

pub async fn analyze(&self, req: AnalyzeRequest) -> Result<AnalyzeResponse>

Get information about a Bitcoin or Lightning payment string, including:

• payable: The payable string encoding the payment method.
• method: The PaymentMethod struct encapsulating information specific to the payment method (e.g. payment hash, metadata, etc…)
• amount/min_amount/max_amount: The amount constraints requested by the receiver.

See PayableDetails for all fields.

The following encodings are supported:

• BIP 321 URI: bitcoin:bc1...
• Lightning URI: lightning:ln...
• BOLT 11 invoice: lnbc1...
• BOLT 12 offer: lno1...
• Onchain bitcoin address: bc1...
• Human Bitcoin Address: ₿satoshi@lexe.app
• Lightning Address: satoshi@lexe.app
• LNURL: lnurl1... or lnurlp://domain.com/path

Within the encodings, the following payment methods are supported:

• BOLT 11 invoice
• BOLT 12 offer
• Bitcoin address
• Lightning Address
• LNURL

pub async fn pay(&self, req: PayRequest) -> Result<Payment>

Pay any string which encodes a Bitcoin or Lightning payment method.

If there exist multiple encoded payment methods, one best recommended payment method will be chosen.

Returns the resulting Payment once it reaches a terminal state (completed or failed). Exception: onchain sends return immediately with the payment still in Pending state, since on-chain confirmation takes ~1 hour.

For finer control over how to pay, consider first using analyze to resolve the contents of the payable string, then invoking the specific pay function for the payment method of choice: pay_invoice, pay_offer, etc.

The following encodings are supported:

• BIP 321 URI: bitcoin:bc1...
• Lightning URI: lightning:ln...
• BOLT 11 invoice: lnbc1...
• BOLT 12 offer: lno1...
• Onchain bitcoin address: bc1...
• Human Bitcoin Address: ₿satoshi@lexe.app
• Lightning Address: satoshi@lexe.app
• LNURL: lnurl1... or lnurlp://domain.com/path

See PaymentMethod for more details on supported payment methods.

pub async fn create_invoice( &self, req: CreateInvoiceRequest, ) -> Result<CreateInvoiceResponse>

Create a BOLT 11 invoice to receive a Lightning payment.

pub async fn pay_invoice(&self, req: PayInvoiceRequest) -> Result<Payment>

Pay a BOLT 11 invoice over Lightning.

Returns the resulting Payment once it reaches a terminal state (completed or failed).

pub async fn create_offer( &self, req: CreateOfferRequest, ) -> Result<CreateOfferResponse>

Create a BOLT 12 offer to receive Lightning payments.

Unlike invoices, offers are reusable: multiple payments can be made to it, including from multiple payers.

pub async fn pay_offer(&self, req: PayOfferRequest) -> Result<Payment>

Pay a BOLT 12 offer over Lightning.

Returns the resulting Payment once it reaches a terminal state (completed or failed).

pub async fn pay_lnurl(&self, req: PayLnurlRequest) -> Result<Payment>

Pay an LNURL or Lightning Address via the payRequest flow.

Returns the resulting Payment once it reaches a terminal state (completed or failed).

pub async fn withdraw_lnurl(&self, req: WithdrawLnurlRequest) -> Result<Payment>

Withdraw an LNURL via the withdrawRequest flow.

Returns the resulting Payment once the withdrawal reaches a terminal state (completed or failed).

pub async fn get_payment( &self, req: GetPaymentRequest, ) -> Result<GetPaymentResponse>

Get information about a payment by its created index.

pub async fn get_updated_payments( &self, req: GetUpdatedPaymentsRequest, ) -> Result<GetUpdatedPaymentsResponse>

Get a batch of payments in ascending updated_at order, starting from a given updated_at index.

Useful for tailing / syncing payment updates as they occur and merging them into a local payments store.

pub async fn update_personal_note( &self, req: UpdatePersonalNoteRequest, ) -> Result<()>

Update the personal note on an existing payment. The note is stored on the user node and is not visible to the counterparty.