HASHRATE: 1.35 Eh/s LAST BLOCK: 844208 (6H AGO)

1.35 Eh/s • BLOCK: 6H AGO

Lightning Payouts

Bitcoin Mechanic
April 22, 2024
Overview

OCEAN uses BOLT12 offers for Lightning payouts.

To ensure the security and anonymity of the payouts, OCEAN requires that a message is signed linking your OCEAN bitcoin address to a BOLT12 offer.

To do this, message signing will need to be supported by your wallet and/or signing device.

Once you have generated a BOLT12 offer, OCEAN will provide you with a message to sign.

Note: You must ensure that you have one or more Lightning channels and the necessary inbound liquidity to receive payments, otherwise payments to you will fail.

Should OCEAN be unable to pay via Lightning, your on-chain address will be used as a fallback once your earnings reach the payout threshold.

Getting Core Lightning

Due to our use of Core Lightning (CLN) and the experimental nature of BOLT12, it is best to use CLN as your node. At the time of writing, only CLN is known to work, but we will update this documentation as more compatible implementations of BOLT12 become available.

A simple way to do this is using StartOS. You can buy a Start9 server here (buying through this link will give you a 5% discount). Alternatively you can download the OS for free here.

If you have the ability, set up your own server and install Core Lightning on it. You can also install Core Lightning on a laptop, though it's generally advisable to run a Lightning node on devices that are designed to be on 100% of the time, which is why we suggest running a dedicated server.

Generating the BOLT12 Offer

Follow the instructions below to generate a BOLT12 offer.

StartOS arrow_down

To generate the BOLT12 offer on StartOS, click the Launch UI button pictured below, then:

  • Enter your password
  • Click "Receive"
  • Click "Offer"
  • Enter "OCEAN Payouts for address" (where address is your OCEAN Bitcoin address), and leave "Amount" blank (Note: this text, including your Bitcoin address, is case-sensitive)
  • Click "Generate Offer".

Do not enter an amount, as OCEAN needs to have the freedom to payout varying amounts.

Copy the generated text - you will need it for the next step.

The above all works on Umbrel.

Command Line arrow_down

Note: to do this you will need to launch Core Lightning with the flag --experimental-offers.

To generate a BOLT12 offer on your Core Lightning node simply enter the command

lightning-cli offer any "OCEAN Payouts for address"

where address is your OCEAN Bitcoin address. (Note: this text, including your Bitcoin address, is case-sensitive.)

If the BOLT12 offer has an expiration, it must be at least one week in the future.

Copy the text after "bolt12":

Generating the Configuration Message

Once you have generated a BOLT12 offer, navigate to the My Stats page for your OCEAN Bitcoin address, then click the Configuration link next to Next Block to access the configuration form.

Paste the BOLT12 offer here, update the block height to latest, click GENERATE, and copy the generated unsigned message.

Signing the Configuration Message

To sign the generated message, follow the instructions for your wallet or signing device below. (This list is still being updated.)

Bitcoin Knots/Bitcoin Core arrow_down

Note: at present, this only works for legacy addresses.

Click File -> Sign Message.

Paste in your Bitcoin address and unsigned message.

Click Sign Message and copy the signature.

Coldcard arrow_down

Find instructions here -> https://coldcard.com/docs/sign-text-file/

This requires learning the derivation path of your OCEAN address. You will need to:

  • Save the generated un-signed message provided by OCEAN
  • Paste it into a text file
  • Add the derivation path and address type to the text file, on separate lines as shown below
  • Save the text file to and SD card and use your Coldcard to sign it
  • Open the newly generated text file and copy only the signature. The signature is the second line between BEGIN BITCOIN SIGNATURE and END BITCOIN SIGNATURE, following your Bitcoin address.
Electrum arrow_down

Go to Tools -> Sign/verify message, then enter the unsigned message and your OCEAN address and click Sign, as below.

Copy the signature from the highlighted box and head back to OCEAN.

Seedsigner arrow_down

Follow the instructions in this video.

Sparrow arrow_down
  • Go to "Tools" -> "Sign/Verify Message"
  • Paste in your Bitcoin address
  • Paste in the unsigned message generated by OCEAN
  • Click "Sign"
  • Copy and paste the signature back into OCEAN

Specter arrow_down

Note: only works with USB-connected devices and single-sig addresses.

Follow the guide here: https://docs.specter.solutions/desktop/sign-message/

Trezor arrow_down

Follow Trezor's instructions here.

Submitting the Signed Message

Once signed, copy the signature, paste it into the configuration form, and click CONFIRM.