Cadeado do HTLC

Teste a relação entre preimage, payment_hash e timeout em um HTLC Lightning

Um HTLC, ou Hashed Timelock Contract, é uma promessa condicional. Ele diz: "este valor pode ser recebido por quem revelar a preimage correta antes do prazo; se isso não acontecer, o caminho de timeout protege quem ofereceu o pagamento".

Na Lightning, esse mecanismo conecta uma invoice BOLT 11, um pagamento roteado por vários canais e a possibilidade de resolver o estado on-chain se algo der errado. A ferramenta usa apenas preimages fictícias. Não cole seed, mnemonic, chave privada, backup de canal, macaroon, senha, invoice privada real nem dados reais de carteira.

Conteúdo

Ferramenta

Cadeado do HTLC

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.

Tentar resgatar o pagamento

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

Janela de tempo CLTV

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

Fonte primária

A vida off-chain do HTLC aparece principalmente na BOLT 2, nas mensagens update_add_htlc, update_fulfill_htlc, update_fail_htlc, commitment_signed e revoke_and_ack. A forma que esse HTLC assume dentro de uma commitment transaction e nas transações de segunda etapa vem da BOLT 3. A reação quando algo aparece na blockchain é tratada pela BOLT 5. A invoice BOLT 11 fornece o payment_hash usado no HTLC.

Ideia simples

O recebedor escolhe uma preimage de 32 bytes e publica apenas o hash dela na invoice:

payment_hash = SHA256(payment_preimage)

O pagador e os intermediários não conhecem a preimage no começo. Eles só conhecem o payment_hash. Cada canal da rota cria um HTLC travado por esse mesmo hash. Quando o recebedor revela a preimage, ela volta pela rota e permite que cada intermediário cumpra seu HTLC de entrada.

O segundo lado do contrato é o tempo. Se a preimage não aparece antes do cltv_expiry, o HTLC pode falhar ou, em caso de fechamento unilateral, seguir o caminho de timeout definido pelos scripts e pelas regras on-chain.

Campos envolvidos

Peças do HTLC no protocolo
Peça Onde aparece Função
payment_preimage Revelada em update_fulfill_htlc. Prova que destrava o pagamento e vira recibo prático.
payment_hash Invoice BOLT 11 e update_add_htlc. Hash SHA256 da preimage; é o cadeado comum dos HTLCs da rota.
amount_msat update_add_htlc e payload onion. Valor prometido naquele canal; pode variar por salto por causa das taxas.
cltv_expiry update_add_htlc e scripts de timeout. Altura de bloco usada para proteger o timeout do HTLC.
onion payload BOLT 4. Diz ao hop quanto encaminhar, qual CLTV usar e para qual próximo canal enviar.

Fluxo passo a passo

  1. Carol cria uma invoice com payment_hash, valor opcional e min_final_cltv_expiry_delta.
  2. Alice calcula uma rota e monta payloads onion para cada hop.
  3. Alice envia update_add_htlc para Bob com valor, payment_hash, cltv_expiry e onion.
  4. Bob só encaminha depois de aplicar as regras do canal, taxa, CLTV e estado de commitment.
  5. Carol recebe o HTLC final e, se aceitar o pagamento, revela a preimage.
  6. A preimage volta com update_fulfill_htlc, removendo os HTLCs no sentido inverso da rota.

Em uma rota com intermediário, o HTLC de entrada precisa expirar depois do HTLC de saída. Essa diferença é o espaço de reação do intermediário. Se Bob paga Carol mas não consegue cobrar Alice a tempo, Bob perde dinheiro. Por isso CLTV delta não é detalhe cosmético.

Exemplo trabalhado

Imagine Alice pagando Carol por Bob:

Dois HTLCs para um pagamento
Canal Valor CLTV Condição
Alice -> Bob51.000 msat850184Bob recebe se revelar a preimage.
Bob -> Carol50.000 msat850144Carol recebe se revelar a preimage.
Taxa de Bob1.000 msat40 blocosDiferença entre entrada e saída.

Se Carol revela a preimage antes do timeout, Bob usa a mesma preimage para cobrar Alice. Se Carol não revela, Bob precisa ter tempo suficiente para cancelar ou deixar expirar o HTLC de saída e depois resolver o HTLC de entrada sem ficar preso. Esse é o motivo da diferença de CLTV entre os saltos.

Quando vai para on-chain

Na maior parte dos pagamentos bem-sucedidos, o HTLC nasce e morre off-chain por mensagens de canal. Ele só vira problema de blockchain quando há fechamento unilateral, disputa, timeout, falha de cooperação ou necessidade de resolver um estado por transações de segunda etapa.

Quando isso acontece, entram conceitos de Bitcoin que já existem fora da Lightning: Script, witness, locktime/CLTV, sequence/CSV, taxas e mempool. Anchor outputs e CPFP também podem importar para confirmar transações em tempo útil.

Armadilhas comuns

Limites da ferramenta

A ferramenta calcula SHA256 da preimage fictícia e mostra uma janela CLTV simplificada. Ela não monta scripts BOLT 3, não serializa transações, não calcula witness, não simula HTLC-success/HTLC-timeout, não aplica dust trimming, não valida onion payload e não substitui carteira ou nó Lightning.

Mapa conceitual

Antes de usar esta ferramenta

Depois de usar esta ferramenta

Referências