​
Understanding Lightning Invoices

The Spark Service Provider enables trustless Lightning interoperability. To send and receive Lightning payments, you can generate and pay Lightning invoices. A Lightning invoice (also called a payment request) is a specially formatted string that contains all the information needed to make a Lightning Network payment:

  • Amount: How many satoshis to send (can be omitted for zero-amount invoices)
  • Destination: The recipient’s node public key
  • Payment Hash: A unique identifier for the payment
  • Description: Optional memo describing the payment
  • Expiry: How long the invoice is valid for (default 24 hours)

Lightning invoices start with “ln” followed by the network identifier (bc for mainnet) and typically look like this: lnbc1...

Mainnet invoice Example: lnbcrt2500n1pj0ytfcpp5qqqsyqcyq5rqwzqfqypqhp58yjmdan79s6qqdhdzgynm4zwqdx40shp5jqp3qymd6qgpy99ppk0jqjzylqg5t7fhqhpl6s4kxmqgmrn59w5k0z0cqqqqqqzqqqqq9qsqqqqqq9qqqqqqgq9qsqxl9l55y5cwa9s2h8nvdh4h7h43tcwjdcysf7v0fprz5uh6vshs4n0tvhgzz2xgcqpg8yqv7

​
Receiving Lightning Payments

To receive a payment, generate a lightning invoice then share it with the sender.

// Generate invoice with amount
const invoice = await wallet.createLightningInvoice({
  amountSats: 100, // amount in satoshis
  memo: "test invoice", // optional description
});
console.log("Invoice:", invoice);

​
Bolt11 Support Updates

createLightningInvoice now accepts two new optional parameters: includeSparkAddress and receiverIdentityPubkey.

​
Embedding Spark Addresses

By passing in true for includeSparkAddress, a 36-byte string consisting of a recognizable header and a receiver’s compressed identity public key SPK:identitypubkey will get embedded in the fallback address (f) field of a BOLT11 invoice:

const invoice = await wallet.createLightningInvoice({
  amountSats: 100,
  memo: "Invoice with Spark address",
  includeSparkAddress: true,
});
console.log("Invoice with Spark address:", invoice);

​
Creating Invoices for Other Spark Users

To generate an invoice for another Spark user, simply pass in the 33-byte compressed identity pubkey as a string to receiverIdentityPubkey:

const invoice = await wallet.createLightningInvoice({
  amountSats: 100,
  memo: "Invoice for another user",
  receiverIdentityPubkey: "033b4f8cf891e45e2e3995e29b3c8b3d4d4e67f8a9b2c1d3e4f567890abcdef12",
});
console.log("Invoice for another user:", invoice);
If a wallet is generating an invoice for itself and wants to embed its own Spark identity in the invoice, it will not need to pass in a receiverIdentityPubkey to embed a Spark address. That will get taken care of on the backend. Passing it in shouldn’t change anything though.

​
Fallback Address Format

It will look something like this:

{
  version: 31,
  address_hash: "53504b0250949ec35b022e3895fd37750102f94fe813523fa220108328a81790bf67ade5"
}
Spark does not currently support Zero amount invoices. But support is coming soon!

​
Get payment status

To check the status of a Lightning payment, you can use the getLightningReceiveRequest

const lightningPaymentStatus = await wallet.getLightningReceiveRequest(
    invoice.id,
  );
  console.log("Lightning Payment Status:", lightningPaymentStatus);

​
Sending Lightning Payments

To send a payment, you’ll need a Lightning invoice from the recipient and the maximum amount of fees to pay. We recommend setting the maximum routing fee to whichever is greater 5 sats or 17 bps * transaction amount.

const payment_response = await wallet.payLightningInvoice({
  invoice:
    "lnbcrt1u1pnm7ammpp4v84f05tl0kzt6g95g056athdpp8f8azvg6d7epz74z562ymer9jqsp5nc50gazvp0e98u42jlu653rw0eutcl067nqq924hf89q4la4kd9sxq9z0rgqnp4qdnmwu8v22cvq9xsv2l05cn9rre7xlcgdtntxawf8m0zxq3qemgzqrzjqtr2vd60g57hu63rdqk87u3clac6jlfhej4kldrrjvfcw3mphcw8sqqqqrj0q7ew45qqqqqqqqqqqqqq9qcqzpgdq5w3jhxapqd9h8vmmfvdjs9qyyssqj7lf2w4m587g04n4t0ferdv0vnwftzca0xuc9yxycng78cnhrvmyw2mzaa8t76jskpypqnwqhp9xh0vnwxz90jytd34vrmhcngsnl8qplz7ylk",
  maxFeeSats: 5,
});
console.log("Payment Response:", payment_response);

​
Spark Transfer Preference

payLightningInvoice now accepts a preferSpark boolean that defaults to false:

// Pay with Spark preference
const payment_response = await wallet.payLightningInvoice({
  invoice: "lnbc...", // Lightning invoice (potentially with embedded Spark address)
  maxFeeSats: 5,
  preferSpark: true, // Defaults to false
});
console.log("Payment Response:", payment_response);

When preferSpark is set to true, Spark wallets will initiate a Spark transfer instead of a Lightning transfer if a valid Spark address is found in the invoice. If not, a regular Lightning payment will occur.

​
Checking Balance

You can use getBalance() to check a Wallet balance after sending or receiving payments.

The getBalance() method returns a Promise resolving to an object containing:

  • balance: A bigint representing the total amount in satoshis
  • tokenBalances: A Map of token balances, where each entry contains:
    • balance: A bigint representing the token amount
    • tokenInfo: information about the specific token the wallet is holding

Additionally, you can listen for balance update events.

wallet.on("transfer:claimed", (transferId: string, balance: number) => {
  console.log(
    `Transfer ${transferId} claimed. New balance: ${balance}`,
  );

​
Best Practices

  • Always verify invoice amounts before paying
  • Keep track of invoice ids to match balance changes to created invoices
  • Set appropriate expiry times for invoices if necesary
  • Monitor payment status for confirmation

​
Next Steps

Now that you can send and receive Lightning payments, you might want to:

​
Need Help?