Operação de Canais e Encaminhamento

HTLCs, estados de canal, CLTV, taxas e falhas de roteamento

Eric de Castro
Atualizado em 26/06/2026

Lightning · Técnico

Na página de Canais de Pagamento a fundo, vimos que o canal é ancorado por uma funding transaction e atualizado por commitment transactions. Agora vamos colocar esse canal em movimento: como um pagamento entra no estado do canal, como ele é encaminhado para outro nó, como é liquidado com um segredo e como falha sem deixar intermediários pagando a conta.

As fontes primárias desta página são a BOLT 2 (mensagens de operação do canal), a BOLT 3 (outputs HTLC, HTLC-success e HTLC-timeout), a BOLT 4 (payload onion e falhas de roteamento) e a BOLT 7 (políticas de roteamento, taxas e cltv_expiry_delta).

Conteúdo

O papel do HTLC

Um canal parado só divide saldo entre dois participantes. Um canal operando precisa representar pagamentos que ainda não terminaram. Na Lightning, esse pagamento em voo é um HTLC: Hash Time-Locked Contract.

Em termos práticos, um HTLC é uma promessa condicional dentro do estado do canal:

Se o segredo correto aparecer: o valor vai para quem consegue revelar a preimage.
Se o prazo expirar: o valor pode voltar para quem ofereceu o HTLC.

Enquanto todo mundo coopera, isso é apenas estado off-chain: mensagens, assinaturas e revogações. Se o canal fecha unilateralmente com HTLCs pendentes, a BOLT 3 define como esses HTLCs aparecem como outputs e quais transações de segunda etapa podem ser usadas on-chain.

Os campos que aparecem o tempo todo são:

Campos essenciais de um HTLC
Campo	Função
`payment_hash`	Hash do segredo. Entra no HTLC e permite verificar se uma preimage é correta.
`payment_preimage`	Segredo revelado pelo recebedor final para liquidar o pagamento.
`amount_msat`	Valor do HTLC em millisatoshis. Pode ser maior nos saltos anteriores por causa das taxas.
`cltv_expiry`	Altura de bloco limite usada para timeout do HTLC.
`id`	Identificador local do HTLC naquele canal, usado nas mensagens de fulfill/fail.
`onion_routing_packet`	Pacote onion que carrega as instruções criptografadas para o próximo salto.

Hash, segredo e prazo

O recebedor final sorteia um segredo aleatório, chamado preimage. A invoice divulga apenas o payment_hash = SHA256(preimage). Quem não conhece a preimage consegue verificar o cadeado, mas não consegue abrir.

O HTLC combina esse cadeado de hash com um prazo. A saída pode ser pensada como uma bifurcação:

Caminho do hash: quem apresentar a preimage correta liquida o HTLC.
Caminho do tempo: se a preimage não aparecer até o cltv_expiry, o HTLC pode expirar.

Um HTLC como uma bifurcação: o caminho do hash libera o valor para quem revela a preimage correta; o caminho do tempo permite reembolso após o timeout.

Experimente o cadeado de hash com dados fictícios. A ferramenta sorteia uma preimage, calcula o payment_hash e deixa você testar se um segredo destrava ou não o pagamento:

Cadeado do HTLC

Use uma preimage fictícia de 32 bytes, calcule payment_hash = SHA256(preimage) e simule se o HTLC cumpre por preimage ou expira por CLTV.

Preimage fictícia — 32 bytes em hex

Cadeado (payment_hash = SHA256 do segredo)

Tentar resgatar o pagamento

Apresente uma preimage. O nó só libera o valor se o SHA256 dela bater com o payment_hash acima.

Preimage apresentada

Janela de tempo CLTV

O hashlock permite cumprir; o timelock define quando o caminho de timeout passa a importar.

Altura atual

cltv_expiry do HTLC

delta mínimo do intermediário

Esta ferramenta é didática. Ela não deve receber seed, mnemonic, chave privada, backup de carteira, macaroon, senha ou dado real de pagamento.

HTLC oferecido vs. recebido

Os termos offered HTLC e received HTLC só fazem sentido quando você define a perspectiva. A pergunta correta é: olhando para esta commitment transaction, este lado ofereceu o HTLC ou recebeu o HTLC?

HTLC oferecido e recebido na perspectiva de uma commitment transaction
Tipo	Intuição	Preimage	Timeout	On-chain se necessário
HTLC oferecido	O publicador prometeu pagar se a preimage aparecer.	A contraparte pode resolver com a preimage.	O publicador pode recuperar após o prazo.	`HTLC-timeout`
HTLC recebido	O publicador recebeu uma promessa condicional.	O publicador pode resolver com a preimage.	A contraparte recupera se o prazo expirar.	`HTLC-success`

Essas transações de segunda etapa também carregam a lógica de revogação do canal. Se alguém publica uma commitment antiga, os outputs de HTLC continuam sujeitos a penalidade. Por isso, um HTLC não é um objeto isolado: ele faz parte de um estado de canal que precisa ser assinado, revogado e monitorado.

Ciclo de vida de um HTLC

Adicionar um HTLC não significa apenas mandar uma mensagem. O HTLC precisa entrar nas commitment transactions e o estado anterior precisa ser revogado. A BOLT 2 descreve a máquina de estados por mensagens.

Mensagens principais durante a vida de um HTLC
Mensagem	Função
`update_add_htlc`	Propõe adicionar um HTLC ao canal com valor, hash, prazo e payload onion.
`commitment_signed`	Assina as mudanças pendentes para a commitment transaction da contraparte.
`revoke_and_ack`	Revoga o estado anterior e reconhece a transição para o novo estado.
`update_fulfill_htlc`	Remove um HTLC revelando a `payment_preimage`.
`update_fail_htlc`	Remove um HTLC porque o pagamento falhou em algum ponto da rota.
`update_fail_malformed_htlc`	Remove um HTLC cujo pacote onion não pôde ser processado corretamente.

Uma sequência simplificada para adicionar um HTLC é:

Alice envia update_add_htlc para Bob.
Alice envia commitment_signed, dando a Bob uma nova commitment válida.
Bob verifica a assinatura e responde com revoke_and_ack, revogando o estado anterior dele.
O processo se completa no outro sentido, até os dois lados estarem sincronizados.

Troca de mensagens entre dois nós para adicionar um HTLC: update_add_htlc, commitment_signed e revoke_and_ack, com assinaturas e revogação de estado.

O commitment_signed sozinho não finaliza a atualização. Updates podem ser acumulados antes da assinatura, cada lado tem sua própria commitment transaction e a transição só fica segura quando as assinaturas e revogações necessárias foram trocadas.

Depois, o HTLC sai do canal de duas formas principais: sucesso ou falha. No sucesso, a preimage aparece em update_fulfill_htlc. Na falha, o HTLC é removido com update_fail_htlc ou update_fail_malformed_htlc. Em todos os casos, remover o HTLC também exige novo ciclo de assinatura e revogação.

Encaminhando por vários canais

Agora coloque um intermediário no caminho. Alice quer pagar Carol, mas só tem canal com Bob. Bob tem canal com Carol. O pagamento usa o mesmo payment_hash nos saltos, mas cada canal tem seu próprio HTLC, seu próprio valor e seu próprio prazo.

Carol cria a invoice com um payment_hash.
Alice oferece um HTLC para Bob com esse hash.
Bob oferece outro HTLC para Carol com o mesmo hash.
Carol revela a preimage para receber de Bob.
Bob usa a mesma preimage para receber de Alice.

A preimage volta no sentido contrário ao pagamento: Carol revela para Bob, Bob revela para Alice. Quando o nó intermediário segue a ordem correta de compromisso, revogação e CLTV, a mesma preimage que permite pagar o próximo salto também permite cobrar o salto anterior.

Encaminhamento Alice, Bob e Carol: o mesmo payment_hash aparece em cada salto, os prazos CLTV diminuem em direção ao destino e a preimage volta de Carol para Bob e depois para Alice.

Para o intermediário, há quatro condições importantes:

o HTLC de entrada precisa expirar depois do HTLC de saída;
a diferença de prazos precisa respeitar o cltv_expiry_delta anunciado para o canal;
a diferença de valores precisa pagar a taxa de roteamento;
update_fulfill_htlc, update_fail_htlc e update_fail_malformed_htlc só devem ser enviados depois que o HTLC correspondente estiver irrevogavelmente comprometido nos dois lados.

CLTV delta

O cltv_expiry_delta é a margem de segurança de tempo que um nó exige ao encaminhar pagamentos. Ele aparece nas políticas de roteamento divulgadas por channel_update na BOLT 7.

A regra operacional é simples: quanto mais perto da origem, maior o prazo. Quanto mais perto do destino, menor o prazo. Isso dá ao intermediário tempo para reagir se o próximo salto não liquidar corretamente.

Exemplo simplificado de CLTV em uma rota
Trecho	HTLC enviado	CLTV
Alice -> Bob	51.000 msat	758
Bob -> Carol	50.000 msat	718

Nesse exemplo, Bob exige uma folga de 40 blocos. Se o HTLC Bob->Carol tiver problema, Bob ainda tem margem para resolver o HTLC Alice->Bob antes que o prazo de entrada expire.

A página de Busca de Caminho entra no cálculo completo: soma de deltas, políticas por canal, liquidez, tentativas que falham e escolha de rota.

Taxas de roteamento

O nó intermediário cobra uma taxa para encaminhar. Essa taxa é diferente da taxa on-chain paga a mineradores. Ela é definida pela política de roteamento do canal, divulgada em channel_update.

fee_msat = fee_base_msat + amount_to_forward_msat * fee_proportional_millionths / 1_000_000

O cálculo usa aritmética inteira em millisatoshis e o valor a encaminhar no próximo salto. Por exemplo, se Bob vai entregar 50.000 msat para Carol, cobra fee_base_msat = 1.000 e usa fee_proportional_millionths = 0, Alice precisa oferecer a Bob um HTLC de 51.000 msat. A diferença é a taxa de roteamento do Bob.

Não misture estes custos:

Taxa de roteamento: fica com o nó intermediário por encaminhar o pagamento.
Taxa da commitment transaction: custo on-chain se o canal fechar unilateralmente.
Taxa de HTLC-success/HTLC-timeout: custo de transações de segunda etapa quando HTLCs precisam ser resolvidos on-chain.
Anchor/CPFP: mecanismo de fee bumping para cenários em que a transação precisa confirmar em uma mempool diferente da esperada.

Limites, dust e validações

Um nó não deve aceitar qualquer HTLC. O protocolo e as implementações precisam limitar valores, quantidade, prazos e exposição on-chain. Sem isso, um atacante poderia prender liquidez, ocupar slots de HTLC ou empurrar custos on-chain para outro participante.

Limites que afetam HTLCs
Limite	Efeito prático
`max_accepted_htlcs`	Limita quantos HTLCs simultâneos a contraparte pode manter no canal.
`htlc_minimum_msat`	Valor mínimo para aceitar encaminhar um HTLC naquela direção.
`htlc_maximum_msat`	Valor máximo por HTLC anunciado em `channel_update` para aquela direção do canal.
`max_htlc_value_in_flight_msat`	Exposição total máxima em HTLCs em voo aceita no canal.
`channel_reserve_satoshis`	Impede que um lado drene o canal até zero e preserve margem econômica.
`dust_limit_satoshis`	Define quando outputs pequenos demais não entram na commitment transaction.
`max_dust_htlc_exposure_msat`	Controla exposição acumulada em HTLCs que podem ser removidos por dust.

O ponto mais traiçoeiro é dust. Se um HTLC for pequeno demais, ele pode não virar output explícito na commitment transaction. Isso não significa que existe uma saída separada escondida para resgatar depois. No modelo comum, o valor entra como diferença econômica da commitment transaction; em modelos como zero_fee_commitments, outputs trimmed podem ir para shared_anchor, conforme a variante definida na BOLT 3.

HTLC pequeno não é automaticamente "barato". Ele pode ser barato para encaminhar off-chain, mas problemático se o canal precisar fechar com muitos HTLCs pendentes ou se a exposição por dust ficar alta.

Falhas de roteamento

Nem todo HTLC termina com preimage. Um pagamento pode falhar porque não há liquidez suficiente, a taxa está errada, o CLTV é curto demais, o pacote onion está inválido, o destino não reconhece o pagamento ou a invoice expirou.

Quando a falha acontece, ela volta pela rota. O nó que recebeu o HTLC remove sua promessa com uma mensagem de falha, e cada salto anterior remove o HTLC correspondente no seu próprio canal. Como sempre, remover também precisa passar pela dança de assinatura e revogação.

Falhas comuns durante encaminhamento
Tipo de problema	Exemplo	Onde aprofundar
Liquidez	Canal não tem saldo na direção necessária, por exemplo `temporary_channel_failure`.	Busca de Caminho
Política	Taxa ou `cltv_expiry` abaixo do exigido, como `fee_insufficient` ou `incorrect_cltv_expiry`.	Gossip e políticas de canal
Onion	Payload ausente, HMAC inválido ou próximo salto desconhecido, como `invalid_onion_hmac`.	Roteamento Onion
Destino	Pagamento desconhecido, invoice expirada ou valor incorreto.	Pedidos de Pagamento BOLT 11

Um detalhe importante para privacidade: a falha não precisa revelar tudo para todos. A BOLT 4 define erros onion para que a informação volte de forma compatível com o caminho criptografado. Cada nó só deveria enxergar o que precisa para sua etapa.

Privacidade e onion

Nesta página, Bob aparece sabendo que Alice paga Carol porque estamos usando um exemplo simples. Na rede real, o roteamento onion tenta limitar o que cada intermediário sabe.

Um nó intermediário normalmente sabe:

de qual canal recebeu o HTLC;
para qual canal deve encaminhar;
quanto recebe e quanto encaminha;
qual diferença de CLTV existe entre entrada e saída;
qual taxa fica com ele.

Ele não deveria saber a rota completa, nem se o nó anterior é a origem real, nem se o próximo nó é o destino final. Essa separação é tratada na página de Roteamento Onion. As limitações e ataques de privacidade entram em Segurança e Privacidade a fundo.

Exemplo trabalhado

Imagine que Alice quer pagar Carol 50.000 msat passando por Bob. Bob cobra 1.000 msat de taxa. No exemplo, o HTLC final para Carol usa cltv_expiry = 718; em uma invoice real, Carol normalmente informa um delta mínimo final calculado a partir da altura atual. Bob exige cltv_expiry_delta de 40 blocos.

HTLCs criados no exemplo Alice -> Bob -> Carol
Canal	Valor do HTLC	CLTV	O que acontece
Alice -> Bob	51.000 msat	758	Alice paga Bob se ele revelar a preimage.
Bob -> Carol	50.000 msat	718	Bob paga Carol se ela revelar a preimage.
Taxa do Bob	1.000 msat	-	Diferença entre entrada e saída do intermediário.

Se Carol revela a preimage a Bob depois que os HTLCs estão corretamente comprometidos, Bob consegue cumprir o HTLC de entrada com Alice. Se Carol não revela a preimage, Bob deixa o HTLC de saída falhar ou expirar e ainda tem margem de tempo para cancelar ou expirar o HTLC de entrada. É essa combinação de hash, tempo e estado revogável que torna o encaminhamento seguro para intermediários.

Armadilhas comuns

Achar que todo HTLC vira transação on-chain. Normalmente ele é resolvido off-chain.
Confundir HTLC oferecido e recebido sem dizer de qual commitment transaction você está falando.
Achar que commitment_signed sozinho finaliza o estado.
Confundir taxa de roteamento com taxa de mineração.
Ignorar dust e assumir que todo valor em voo vira output separado.
Usar CLTV delta pequeno demais e deixar intermediários sem tempo de reação.
Revelar ou propagar preimage antes do HTLC estar seguro no estado do canal.
Tratar falha onion como erro transparente que todos os nós conseguem interpretar por completo.

Resumo operacional

HTLC é uma promessa condicional: preimage liquida, timeout protege contra pagamento incompleto.
Adicionar ou remover HTLC exige atualização de estado com assinaturas e revogações.
Em uma rota, cada canal tem seu próprio HTLC, mas todos usam o mesmo payment_hash.
A preimage volta do destino para a origem, liquidando os HTLCs no caminho.
CLTV delta protege intermediários contra perda por corrida de tempo.
Taxas, dust, limites de HTLC e falhas onion são parte central da operação real.

Mapa de dependências conceituais

Antes de ler esta página, ajuda conhecer:

Depois desta página, siga para:

Referências técnicas usadas

A seguir: como o pacote onion esconde o caminho completo e entrega para cada nó apenas as instruções do seu próprio salto.