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
A simple package for handling variables in string.

A simple package for handling string variables. Welcome! This is a simple package for handling variables in string, You can add or remove variables wi

1 Dec 31, 2021
Dice Rolling Simulator using Python-random

Dice Rolling Simulator As the name of the program suggests, we will be imitating a rolling dice. This is one of the interesting python projects and wi

PyLaboratory 1 Feb 02, 2022
Shypan, a simple, easy to use, full-featured library written in Python.

Shypan, a simple, easy to use, full-featured library written in Python.

ShypanLib 4 Dec 08, 2021
Definitely legit social credit generator with python

definitely-legit-social-credit-generator I made this simple GUI program for a meme, no cap. Video: https://youtu.be/RmjxKtoli04 How to run: Clone this

Joshua Malabanan 8 Nov 01, 2021
A small python library that helps you to generate localization strings for your mobile projects.

LocalizationUtiltiy A small python library that helps you to generate localization strings for your mobile projects. This small script aims to help yo

1 Nov 12, 2021
A Python utility belt containing simple tools, a stdlib like feel, and extra batteries. Hashing, Caching, Timing, Progress, and more made easy!

Ubelt is a small library of robust, tested, documented, and simple functions that extend the Python standard library. It has a flat API that all behav

Jon Crall 638 Dec 13, 2022
Go through a random file in your favourite open source projects!

Random Source Codes Never be bored again! Staring at your screen and just scrolling the great world wide web? Would you rather read through some code

Mridul Seth 1 Nov 03, 2022
Data Utilities e.g. for importing files to onetask

Use this repository to easily convert your source files (csv, txt, excel, json, html) into record-oriented JSON files that can be uploaded into onetask.

onetask.ai 1 Jul 18, 2022
A string to hashtags module

A string to hashtags module

Fayas Noushad 4 Dec 01, 2021
Produce a simulate-able SDF of an arbitrary mesh with convex decomposition.

Mesh-to-SDF converter Given a (potentially nasty, nonconvex) mesh, automatically creates an SDF file that describes that object. The visual geometry i

Greg Izatt 22 Nov 23, 2022
SysInfo is an app developed in python which gives Basic System Info , and some detailed graphs of system performance .

SysInfo SysInfo is an app developed in python which gives Basic System Info , and some detailed graphs of system performance . Installation Download t

5 Nov 08, 2021
Airspy-Utils is a small software collection to help with firmware related operations on Airspy HF+ devices.

Airspy-Utils Airspy-Utils is a small software collection to help with firmware related operations on Airspy HF+ devices on Linux (and other free syste

Dhiru Kholia 11 Oct 04, 2022
Fcpy: A Python package for high performance, fast convergence and high precision numerical fractional calculus computing.

Fcpy: A Python package for high performance, fast convergence and high precision numerical fractional calculus computing.

SciFracX 1 Mar 23, 2022
Python HTTP Agent Parser

Features Fast Detects OS and Browser. Does not aim to be a full featured agent parser Will not turn into django-httpagentparser ;) Usage import ht

Shekhar 213 Dec 06, 2022
Python USD rate in RUB parser

Python EUR and USD rate parser. Python USD and EUR rate in RUB parser. Parsing i

Andrew 2 Feb 17, 2022
Gradually automate your procedures, one step at a time

Gradualist Gradually automate your procedures, one step at a time Inspired by https://blog.danslimmon.com/2019/07/15/ Features Main Features Converts

Ross Jacobs 8 Jul 24, 2022
A clock app, which helps you with routine tasks.

Clock This app helps you with routine tasks. Alarm Clock Timer Stop Watch World Time (Which city you want) About me Full name: Matin Ardestani Age: 14

Matin Ardestani 13 Jul 30, 2022
Package that allows for validate and sanitize of string values.

py.validator A library of string validators and sanitizers Insipired by validator.js Strings only This library validates and sanitizes strings only. P

Sanel Hadzini 22 Nov 08, 2022
A BlackJack simulator in Python to simulate thousands or millions of hands using different strategies.

BlackJack Simulator (in Python) A BlackJack simulator to play any number of hands using different strategies The Rules To keep the code relatively sim

Hamid 4 Jun 24, 2022
An online streamlit development platform

streamlit-playground An online streamlit development platform Run, Experiment and Play with streamlit Components Develop full-fledged apps online All

Akshansh Kumar 3 Nov 06, 2021