Skip to main content

Lightning Sends and Receives

Fedimint ecash is issued against onchain bitcoin, but is interoperable with the Lightning Network via "Gateways": users of the Fedimint who also run lightning nodes and perform payments as a service in exchange for ecash.

Fedi follows a Lightning-First design pattern: lightning is always presented as the primary payment mechanism, then Fedi internally handles it most effectively e.g. by recognizing the lightning invoice is from someone within your same or another connected federation and settling it directly with ecash to save on fees. Presenting Lightning first promotes easy interoperability with other wallets and services in the Bitcoin ecosystem.

Paying a Lightning Invoice from Fedi​

A Fedi User can scan or enter a standard Bolt11 Invoice, LNURL, or Lightning Address (or Bolt12 soon!) from the Send Button or universal QR scanner, then simply click "Send" on the confirmation page to make the payment. From the user's perspective, the invoice will just get paid and their Fedi wallet balance will go down by that amount.

How it Works Under the Hood​

When the user scans the invoice, the wallet builds an ecash transaction structured as:

  1. The invoice which the user wants a Gateway to pay for X satoshis
  2. The user's wallet funds a Lightning Contract with the invoice + X+fees satoshis of ecash
  3. The Lightning Gateway can unlock the contract and sweep the ecash by providing the preimage it receives when it pays the invoice
  4. If the Gateway doesn't pay the invoice, the user can sweep the ecash back to themselves after a timeout

and publishes the transaction to the federation consensus.

The transaction is structured as "Anyone can sweep these X+fees satoshis of ecash if they prove they paid the attached invoice for X satoshis, otherwise the user can sweep it back after a timeout."

info

This X+fees is why Fedi can't currently support amountless invoices: the amount commitment needs to be in the invoice itself otherwise the gateway would just pay 1 satoshi and sweep the rest as fees.

Lightning Gateways compete to pay the user's invoice, incentivized by the fees delta they make.

Receiving via Lightning Invoice from Fedi​

To receive via lightning, simply click the Receive Button on your wallet to create a Bolt11 invoice for a specified amount. Again, Fedi does not support amountless invoice because the invoice must commit to the amount the gateway needs to pay. When the invoice is paid by the sender, the Fedi User will see the invoice marked as "Paid" and their balance increase.

info

Because Fedimint ecash is locked to a pubkey, a Fedimint user doesn't have to be online to receive a lightning payment. Several Fedimint developers are leveraging this to create noncustodial Fedimint backed lightning addresses that can create an invoice on behalf of a Fedimint user's pubkey when prompted via the standard LNURL or Lightning Address protocols.

How it Works Under the Hood​

Receiving via Lightning Gateway works similarly to sending but in reverse and with a specific gateway. The Fedi user tweaks the Gateway's NodeId to create a fake recipient pubkey and creates a lightning invoice with:

  1. The fake pubkey as the recipient
  2. The amount (X + fees) for the invoice
  3. The Gateway NodeId as a "route hint", for the sender to use in their pathfinding
  4. An indicator as a scid in the Gateway nodeid "route hint"

The user then structures a fedimint contract containing the user created invoice for X+fees satoshis and broadcasts it to the federation.

When someone attempts to pay the lightning invoice, they'll create a payment path with the Gateway as the final hop. When the gateway receives the onion message for the payment, its gatewayd interceptor will inspect the invoice and recognize that it's intended for a user of the Federation hidden in the scid. The gateway will ping that federation looking for a contract for that invoice.

The gateway sees that a fedimint user created a contract stating "If you prove you locked X satoshis of ecash to my public key, it will reveal the preimage for the X+fees satoshis lightning payment which you can sweep." The Lightning Gateway locks ecash to the user's pubkey, and sweeps the preimage to complete the invoice, incentivized by the fees delta he makes. The Fedimint user can sweep the ecash whenever they next come online.