DApp Function Overview

A royalty-compliant NFT rental marketplace supporting ERC‑721/1155 minting, listing, renting, returning, and overdue liquidation. Deposits and rent are managed by an escrow contract. Each rental term is represented by a lease-voucher NFT. Lenders can set daily rent, deposit, and a whitelist. The system integrates on-chain royalties (EIP‑2981), delegated signing via EIP‑712/Permit2, off‑chain metadata sync with IPFS gateway switching, and a front end with batch listing, approval checks, rental countdown, webhooks, dispute arbitration, and evidence anchoring.

Error 1

• Error Code: NRM-NFT-APPROVAL-001
• Error Description: NFT approval missing. The marketplace cannot transfer your NFT to escrow, so listing or renting cannot proceed. (Severity: High)
• Possible Causes:
  • setApprovalForAll was not granted to the escrow contract for this collection.
  • For ERC‑721, a single‑token approval was set for a different tokenId; batch listing requires collection-wide approval.
  • For ERC‑1155, approval exists but the selected tokenId/amount combination is not valid for your wallet.
• Solutions:
  • Grant collection-wide approval: open the wallet prompt to approve the escrow contract (setApprovalForAll).
  • If batch listing, ensure approval covers every targeted collection.
  • Refresh wallet balances and token IDs; verify you still own the NFT and the amount (for ERC‑1155).
  • Developers: preflight check isApprovedForAll(owner, escrow) and show a guided one‑click approval flow before sending any listing/rent transaction.

Error 2

• Error Code: NRM-PERMIT2-SIG-002
• Error Description: Payment authorization invalid or expired. The app cannot pull your rent/deposit via Permit2. (Severity: Critical)
• Possible Causes:
  • The EIP‑712/Permit2 signature is past its deadline or was revoked.
  • The signature domain (chainId or verifying contract) doesn’t match the current network.
  • Nonce mismatch: you used a previously consumed or incorrect nonce.
  • The payment token changed or is unsupported by the escrow.
• Solutions:
  • Re‑authorize: re‑sign the Permit2 approval with the correct chain and token, ensuring a valid deadline.
  • Switch to the correct network and retry.
  • Clear stale allowances in your wallet, then re‑sign to refresh nonce and amounts.
  • Developers: validate signature client‑side before broadcast, display the exact expiry time, and verify chainId, verifyingContract, nonce, and token address match the typed data.

Error 3

• Error Code: NRM-LEASE-STATE-003
• Error Description: Lease state conflict. The NFT is already in an active lease or the voucher state is inconsistent, so your action cannot be completed. (Severity: High)
• Possible Causes:
  • Another transaction has already started a lease for this NFT; a lease-voucher NFT exists and is active.
  • You are trying to return or extend a lease that is already finalized or whose voucher has been burned.
  • UI data is stale due to indexing delay; on-chain state changed after your view loaded.
• Solutions:
  • Refresh on-chain state and try again; confirm whether a current lease-voucher exists and who holds it.
  • Wait for finality (e.g., a few blocks) if another transaction just executed.
  • If returning, ensure the voucher NFT is in your wallet and not already burned or transferred.
  • Developers: read dedicated view functions (e.g., getLease(token, tokenId)) from the latest block to confirm status; never rely solely on cached/subgraph data before sending a transaction.

Error 4

• Error Code: NRM-ROYALTY-005
• Error Description: Royalty validation failed. This listing or rental cannot proceed under royalty-compliance mode. (Severity: Medium)
• Possible Causes:
  • EIP‑2981 royaltyInfo returns a zero receiver or an amount above the marketplace’s cap.
  • The royalty receiver address is not payable or is blocked by policy.
  • The collection lacks EIP‑2981 and no valid override/registry entry is available.
• Solutions:
  • Creators/collection admins: fix or update royalty settings so royaltyInfo returns a valid receiver and amount.
  • Lenders: if allowed, disable strict compliance for this listing or choose a supported collection.
  • Developers: pre‑query royaltyInfo; if invalid, offer a fallback to an approved registry/override or block the action with this clear error before sending a transaction.

Error 5

• Error Code: NRM-LIQUIDATION-TIMING-006
• Error Description: Liquidation not allowed yet. The lease is not overdue or is within a grace period. (Severity: Medium)
• Possible Causes:
  • Current block time has not passed the lease end plus grace period.
  • The UI countdown used local clock data, but on-chain time is slightly different.
  • The voucher indicates an extension or renewal that you haven’t fetched yet.
• Solutions:
  • Wait until the on‑chain countdown expires (lease end + any grace period) and try again.
  • Refresh on‑chain lease data; confirm no extension was executed.
  • Developers: compute deadlines from on‑chain timestamps, not the client clock; display both local estimate and authoritative on‑chain expiry to avoid confusion.

Technical Implementation Suggestions

• Preflight checks in UI:

  • Approvals: call isApprovedForAll for ERC‑721/1155 before listing/renting; prompt a single approval flow for batch actions.
  • Payments: verify Permit2 typed data (chainId, verifyingContract, nonce, deadline, token address) client‑side before sending state‑changing calls.
  • Lease status: query on‑chain view functions for active leases and voucher ownership from the latest block; invalidate cached results on pending txs.
  • Timing: drive countdowns from on‑chain timestamps and include grace period logic. Warn users about small clock drifts.
  • Royalties: probe EIP‑2981 via supportsInterface and royaltyInfo; enforce caps and receiver checks. Provide registry/override fallback if policy allows.

• Contract-side best practices:

  • Use custom errors for precise revert reasons (e.g., ApprovalMissing, LeaseActive, RoyaltyInvalid, NotOverdue), and map them to the above codes in your SDK.
  • Enforce non-reentrant and checks-effects-interactions patterns for escrow transfers.
  • Emit granular events (LeaseStarted, LeaseReturned, LeaseExtended, Liquidated, RoyaltyPaid) with indexed fields to support fast, reliable off‑chain indexing.

• Resilience and UX:

  • Handle chain reorgs by confirming actions after N blocks and re‑querying state before presenting final status.
  • For batch operations, run dry‑run simulations per item and surface itemized errors with the relevant codes.
  • Cache multi‑gateway endpoints for metadata/IPFS, but clearly distinguish UI metadata delays from on‑chain state to avoid user confusion.

• Integration for institutions:

  • Provide a policy toggle for royalty compliance levels (strict/block, warn, or bypass if permitted) and document how each affects transactions.
  • Offer webhooks anchored to specific event signatures and block numbers, with idempotent delivery and replay support.

Descripción general del DApp

Sistema de gobernanza y tesorería para DAO con operación multi‑cadena (L1/L2). Soporta:

• Gobernanza: creación de propuestas, votación por snapshot, timelock para ejecución, delegación de voto, plantillas de propuesta y parámetros de gobernanza actualizables.
• Tesorería: multisig y control de roles (RBAC), distribución de ingresos, desembolsos de presupuesto, desbloqueos por desempeño y pausa de emergencia.
• Interoperabilidad: sincronización de resultados de votación entre cadenas mediante puente de mensajes; ejecución mediante contratos Executor/Treasury.
• Frontend: envío por lotes de firmas, suscripción de estados, exportación de auditoría y observabilidad on‑chain.

A continuación se listan 5 errores representativos (cubre distintos niveles de severidad) con códigos, descripciones, causas y soluciones.

1) Verificación de resultado de votación en cadena destino

• Código de error: GOV-CC-BRIDGE-001-CRIT
• Descripción: El resultado de la votación no puede verificarse en la cadena destino. El mensaje del puente aún no es final o su prueba no es válida.
• Posibles causas:
  • La transacción en la cadena origen no tiene suficientes confirmaciones.
  • ID de cadena o número de secuencia (nonce) no coincide con lo esperado por el Executor.
  • El estado del puente está desactualizado y aún no reconoce el cambio.
  • La ventana de validez del mensaje expiró o el mensaje ya fue consumido (re‑ejecución).
• Solución:
  • Espere el número recomendado de confirmaciones en la cadena origen antes de reenviar.
  • Verifique en la interfaz que chainId, nonce y el puente seleccionado sean correctos; regenere la prueba si es necesario.
  • Reintente cuando el puente reporte sincronización normal; no fuerce ejecuciones durante incidentes.
  • Si el mensaje ya se consumió, sincronice el estado y adjunte el hash de ejecución previa en la auditoría.

2) Ejecución bloqueada por timelock

• Código de error: GOV-TIMELOCK-EXEC-002-ERR
• Descripción: La propuesta no puede ejecutarse porque aún está en timelock o no fue correctamente puesta en cola.
• Posibles causas:
  • El tiempo de desbloqueo (ETA) no se ha alcanzado.
  • La propuesta aprobada no se encoló antes de intentar ejecutarla.
  • La ETA caducó (grace period vencido).
  • Los parámetros a ejecutar (destinos, valores, datos) no coinciden con lo encolado.
• Solución:
  • Espere hasta el tiempo de desbloqueo mostrado por la interfaz/contrato.
  • Encole nuevamente la propuesta con exactamente los mismos parámetros aprobados.
  • Si la ETA caducó, vuelva a encolarla o cree una nueva propuesta.
  • Valide localmente los parámetros antes de firmar para evitar discrepancias.

3) Desembolso rechazado por multisig o lote de firmas inválido

• Código de error: TREASURY-MSIG-THRESH-003-ERR
• Descripción: La tesorería rechazó el desembolso: no se alcanzó el umbral de firmas o el lote enviado es inválido.
• Posibles causas:
  • Se actualizó el umbral del multisig y el conjunto de firmas quedó incompleto.
  • Algún firmante no pertenece al conjunto vigente de firmantes autorizados.
  • Las firmas se generaron con información de dominio/cadena incorrecta (p. ej., datos de red).
  • Las firmas están desordenadas, duplicadas o el lote mezcla versiones diferentes.
• Solución:
  • Actualice la lista de firmantes y el umbral consultando la cadena antes de recolectar firmas.
  • Recolecte firmas nuevamente usando el dominio correcto (nombre, versión, chainId y dirección del contrato).
  • Ordene y desduplice el lote de firmas antes del envío.
  • Si hubo rotación de claves, solicite nuevas firmas a los firmantes vigentes.

4) Permisos insuficientes para pausa, reanudación o actualización

• Código de error: ACCESS-RBAC-PAUSE-004-WARN
• Descripción: Acción bloqueada: la cuenta no tiene el rol requerido para pausar, reanudar o modificar parámetros de gobernanza.
• Posibles causas:
  • La cuenta solo tiene poder de voto delegado, pero no rol de ejecución/guardian.
  • La operación debe canalizarse mediante Timelock o Multisig según la política de seguridad.
  • El sistema está en modo de pausa de emergencia y restringe cambios.
• Solución:
  • Use una cuenta con el rol adecuado o proponga la asignación del rol vía gobernanza.
  • Ejecute la acción mediante el Timelock/Executor o someta la solicitud al multisig.
  • Siga el procedimiento de despausa definido por la política de guardian.

5) Poder de voto no disponible en el snapshot

• Código de error: GOV-VOTE-SNAPSHOT-005-INFO
• Descripción: No se puede votar porque el poder de voto no está disponible para el bloque de snapshot.
• Posibles causas:
  • No realizó la delegación de votos (autodelegación incluida).
  • El bloque de snapshot aún no se alcanza o el indexador está retrasado.
  • El token utilizado no soporta conteo de votos por checkpoints en el bloque indicado.
  • Cambios de balance posteriores al snapshot (transferencias/rebases) no aplican.
• Solución:
  • Delegue sus votos y espere confirmación on‑chain antes de votar.
  • Espere a que se mine el bloque de snapshot y recargue la interfaz.
  • Verifique que está usando el token/capa compatible con conteo de votos por checkpoints.
  • Confirme su poder de voto en la vista de perfil antes de emitir el voto.

Sugerencias de implementación técnica

• Esquema de códigos de error:

  • Defina un formato consistente: MÓDULO-SUBMÓDULO-TIPO-NÚMERO-SEVERIDAD (p. ej., GOV-CC-BRIDGE-001-CRIT).
  • Mantenga un diccionario en frontend/backend para mapear códigos a textos localizables y acciones sugeridas.

• Contratos inteligentes:

  • Use errores personalizados de Solidity para ahorrar gas y estandarizar diagnósticos (p. ej., error NotExecutable(bytes32 proposalId, uint256 nowTs, uint256 eta)).
  • En Timelock y Executor, valide estrictamente los parámetros encolados (destinos, valores, calldata, salt).
  • Marque la idempotencia en ejecuciones cross‑chain: registre messageId/nonce consumidos para prevenir replays.
  • En Tesorería multisig, firme con EIP‑712 y fije domainSeparator con nombre, versión, chainId y dirección del contrato; incluya un campo de expiración opcional.
  • Para RBAC, utilice roles explícitos (EXECUTOR_ROLE, TREASURY_ROLE, GUARDIAN_ROLE, UPGRADER_ROLE) y funciones onlyRole; exponga getters para que el frontend lea el estado actual.
  • Para votación por snapshot, utilice ERC20Votes/IVotes y el método getPastVotes en el bloque de snapshot; no derive poder de voto del balance actual.

• Interoperabilidad L1/L2:

  • Espere finalización suficiente en la cadena origen antes de generar pruebas; parametrice el umbral por red.
  • Valide chainId, nonce y destino en el contrato receptor; rechace mensajes expirados.
  • Registre eventos con IDs correlacionables (proposalId, messageId, executionId) para auditoría y reintentos seguros.

• Frontend y UX:

  • Prevenga errores con pre‑checks: mostrar ETA, estado del puente, poder de voto proyectado y si el usuario tiene el rol necesario.
  • Para lotes de firmas, normalice orden, dedupe y valide dominio antes de permitir “Enviar”.
  • Incluya guías de remediación in‑app alineadas a cada código de error y enlaces a transacciones relevantes.

• Observabilidad y soporte:

  • Emita eventos detallados en cada transición de estado y sincronícelos con un indexador/Subgraph.
  • Exporte logs de auditoría con: timestamp, cadena, rol del emisor, código de error, IDs (proposalId/messageId), y sugerencias aplicadas.
  • Métricas clave: latencia del puente, tasa de fallos por módulo, edad promedio de ETA, desalineación de firmantes vs. umbral, retrasos de indexación.

• Pruebas y simulaciones:

  • Pruebas unitarias y de integración que cubran las 5 rutas de error anteriores.
  • Fuzzing para parámetros de puente y ejecución; tests de reorg/finalidad y expiración de mensajes.
  • Simulaciones de pausa de emergencia y roll‑back controlado para garantizar recuperabilidad.