Rede Lightning e segunda camada

Como resolver falhas de pagamento na Lightning

Uma conta de cerâmica ao lado de um trecho frouxo de fio entre blocos de pedra, uma imagem que representa uma rota de pagamento que falhou.

Este guia é uma tradução do original em inglês, que é o texto de referência. Ler em inglês

Um pagamento na Lightning pode falhar antes de sair do seu nó ou em um nó no caminho. Também pode ficar preso no meio da rota. Um canal também pode sofrer um fechamento forçado que bloqueie os fundos por um tempo. Este guia explica o que significa cada erro comum, como usar comandos para diagnosticar o problema e como resolvê-lo. Cobre desde problemas de liquidez até a conectividade do nó e a recuperação.

Os comandos são para o LND (lncli). O Core Lightning (CLN) e o Eclair usam mensagens de erro diferentes, mas as causas são as mesmas, e a lógica das soluções também.

Falhas de pagamento comuns e códigos de erro

Quando um pagamento falha na Lightning, aparecem códigos de erro específicos. No LND, cada pagamento malsucedido termina com um motivo, como NO_ROUTE, INSUFFICIENT_BALANCE ou TIMEOUT. Durante a busca, os nós da rota podem devolver erros de encaminhamento em tentativas individuais. Seu nó usa essas informações para tentar de novo. Confira os erros mais frequentes e o que significam.

Como o LND tenta pagar uma fatura. Passo 1. O LND confere se todos os seus canais, juntos, conseguem enviar o valor. Caso contrário, o pagamento falha com INSUFFICIENT_BALANCE. Passo 2. O LND escolhe uma rota no mapa da rede. Se não restar nenhuma rota que comporte o pagamento, nem dividido em partes, o pagamento falha com NO_ROUTE. Passo 3. O LND envia o pagamento como um HTLC que passa de nó em nó. Quando o destinatário liquida o HTLC, o pagamento é efetuado e você recebe um comprovante. Se um nó da rota devolver um erro (TEMPORARY_CHANNEL_FAILURE, FEE_INSUFFICIENT, INCORRECT_CLTV_EXPIRY ou CHANNEL_DISABLED), seu nó atualiza o mapa e volta ao passo 2 para escolher outra rota. O LND continua tentando por até 60 segundos, seu limite padrão. Depois disso, deixa de iniciar tentativas. O pagamento só falha com TIMEOUT depois que todas as tentativas já enviadas falharem. Se alguma tentativa ainda estiver a caminho, o pagamento continua em IN_FLIGHT e ainda pode ser concluído.
Em geral, um pagamento falha de vez por um de três motivos: falta saldo, acabam as rotas ou acaba o tempo. Os erros que os nós da rota devolvem fazem parte da busca. Seu nó usa cada um para testar outra rota.

FAILURE_REASON_NO_ROUTE

Seu nó não encontra na rede uma rota que consiga levar o pagamento até o destino. Pode ser que não exista rota desde o início e que o pagamento nem saia do seu nó. Ou que o nó tente todas as rotas que encontrou e todas falhem.

Causas comuns:

  • Nenhum canal tem liquidez de saída suficiente para o valor do pagamento
  • O nó de destino está offline ou não tem canais públicos
  • Em todas as rotas possíveis, há nós intermediários offline
  • O grafo de canais do seu nó está desatualizado ou incompleto
  • O valor do pagamento ultrapassa o tamanho máximo de um HTLC nas rotas disponíveis

Diagnóstico:

Primeiro, confira a liquidez de saída de todos os canais:

lncli listchannels | jq '[.channels[] | select(.active==true)] | map({alias: .peer_alias, local: .local_balance, remote: .remote_balance, capacity: .capacity}) | sort_by(-.local | tonumber)'

O resultado mostra os canais ativos em ordem de saldo de saída (local) disponível. Se nenhum canal tiver liquidez de saída suficiente por conta própria, o pagamento não consegue sair de uma vez. Pagamentos em várias partes (MPP) podem dividir o valor entre os canais.

Confira se é possível chegar ao destino:

lncli getnodeinfo --pub_key=DESTINATION_PUBKEY

Se aparecer um erro, o nó de destino não consta no grafo ou não tem canais públicos. Confira se o grafo está atualizado:

lncli getnetworkinfo

Compare num_nodes e num_channels com estatísticas conhecidas da rede. Se os números forem muito mais baixos, o grafo precisa de uma atualização. Reiniciar o nó ou esperar que os anúncios da rede se propaguem costuma resolver.

Soluções:

  • Abra um canal direto com o destino ou com um nó bem conectado que esteja perto dele
  • Use o Lightning Loop para reequilibrar os canais existentes e aumentar a liquidez de saída
  • Deixe o pagamento se dividir. O lncli payinvoice já faz isso, com até 16 partes por padrão (--max_parts). Em outras carteiras, confira se os pagamentos em várias partes estão ativados
  • Se o MPP não estiver disponível, reduza o valor e faça pagamentos menores
  • Espere e tente de novo. Interrupções temporárias em nós de roteamento se resolvem por conta própria

FAILURE_REASON_INSUFFICIENT_BALANCE

O saldo disponível para gastar somando todos os canais não cobre o valor do pagamento. O LND verifica isso antes de buscar uma rota, por isso o pagamento nem sai do seu nó. Se o total for suficiente, mas nenhum canal comportar o valor por conta própria, o LND tenta dividi-lo. Se nenhuma divisão funcionar, o pagamento falha com NO_ROUTE.

Causas comuns:

  • A reserva obrigatória do canal compromete parte do saldo, em geral 1% da capacidade do canal
  • Os HTLCs em andamento (pagamentos que ainda estão a caminho) prendem liquidez até a liquidação ou a falha
  • As taxas de roteamento se somam ao valor. Se o saldo cobrir o valor, mas faltar para as taxas, o pagamento falha com NO_ROUTE
  • Atualizações pendentes do canal ainda não aparecem no saldo

Diagnóstico:

Verifique se há HTLCs pendentes que possam estar bloqueando fundos:

lncli listchannels | jq '.channels[] | select(.pending_htlcs | length > 0) | {chan_id: .chan_id, alias: .peer_alias, pending_htlcs: .pending_htlcs}'

Compare o saldo disponível para gastar com o saldo exibido:

lncli walletbalance
lncli channelbalance

Em channelbalance, local_balance é o valor que está do seu lado agora. Um pagamento que você ainda está enviando já saiu do seu saldo e aparece em unsettled_remote_balance até ser liquidado ou falhar. Pagamentos de entrada ainda a caminho aparecem em unsettled_local_balance. A reserva do canal reduz ainda mais o saldo que você pode gastar. Em um canal de 1 milhão de sats, espere cerca de 10.000 sats na reserva, que você nunca pode gastar por esse canal.

Uma barra representa um canal de exemplo de 1.000.000 de sats. Do seu lado, há 400.000 sats (local_balance). Do lado do nó parceiro, há 550.000 (remote_balance). Entre os dois, há 50.000 sats em andamento. É um pagamento que já saiu do seu lado e volta se falhar (unsettled_remote_balance). Na extremidade do seu lado, uma faixa de 10.000 sats representa a reserva que você precisa manter, 1% do canal (chan_reserve_sat). Você pode enviar agora 400.000 menos os 10.000 da reserva e menos as taxas de roteamento. O resultado fica um pouco abaixo de 390.000. O saldo do nó parceiro dá uma ideia de quanto você pode receber.
Você pode enviar um pouco menos do que tem do seu lado do canal. O 1% da reserva fica sempre no canal e as taxas de roteamento se somam ao valor. Um pagamento em andamento já saiu do seu lado. Se você abriu o canal, uma parcela adicional fica reservada para as taxas on-chain.

Soluções:

  • Espere a liquidação ou a falha dos HTLCs pendentes. Se um falhar, os fundos voltam para o seu lado
  • Inclua a reserva e as taxas no cálculo do saldo disponível. O valor que você pode gastar é sempre menor que o saldo exibido no canal
  • Abra canais maiores para reduzir o peso relativo da reserva obrigatória
  • Gerencie seus canais para manter a liquidez equilibrada

FAILURE_REASON_TIMEOUT

Seu nó continuou testando rotas até acabar o tempo de espera do pagamento (60 segundos por padrão no LND). Depois, parou de iniciar tentativas. As que já estão a caminho seguem em andamento. O LND espera que cada uma seja liquidada ou falhe, por isso o pagamento pode aparecer como IN_FLIGHT por um tempo. Quando o status mostrar FAILED, os fundos estarão liberados e você pode tentar de novo. Se uma tentativa tardia der certo, o status mostrará SUCCEEDED. Nesse caso, você já pagou e não deve pagar novamente. Se o pagamento continuar em andamento por muito tempo, uma tentativa está presa em um nó da rota e os passos abaixo se aplicam.

Quando o tempo de espera do pagamento acaba, depois de 60 segundos por padrão no LND, seu nó deixa de iniciar tentativas. As que já saíram seguem em andamento. O LND espera que cada uma seja liquidada ou falhe. Se todas falharem e voltarem com erro, o pagamento aparece como FAILED, com o motivo TIMEOUT. Os fundos estão liberados, por isso você pode tentar de novo. Seu nó costuma evitar o nó lento. Se alguma tentativa ainda não tiver voltado porque um nó da rota parou de responder, o status continua IN_FLIGHT e os fundos ficam bloqueados, bloco após bloco, até a liquidação, a falha ou o fim do prazo. No LND, o limite é de até 2.016 blocos, cerca de duas semanas. Espere. Não pague de novo e mantenha seu nó online. Se uma tentativa tardia der certo, o status muda para SUCCEEDED. Você já pagou.
Um pagamento que atinge o tempo limite se parece com um pagamento preso. O status indica a diferença. FAILED com o motivo TIMEOUT indica que os fundos estão liberados, por isso você pode tentar de novo. IN_FLIGHT indica que uma tentativa ainda está a caminho. Pagar novamente não a libera, então mantenha o nó online e espere a tentativa terminar. Se uma tentativa tardia der certo, o status muda para SUCCEEDED e o pagamento foi efetuado.

Causas comuns:

  • Um nó intermediário ficou offline enquanto encaminhava o pagamento
  • O nó de destino recebeu o HTLC, mas ainda não o liquidou
  • O congestionamento da rede atrasa o encaminhamento ao longo da rota
  • Um nó da rota usa uma implementação lenta ou sobrecarregada

Diagnóstico:

Procure pagamentos em andamento:

lncli listpayments --include_incomplete | jq '.payments[] | select(.status=="IN_FLIGHT") | {hash: .payment_hash, amount: .value_sat, creation_date: .creation_date}'

Consulte o estado dos HTLCs desse pagamento:

lncli trackpayment PAYMENT_HASH

O resultado mostra em tempo real o andamento do pagamento pela rede. Se o HTLC ficar preso em um salto específico, você pode ver qual nó está segurando o pagamento.

Soluções:

  • Se uma tentativa ficar presa, espere. Os fundos voltam quando ela falhar ou o prazo do HTLC terminar. O LND aceita encaminhamentos bloqueados por até 2.016 blocos (cerca de duas semanas). Se um HTLC ainda não puder ser liquidado normalmente quando o prazo terminar, o canal que o retém precisa fechar on-chain
  • NÃO envie um pagamento duplicado enquanto o primeiro estiver em andamento, porque você pode pagar duas vezes
  • Se isso acontecer com frequência com o mesmo nó parceiro, considere fechar o canal
  • Se o tempo de espera continuar acabando sem deixar pagamentos presos, dê mais tempo com lncli payinvoice --timeout (60 segundos por padrão)
  • Se o pagamento preso terminar com o status FAILED, tente de novo. O LND se lembra da falha e costuma escolher uma rota que evite esse nó. Se terminar com o status SUCCEEDED, o pagamento já foi concluído, por isso não pague de novo

Erros de encaminhamento dos nós da rota

Quando um nó da rota não consegue encaminhar uma tentativa, ele devolve um erro. O LND registra o erro nessa tentativa, na lista htlcs do pagamento, e segue buscando. FAILURE_REASON_ERROR é um motivo de falha definitiva, reservado para erros menos frequentes dos quais o LND não consegue se recuperar. Estes são os erros de encaminhamento mais comuns:

  • FEE_INSUFFICIENT: seu nó calculou uma rota com dados desatualizados de taxas. O nó de roteamento aumentou as taxas desde a última atualização do grafo.
  • CHANNEL_DISABLED: um dos dois nós de um canal da rota desativou o canal, muitas vezes temporariamente para manutenção.
  • TEMPORARY_CHANNEL_FAILURE: o nó que precisa encaminhar o HTLC não consegue processá-lo naquele momento. Em geral, o nó tem um problema temporário de liquidez ou capacidade.
  • INCORRECT_CLTV_EXPIRY: o delta CLTV (CheckLockTimeVerify) difere do que o nó de roteamento exige. Os dados do grafo sobre a política desse nó estão desatualizados.

A maioria desses erros se resolve em uma nova tentativa. Seu nó atualiza o grafo com os dados do erro e escolhe outra rota. Se um erro específico persistir, execute lncli queryroutes --dest=PUBKEY --amt=AMOUNT para ver quais rotas o nó tenta usar.

Problemas nos canais: fechamentos forçados e canais presos

Os problemas nos canais são os que mais preocupam operadores de nós, porque envolvem transações on-chain, períodos de espera e fundos bloqueados. Quem opera um nó da Lightning precisa entender os fechamentos forçados.

Canais com fechamento forçado

Um fechamento forçado ocorre quando um dos nós do canal publica por conta própria o estado mais recente do canal na blockchain. Isso dispensa o processo de fechamento cooperativo e ativa um bloqueio temporal sobre os fundos.

Por que ocorre o fechamento forçado de um canal:

  • O nó parceiro ficou offline por muito tempo e seu nó deixou de esperar
  • Seu nó ficou offline e o nó parceiro forçou o fechamento para recuperar os próprios fundos
  • Um HTLC pendente está prestes a expirar on-chain e obriga o fechamento do canal para que seja resgatado
  • O estado do canal deixou de coincidir entre os dois nós, algo raro, mas grave
  • Você ou o nó parceiro forçou o fechamento por causa de problemas de roteamento sem solução

Como verificar fechamentos forçados pendentes:

lncli pendingchannels | jq '.pending_force_closing_channels[] | {channel_point: .channel.channel_point, limbo_balance: .limbo_balance, blocks_til_maturity: .blocks_til_maturity, recovered_balance: .recovered_balance}'

O campo blocks_til_maturity indica quantos blocos faltam para você poder gastar os fundos. Se você iniciou o fechamento forçado, precisa esperar o prazo que o nó parceiro definiu na abertura do canal. Com os padrões do LND, são 144 blocos (cerca de um dia) em canais com menos de cerca de 1,2 milhão de sats. O prazo aumenta com o tamanho do canal e chega a 2.016 blocos (cerca de duas semanas) nos maiores. O lncli listchannels mostra o seu prazo em csv_delay, dentro de local_constraints. Se o nó parceiro forçou o fechamento, você pode gastar seu saldo um bloco depois da confirmação do fechamento nos canais atuais com âncoras. HTLCs pendentes complicam o processo.

Quando você pode voltar a gastar seu saldo de um canal fechado. No fechamento cooperativo, os dois nós assinam uma transação e você pode gastar o saldo assim que ela for confirmada. Se o nó parceiro forçar o fechamento publicando o último saldo, você pode gastar seu saldo um bloco depois da confirmação. Se você forçar o fechamento, seu saldo aparece como limbo_balance e fica bloqueado pelo prazo que o nó parceiro definiu na abertura do canal. Com os padrões do LND, são 144 blocos, cerca de um dia, em canais abaixo de cerca de 1,2 milhão de sats. Nos maiores, são até 2.016 blocos, cerca de duas semanas. Então, seu nó transfere os fundos para a carteira. O comando lncli pendingchannels mostra quantos blocos faltam em blocks_til_maturity.
Se você fechar o canal por conta própria, sem o nó parceiro, a espera será a mais longa. Um fechamento cooperativo paga os dois lados de uma vez. Se o nó parceiro forçar o fechamento, seu saldo fica livre um bloco depois. Se você forçar, precisa cumprir o prazo que o nó parceiro escolheu. Os pagamentos em andamento no fechamento são liquidados on-chain separadamente.

Canais aguardando fechamento:

lncli pendingchannels | jq '.waiting_close_channels'

Nesses canais, uma transação de fechamento já foi transmitida e ainda não foi confirmada. Em períodos de taxas altas, esse estado pode durar horas ou dias. Se a transação representar um estado antigo que o nó parceiro já não deveria publicar, seu nó responde com uma transação de penalidade que toma todos os fundos do canal. Se o nó estiver offline, a watchtower pode responder por ele.

Canais zumbis

Em um canal zumbi, o nó parceiro parou de responder há muito tempo. O canal aparece como inativo na lista, não consegue rotear pagamentos e mantém os fundos presos.

lncli listchannels | jq '[.channels[] | select(.active==false and .private==false)] | length'

Se você tiver muitos canais públicos inativos, considere fechá-los para liberar fundos on-chain e usá-los em canais produtivos. Antes de fechar um canal, tente se reconectar:

lncli connect PEER_PUBKEY@ADDRESS:PORT

Se o nó parceiro voltar a ficar online, o fechamento cooperativo com lncli closechannel --chan_point=FUNDING_TXID:OUTPUT_INDEX é a saída mais limpa. Se as tentativas de conexão continuarem falhando, o fechamento cooperativo não é possível. Os dois nós precisam assiná-lo, e o LND recusa o fechamento cooperativo enquanto o nó parceiro está offline. Adicione --force para fechar o canal por conta própria e conte com o bloqueio do seu saldo durante o prazo descrito acima.

Problemas de liquidez

Gerenciar a liquidez é a tarefa central de quem opera um nó da Lightning. A maioria das falhas de pagamento vem de desequilíbrios de liquidez. O guia de otimização de roteamento na Lightning explica o assunto em detalhes.

Dois canais com problemas opostos. No primeiro, seu lado está quase vazio, por isso você não consegue enviar. As soluções aproximam a divisão do centro ao repor saldo no seu lado. Com o Loop In, você troca bitcoin on-chain por saldo no seu lado. Também dá para fazer um rebalanceamento circular que puxa sats de um canal cheio demais ou receber pagamentos pelo canal. Outra opção é abrir um canal, que começa com todo o saldo do seu lado. No segundo, seu lado está quase cheio, por isso você não consegue receber. As soluções esvaziam seu lado. Com o Loop Out, você troca os sats que saem do seu lado por bitcoin on-chain. Também dá para fazer um rebalanceamento circular que envia sats a um canal vazio demais ou gastar pelo canal. Outra opção é alguém abrir um canal com você, por exemplo pelo LN+ ou pelo Magma. Nós de roteamento procuram manter de 25% a 75% do saldo dos canais no próprio lado.
Primeiro, descubra qual lado está vazio. Depois, escolha uma solução que mova o saldo para esse lado. O Loop In e o Loop Out fazem o oposto um do outro. Um canal que você abre dá espaço para enviar. Para receber, é preciso ter saldo do outro lado. Configure alertas para quando seu lado de um canal ficar abaixo de 10% ou acima de 90%.

Liquidez de saída esgotada

Depois de enviar muitos pagamentos, os canais ficam cheios do lado dos nós parceiros. Você tem capacidade para receber, mas não consegue enviar. Nos pagamentos de saída, isso aparece como NO_ROUTE ou INSUFFICIENT_BALANCE.

Diagnóstico:

lncli listchannels | jq '.channels[] | select(.active==true) | {alias: .peer_alias, local_pct: ((.local_balance|tonumber) / ((.local_balance|tonumber) + (.remote_balance|tonumber)) * 100 | floor)} | select(.local_pct < 20)'

O resultado mostra os canais ativos cujo saldo local (de saída) está abaixo de 20% da capacidade. Esses canais precisam de rebalanceamento.

Opções de rebalanceamento:

  • Rebalanceamento circular: envie um pagamento para você mesmo pela rede. Faça o pagamento sair por um canal cheio do seu lado e voltar pelo canal esgotado. Ferramentas como bos rebalance (Balance of Satoshis) automatizam o processo.
  • Loop In: use o Lightning Loop para trocar bitcoin on-chain por sats na Lightning que cheguem ao seu lado de um canal. Assim, você aumenta a capacidade de saída.
  • Receba pela Lightning: é o rebalanceamento mais simples. Cada pagamento que você recebe traz sats de volta para o seu lado.

Liquidez de entrada esgotada

É o problema oposto. Você recebeu muitos pagamentos, os canais estão cheios do seu lado e você não consegue receber mais. Isso acontece com frequência com comerciantes e prestadores de serviços.

Soluções:

  • Loop Out: troque sats na Lightning por bitcoin on-chain com um swap submarino. Assim, seu lado do canal esvazia e você pode receber
  • Peça que abram canais com você: serviços como o LN+ e o Magma oferecem liquidez de entrada
  • Abra canais novos e depois faça pagamentos por meio deles: um canal que você abre começa com todo o saldo do seu lado, por isso só dá espaço para receber depois que você gasta uma parte
  • Esvazie os canais: gaste ou rebalanceie para tirar saldo do seu lado

Canais desequilibrados que causam falhas de roteamento

Se você roteia pagamentos de outras pessoas, o saldo dos canais afeta diretamente a receita de roteamento. Um canal esgotado em uma direção não consegue encaminhar pagamentos nessa direção. Acompanhe a taxa de sucesso do roteamento:

lncli fwdinghistory --start_time=-30d | jq '.forwarding_events | length'

Compare esse resultado com as tentativas de encaminhamento que falharam nos logs para calcular a taxa de sucesso do roteamento. Um nó de roteamento saudável mantém o saldo local da maioria dos canais entre 25% e 75%. O guia de taxas na Lightning explica como otimizar as taxas e a liquidez.

Problemas de conectividade do nó

Problemas de conectividade impedem que seu nó se comunique com outros nós, propague anúncios e encaminhe pagamentos. Muitas vezes são a causa oculta do que parece um problema de roteamento ou liquidez.

Conectividade com o Tor

Muitos nós domésticos da Lightning usam o Tor para proteger a privacidade. O Tor aumenta a latência e pode causar problemas ocasionais de conexão.

Problemas comuns do Tor:

  • O Tor não consegue estabelecer um circuito, o que impede conexões com outros nós
  • A publicação do descritor do serviço onion falha e outros nós não conseguem acessar o seu
  • A latência alta esgota o tempo de espera no encaminhamento de HTLCs

Como verificar o estado do Tor:

systemctl status tor
# Confirm that traffic through Tor works (the reply shows "IsTor": true)
torsocks curl -s https://check.torproject.org/api/ip

Se o Tor estiver fora do ar, reinicie-o com sudo systemctl restart tor. Se os problemas persistirem, pare o Tor, apague apenas os arquivos de rede em cache (os arquivos cached-* no diretório de dados, geralmente /var/lib/tor) e inicie o Tor novamente para que ele baixe esses arquivos de novo. Não apague o diretório inteiro. Um serviço onion configurado com HiddenServiceDir costuma guardar ali a chave privada do serviço. Se você apagar essa chave, o endereço .onion do serviço muda de forma permanente. Por padrão, o LND guarda a própria chave onion no diretório do LND (v3_onion_private_key).

Modo híbrido: se os requisitos de privacidade permitirem, considere operar seu nó em modo híbrido, pelo Tor e pela rede pública (clearnet). Isso melhora muito a conectividade e a confiabilidade dos pagamentos, mantendo um ponto de acesso pelo Tor para os nós que priorizam a privacidade.

Desconexões de outros nós

Desconexões frequentes de certos nós causam falhas de pagamento. Se durarem muito, podem provocar fechamentos forçados.

lncli listpeers | jq '.peers[] | {pubkey: .pub_key, bytes_recv: .bytes_recv, ping_time: .ping_time, sat_sent: .sat_sent}'

Tempos altos de resposta ao ping (acima de 5 segundos) indicam problemas de conectividade. Se o nó parceiro apresentar latência alta com frequência ou ficar offline, talvez não valha a pena manter o canal.

Problemas no banco de dados e no disco

O banco de dados de canais do LND (channel.db) pode crescer muito e causar problemas de desempenho. Um banco de dados corrompido é um dos piores cenários para quem opera um nó da Lightning.

# Check database size
ls -lh ~/.lnd/data/graph/mainnet/channel.db

# Check disk space
df -h /

Se channel.db passar de 1 GB, considere compactar o arquivo durante uma parada programada. Mantenha sempre atualizados os arquivos de backup estático de canais (SCB, Static Channel Backup). São a forma de recuperar os fundos se o banco de dados for corrompido:

lncli exportchanbackup --all --output_file=/path/to/backup/channel-backup-$(date +%Y%m%d).backup

Dicas para prevenir falhas

Boas práticas de operação evitam a maioria das falhas na Lightning. Esses hábitos distinguem os nós confiáveis dos problemáticos.

Monitoramento e alertas

  • Monitoramento do saldo: configure alertas para quando o saldo local de algum canal ficar abaixo de 10% ou acima de 90%. Ferramentas como o ThunderHub, o RTL (Ride The Lightning) e o LNDmon oferecem painéis e opções de notificação.
  • Monitoramento do tempo de atividade: use uma tarefa simples no cron ou um serviço externo para enviar um ping ao nó. Se o tempo de atividade ficar abaixo de 99%, investigue os problemas de conectividade antes que causem fechamentos forçados.
  • Alertas de espaço em disco: se o espaço acabar, o nó encerra de forma abrupta e pode corromper o banco de dados. Monitore o uso do disco e configure alertas ao chegar a 80% da capacidade.
  • Backups automáticos: use um script para exportar os backups SCB todos os dias para um local fora do nó. Se o hardware do nó falhar, os backups SCB permitem recuperar os fundos de todos os canais.

Escolha de canais

  • Conecte-se a nós bem mantidos e com tempo de atividade alto. Confira o histórico deles no amboss.space ou no 1ML antes de abrir canais
  • Evite abrir canais com menos de 500.000 sats. Canais pequenos têm reservas obrigatórias proporcionalmente altas e utilidade limitada para roteamento
  • Escolha nós que usem implementações diferentes e estejam em regiões e posições diferentes na rede
  • Abra canais em períodos de taxas baixas para minimizar o custo on-chain de abertura

Manutenção periódica

  • Atualize o software do nó sem demora. Novas versões do LND, do CLN e do Eclair costumam corrigir falhas de roteamento e melhorar a confiabilidade dos pagamentos
  • Revise e feche os canais zumbis todo mês para liberar fundos
  • Rebalanceie os canais antes que os pagamentos comecem a falhar
  • Teste o processo de restauração pelo menos uma vez. Um backup sem teste não serve de garantia

Política de taxas

Uma configuração inadequada das taxas causa falhas indiretas. Se as taxas forem altas demais, ninguém roteia pagamentos pelo seu nó e a presença dele no grafo diminui. Taxas baixas demais atraem pagamentos que drenam a liquidez. Comece com taxas moderadas e ajuste-as conforme o volume real de roteamento. O guia de taxas explica a economia em detalhes.

Procedimentos de recuperação de emergência

Quando algo dá muito errado, conhecer os passos de recuperação evita erros por desespero.

O nó não inicia

  1. Primeiro, consulte os logs com journalctl -u lnd --since "1 hour ago" -n 200
  2. Se o log mostrar Waiting for wallet encryption password, execute lncli unlock e digite a senha da carteira. O LND precisa dela depois de cada reinicialização. O bloqueio da carteira é diferente de corrupção.
  3. Se o banco de dados estiver corrompido, NÃO o apague. Faça uma cópia em um local seguro e depois tente repará-lo.
  4. Se o reparo falhar, restaure a partir de um backup SCB. Isso força o fechamento de todos os canais, mas recupera os fundos.

A abertura de um canal fica pendente

A transação de financiamento do canal foi transmitida, mas ainda não foi confirmada. O canal continua pendente.

lncli pendingchannels | jq '.pending_open_channels'

Se a taxa da transação de financiamento estiver baixa demais, você pode aumentá-la com CPFP (Child Pays For Parent), se a sua versão do LND oferecer suporte. Caso contrário, espere a transação ser confirmada ou sair da mempool.

Recuperação depois de muito tempo offline

Se seu nó ficou offline por dias, é possível que nós parceiros tenham forçado o fechamento de alguns canais. Depois de reiniciá-lo:

  1. Deixe o nó sincronizar por completo a blockchain e o grafo de canais
  2. Confira com lncli pendingchannels se há canais com fechamento forçado
  3. Verifique com lncli walletbalance se o saldo on-chain inclui os fundos recuperados
  4. Reconecte-se aos nós restantes e veja quais canais continuam abertos
  5. Considere abrir canais novos para substituir os que perdeu. Siga os critérios de escolha dos fundamentos da Lightning
Parte do nosso curso gratuito de Bitcoin: a aula Pagamentos Lightning na prática: enviar, receber e resolver problemas, do curso Rede Lightning e nós de Bitcoin, trata do assunto em detalhes.

Perguntas frequentes

Meu pagamento falhou com NO_ROUTE, mas o destino existe. O que aconteceu?

Seu nó vê o destino no grafo, mas não consegue montar uma rota viável com liquidez suficiente. Em geral, a capacidade de saída está baixa ou fragmentada demais. Experimente estas opções: (1) rebalanceie o maior canal para aumentar a capacidade de saída, (2) divida o pagamento com MPP se a carteira oferecer suporte ou (3) abra um canal com um nó bem conectado à vizinhança do destino.

Houve um fechamento forçado e meus fundos aparecem como “limbo_balance”. Eu os perdi?

Não. Esse saldo indica que os fundos estão em uma transação on-chain com bloqueio temporal. Você poderá gastá-los quando o bloqueio expirar. Se você iniciou o fechamento forçado, esse é o prazo que o nó parceiro definiu na abertura do canal. Com os padrões do LND, são 144 blocos (cerca de um dia) em canais abaixo de cerca de 1,2 milhão de sats e até 2.016 blocos (cerca de duas semanas) nos maiores. Se o nó parceiro iniciou o fechamento, você pode gastar seu saldo um bloco depois da confirmação do fechamento. Use lncli pendingchannels para ver em blocks_til_maturity quantos blocos faltam. Os fundos estão seguros, embora temporariamente inacessíveis.

Como evito fechamentos forçados?

Mantenha o tempo de atividade alto (99% ou mais), atualize o software do nó, garanta uma conexão estável à internet e monitore o espaço em disco. A maioria dos fechamentos forçados ocorre porque um nó ficou offline por tempo demais. Uma watchtower protege você se o nó parceiro transmitir estados antigos do canal enquanto o seu estiver offline. O fechamento forçado ainda pode ocorrer.

Devo usar keysend ou faturas comuns?

Faturas comuns são mais confiáveis porque o destino cria expressamente os parâmetros do pagamento. O keysend, para pagamentos espontâneos, pode falhar se o destino não oferecer suporte ou se o roteamento precisar tomar decisões com base em sondagens. Para pagamentos de rotina, prefira sempre faturas. O keysend é útil para gorjetas e doações quando pedir uma fatura não é prático.

Meu banco de dados de canais está enorme. Posso compactá-lo com segurança?

Sim, com a configuração do próprio LND. Exporte um backup SCB e confira se há espaço livre em disco. Depois, defina db.bolt.auto-compact=true em lnd.conf e reinicie o LND. Na inicialização, o LND compacta os arquivos do próprio banco de dados. O LND grava o banco de dados compactado em um arquivo temporário e só substitui o original ao terminar. Por isso, se a compactação falhar, o original continua no lugar. A opção vem desativada por padrão porque a compactação precisa de espaço extra em disco enquanto roda. Nunca compacte o banco de dados com outra ferramenta enquanto o LND estiver rodando.

Qual é a diferença entre um fechamento cooperativo e um fechamento forçado?

Um fechamento cooperativo exige que os dois nós estejam online e concordem com a divisão final do saldo. Ele gera uma única transação on-chain sem bloqueios temporais. Os fundos podem ser gastos assim que ela for confirmada. Em um fechamento forçado, um só nó transmite a transação de compromisso. Isso ativa bloqueios temporais e pode aumentar as taxas on-chain. Prefira sempre o fechamento cooperativo quando for possível.

Os pagamentos por um canal específico continuam falhando. Devo fechá-lo?

Primeiro, confira se o problema é de liquidez (dá para rebalancear) ou de confiabilidade do nó parceiro (um problema sistêmico). Execute lncli listchannels | jq '.channels[] | select(.chan_id=="CHANNEL_ID")' para verificar o estado do canal, o tempo de atividade e os HTLCs pendentes. Se o nó parceiro costuma ficar offline ou não responde, fechar o canal e abrir outro com um nó mais confiável é melhor no longo prazo. Se o problema for só o saldo, rebalanceie o canal.

Categoria: Rede Lightning e segunda camada
← Voltar aos cursos