Invoices

Entendendo o pedido de pagamento da Lightning

Lightning Network

Uma invoice é um pedido de pagamento Lightning. Ela geralmente aparece como QR code, mas por baixo é uma string codificada, normalmente começando com lnbc na rede principal do Bitcoin.

A invoice não é o pagamento em si. Ela é a instrução que permite à carteira saber o que pagar, até quando pagar, como reconhecer o recebedor e qual segredo provará que o pagamento chegou.

Conteúdo

Por que existe invoice?

Em Bitcoin on-chain, você consegue receber mostrando um endereço. Na Lightning, o recebedor normalmente precisa criar um pedido novo para cada pagamento. Isso acontece porque o pagamento usa um hash de pagamento, uma expiração e dados que a carteira do pagador precisa colocar no caminho até o destino.

O fluxo simples é:

  1. Bob quer receber e cria uma invoice.
  2. A carteira de Bob escolhe um segredo e coloca na invoice apenas o hash desse segredo.
  3. Você lê o QR code e sua carteira valida valor, descrição, destino, expiração e recursos exigidos.
  4. Sua carteira procura uma rota, cria HTLCs e envia a tentativa de pagamento.
  5. Bob revela o segredo correto; essa revelação liquida a rota e vira a prova prática de pagamento.

Para o usuário, parece só "escanear e pagar". Para a carteira, a invoice é a entrada que liga rota, HTLC, onion e preimage.

O que tem dentro

Uma invoice BOLT 11 pode carregar:

Anatomia de uma invoice Lightning: QR code, valor, descrição, payment hash, expiração e assinatura do recebedor.
O QR code só é a embalagem visual. A invoice contém dados que a carteira usa para pagar.
Descrição longa do diagrama

O diagrama mostra uma invoice Lightning como QR code e como texto codificado. Ao redor, a imagem destaca campos como valor, descrição, hash do pagamento, validade, assinatura e informações para roteamento. A ideia central é que a carteira não paga apenas para um QR code: ela decodifica dados específicos antes de montar o pagamento.

O formato técnico clássico dessas invoices é a BOLT 11. Ele usa Bech32 para codificar a string, SHA256 para o hash do segredo e assinatura para autenticar o pedido.

O que conferir antes de pagar

Uma carteira bem feita deve mostrar informações humanas antes da confirmação. Para pagamentos pequenos, ainda assim vale conferir:

Campos que importam para o usuário
Campo visível Por que conferir
Valor Evita pagar uma invoice de valor diferente do combinado. Se a invoice não fixa valor, você deve digitar o valor manualmente.
Descrição Ajuda a reconhecer o pedido, mas não prova identidade sozinha. Descrição é texto criado por quem gerou a invoice.
Expiração Invoice vencida deve falhar. Pagar perto do vencimento aumenta a chance de retry ou erro.
Taxa estimada A taxa Lightning vem da rota, não da invoice. Ainda assim, a carteira deve mostrar se a taxa está acima do esperado.
Rede Uma invoice de testnet, signet ou regtest não é pagável com saldo mainnet.

Não cole seed, mnemonic, chave privada, backup de canal, macaroon, senha ou dados reais de carteira em decodificadores públicos. Uma invoice pública de teste é aceitável; segredo de carteira não é.

O segredo que prova o pagamento

A parte mais inteligente é o par segredo / cadeado — o mesmo "cadeado com segredo" que vimos em Como a Lightning funciona.

Quando Bob cria a invoice, a carteira dele sorteia uma preimage. A invoice não revela essa preimage. Ela revela apenas o payment hash, que é o hash da preimage.

preimage ficticia -> SHA256 -> payment_hash na invoice
segredo de Bob   -> hash    -> cadeado usado nos HTLCs

Sua carteira cria a tentativa de pagamento usando esse hash. Intermediários só veem que existe um HTLC travado por aquele hash. Eles não sabem a preimage.

O pagamento só se completa quando Bob revela a preimage correta. Essa revelação destrava o último HTLC, depois o anterior, e assim por diante até sua carteira. Por isso a preimage funciona como um recibo verificável: quem pagou pode checar que SHA256(preimage) bate com o payment_hash da invoice.

O payment secret é outro valor. Ele não é a preimage. Ele é colocado no payload final enviado a Bob para ajudar Bob a saber que aquele pagamento veio de alguém que realmente recebeu a invoice, reduzindo alguns tipos de probing contra o destino.

Expiração e uso único

Invoice BOLT 11 é pensada para um pagamento específico. Ela pode expirar, e normalmente deve ser usada uma vez.

Isso evita ambiguidades:

Se uma invoice venceu, peça outra. Se uma carteira oferece "tentar mesmo assim", isso normalmente só desperdiça tempo: o destino deve rejeitar, e a rota pode falhar depois de alguns segundos.

Invoice sem valor

Algumas invoices não têm valor fixo. Isso é comum em doações, gorjetas ou carteiras que querem deixar o pagador escolher o montante.

Nesse caso, a responsabilidade muda:

Invoice sem valor não é autorização para pagar "qualquer coisa" sem revisão. Ela só deixa o valor fora da string inicial.

Dicas de rota e canais privados

Nem todo canal Lightning aparece no grafo público. Um recebedor pode ter um canal privado, não anunciado via gossip. Se a carteira do pagador não conhece esse último trecho, ela precisa de ajuda.

Por isso uma invoice pode incluir dicas de rota. Elas dizem algo como: "para chegar em mim, tente este nó e este canal no final". Isso não garante sucesso, mas permite que a busca de caminho considere canais que não estavam no grafo público.

Essas dicas conectam a invoice com a busca de caminho: a carteira combina dados públicos de canais, políticas de taxa, CLTV, liquidez local, tentativas anteriores e dicas privadas da invoice.

Lightning Address

Uma Lightning Address parece um e-mail, por exemplo bob@example.com. Ela é conveniente porque pode ser reutilizada e lembrada por humanos.

Mas ela não é a mesma coisa que uma invoice. Em geral, quando alguém paga uma Lightning Address, a carteira consulta um servidor associado ao domínio e recebe uma invoice nova nos bastidores. A invoice continua existindo; ela só foi gerada automaticamente.

Invoice e Lightning Address
Item Como pensar
Invoice BOLT 11 Pedido específico, normalmente de uso único, com hash, expiração, assinatura e dados de pagamento.
Lightning Address Endereço reutilizável que costuma acionar um servidor para gerar uma invoice nova.

Isso tem consequência prática: se o servidor da Lightning Address estiver fora do ar, o pagamento pode falhar antes mesmo de existir uma invoice. E o domínio pode aprender metadados sobre tentativas de pagamento.

Quando uma invoice falha

Falha ao pagar uma invoice não significa automaticamente perda de fundos. Motivos comuns:

Quando falha, o caminho normal é pedir uma nova invoice ou tentar novamente com outra rota, dependendo da mensagem da carteira.

Privacidade

Invoices podem vazar metadados. Uma invoice pode revelar valor, descrição, node id do recebedor, dicas de rota para canais privados, expiração e features aceitas. Se você publica uma invoice em um lugar público, qualquer pessoa pode tentar analisá-la.

Isso não quer dizer que pagar uma invoice publique sua compra na blockchain. O pagamento Lightning, quando não abre ou fecha canal, fica fora da blockchain. O ponto é outro: a invoice é um objeto que contém informação sobre o pedido. Compartilhe conforme o contexto.

Para valores pequenos e cotidianos, isso costuma ser aceitável. Para uso mais sensível, entenda o modelo de carteira, evite reutilização indevida, cuidado com Lightning Address pública e prefira ferramentas que expliquem claramente o que está sendo enviado.

Resumo

Mapa de dependências conceituais

Antes de ler esta página

Depois desta página

Referências técnicas

Esta página simplifica o formato para iniciantes. Os detalhes completos estão em:

Na próxima página, vamos ver o que muda quando você quer rodar seu próprio nó Lightning: canais, liquidez, backups, uptime e operação diária.