BOLT 11

Anna compra um livro digital. Em vez de dados bancários, a loja mostra uma fatura Lightning, que sua carteira interpreta. Anna não precisa entender a sequência: antes de confirmar, confere o valor, a finalidade e a tarifa. Algumas faturas deixam o valor em aberto, como nas contribuições voluntárias. Nesse caso, quem paga o informa; valor ausente não significa pagamento de zero. Para quem quiser ir além: lnbc identifica a rede principal; lntb, testnet; lntbs, signet; e lnbcrt, regtest, estes últimos ambientes de teste. O valor codificado está em BTC, com um possível multiplicador m, u, n ou p, não diretamente em satoshi. Com p, precisa terminar em 0 para representar millisatoshi inteiros: 1000 msat = 1 sat. [1]

A descrição liga o pedido técnico a uma finalidade compreensível, como o livro de Anna. A fatura contém o texto no campo d ou sua impressão digital no campo h. Essa impressão é calculada com SHA256; a carteira deve verificar se uma descrição fornecida separadamente produz o mesmo resultado. Esse valor curto de verificação, calculado a partir do texto, é chamado de hash. Só a impressão não permite ler o pedido. Uma assinatura válida vincula a descrição à chave do destinatário, mas não promete que o vendedor entregará o livro. Quem desenvolve o aplicativo tem outra responsabilidade: a descrição é texto de terceiros, que deve ser exibido com segurança como dado, nunca executado como código. [1]

Anna deixa o pedido aberto e volta depois. Se a carteira informar que a fatura venceu, ela deve pedir outra. O prazo é calculado a partir da criação timestamp e da duração x. Sem x, o padrão é 3600 segundos, ou uma hora. O vencimento não desfaz um pagamento concluído. O campo c, tecnicamente min_final_cltv_expiry_delta, trata de outra coisa: uma margem de tempo para o último pagamento condicional, um HTLC, na rota. O HTLC condiciona a liquidação à apresentação do segredo correto dentro do prazo. A margem é medida em blocos, não em segundos de validade da fatura; sem c, o pagador usa pelo menos 18 blocos. Esses dois prazos não devem ser confundidos. [1]

Um pagamento Lightning percorre canais de pagamento. Dentro de um canal, duas partes atualizam a divisão dos fundos sem registrar cada pagamento comum na blockchain principal do Bitcoin. Para o pagamento chegar, é preciso ter uma rota utilizável e fundos suficientes nos lados certos dos canais: liquidez. O campo r pode trazer routing hints, pistas para o trecho final. Elas ajudam a encontrar o destinatário, mas não mostram a capacidade disponível em tempo real. Também podem revelar chaves públicas de nós, identificadores de canais e parâmetros de tarifas; portanto, não considere privada a fatura completa. O campo opcional f pode oferecer um endereço Bitcoin comum como alternativa. Pagar esse endereço usa a cadeia principal, tem tarifas próprias e depende de confirmações. Não é apenas outro botão para o mesmo modo de envio. [1] [2] [5]

Um QR escaneado ou uma fatura recebida não é um recibo. Depois de enviar, confira o resultado na carteira: pendente é diferente de concluído. A liquidação também é comprovada pelo preimage correto, um valor secreto cujo hash deve corresponder ao hash de pagamento da fatura. Guarde os dois como evidência do pagamento, não como garantia de entrega do produto. Se o aplicativo desconectar ou perder a resposta, verifique primeiro o estado do pagamento original. Pedir imediatamente outra fatura ou usar o endereço alternativo pode levar a um segundo pagamento. Algumas carteiras reconhecem novas tentativas, mas o formato não oferece proteção universal entre aplicativos e formas de pagar. [2] [4]

A longa sequência usa a codificação Bech32. Sua soma de verificação ajuda a detectar erros de transcrição; não é criptografia nem oculta o conteúdo. A assinatura digital ECDSA sobre secp256k1 tem outra função: verificar que os dados correspondem à chave do destinatário e não foram alterados depois. Ela não verifica a identidade civil nem a honestidade de quem controla a chave. Ao contrário dos endereços Bitcoin Bech32, BOLT 11 pode ultrapassar 90 caracteres. Letras maiúsculas são adequadas para QR codes, mas uma sequência válida não pode misturar maiúsculas e minúsculas. Em geral, a pessoa escaneia ou copia e a carteira realiza as verificações. [1]

Payment hash é a impressão digital de um valor secreto, o payment preimage, calculada com SHA256 e armazenada em p. Quando o pagamento é liquidado, o pagador obtém o preimage e pode conferir a impressão. Já o campo s contém payment_secret. O pagador lê esse valor na própria fatura e o entrega ao destinatário na etapa final do pagamento roteado; ele ajuda a proteger o destinatário contra sondagens dos nós intermediários. Secret não é o preimage nem o seed da carteira. Lê-lo de um QR não prova um pagamento nem permite restaurar a carteira. O BOLT 11 atual exige p e s. Nomes parecidos escondem funções distintas: identificar o pagamento, transmitir um dado necessário e comprovar a liquidação. [1] [2]

As carteiras também precisam saber se suportam o pagamento solicitado. O campo 9 contém indicadores de funções. Um bit par desconhecido representa uma função obrigatória e exige recusar o pagamento; um bit ímpar desconhecido é opcional e pode ser ignorado. As dependências conhecidas entre funções também precisam ser atendidas. Basic MPP, por exemplo, divide um pagamento em partes que se reúnem no destinatário. Só pode ser usado quando a fatura oferece basic_mpp. Isso não cria várias faturas independentes nem justifica pagar cada parte novamente. Para quem está começando, a conclusão é simples: não contorne um aviso de função incompatível editando a fatura; resolva primeiro a compatibilidade das carteiras. [1] [3]