Documentação

Español

Português
English

Español

Português
English

Appearance

Quema de NFTs ​

Requisitos de acceso

  • Permiso (módulo): burnNftAsset
  • Licencia/Feature: MANAGE_NFTS
  • Contenedor del menú: TOKENIZACIÓN → grupo Tokenización → Quema de NFTs
  • Seguridad: la ejecución requiere step-up (re-autenticación contraseña + MFA) y pasa por verificación de riesgo de la acción admin.

Qué es / cuándo usar ​

Permite quemar todos los NFTs de un activo (asset_id) — es decir, retirar de todos los holders las entradas de customer_nfts de ese activo. Es el camino oficial para recall, fraude o cierre de oferta, sin dejar saldo "fantasma" en la cartera principal y bloqueando el activo para nuevas ventas en el momento de la quema.

La quema es asíncrona: el operador dispara la operación y recibe un operationId en segundos; el procesamiento on-chain de cada NFT ocurre en segundo plano (watcher), y la pantalla de detalle hace polling cada 30s para el seguimiento.

Pre-condiciones ​

  • Permiso: burnNftAsset (doble — enum CPM burnNftAsset en el backend + módulo dinámico en la DB). Sin ambos, la acción no aparece o retorna 403.
  • Licencia/Feature: MANAGE_NFTS.
  • Step-up obligatorio: contraseña + MFA (ventana de 5 min, header X-Step-Up-Token). No es aprobación 4-eyes — es re-autenticación del propio operador.

Paso a paso ​

  1. Accede a Tokenización → Quema de NFTs.
  2. Haz clic en Nueva quema para abrir el panel de creación.
  3. Busca y selecciona el activo (NFT) a quemar.
  4. El sistema genera un preview (vista previa) de la operación — ver la tabla abajo.
  5. Completa el motivo (mínimo 20 caracteres) y confirma escribiendo el nombre del activo.
  6. Haz clic en Ejecutar quema → el sistema solicita step-up (contraseña + MFA).
  7. Sigue la operación en el listado y en la pantalla de detalle (polling 30s).

Preview de la operación ​

Antes de ejecutar, el preview muestra lo que será afectado:

Campo del previewQué muestra
Total de holdersCuántos usuarios poseen el activo
Total de NFTsCuántos NFTs serán quemados
Quema nativa (conteo)NFTs que serán quemados via burn(tokenId) on-chain (estrategia NATIVE_BURN, contrato v2)
Transferencia a sink (conteo)NFTs que serán movidos a la sink wallet (estrategia SINK_TRANSFER, contrato v1)
Direcciones de sink usadasSink wallet por chain (EVM/SOL/XRPL) configurada por env var
Block sell / Block resell actualesEstado actual de los bloqueos del activo
¿Operación activa?Si ya existe una quema en curso para el mismo activo (bloquea nueva)
Omitidos (skipped)NFTs no quemables: AT_AUCTION (en subasta), NO_SINK_CONFIGURED, XRPL_NOT_SUPPORTED, ALREADY_SINK

Campos (creación) ​

CampoQué es¿Obligatorio?Efecto en el sistema/backend
Activo (asset)NFT objetivo de la quemaSíassetId — recorre customer_nfts WHERE asset_id = X.
MotivoJustificación de la quema (≥ 20 caracteres)Síreason — registrado en la operación para auditoría.
Confirmación del nombreEscribir el nombre (o id) del activoSíBloqueo de seguridad: solo habilita Ejecutar si coincide exactamente.

Qué ocurre en la ejecución ​

  • Bloqueos del activo: block_sell y block_resell se activan en la misma transacción atómica del encabezado de la operación, con snapshot de los valores anteriores (previous_block_sell/resell) para reversión manual posterior.
  • Destino de los holders: el customer_id de cada NFT cambia a BURN_SINK_<CHAIN> (BURN_SINK_EVM/SOL/XRPL). La fila en customer_nfts se mantiene (no se elimina) — no va a TKN_OWNER.
  • On-chain: según collections.contract_version — v2 quema nativamente (NATIVE_BURN); v1 (default actual) mueve a la sink wallet (SINK_TRANSFER). XRPL no es compatible en el MVP (aparece como omitido).
  • Contabilidad: el libro mayor (general_journal) registra solo el débito del holder (baja de activo), sin crédito espejo.

Estado de la operación ​

EstadoSignificado
PENDING / IN_PROGRESSOff-chain ya efectuado; on-chain todavía sincronizando (mostrado como éxito con leyenda "sincronizando blockchain").
COMPLETEDTodos los ítems confirmados on-chain.
PARTIAL_FAILEDParte de los ítems falló on-chain.
FAILEDLa operación falló.

Cada ítem (NFT) tiene su propio estado: PENDING → CONFIRMED / FAILED, con transaction_hash y error_message.

Acciones y modales ​

  • Ejecutar quema: dispara execute con step-up obligatorio.
  • Reprocesar ítem (retry): en la pantalla de detalle, re-ejecuta un ítem que falló — también con step-up.
  • Polling: la pantalla de detalle se actualiza automáticamente cada 30s mientras la operación está en curso.

Reglas de negocio / precauciones ​

Irreversible

  • La quema retira el NFT de todos los holders y no tiene rollback automático. Cada NFT solo puede quemarse una vez en su historia (unicidad por customer_nft_id).
  • Los bloqueos block_sell/block_resell quedan activados; la reversión es manual (usando el snapshot previous_block_*).

Atención

  • Una quema por activo a la vez: una restricción única parcial en (asset_id) WHERE status IN ('PENDING','IN_PROGRESS') impide dos quemas concurrentes en el mismo activo.
  • Las consultas operacionales deben filtrar customer_id NOT LIKE 'BURN_SINK_%' — los saldos en sink no son posiciones reales.
  • NFTs en subasta (AT_AUCTION) y XRPL son omitidos.
  • Idempotencia: la operación es idempotente por activo (encabezado) y por NFT (ítem). Reprocesar un ítem ya confirmado es seguro.

Ejemplos ​

Escenario 1 — Cierre de oferta (recall total)
  1. Abrir Nueva quema y seleccionar el activo de la oferta cerrada.
  2. El preview muestra, por ejemplo, 120 holders / 300 NFTs, todos SINK_TRANSFER (colección v1).
  3. Motivo: "Cierre de la oferta X conforme la cláusula Y del contrato."
  4. Confirmar escribiendo el nombre del activo → Ejecutar → step-up.
  5. Se activan los bloqueos, 300 filas migran a BURN_SINK_EVM, el watcher confirma cada transferencia. Seguir hasta COMPLETED.
Escenario 2 — NFT fraudulento con ítems en subasta
  1. Seleccionar el activo. El preview lista algunos ítems como omitidos: AT_AUCTION.
  2. Esos no se queman en esta operación — finaliza/cancela la subasta y ejecuta la quema nuevamente para capturarlos.
  3. Los ítems que fallen on-chain pueden ser reprocesados individualmente en la pantalla de detalle (con step-up).

Pantallas relacionadas ​

El seguimiento on-chain de las quemas (tipo de transacción burn) también aparece en el diario Transacciones Blockchain de NFTs del contenedor Tokenización.