Mensagens do Protocolo

Como ler, classificar e usar os tipos de mensagem Lightning

• Eric de Castro
• Atualizado em 24/06/2026

⚡ Lightning · Técnico

A página de Protocolo Wire mostrou o envelope: type, payload e extensão TLV opcional. Agora vamos olhar para os tipos de mensagem que aparecem dentro desse envelope e entender o papel operacional de cada família.

Esta página é uma referência didática, não uma cópia completa dos BOLTs. Ela cobre as mensagens mais importantes para entender canais, HTLCs, fechamento e gossip. As fontes primárias são a BOLT 1, a BOLT 2 e a BOLT 7.

Conteúdo

Modelo mental

Um tipo de mensagem não é só um número. Ele diz qual máquina de estados deve processar o payload. A mensagem ping pertence ao controle da conexão. A mensagem open_channel pertence à abertura de canal. A mensagem update_add_htlc pertence à atualização de commitment. A mensagem channel_update pertence ao grafo público usado em roteamento.

Pense em três perguntas:

• Quem deve processar? O gerenciador de conexão, o canal específico, o estado de commitment ou o banco de gossip?
• O payload tem channel_id? Muitas mensagens de canal são multiplexadas em uma única conexão e precisam apontar para o canal correto.
• É público ou privado? Mensagens de gossip podem ser retransmitidas; mensagens de canal ficam entre os dois peers daquele canal.

A BOLT 1 organiza os tipos por faixa. Isso ajuda o parser a classificar rapidamente a mensagem, mas a validação real ainda depende do BOLT específico.

Catálogo por família

Controle e setup

Fonte principal: BOLT 1. Negociar a conexão, anunciar funcionalidades, testar vivacidade e comunicar erros.

Mensagens: Controle e setup

Tipo	Hex	Mensagem	Direção	Quando aparece
1	0x0001	warning	ambos	problema não fatal ou diagnóstico que um peer antigo pode ignorar por ser tipo ímpar
7	0x0007	peer_storage	ambos	armazenamento remoto de dados do peer, quando suportado pela feature correspondente
9	0x0009	peer_storage_retrieval	ambos	recuperação de dados armazenados no peer, quando suportado pela feature correspondente
16	0x0010	init	ambos	primeira mensagem Lightning depois da autenticação do transporte
17	0x0011	error	ambos	falha fatal de canal ou conexão; pode usar channel_id zero para todos os canais
18	0x0012	ping	ambos	teste de vivacidade e padding operacional
19	0x0013	pong	ambos	resposta a ping com o tamanho solicitado

Abertura e fechamento de canal

Fonte principal: BOLT 2. Criar o canal, trocar assinaturas iniciais, confirmar que o funding está pronto e fechar cooperativamente.

Mensagens: Abertura e fechamento de canal

Tipo	Hex	Mensagem	Direção	Quando aparece
32	0x0020	open_channel	fundador -> peer	proposta de abertura v1, com parâmetros econômicos e chaves do canal
33	0x0021	accept_channel	peer -> fundador	aceitação da proposta v1 com os parâmetros da contraparte
34	0x0022	funding_created	fundador -> peer	informa o funding outpoint e entrega assinatura da commitment remota
35	0x0023	funding_signed	peer -> fundador	entrega a assinatura da commitment do fundador
36	0x0024	channel_ready	ambos	avisa que o canal está pronto após o funding ter profundidade suficiente
38	0x0026	shutdown	ambos	inicia fechamento cooperativo e informa script de entrega
39	0x0027	closing_signed	ambos	negocia taxa e assinatura da transação de fechamento mútuo

Commitment e HTLCs

Fonte principal: BOLT 2. Adicionar, assinar, revogar, cumprir ou falhar mudanças no estado do canal.

Mensagens: Commitment e HTLCs

Tipo	Hex	Mensagem	Direção	Quando aparece
128	0x0080	update_add_htlc	ambos	oferece um HTLC com valor, payment_hash, CLTV e pacote onion
130	0x0082	update_fulfill_htlc	ambos	liquida um HTLC revelando a payment_preimage
131	0x0083	update_fail_htlc	ambos	remove um HTLC por falha retornada via onion
132	0x0084	commitment_signed	ambos	assina a commitment remota com as mudanças pendentes
133	0x0085	revoke_and_ack	ambos	revoga estado antigo e entrega próximo per_commitment_point
134	0x0086	update_fee	pagador da taxa -> peer	atualiza a feerate da commitment quando a variante do canal usa fee on-chain
135	0x0087	update_fail_malformed_htlc	ambos	remove HTLC cujo pacote onion está malformado
136	0x0088	channel_reestablish	ambos	ressincroniza estado do canal depois de reconexão

Gossip e descoberta de rede

Fonte principal: BOLT 7. Anunciar canais públicos, nós, políticas de roteamento e consultas ao grafo.

Mensagens: Gossip e descoberta de rede

Tipo	Hex	Mensagem	Direção	Quando aparece
256	0x0100	channel_announcement	gossip/peer	distribui canal público e prova o funding output on-chain
257	0x0101	node_announcement	gossip/peer	distribui identidade pública do nó, aliases, endereços e features
258	0x0102	channel_update	gossip/peer	distribui política de uma direção: taxa, CLTV delta, mínimo e máximo de HTLC
259	0x0103	announcement_signatures	ambos no canal	troca assinaturas necessárias para publicar channel_announcement
261	0x0105	query_short_channel_ids	consulta	pede detalhes de canais específicos por short_channel_id
262	0x0106	reply_short_channel_ids_end	resposta	marca o fim da resposta a query_short_channel_ids
263	0x0107	query_channel_range	consulta	pede canais anunciados em um intervalo de blocos
264	0x0108	reply_channel_range	resposta	responde com SCIDs para o intervalo consultado
265	0x0109	gossip_timestamp_filter	filtro	limita gossip recebido por intervalo de timestamp

A lista acima não é exaustiva. BOLT 2 também define mensagens para abertura v2, quiescence, splicing e fee bumping. Nesta página, elas aparecem como evolução do protocolo, não como base mínima para entender a pilha atual.

Fluxos reais

Mensagens isoladas são úteis para referência, mas o protocolo só faz sentido em sequência. O tipo da mensagem indica onde ela entra no fluxo.

Abertura de canal v1

1. open_channel: o fundador propõe o canal e seus limites.
2. accept_channel: a contraparte aceita e informa seus próprios parâmetros.
3. funding_created: o fundador indica o funding outpoint e entrega assinatura de commitment.
4. funding_signed: a contraparte entrega a assinatura correspondente.
5. channel_ready: após confirmação suficiente, cada lado indica que o canal pode operar.

Esse fluxo conecta mensagens off-chain a uma transação on-chain. Para revisar a parte de funding, veja Canais de Pagamento a fundo, Transação, Saída e UTXO.

Atualização com HTLC

1. update_add_htlc: adiciona uma promessa condicional ao estado do canal.
2. commitment_signed: assina a nova commitment remota com as mudanças pendentes.
3. revoke_and_ack: revoga o estado anterior de quem recebeu a assinatura e avança a sequência.
4. Um segundo par commitment_signed e revoke_and_ack, no sentido oposto, faz o HTLC entrar de forma irrevogável nos dois lados.
5. update_fulfill_htlc, update_fail_htlc ou update_fail_malformed_htlc: remove o HTLC por sucesso ou falha.
6. Outro ciclo de commitment_signed e revoke_and_ack torna a remoção parte do novo estado.

Esse fluxo é a base da página Operação de Canais e Encaminhamento. A mensagem não liquida nada sozinha: ela precisa entrar na máquina de estados assinada e revogável do canal. Em especial, uma mensagem de remoção, como update_fulfill_htlc ou update_fail_htlc, só deve ser enviada depois que o HTLC correspondente estiver irrevogavelmente comprometido nos dois lados.

Gossip público

1. announcement_signatures: peers do canal trocam assinaturas para poder anunciar o canal.
2. channel_announcement: o canal público entra no grafo, ligado a um short_channel_id.
3. node_announcement: o nó publica metadados públicos, como alias, cor e endereços.
4. channel_update: cada direção do canal informa taxas, CLTV delta e limites de HTLC.

channel_update é especialmente importante para roteamento: a BOLT 7 explica que uma rota calcula valores e expiries de trás para frente, partindo do destino para a origem. Aqui usamos "gossip" no sentido didático de distribuição entre peers; implementações reais aplicam filtros, queries e regras de retransmissão.

O que existe no payload

O campo type diz qual mensagem é. O payload diz o que ela carrega. Para desenvolvedores, a diferença entre "identificar" e "validar" é essencial: ler 0080 identifica update_add_htlc, mas não garante que o payload tenha campos suficientes, ordem correta ou valores válidos.

Padrões de payload por família

Família	Campos que você costuma procurar
Controle	gflen, features, tamanho de ping/pong, channel_id em erros.
Abertura	chain_hash, temporary_channel_id, funding, dust, reserve, limites de HTLC, chaves basepoints e delays.
Commitment	channel_id, id do HTLC, amount_msat, payment_hash, cltv_expiry, assinaturas e pontos de commitment.
Gossip	short_channel_id, assinaturas, node_id, timestamp, flags, taxas, CLTV delta e limites de HTLC.

Três formas simplificadas ajudam a reconhecer a intenção da mensagem:

update_add_htlc
type: 128
campos principais:
- channel_id
- id
- amount_msat
- payment_hash
- cltv_expiry
- onion_routing_packet

channel_update
type: 258
campos principais:
- signature
- chain_hash
- short_channel_id
- timestamp
- message_flags
- channel_flags
- cltv_expiry_delta
- htlc_minimum_msat
- fee_base_msat
- fee_proportional_millionths
- htlc_maximum_msat

As estruturas completas têm mais detalhes e variações por feature. Use esses blocos como mapa de leitura, não como schema completo de implementação.

Exemplos práticos

Comece com uma mensagem pequena. Este ping tem 6 bytes: 2 bytes de tipo e 4 bytes de payload.

0012 0004 0000
0012 = type = 18 = ping
0004 = num_pong_bytes
0000 = byteslen

num_pong_bytes = 4
byteslen = 0

Se você colar 001200040000 na ferramenta abaixo, ela identifica o tipo 18, mostra ping e informa que há 4 bytes de payload. Ela não valida todos os campos internos do ping; esse é o trabalho do decoder específico da mensagem.

Outros exemplos didáticos para colar ou acionar pelos botões da ferramenta:

Exemplos para experimentar

Hex	O que mostra	Lição
001000000000	init mínimo	Mensagem de setup sem feature bits.
0001	warning, só o type	Tipo ímpar conhecido no grupo de controle; o payload está incompleto de propósito.
0100	channel_announcement, só o type	Tipo 256 entra na família de gossip; uma mensagem real tem payload grande com assinaturas e campos do canal.
c9012acb0104	TLV ímpar válido	Registros em ordem crescente e com BigSize mínimo.
c90101c90102	TLV duplicado	Um stream TLV canônico não pode repetir o mesmo tipo.
fd00fc0100	BigSize não mínimo	O número 252 deveria ser codificado como fc, não como fd00fc.

Ferramenta

A ferramenta abaixo identifica o tipo de uma mensagem e desmonta streams TLV. Ela tem exemplos prontos e todos usam dados fictícios. Use os botões para comparar casos válidos e inválidos antes de colar seus próprios bytes.

Mensagens Wire e TLV

Mensagens Wire e TLV

Identifica o tipo de 2 bytes e valida a estrutura genérica de um stream TLV. Não valida o schema completo.

Tipo da mensagem

Mensagem em hexadecimal

Os 2 primeiros bytes são o tipo em big-endian. O catálogo de nomes desta ferramenta é parcial.

Exemplos:

init mínimo ping simples só type warning só type gossip 256 custom par desconhecido custom ímpar desconhecido

Resultado da mensagem wire

Stream TLV

Stream TLV em hexadecimal

Sequência type-length-value com BigSize mínimo e types em ordem crescente.

Exemplos:

válido ímpar par estrutural duplicado BigSize não mínimo truncado

Resultado do stream TLV

A ferramenta valida a estrutura genérica. Uma implementação completa ainda precisa validar o schema específico da mensagem, campos obrigatórios, features negociadas, assinaturas e regras de estado do canal.

Armadilhas comuns

• Achar que identificar o type já valida o payload inteiro.
• Confundir mensagens privadas de canal com mensagens públicas de gossip.
• Processar update_add_htlc sem checar se o canal está no estado correto para aceitar updates.
• Tratar channel_update como prova de liquidez. Ele anuncia política, não saldo disponível.
• Esquecer que mensagens com channel_id são multiplexadas na mesma conexão com o peer.
• Assumir que mensagens v2, splicing ou storage são suporte universal. Elas dependem de feature negotiation e estágio de adoção.
• Ignorar que tipos pares desconhecidos e TLVs pares desconhecidos têm comportamento de falha, não de silêncio.

Resumo

• BOLT 1 define as faixas de tipos e mensagens de controle.
• BOLT 2 define as mensagens que abrem, atualizam, fecham e ressincronizam canais.
• BOLT 7 define mensagens de gossip usadas para construir e atualizar o grafo público.
• O type classifica a mensagem; o BOLT específico valida o payload.
• Fluxos reais importam mais que mensagens isoladas: abertura, HTLC/commitment e gossip têm sequências próprias.

Mapa de dependências conceituais

Antes de ler esta página, ajuda conhecer:

• Protocolo Wire
• Canais de Pagamento a fundo
• Operação de Canais e Encaminhamento
• Transação

Depois desta página, siga para:

• Pedidos de Pagamento BOLT 11
• Roteamento Onion
• Gossip e o Grafo de Canais
• Busca de Caminho

Referências técnicas usadas

• BOLT 1 — Base Protocol
• BOLT 2 — Peer Protocol for Channel Management
• BOLT 7 — P2P Node and Channel Discovery

A seguir: como uma invoice BOLT 11 codifica destino, valor, hash de pagamento, expiração, features e hints de rota.