Lightning Network Testing Guide

Release Date

Tuesday, April 30, 2024

Updated July 18, 2024

Note: The Lightning Network testing guide is now published as a standalone section in our API documentation.

Summary

Zero Hash is incrementally releasing Lightning Network functionality into the CERT environment as these flows pass our internal testing. This document will be updated as new functionality is released.

Note: Lightning Network transactions use the BTC symbol however are NOT available in NY at this time.

Lightning Network Validation

It is important to note some validations in place for Lightning support at Zero Hash:

The CERT environment points to Lightning Network's Testnet. If you want to create invoices to test withdrawals in CERT, they will need to be gnerated on Testnet (not on Regtest which is the other test network).
Adhere to Zero Hash’s withdrawal amount minimums.
Zero Hash does not support units smaller than satoshis such as millisatoshis.
Lightning Network invoice lengths can grow to significant sizes depending on the amount of data being encoded. Zero Hash will not accept invoices greater than 1,000 characters long. More information on invoice structures can be found on this page.
BTC is the asset symbol used for Lightning Network transactions, where the value being transferred and the Lightning Network fee will be deducted from the participant’s BTC wallet (unless different network fee payor configurations are used).
A Lightning Network invoice input as the destination address will specify that it is a Lightning Network withdrawal. If an L1 BTC destination address is used, funds will be sent across the L1 Bitcoin Network.
Until LNURL support is added, only BOLT11 invoices will be initially supported for CERT testing.

Timeline of Features in CERT and PROD (Updated May 15, 2024)

Bold items are live and have an expanded explanation section below.

CERT Launch (Testnet)

The CERT launch will happen in iterative releases that unlock additional functionality:

April 29: Estimate fee to send payment to BOLT11 invoice on REGTEST
May 6: BOLT11 Lightning Network BTC withdrawals via /withdrawals/
May 8: Migrate CERT environment to Lightning Network's TESTNET (off of REGTEST)
May 21: UMA Deposits and invoice generation
May 30: Universal Money Address (UMA) support for deposits
July 17: BOLT11 Lightning Network withdrawals via /convert_withdraw/
Sept 9: BOLT11 Lightning Network Deposits and invoice generation
Sept 23: Universal Money Address (UMA) support for withdrawals
Sept 30: LNURL Lightning Network BTC withdrawals via /withdrawals/and /convert_withdraw/
Sept 30: LNURL Lightning Network Deposits and invoice generation

PROD Launch (Mainnet)

The PROD launch will happen in weekly releases:

May 21: BOLT11 Lightning withdrawals via /withdrawals/
May 23: UMA deposits and invoice generation
July 18: BOLT11 Lightning Network withdrawals via /convert_withdraw/
Sept 11: BOLT11 Lightning Network Deposits and invoice generation
Sept 27: Universal Money Address (UMA) support for withdrawals
Oct 7: LNURL Lightning Network BTC withdrawals via /withdrawals/and /convert_withdraw/
Oct 7: LNURL Lightning Network Deposits and invoice generation

CERT Release Details (Live)

Estimate Network Fee

To estimate the cost to send a payment to an invoice, call GET /withdrawals/estimate_network_fee.

BOLT11 Lightning Network BTC Withdrawals

To send BTC that is already held in a wallet:

Lock a network fee and return a quote ID by calling GET /withdrawals/locked_network_fee.
Execute the locked network fee quote by calling POST /withdrawals/execute. The destination address needs to be a Lightning Invoice to identify the transaction as one that should be sent on the Lightning Network.

To convert fiat to BTC then send to a Lightning invoice using convert_withdraw:

Convert_withdraw can typically be used ByTotal or ByQuantity. For Lightning Network invoices, only ByQuantity is allowed.

Get RFQ quote using POST /convert_withdraw/rfq
Execute the Quote by calling POST /convert_withdraw/execute

For Lightning Network withdrawals, the destination address must be a Lightning Invoice and

More information on convert_withdraw can be found using this guide.

Generate UMA Invoice

An invoice must be generated in order to receive a deposit over the Lightning Network. This step currently assumes you would like to use your own domain and manage your own UMA server, which will require working with the Zero Hash team to setup (support for ZH-managed available soon).

Once your UMA server is setup, a user must first be registered by your server and then sent to Zero Hash via POST /deposits/uma

Once successfully registered, that participant can then generate an invoice in CERT by calling: uma.cert.zerohash.com/.well-known/lnurlp

Note: if you will see the error message "UMA recipient not found" if attempting to generate an invoice without registering the participant first.

Update UMA username

After an UMA address is registered, it is possible to later update that address using the PATCH /deposits/uma endpoint.

PROD Release Details (Live)

Note that it is recommended to test these flows in CERT first. All platforms must be allow-listed to use Lightning Network functionality in Production.

Estimate Network Fee

To estimate the cost to send a payment to an invoice, call GET /withdrawals/estimate_network_fee.

BOLT11 Lightning Network BTC Withdrawals

To lock a network fee and return a quote ID, call GET /withdrawals/locked_network_fee.

To execute a locked network fee, call POST /withdrawals/execute. The destination address should be an invoice address to identify the transaction as one that should be sent on the Lightning Network.

Generate UMA Invoice

Once your UMA server is setup, a user must first be registered by your server and then sent to Zero Hash via POST /deposits/uma

Once successfully registered, that participant can then generate an invoice in PROD by calling: uma.zerohash.com/.well-known/lnurlp

Note: if you will see the error message "UMA recipient not found" if attempting to generate an invoice without registering the participant first.

Upcoming Features (Not Yet Live)

Upcoming features that will be updated and marked LIVE once they can be tested in CERT:

[Upcoming] LNURL Lightning Network withdrawals via /withdraw/
[Upcoming] BOLT11 and LNURL Lightning Network withdrawals via /convert_withdraw/
[Upcoming] Lightning Network Deposits
[Upcoming] Universal Money Address (UMA) Domain Registration
[Upcoming] Universal Money Address (UMA) Withdrawals
[Upcoming] Universal Money Address (UMA) Deposits

Additional Information

Invoice Formats

There are different types of Lightning Network invoices. Zero Hash plans to first support BOLT11 and then add support for LNURL and UMA. Initial testing in April will only support BOLT11 with the remainder added according to the timeline above.

Launching in Production

CERT functionality is open to all platforms testing in this environment however PROD must be enabled by Zero Hash. If you wish to enable Lightning transactions in your PROD environment please contact the Zero Hash team and we will work with you to enable this network. Please see the following note if you also wish to enable UMA functionality.

Universal Money Address (UMA) Domains

UMA allows you to register end customers to a specific human-readable handle such as an email address (such as $[email protected]). By default, participants will be registered to a Zero Hash-owned domain. If you wish to use your own domain, or want a custom sub-domain instead of the Zero Hash default, please reach out to your Zero Hash team.

Questions

What if I have additional questions? Please reach out to your Zero Hash team who will be happy to support you or refer to one of the following documents: