BOLT12 Lightning Address Format

Overview

BOLT12 Address Support (DRAFT!)

Inspired by the awesome lightningaddress.com, except for BOLT12:

  1. Supports BOLT12
  2. Allows BOLT12 vendor string authentication
  3. Doesn't require your wallet to query the server directly
  4. Required only to establish the initial node linkage

How Does it Work?

Like lightningaddress.com, you turn [email protected] into a web request:

https://domain.com/.well-known/bolt12/bitcoin/[email protected]

But you can also authenticate the entire domain:

https://domain.com/.well-known/bolt12/bitcoin/domain.com

(Instead of bitcoin you could use testnet, signet or regtest)

The Format

The format is a bolt12 TLV binary (Content-type: application/x-lightning-bolt12), containing the following fields:

  1. tlv_stream: addressproof
  2. types:
    • type: 2 (chains)
    • data:
      • [...*chain_hash:chains]
    • type: 10 (description)
    • data:
      • [...*utf8:description]
    • type: 12 (features)
    • data:
      • [...*byte:features]
    • type: 14 (absolute_expiry)
    • data:
      • [tu64:seconds_from_epoch]
    • type: 16 (paths)
    • data:
      • [...*blinded_path:paths]
    • type: 20 (vendor)
    • data:
      • [...*utf8:vendor]
    • type: 60 (node_ids)
    • data:
      • [...*point32:node_ids]
    • type: 500 (certsignature)
    • data:
      • [...*byte:sig]
    • type: 501 (cert)
    • data:
      • [...*byte:cert]
    • type: 503 (certchain)
    • data:
      • [...*byte:chain]

Only the vendor, node_ids and certsignature fields are required, the others are optional.

Requirements

The writer:

  • MUST set vendor to filename being served:
  • MUST set node_ids to zero or more node_ids which will be used to sign offers for this vendor.
  • MUST set chains to the chains these node_ids are valid for, or MAY not set chains if the node_ids are valid for Bitcoin.
  • MAY set features, absolute_expiry, description and paths (see BOLT 12).
  • MUST set certsignature to the RSA signature (using PSS padding mode maximum saltlen) of the BOLT-12 merkle root as per BOLT12 Signature Calculation using the secret key for the domain in vendor.
  • MUST NOT set description unless it has an offer which is constructed using the other fields, and the offer's node_id set to the first of the node_ids.
  • If it is serving the addressproof over HTTPS:
    • MAY set cert and certchain
  • Otherwise:
    • MUST set both cert and certchain
  • If it sets cert:
    • MUST set it to the PEM-encoded certificate corresponding to the domain
  • If it sets certchain:
    • MUST set it to the PEM-encoded chain of certificates leading from cert to the root CA

The reader:

  • MUST NOT accept the address proof if vendor, node_ids or certsignature is not present.

  • MUST NOT accept the address proof if an even unknown bit is set in features.

  • If it has NOT retrieved the addressproof over HTTPS:

    • MUST NOT accept the address proof if:
      • cert is not present, or not valid for the domain in vendor.
      • certchain is not present, or does not link cert to a root certificate authority.
      • certsignature field is not a valid signature for BOLT-12 merkle root using the key in cert.
  • otherwise:

    • MAY retrieve cert and certchain from the HTTPS connection.
    • MAY NOT accept the address proof as it would in the non-HTTPS case above.
  • If if has a previous, valid addressproof for this vendor:

    • MUST ONLY replace it with this address proof if:
      • absolute_expiry is set, AND
      • it is greater than the previous absolute_expiry OR the previous had no absolute_expiry field.
  • MUST consider the addressproof no longer valid if absolute_expiry is set and the current number of seconds since 1970 is greater than that value.

  • if description is present:

    • MAY use the fields of this addressproof as an unsigned offer.
  • When it encounters a vendor field in a BOLT12 offer or invoice:

    • if the vendor begins with a valid domain, up to a space character:
      • SHOULD WARN the user if it cannot find a current valid address proof.
      • SHOULD reject the offer or invoice if the node_id is not one of the node_ids in the offer.

Text Encoding

The human-readable prefix for addressproof is lnap, if you want it encoded as a string.

What Does All This Do?

This allows domain validation for bolt 12 offers, which already have a vendor field for this purpose. e.g if the vendor in an offer is "blockstream.com Get your blocks here!" then your wallet can reach out to blockstream.com to see if it the node_id in the offer really is under their control.

It also allows node_id proofs for individual addresses.

But you don't need to reach out to blockstream.com: anyone (including your wallet vendor, or the node claiming to be blockstream.com) can collect all the addressproofs and certificates for you, as they contain a signature using the existing web certificate infrastructure. Bundling these protects your privacy more than having to request to a vendor's website before making a payment.

This format is a subset of the BOLT12 offer format, so if it has a description it is actually a valid (amountless) offer, allowing immediate tipping using it.

You can also include zero node_ids, as a way of indicating that you do not have any lightning nodes.

Examples

You will need access to your privkey.pem, cert.pem and chain.pem files on your HTTPS webserver which serves the domain.

This creates a proof that bolt12.org operates nodeid 4b9a1fa8e006f1e3937f65f66c408e6da8e1ca728ea43222a7381df1cc449605 (note we omit the 02/03 prefix):

$ ./shell/make-addressproof.sh \
   --vendor=bolt12.org \
   --nodeid=4b9a1fa8e006f1e3937f65f66c408e6da8e1ca728ea43222a7381df1cc449605 \
   --privkeyfile=certs/privkey.pem \
   --certfile=certs/cert.pem \
   --chainfile=certs/chain.pem > .well-known/bolt12/bitcoin/bolt12.org

This does the same thing using the Python script:

$ ./python/bolt12address.py create \
   --raw \
   bolt12.org \
   certs/privkey.pem \
   certs/cert.pem \
   certs/chain.pem \
   4b9a1fa8e006f1e3937f65f66c408e6da8e1ca728ea43222a7381df1cc449605 \
   > .well-known/bolt12/bitcoin/bolt12.org

This creates a signet signature for multiple nodeids, for the user [email protected], and adds a description so it can also serve as offer for sending unsolicited payments (note: see below!):

$ ./shell/make-addressproof.sh \
   [email protected] \
   --nodeid=4b9a1fa8e006f1e3937f65f66c408e6da8e1ca728ea43222a7381df1cc449605 \
   --nodeid=994b9a1fa8e006f1e3937f65f66c408e6da8e1ca728ea43222a7381df1cc4496 \
   --privkeyfile=certs/privkey.pem \
   --certfile=certs/cert.pem \
   --chainfile=certs/chain.pem \
   --chain=signet \
   --description='Unsolicited bolt12address donation' \
   > .well-known/bolt12/signet/[email protected]

And in Python:

$ ./python/bolt12address.py create \
   --raw \
   --description='Unsolicited bolt12address donation' \
   --chain=signet \
   [email protected] \
   certs/privkey.pem \
   certs/cert.pem \
   certs/chain.pem \
   4b9a1fa8e006f1e3937f65f66c408e6da8e1ca728ea43222a7381df1cc449605 \
   994b9a1fa8e006f1e3937f65f66c408e6da8e1ca728ea43222a7381df1cc4496 \
   > .well-known/bolt12/signet/[email protected]

We can check this using python:

$ ./python/bolt12address.py check --raw-stdin < .well-known/bolt12/signet/[email protected]
chains: ['f61eee3b63a380a477a063af32b2bbc97c9ff9f01f2c4225e973988108000000']
description: Unsolicited bolt12address donation
vendor: [email protected]
node_ids: ['4b9a1fa8e006f1e3937f65f66c408e6da8e1ca728ea43222a7381df1cc449605', '994b9a1fa8e006f1e3937f65f66c408e6da8e1ca728ea43222a7381df1cc4496']
certsignature: 173e...

offer_id: 3234297fb2414b62c16ac9751ac241050199ec5e2cd83e713136cc26974f09a8
offer_id: 3139b327c9fa6637a7ef620149425a1163e19a1181c9f1cbdc7820360dd40c23

The offer_id at the end if description is populated (one for each node_id) is the offer_id anyone reading would expect to be able to send funds to. You should create this offer (with that description and no amount) on your node!

Refreshing Existing Proofs

There's a simple helper to refresh existing address proofs, such as when your certificate changes:

$ ./python/bolt12address.py refresh \
   certs/privkey.pem \
   certs/cert.pem \
   certs/chain.pem \
   .well-known/bolt12/signet/*bolt12.org
.well-known/bolt12/signet/[email protected]: REFRESHED

TODO

This is a draft: I expect it to change after feedback (especially since the certinficates and signatures are large and clunky).

The code does not check the certificate chain, and is generally could use polishing.

We also need more routines in different languages to fetch and check the bolt12address, and a method so Lightning nodes can serve their addressproof directly.

Feedback

You can reach out to me as [email protected] or join the bolt12 telegram group at https://t.me/bolt12org.

Happy hacking!

Owner
Rusty Russell
GPG: 15EE 8D6C AB0E 7F0C F999 BFCB D920 0E6C D1AD B8F1 Rusty Russell
Rusty Russell
Install, run, and update apps without root and only in your home directory

Qube Apps Install, run, and update apps in the private storage of a Qube. Build and install in Qubes Get the code: git clone https://github.com/micahf

Micah Lee 26 Dec 27, 2022
Create C bindings for python automatically with the help of libclang

Python C Import Dynamic library + header + ctypes = Module like object! Create C bindings for python automatically with the help of libclang. Examples

1 Jul 25, 2022
Adding two matrix from scratch using python.

Adding-two-matrix-from-scratch-using-python. Here, I have take two matrix from user and add it without using any library. I made this program from scr

Sachin Vinayak Dabhade 4 Sep 24, 2021
A python app which aggregates and splits costs from multiple public cloud providers into a csv

Cloud Billing This project aggregates the costs public cloud resources by accounts, services and tags by importing the invoices from public cloud prov

1 Oct 04, 2022
This is a tool to calculate a resulting color of the alpha blending process.

blec: alpha blending calculator This is a tool to calculate a resulting color of the alpha blending process. A gamma correction is enabled and the def

Igor Mikushkin 12 Sep 07, 2022
glip is a module for retrieve ip address like local-ip, global-ip, external-ip as string.

gle_ip_info glip is a module for retrieve ip address like local-ip, global-ip, external-ip as string.

Fatin Shadab 3 Nov 21, 2021
jsoooooooon derulo - Make sure your 'jason derulo' is featured as the first part of your json data

jsonderulo Make sure your 'jason derulo' is featured as the first part of your json data Install: # python pip install jsonderulo poetry add jsonderul

jesse 3 Sep 13, 2021
Two fast AUC calculation implementations for python

fastauc Two fast AUC calculation implementations for python: python-based is approximately 5X faster than the default sklearn.metrics.roc_auc_score()

Vsevolod Kompantsev 26 Dec 11, 2022
Analyze metadata of your Python project.

Analyze metadata of your Python projects Setup: Clone repo py-m venv venv (venv) pip install -r requirements.txt specify the folders which you want to

Pedro Monteiro de Carvalho e Silva Prado 1 Nov 10, 2021
A utility that makes it easy to work with Python projects containing lots of packages, of which you only want to develop some.

Mixed development source packages on top of stable constraints using pip mxdev [mɪks dɛv] is a utility that makes it easy to work with Python projects

BlueDynamics Alliance 6 Jun 08, 2022
Retrying library for Python

Tenacity Tenacity is an Apache 2.0 licensed general-purpose retrying library, written in Python, to simplify the task of adding retry behavior to just

Julien Danjou 4.3k Jan 05, 2023
Extract XML from the OS X dictionaries.

Extract XML from the OS X dictionaries.

Joshua Olson 13 Dec 11, 2022
Grank is a feature-rich script that automatically grinds Dank Memer for you

Grank Inspired by this repository. This is a WIP and there will be more functions added in the future. What is Grank? Grank is a feature-rich script t

42 Jul 20, 2022
✨ Un chois aléatoire d'un article sur Wikipedia totalement fait en Python par moi, et en français.

Wikipedia Random Article ❗ Un chois aléatoire d'un article sur Wikipedia totalement fait en Python par moi, et en français. 🔮 Grâce a une requète a w

MrGabin 4 Jul 18, 2021
python-codicefiscale: a tiny library for encode/decode Italian fiscal code - codifica/decodifica del Codice Fiscale.

python-codicefiscale python-codicefiscale is a tiny library for encode/decode Italian fiscal code - codifica/decodifica del Codice Fiscale. Features T

Fabio Caccamo 53 Dec 14, 2022
Small project to interact with python, C, HTML, JavaScript, PHP.

Micro Hidroponic Small project to interact with python, C, HTML, JavaScript, PHP. Table of Contents General Info Technologies Used Screenshots Usage P

Filipe Martins 1 Nov 10, 2021
Utility to play with ADCS, allows to request tickets and collect information about related objects.

certi Utility to play with ADCS, allows to request tickets and collect information about related objects. Basically, it's the impacket copy of Certify

Eloy 185 Dec 29, 2022
JavaScript-style async programming for Python.

promisio JavaScript-style async programming for Python. Examples Create a promise-based async function using the promisify decorator. It works on both

Miguel Grinberg 191 Dec 30, 2022
Easy compression and extraction for any compression or archival format.

Tzar: Tar, Zip, Anything Really Easy compression and extraction for any compression or archival format. Usage/Examples tzar compress large-dir compres

DanielVZ 37 Nov 02, 2022
Monte Carlo simulation of 3G rules

mc3g Monte Carlo simulation of 3G rules This project contains the Python code to do simulations of events according to the 3G rule (in German: "Geimpf

Jan Christoph Terasa 4 Nov 01, 2021