Address Lookup Tables in Practice

Use Address Lookup Tables (ALTs) com transações versionadas (v0) para caber mais contas em uma transação sem exceder limites de tamanho de pacote.

Receita

Cartão de receita para referência rápida - pronto para copiar e colar.

solana address-lookup-table create
solana address-lookup-table extend <ALT_ADDRESS> <PUBKEY1> <PUBKEY2>
solana address-lookup-table freeze <ALT_ADDRESS>

Quando usar:

Rotas estilo Jupiter referenciando dezenas de contas.
Agrupando múltiplas instruções com conjuntos de contas sobrepostos.
Reduzindo tamanho serializado de transação para relayers.
Migrando de txs legacy que atingem erros de tamanho.

Exemplo Prático

solana config set --url devnet
solana airdrop 2
 
# Create lookup table (returns table address)
solana address-lookup-table create
 
ALT="<LOOKUP_TABLE_ADDRESS>"
solana address-lookup-table extend "$ALT" \
  TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA \
  YOUR_PROGRAM_ID
 
# Wait for slot activation (~1 slot) then use in v0 tx from client
solana address-lookup-table get "$ALT"

import { createSolanaRpc, address } from "@solana/kit";
 
const rpc = createSolanaRpc(process.env.RPC_URL!);
 
const alt = await rpc
  .getAddressLookupTable(address("ALT_PUBKEY"))
  .send();
 
console.log("addresses:", alt.value?.data.addresses.length);

O que isso demonstra:

ALT armazena lista estática de pubkeys on-chain uma vez.
Transações v0 referenciam contas por índice na ALT mais chaves estáticas.
Extensão exige assinatura de authority até congelar.

Aprofundamento

Como funciona

Conta de lookup table mantém vetor de pubkeys.
Mensagem versionada comprime chaves de 32 bytes para índices de 1 byte para entradas ALT.
AddressLookupTableProgram gerencia create/extend/deactivate/close.
Clientes compilam mensagens v0 com campo addressTableLookups preenchido.

Ciclo de vida da ALT

Etapa	Ação
Create	Alocar conta de tabela
Extend	Acrescentar pubkeys (authority)
Activate	Esperar ~1 slot antes do uso
Freeze	Imutabilidade opcional
Deactivate	Cooldown antes de close

Notas TypeScript

// @solana/kit 7.0.0 supports versioned transaction building
// Fetch ALT accounts with getAddressLookupTable before compile

Erros comuns

Usar ALT antes do slot de ativação - transação falha ao compilar ou verificar. Correção: espere um slot após extend.
Transação legacy com muitas contas - excede limite de pacote de 1232 bytes. Correção: migre para v0 + ALT.
Entradas ALT obsoletas - contas fechadas ainda na tabela. Correção: estenda nova versão de tabela; desative a antiga.
Índice de lookup errado - compila para pubkey errada. Correção: regenere etapa de compile do cliente a partir da leitura on-chain da ALT.
Esquecer flags de índice writable - permissões de account meta erradas. Correção: marque writable/signers corretamente na mensagem compilada.

Alternativas

Alternativa	Use quando	Não use quando
Menos contas / merge ix	Programas simples	Metas grandes inevitáveis
Múltiplas transações	Não-atômico aceitável	Swap atômico obrigatório
Atomicidade Jito bundle	Aterrissagem multi-tx atômica	v0 único suficiente
Padrão remaining accounts	Metas dinâmicas on-chain	Tamanho no cliente ainda grande

FAQs

Quantos endereços por ALT?

Grande capacidade por tabela - estenda em lotes; múltiplas tabelas por tx permitidas dentro dos limites.

Custo para criar ALT?

Lamports rent-exempt para conta de tabela proporcional às pubkeys armazenadas mais fees de tx.

Quem pode estender?

Authority definida na criação - frequentemente multisig do deployer.

Teste de ALT em devnet?

Mesmo fluxo - essencial antes de txs grandes na mainnet.

Relação com doc de transações versionadas?

Veja Versioned Transactions v0.

Carteiras assinam v0?

Carteiras modernas suportam transações versionadas - teste matriz de carteiras cedo.

ALT e priority fees?

Independentes - economia de tamanho habilita aterrissagem; fees ainda necessárias sob congestionamento.

Fechar ALT?

Desative depois feche após cooldown para recuperar rent.

ALT hardcoded no programa?

Programas não embutem ALT - cliente fornece lookup na mensagem de transação.

Helpers de compile kit?

Use builders de mensagem de transação kit com contas de lookup table buscadas.

Relacionados

Versioned Transactions v0 - formato v0
Address Lookup Tables (ALTs) - visão conceitual
Transaction Assembly - ordenação de ixs
Why Transactions Fail to Land - descartes por tamanho

Versões da stack: Esta página foi escrita para Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, anchor-lang 0.32.1, Rust 1.91.1, @solana/kit 7.0.0, Surfpool 0.12.0 e LiteSVM 0.6.x.

Receita

Cartão de receita para referência rápida - pronto para copiar e colar.

solana address-lookup-table create
solana address-lookup-table extend <ALT_ADDRESS> <PUBKEY1> <PUBKEY2>
solana address-lookup-table freeze <ALT_ADDRESS>

Quando usar:

Rotas estilo Jupiter referenciando dezenas de contas.
Agrupando múltiplas instruções com conjuntos de contas sobrepostos.
Reduzindo tamanho serializado de transação para relayers.
Migrando de txs legacy que atingem erros de tamanho.

Exemplo Prático

solana config set --url devnet
solana airdrop 2
 
# Create lookup table (returns table address)
solana address-lookup-table create
 
ALT="<LOOKUP_TABLE_ADDRESS>"
solana address-lookup-table extend "$ALT" \
  TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA \
  YOUR_PROGRAM_ID
 
# Wait for slot activation (~1 slot) then use in v0 tx from client
solana address-lookup-table get "$ALT"

import { createSolanaRpc, address } from "@solana/kit";
 
const rpc = createSolanaRpc(process.env.RPC_URL!);
 
const alt = await rpc
  .getAddressLookupTable(address("ALT_PUBKEY"))
  .send();
 
console.log("addresses:", alt.value?.data.addresses.length);

O que isso demonstra:

ALT armazena lista estática de pubkeys on-chain uma vez.
Transações v0 referenciam contas por índice na ALT mais chaves estáticas.
Extensão exige assinatura de authority até congelar.

Aprofundamento

Como funciona

Conta de lookup table mantém vetor de pubkeys.
Mensagem versionada comprime chaves de 32 bytes para índices de 1 byte para entradas ALT.
AddressLookupTableProgram gerencia create/extend/deactivate/close.
Clientes compilam mensagens v0 com campo addressTableLookups preenchido.

Ciclo de vida da ALT

Etapa	Ação
Create	Alocar conta de tabela
Extend	Acrescentar pubkeys (authority)
Activate	Esperar ~1 slot antes do uso
Freeze	Imutabilidade opcional
Deactivate	Cooldown antes de close

Notas TypeScript

// @solana/kit 7.0.0 supports versioned transaction building
// Fetch ALT accounts with getAddressLookupTable before compile

Erros comuns

Usar ALT antes do slot de ativação - transação falha ao compilar ou verificar. Correção: espere um slot após extend.
Transação legacy com muitas contas - excede limite de pacote de 1232 bytes. Correção: migre para v0 + ALT.
Entradas ALT obsoletas - contas fechadas ainda na tabela. Correção: estenda nova versão de tabela; desative a antiga.
Índice de lookup errado - compila para pubkey errada. Correção: regenere etapa de compile do cliente a partir da leitura on-chain da ALT.
Esquecer flags de índice writable - permissões de account meta erradas. Correção: marque writable/signers corretamente na mensagem compilada.

Alternativas

Alternativa	Use quando	Não use quando
Menos contas / merge ix	Programas simples	Metas grandes inevitáveis
Múltiplas transações	Não-atômico aceitável	Swap atômico obrigatório
Atomicidade Jito bundle	Aterrissagem multi-tx atômica	v0 único suficiente
Padrão remaining accounts	Metas dinâmicas on-chain	Tamanho no cliente ainda grande

FAQs

Quantos endereços por ALT?

Grande capacidade por tabela - estenda em lotes; múltiplas tabelas por tx permitidas dentro dos limites.

Custo para criar ALT?

Lamports rent-exempt para conta de tabela proporcional às pubkeys armazenadas mais fees de tx.

Quem pode estender?

Authority definida na criação - frequentemente multisig do deployer.

Teste de ALT em devnet?

Mesmo fluxo - essencial antes de txs grandes na mainnet.

Relação com doc de transações versionadas?

Veja Versioned Transactions v0.

Carteiras assinam v0?

Carteiras modernas suportam transações versionadas - teste matriz de carteiras cedo.

ALT e priority fees?

Independentes - economia de tamanho habilita aterrissagem; fees ainda necessárias sob congestionamento.

Fechar ALT?

Desative depois feche após cooldown para recuperar rent.

ALT hardcoded no programa?

Programas não embutem ALT - cliente fornece lookup na mensagem de transação.

Helpers de compile kit?

Use builders de mensagem de transação kit com contas de lookup table buscadas.

Relacionados

Versioned Transactions v0 - formato v0
Address Lookup Tables (ALTs) - visão conceitual
Transaction Assembly - ordenação de ixs
Why Transactions Fail to Land - descartes por tamanho

Versões da stack: Esta página foi escrita para Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, anchor-lang 0.32.1, Rust 1.91.1, @solana/kit 7.0.0, Surfpool 0.12.0 e LiteSVM 0.6.x.

Address Lookup Tables in Practice

Buscar na documentação

Address Lookup Tables in Practice