Pedidos de Pagamento (BOLT 11)
O formato da invoice, por dentro
-
Eric de Castro - Atualizado em
⚡ Lightning · Técnico
A invoice é o pedido de pagamento que a origem lê para saber quanto, para quem e com qual payment_hash. O formato é o BOLT 11, e ele é, no fundo, uma string bech32 — a mesma codificação dos endereços segwit, mas sem o limite de tamanho.
A estrutura da string
Uma invoice lnbc… tem duas partes, separadas pelo último 1 (o separador bech32):
- HRP (human-readable part):
ln+ a rede (bcmainnet,tbtestnet…) + o valor opcional (dígitos + multiplicadorm/u/n/p). Ex.:lnbc2500u= 2500 micro-bitcoins. - Parte de dados: um timestamp (quando foi criada) + os campos com tag + a assinatura.
Os campos com tag
Cada campo da parte de dados tem um tipo (1 caractere bech32) e um tamanho. Os principais:
- p — payment_hash (o cadeado; obrigatório)
- s — payment_secret (amarra as partes de um MPP)
- d — descrição (texto) ou h — hash da descrição
- x — expiração (segundos) · c — min_final_cltv_expiry
- n — node id do destinatário · 9 — features
- r — dicas de roteamento (para canais privados) · f — endereço on-chain de fallback
A assinatura prova quem emitiu
No fim vem a assinatura (65 bytes: r, s e um byte de recuperação), feita sobre o HRP + a parte de dados. O detalhe elegante: com o byte de recuperação, o pagador consegue recuperar a chave pública (o node id) de quem assinou — então a invoice prova quem a emitiu, mesmo sem o campo n.
Cole uma invoice e veja tudo decodificado — inclusive o nó recuperado da assinatura:
Decodificador de Invoice (BOLT 11)
A evolução: offers (BOLT 12)
A invoice BOLT 11 tem dois incômodos: é de uso único (cada pagamento exige uma invoice nova) e expira. Péssimo para um botão de doação fixo ou um QR impresso num cartaz.
O BOLT 12 resolve isso com os offers: um endereço de pagamento reutilizável (a string começa com lno1). Um mesmo offer serve para qualquer valor, quantas vezes quiser, e não expira.
Como um offer vira um pagamento
Diferente do BOLT 11 (onde a invoice já é o documento final que você paga), o offer é só um convite. Na hora de pagar:
- A carteira do pagador lê o offer e envia um pedido de invoice (
invoice_request) ao destinatário — pela própria rede Lightning, numa mensagem cifrada (onion), e não por um servidor web. - O destinatário responde com uma invoice fresca (uma invoice BOLT 12, com seu próprio
payment_hash), assinada na hora. - A carteira paga essa invoice normalmente.
Tudo isso acontece nos bastidores, em segundos, e usa caminhos cegados (blinded paths) para esconder o nó do destinatário. Resultado: cada pagamento tem uma invoice única (sem reusar payment_hash) e quem recebe fica mais privado.
Offer (BOLT 12) × Lightning Address
Os dois dão um "endereço reutilizável", mas por caminhos bem diferentes:
- Lightning Address (
nome@dominio) usa LNURL sobre HTTP: a carteira faz uma requisição a um servidor web do domínio para buscar a invoice. É simples e amplamente suportado, mas depende desse servidor (e do domínio) e é menos privado. - Offer BOLT 12 faz a mesma negociação dentro da própria rede Lightning, sem servidor web nem domínio, e com mais privacidade. Em troca, o suporte nas carteiras ainda é menor.
É por isso que a nossa página de doação oferece os dois: um Lightning Address (funciona em quase toda carteira) e, para quem tem carteira compatível, um offer BOLT 12.
O BOLT 12 ainda está em adoção: já funciona em carteiras/nós como a Phoenix, o Core Lightning e versões recentes do LND, mas nem toda carteira reconhece (a Wallet of Satoshi, por exemplo, ainda não). Há também extensões em desenvolvimento, como offers com recorrência (assinaturas).
A seguir, descemos ao nível das mensagens trocadas entre os nós: o protocolo Wire.