Queima de NFTs

Pré-requisitos de acesso

• Permissão (módulo): burnNftAsset
• Licença/Feature: MANAGE_NFTS
• Contêiner do menu: TOKENIZAÇÃO → grupo Tokenização → Queima de NFTs
• Segurança: a execução exige step-up (re-autenticação senha+MFA) e passa por verificação de risco da ação admin.

O que é / quando usar

Permite queimar todas as NFTs de um ativo (asset_id) — ou seja, retirar de todos os holders as entradas de customer_nfts daquele ativo. É o caminho oficial para recall, fraude ou encerramento de oferta, sem deixar saldo "fantasma" na carteira principal e travando o ativo para novas vendas no instante da queima.

A queima é assíncrona: o operador dispara a operação e recebe um operationId em segundos; o processamento on-chain de cada NFT acontece em segundo plano (watcher), e a tela de detalhe faz polling a cada 30s para acompanhar.

Pré-condições

• Permissão: burnNftAsset (dupla — enum CPM burnNftAsset no backend + módulo dinâmico no DB). Sem ambos, a ação não aparece ou retorna 403.
• Licença/Feature: MANAGE_NFTS.
• Step-up obrigatório: senha + MFA (janela de 5 min, header X-Step-Up-Token). Não é aprovação 4-eyes — é re-autenticação do próprio operador.

Passo a passo

1. Acesse Tokenização → Queima de NFTs.
2. Clique em Nova queima para abrir o painel de criação.
3. Busque e selecione o ativo (NFT) a ser queimado.
4. O sistema gera um preview (pré-visualização) da operação — veja o quadro abaixo.
5. Preencha o motivo (mínimo 20 caracteres) e confirme digitando o nome do ativo.
6. Clique em Executar queima → o sistema solicita step-up (senha+MFA).
7. Acompanhe a operação na listagem e na tela de detalhe (polling 30s).

Preview da operação

Antes de executar, o preview mostra o que será afetado:

Campo do preview	O que mostra
Total de holders	Quantos usuários possuem o ativo
Total de NFTs	Quantas NFTs serão queimadas
Burn nativo (contagem)	NFTs que serão queimadas via burn(tokenId) on-chain (estratégia NATIVE_BURN, contrato v2)
Transferência para sink (contagem)	NFTs que serão movidas para a sink wallet (estratégia SINK_TRANSFER, contrato v1)
Endereços de sink usados	Sink wallet por chain (EVM/SOL/XRPL) configurada por env var
Block sell / Block resell atuais	Estado atual das travas do ativo
Operação ativa?	Se já existe uma queima em andamento no mesmo ativo (bloqueia nova)
Skipped (pulados)	NFTs não queimáveis: AT_AUCTION (em leilão), NO_SINK_CONFIGURED, XRPL_NOT_SUPPORTED, ALREADY_SINK

Campos (criação)

Campo	O que é	Obrigatório?	Efeito no sistema/backend
Ativo (asset)	NFT alvo da queima	Sim	assetId — varre customer_nfts WHERE asset_id = X.
Motivo	Justificativa da queima (≥ 20 caracteres)	Sim	reason — registrado na operação para auditoria.
Confirmação do nome	Digitar o nome (ou id) do ativo	Sim	Trava de segurança: só habilita Executar se bater exatamente.

O que acontece na execução

• Travas do ativo: block_sell e block_resell são ligados na mesma transação atômica do cabeçalho da operação, com snapshot dos valores anteriores (previous_block_sell/resell) para reversão manual posterior.
• Destino dos holders: o customer_id de cada NFT muda para BURN_SINK_<CHAIN> (BURN_SINK_EVM/SOL/XRPL). A linha em customer_nfts é mantida (não apagada) — não vai para TKN_OWNER.
• On-chain: conforme collections.contract_version — v2 queima nativamente (NATIVE_BURN); v1 (default atual) move para a sink wallet (SINK_TRANSFER). XRPL não é suportado no MVP (aparece como skipped).
• Contabilidade: o razão (general_journal) registra apenas o débito do holder (baixa de ativo), sem crédito espelho.

Status da operação

Status	Significado
PENDING / IN_PROGRESS	Off-chain já efetivado; on-chain ainda sincronizando (pintado como sucesso com legenda "sincronizando blockchain").
COMPLETED	Todos os itens confirmados on-chain.
PARTIAL_FAILED	Parte dos itens falhou on-chain.
FAILED	A operação falhou.

Cada item (NFT) tem status próprio: PENDING → CONFIRMED / FAILED, com transaction_hash e error_message.

Ações e modais

• Executar queima: dispara execute com step-up obrigatório.
• Reprocessar item (retry): na tela de detalhe, reexecuta um item que falhou — também com step-up.
• Polling: a tela de detalhe atualiza sozinha a cada 30s enquanto a operação está em andamento.

Regras de negócio / cuidados

Irreversível

• A queima retira a NFT de todos os holders e não tem rollback automático. Cada NFT só pode ser queimada uma vez na história (unicidade por customer_nft_id).
• As travas block_sell/block_resell ficam ligadas; a reversão é manual (usando o snapshot previous_block_*).

Atenção

• Uma queima por ativo de cada vez: uma restrição única parcial em (asset_id) WHERE status IN ('PENDING','IN_PROGRESS') impede duas queimas concorrentes no mesmo ativo.
• Queries operacionais devem filtrar customer_id NOT LIKE 'BURN_SINK_%' — saldos em sink não são posições reais.
• NFTs em leilão (AT_AUCTION) e XRPL são pulados.

• Idempotência: a operação é idempotente por ativo (cabeçalho) e por NFT (item). Reprocessar um item já confirmado é seguro.

Exemplos

Cenário 1 — Encerramento de oferta (recall total)

1. Abrir Nova queima e selecionar o ativo da oferta encerrada.
2. Preview mostra, por exemplo, 120 holders / 300 NFTs, todos SINK_TRANSFER (coleção v1).
3. Motivo: "Encerramento da oferta X conforme cláusula Y do contrato."
4. Confirmar digitando o nome do ativo → Executar → step-up.
5. Travas ligam, 300 linhas migram para BURN_SINK_EVM, watcher confirma cada transferência. Acompanhar até COMPLETED.

Cenário 2 — NFT fraudulenta com itens em leilão

1. Selecionar o ativo. Preview lista alguns itens como skipped: AT_AUCTION.
2. Esses não são queimados nesta operação — finalize/cancele o leilão e rode a queima novamente para capturá-los.
3. Itens que falharem on-chain podem ser reprocessados individualmente na tela de detalhe (com step-up).

Telas relacionadas

• Gerenciamento de NFTs
• Coleções

O acompanhamento on-chain das queimas (tipo de transação burn) aparece também no jornal Transações Blockchain de NFTs do contêiner Tokenização.