Listas de Acceso

Propósito

Las listas de acceso a nivel de entity proporcionan dos mecanismos complementarios para controlar quién puede interactuar con una entity y sus recursos:

• Lista negra (blacklist): bloquea explícitamente a actores malintencionados conocidos para que no realicen transactions con esta entity.
• Lista de confianza (trusted list): restringe qué contrapartes tienen permitido realizar transactions con esta entity.

Ambas listas operan a nivel de entity. Se aplican a todas las billeteras asociadas con la entity y se hacen cumplir durante la verificación del perímetro de autorización que se ejecuta antes de cada ejecución de una transaction.

---

Lista negra

La lista negra es un conjunto de direcciones de billetera que tienen prohibido enviar cualquier transaction dirigida a esta entity: incluidas las transferencias de valor, las invocaciones de contratos que apunten a los recursos de la entity y los intentos de vincular billeteras.

Casos de uso

• Bloqueo de actores malintencionados: bloquear una billetera maliciosa conocida para que no envíe tokens a la entity ni interactúe con ella.
• Cuarentena de billeteras comprometidas: si se sospecha que una billetera está comprometida, se recomienda incluirla en la lista negra de todas las entities asociadas mientras la recuperación está en curso.
• Cumplimiento regulatorio: bloquear contrapartes que incumplan requisitos jurisdiccionales.
• Resolución de disputas: durante una disputa, bloquear a una contraparte para que no siga interactuando hasta que la disputa se resuelva.

Comportamiento

Una dirección de billetera incluida en la lista negra no puede:

• Enviar transferencias de valor (tokens) a ninguna billetera asociada con la entity que la incluyó en la lista negra.
• Invocar contratos pertenecientes a la entity.
• Enviar transactions que tengan a la entity como sujeto.

La billetera incluida en la lista negra puede seguir realizando transactions libremente en la red; solo queda bloqueado del alcance de gobernanza de esta entity.

---

Lista de confianza

La lista de confianza es un conjunto de direcciones de billetera que tienen permiso explícito para realizar transactions con esta entity. Cuando la lista de confianza tiene contenido, actúa como una lista de permitidos (allowlist): solo las billeteras de la lista pueden realizar transactions con la entity.

Casos de uso

• Control de contrapartes: solo los socios comerciales preaprobados pueden enviar tokens a esta entity o invocar contratos de su propiedad.
• Cumplimiento de KYC/AML: solo las billeteras que han completado la verificación de identidad (verificada off-chain y luego agregada a la lista de confianza) pueden interactuar.
• Gobernanza privada: solo los miembros del council incluidos en la lista de confianza pueden participar en la votación de propuestas.
• Permisos en la cadena de suministro: solo los proveedores y compradores conocidos pueden ejecutar transferencias dentro del alcance de una entity de cadena de suministro.

Comportamiento

Cuando la lista de confianza no está vacía:

• Solo las direcciones de billetera de la lista pueden iniciar transactions dirigidas a esta entity.
• Las billeteras que no están en la lista (incluso si son válidos en otros aspectos) se rechazan en el perímetro de autorización.
• Las billeteras propias de la entity están permitidos implícitamente (no es necesario que figuren en la lista de confianza para administrar la entity).

Cuando la lista de confianza está vacía:

• No se aplica ninguna restricción de lista de confianza. Cualquier billetera que no esté en la lista negra puede realizar transactions con la entity.

---

Gestión de listas de acceso

Las listas de acceso se gestionan mediante SET_ENTITY_ACCESS_LIST:

{
    "entityAddress": "<entity-address>",
    "operation": "ADD_BLACKLIST",
    "targetAddress": "<wallet-to-block>"
}

{
    "entityAddress": "<entity-address>",
    "operation": "REMOVE_BLACKLIST",
    "targetAddress": "<wallet-to-unblock>"
}

{
    "entityAddress": "<entity-address>",
    "operation": "ADD_TRUSTED",
    "targetAddress": "<wallet-to-allow>"
}

{
    "entityAddress": "<entity-address>",
    "operation": "REMOVE_TRUSTED",
    "targetAddress": "<wallet-to-remove>"
}

Operaciones:

Operación	Efecto
ADD_BLACKLIST	Agrega una billetera a la lista negra.
REMOVE_BLACKLIST	Quita una billetera de la lista negra.
ADD_TRUSTED	Agrega una billetera a la lista de confianza.
REMOVE_TRUSTED	Quita una billetera de la lista de confianza.

Solo las billeteras con el permiso ManageAccessList = true sobre la entity pueden enviar estas transactions.

---

Verificaciones del perímetro de autorización

Las verificaciones de las listas de acceso forman parte del perímetro de autorización, que se ejecuta en dos momentos:

1. Validación del bloque: antes de que las transactions sean aceptadas en un bloque propuesto.
2. Ejecución del bloque: antes de procesar cada transaction.

La secuencia de verificación:

1. La cadena de ancestros de la entity del remitente debe estar completamente habilitada.
2. ¿Está el remitente en la lista negra de la entity destino?
   → Sí → rechazar la transaction.
3. ¿La lista de confianza de la entity destino no está vacía?
   → Sí → ¿está el remitente en la lista de confianza?
      → No → rechazar la transaction.
4. ¿Es una transferencia de valor?
   → ¿La lista de acceso de la entity destinataria bloquea transferencias de valor?
      → Sí → rechazar.
5. Continuar con las verificaciones de capabilities y la ejecución.

---

Listas de acceso y billeteras de los agentes

Las listas de acceso son una herramienta útil para gobernar la interacción de los agentes a nivel de entity:

• Se recomienda agregar a la lista de confianza únicamente las direcciones de las billeteras de los agentes específicas que estén autorizadas a interactuar con una entity. Cualquier billetera de agente nueva que se cree pero no se agregue a la lista de confianza no podrá interactuar, aunque posea capabilities válidas.
• Se puede usar la lista negra para revocar al instante el acceso de un agente a una entity sin alterar la billetera de agente en sí. Esto es útil cuando la billetera de agente se comparte entre varias entities y se desea revocar el acceso a una sin deshabilitar la billetera por completo.

Combinar listas negras, listas de confianza y capabilities proporciona defensa en profundidad:

• Las capabilities controlan lo que la billetera puede hacer a nivel de todo el protocolo.
• La lista de confianza controla con qué entities puede interactuar la billetera.
• La lista negra proporciona una anulación que prevalece sobre ambas.