Pedidos de Pagamento BOLT 11

Como uma invoice codifica valor, destino, hash, features e dicas de rota

• Eric de Castro
• Atualizado em 26/06/2026

⚡ Lightning · Técnico

Uma invoice Lightning e um pedido de pagamento assinado pelo recebedor. Ela diz ao pagador qual rede usar, qual valor pagar, qual payment_hash travara o HTLC, qual payment_secret deve chegar ao destino, quais features sao exigidas e, quando necessario, como encontrar o recebedor por canais privados.

A especificacao principal e a BOLT 11. Ela usa Bech32, SHA256 e assinatura ECDSA sobre a curva secp256k1. No fluxo de pagamento, os dados da invoice alimentam o buscador de caminho, o payload onion e os HTLCs enviados pelos canais.

Esta pagina fala de BOLT 11. BOLT 12 offers aparecem no fim como evolucao, mas nao sao o mesmo formato: BOLT 12 usa TLV, assinaturas Schnorr/BIP340 e um fluxo interativo de offer -> invoice_request -> invoice.

Conteúdo

Modelo mental

Uma invoice BOLT 11 nao move dinheiro. Ela prepara o pagamento. O dinheiro so se move quando o pagador transforma aquela invoice em uma rota, monta um pacote onion e envia um update_add_htlc pelo primeiro canal.

1. O recebedor sorteia uma payment_preimage e calcula payment_hash = SHA256(payment_preimage).
2. O recebedor cria uma invoice com payment_hash, payment_secret, descricao, valor opcional, expiracao, CLTV final, features e dicas de rota opcionais.
3. O recebedor assina a invoice com a chave privada do seu node id.
4. O pagador valida a invoice, decide se aceita valor, expiracao, fees e timeout, calcula uma rota e cria o onion packet.
5. O hop final recebe no payload onion o payment_secret e, se existir, o payment_metadata da invoice.
6. Se o recebedor aceitar o conjunto de HTLCs, ele revela a preimage. A preimage vira a prova pratica de pagamento daquele payment_hash.

Estrutura da invoice

Uma invoice como lnbc... tem duas grandes partes separadas pelo ultimo caractere 1:

• HRP, ou human-readable part. Comeca com ln, inclui o prefixo de rede e pode incluir o valor.
• Data part. Contem timestamp, campos com tag, assinatura compacta e checksum Bech32.

Descricao longa do diagrama

O diagrama mostra uma string de invoice separada em HRP, separador 1 e data part. A data part e quebrada em timestamp, campos com tag, assinatura e checksum. A imagem destaca que o HRP informa rede e valor, enquanto a data part carrega os dados tecnicos usados para pagar.

lnbc2500u1...
^^^^^^^^
ln      = invoice Lightning
bc      = Bitcoin mainnet
2500u   = 2500 micro-bitcoins = 0,00250000 BTC

Rede e valor no HRP

O prefixo de rede fica dentro do HRP. Para Bitcoin, os prefixos comuns sao:

Prefixos de rede em invoices BOLT 11

Prefixo	Rede	Exemplo
lnbc	Bitcoin mainnet	lnbc...
lntb	Bitcoin testnet	lntb...
lntbs	Bitcoin signet	lntbs...
lnbcrt	Bitcoin regtest	lnbcrt...

O valor e opcional. Quando existe, a unidade base e bitcoin, nao satoshi. A letra final e um multiplicador decimal:

Multiplicadores de valor

Sufixo	Multiplicador em BTC	Exemplo
m	0,001	lnbc20m = 0,02000000 BTC
u	0,000001	lnbc2500u = 0,00250000 BTC
n	0,000000001	lnbc100n = 10 sats
p	0,000000000001	lnbc1000p = 100 msat

O sufixo p trabalha em pico-bitcoin. Como a Lightning encaminha HTLCs em millisatoshis, a BOLT 11 exige que valores com p terminem em 0, evitando valor abaixo de 1 msat.

Invoice sem valor nao significa pagamento livre sem validacao. Significa que o pagador escolhe o valor, mas o recebedor ainda pode recusar no momento de aceitar o HTLC.

Data part e tagged fields

A data part comeca com um timestamp de 35 bits, em segundos desde 1970-01-01 UTC. Depois vem uma sequencia de campos com tag. Cada campo tem:

[ type: 5 bits ][ data_length: 10 bits ][ data: data_length grupos de 5 bits ]

O tamanho maximo do dado de um campo e limitado por data_length: 1023 grupos de 5 bits, isto e, ate 639 bytes. Isso importa para descricoes, metadata e extensoes futuras.

Campos BOLT 11 mais importantes

Tag	Nome	Obrigacao	Dado	Uso
p (1)	payment_hash	obrigatorio, exatamente um	32 bytes	Hash SHA256 da preimage que o recebedor revelara se o pagamento for concluido.
s (16)	payment_secret	obrigatorio, exatamente um	32 bytes	Segredo escolhido pelo recebedor para dificultar probing e amarrar o pagamento ao payload final.
d (13)	description	d ou h, exatamente um dos dois	UTF-8 variavel	Descricao curta do motivo do pagamento.
h (23)	description_hash	d ou h, exatamente um dos dois	32 bytes	Hash SHA256 de uma descricao externa maior.
x (6)	expiry	opcional	inteiro em segundos	Tempo relativo de expiracao. Se ausente, o default da BOLT 11 e 3600 segundos.
c (24)	min_final_cltv_expiry_delta	recomendado	inteiro em blocos	Delta minimo de CLTV que o recebedor exige no HTLC final. Se ausente, o pagador usa pelo menos 18.
n (19)	node_id	opcional	33 bytes	Chave publica comprimida do no recebedor. Se ausente, o pagador recupera o node id pela assinatura.
9 (5)	features	opcional	feature vector	Funcionalidades exigidas ou aceitas para este pagamento, seguindo a BOLT 9.
r (3)	routing_info	opcional, pode repetir	rotas de 51 bytes por hop	Dicas de rota para canais privados ou nao anunciados.
f (9)	fallback_address	opcional, pode repetir	endereco on-chain codificado	Endereco Bitcoin de fallback caso o pagamento Lightning falhe.
m (27)	payment_metadata	opcional	bytes variaveis	Metadados que o pagador copia para o payload onion final.

O parser precisa ser tolerante com campos que pode ignorar, mas rigido com estrutura invalida. Campos fixos como p, h, s e n precisam ter o tamanho correto. A invoice deve ter exatamente um p, exatamente um s e exatamente um entre d e h.

entrada: invoice BOLT 11

1. verificar Bech32 sem limite de 90 caracteres
2. separar HRP e data part pelo separador "1"
3. validar prefixo "ln" + rede + valor opcional
4. ler timestamp de 35 bits
5. percorrer tagged fields:
   - type: 5 bits
   - data_length: 10 bits
   - data: data_length grupos de 5 bits
6. separar os ultimos 104 grupos de 5 bits como assinatura
7. validar campos obrigatorios:
   - exatamente um p
   - exatamente um s
   - exatamente um d ou exatamente um h
8. validar a assinatura ECDSA/secp256k1
9. montar o pagamento:
   - payment_hash vem do campo p
   - payment_secret vem do campo s
   - min_final_cltv_expiry_delta vem do campo c ou default
   - routing hints vem dos campos r
   - features vem do campo 9

payment_hash, payment_secret e metadata

O campo p carrega o payment_hash. Ele e o cadeado do pagamento: todos os HTLCs daquele pagamento usam o mesmo hash, e o recebedor so recebe de fato ao revelar a preimage correta.

O campo s carrega o payment_secret. Esse valor nao e a preimage. Ele e um segredo diferente, escolhido pelo recebedor, que o pagador precisa colocar no payload onion do hop final. Isso ajuda o recebedor a rejeitar tentativas de probing que descobriram um payment_hash mas nao possuem a invoice correta.

Quando o campo m aparece, ele vira payment_metadata no payload final. Ele permite que o recebedor seja mais stateless, porque pode embutir dados de contexto na invoice e receber esses dados de volta no pagamento. O custo e tamanho: metadata grande consome espaco dentro do pacote onion e pode reduzir o comprimento maximo pratico da rota.

tlv_payload do hop final
type 2  amt_to_forward       = 100000 msat
type 4  outgoing_cltv_value  = 850000
type 8  payment_data:
        payment_secret = 32 bytes vindos do campo s da invoice
        total_msat     = 100000
type 16 payment_metadata     = bytes vindos do campo m, se existir

Nunca trate payment_secret como chave privada, seed ou backup. Ele e sensivel para aquela tentativa de pagamento, mas nao controla fundos sozinho. Mesmo assim, ferramentas educativas devem usar apenas exemplos ficticios.

Routing hints e fallback

Um recebedor pode ter canais privados, isto e, canais que nao aparecem no gossip publico. Nesse caso, o pagador nao consegue descobrir sozinho o ultimo trecho do caminho. O campo r resolve isso fornecendo dicas de rota.

campo r: uma entrada de rota privada
pubkey                         33 bytes
short_channel_id                8 bytes
fee_base_msat                   4 bytes
fee_proportional_millionths     4 bytes
cltv_expiry_delta               2 bytes

total: 51 bytes por hop

Uma invoice pode ter mais de um campo r. Cada um representa uma opcao de caminho, em ordem de preferencia. O pagador pode combinar essas dicas com o grafo publico, calcular fees e CLTVs, e tentar uma rota ate o recebedor.

O campo f e diferente: ele nao ajuda a rotear pela Lightning. Ele fornece um endereco Bitcoin on-chain de fallback. Pela BOLT 11, se a tentativa Lightning falhar, o pagador pode tentar usar o primeiro fallback que entende. Isso nao deve ser usado automaticamente sem mostrar ao usuario, porque uma transacao on-chain tem outra privacidade, outra taxa, outro tempo de confirmacao e nao segue a mesma semantica de HTLC.

Para entender o lado on-chain do fallback, veja Transacao, Saida, Endereco, Bech32 e Memory Pool.

Assinatura e node id

No fim da data part vem a assinatura compacta ECDSA/secp256k1: 64 bytes de R || S mais 1 byte de recovery id. Como ela cobre o HRP e a data part sem a assinatura, qualquer alteracao no valor, descricao, hash, features ou expiracao quebra a validacao.

Descricao longa do diagrama

O diagrama mostra os componentes da assinatura no fim da invoice: os 32 bytes de R, os 32 bytes de S e o byte de recuperacao. Uma seta indica que esses dados, junto com o hash da invoice sem a assinatura, permitem recuperar a chave publica comprimida do emissor.

Quando o campo n existe, ele declara explicitamente o node id do recebedor, e a assinatura deve validar contra essa chave. Quando n nao existe, o pagador recupera a chave publica pela assinatura. Isso e util para economizar bytes, mas implementacoes precisam validar assinatura e regras de canonicalidade com cuidado.

Feature bits

O campo 9 usa feature bits no contexto de invoice. A semantica par/ímpar segue a BOLT 9: bit par representa funcionalidade obrigatoria; bit impar representa funcionalidade opcional. Se a invoice contem um bit par desconhecido, o pagador deve falhar em vez de tentar pagar algo que nao entende.

Features relevantes em invoices incluem basic_mpp, option_route_blinding, option_attribution_data e option_payment_metadata. Nem todo bit que aparece em init ou node_announcement e valido no contexto da tag 9; a coluna de contexto da BOLT 9 e a referencia para isso.

Para experimentar a interpretacao de bits, use tambem a ferramenta Feature Bits BOLT 9.

Ferramenta: decodificador de invoice

Use o decodificador com invoices publicas, de teste ou ficticias. Ele roda no navegador, valida a estrutura Bech32, mostra HRP, valor, timestamp, campos principais e tenta recuperar o node id pela assinatura. Ele nao deve receber seed, mnemonic, chave privada, macaroon, senha, backup de canal ou dados reais de carteira.

Decodificador de Invoice BOLT 11

Decodificador de Invoice BOLT 11

Cole uma invoice lnbc... publica, ficticia ou de teste para ver rede, valor, campos e no assinante. Nao cole dados privados.

Invoice BOLT 11

Aceita o texto da invoice, opcionalmente com prefixo lightning:.

lnbc2500n1p4ruueqpp55skrfhja9s8n5drn0ex2wm63r8dkjujdcse6s6n3lervynpc73dssp5jstu4dyc5493fxxrqfyh8shhfpdtefuprm6jeuhkcfrfgrrzjm0qdpdg4ux2mtsd3hjqerfv3shg6trdusz6grwv9hjqurpvashyxqrrsscqpjlwy9deha9kwu4r4c2xpysaqhkefjmx3dq3uxx9m5lkt0l8prpzlpavh4jsz5fmwuzaghcpftshrn5v8q94hdr9w56zz994w4hrwyszgp6lqc6q

Decodificar

Exemplos didaticos Mainnet: 250 sat com descricaoMainnet: sem valor fixoTestnet: 1.000 sat com hash de descricao

Resultado da invoice

A ferramenta e didatica. Ela ajuda a inspecionar campos e assinatura, mas nao substitui uma implementacao completa de carteira: uma carteira real tambem precisa validar politicas de pagamento, fees, timeout, dependencias de features, rotas, expiracao e resultado do pagamento.

BOLT 12 em contexto

BOLT 11 resolve bem pedidos de pagamento individuais, mas tem limitacoes: a invoice e de uso unico, expira, mistura Bech32 com dados de pagamento, e a assinatura cobre a invoice inteira. Reutilizar a mesma invoice para varias pessoas e perigoso, porque reaproveita o mesmo payment_hash e enfraquece a semantica de recibo.

BOLT 12 muda o modelo. Um offer com prefixo lno e um convite reutilizavel. O pagador envia um invoice_request por onion message, e o recebedor responde com uma invoice nova, em formato TLV, assinada com Schnorr/BIP340. O fluxo tambem usa blinded paths para melhorar a privacidade do recebedor.

Por isso, BOLT 12 nao deve ser descrito como "uma invoice BOLT 11 melhorada". Ele e outro protocolo de negociacao. Esta pagina fica em BOLT 11; offers merecem uma pagina propria quando a secao avancar.

Armadilhas comuns

• Confundir payment_hash com payment_secret. O primeiro trava o HTLC; o segundo autentica o pagamento esperado pelo recebedor.
• Aceitar invoice sem s. A BOLT 11 atual exige exatamente um payment_secret.
• Aceitar invoice com d e h ao mesmo tempo, ou sem nenhum dos dois.
• Ignorar a expiracao x e tentar pagar uma invoice vencida.
• Renderizar a descricao d como HTML confiavel. Descricao de invoice e entrada do usuario e precisa ser escapada.
• Tratar routing hint r como canal publico. Ele e uma dica fornecida pelo recebedor, nao gossip validado globalmente.
• Usar fallback on-chain automaticamente depois de falha Lightning sem consentimento explicito do usuario.
• Aplicar todas as features de BOLT 9 como se valessem no campo 9. O contexto da feature importa.

Resumo

• BOLT 11 e o formato classico de invoice Lightning.
• O HRP indica rede e valor opcional; a data part traz timestamp, campos com tag e assinatura.
• p, s e exatamente um entre d/h sao centrais para uma invoice valida.
• r ajuda a chegar em canais privados; f e fallback on-chain, nao rota Lightning.
• O campo 9 negocia features especificas do pagamento.
• BOLT 12 e uma evolucao com offers, invoice requests, TLV, Schnorr e blinded paths.

Mapa de dependências conceituais

Antes de ler esta pagina, ajuda conhecer:

• Bech32
• Funcao Hash
• Assinatura
• Operacao de Canais e Encaminhamento
• Busca de Caminho

Depois desta pagina, siga para:

• Protocolo Wire
• Roteamento Onion
• Gossip e o Grafo de Canais
• Decodificador de Invoice BOLT 11

Referências técnicas usadas

• BOLT 11 — Invoice Protocol for Lightning Payments
• BOLT 4 — Onion Routing Protocol
• BOLT 9 — Assigned Feature Flags
• BOLT 12 — Negotiation Protocol for Lightning Payments
• Bech32
• Assinatura

A seguir, voltamos ao nivel do envelope de mensagens entre peers: o Protocolo Wire.