Entities

¿Qué es una Entity?

Una entity es la capa de identidad organizacional en ULedgerNET. Mientras que una billetera es un par de claves criptográficas, una entity es un sujeto organizacional con nombre (una empresa, un equipo, una cuenta de usuario o un agente de IA) que agrupa billeteras bajo una jerarquía de gobernanza estructurada.

Las entities existen para responder la pregunta: "¿Para quién trabaja esta billetera y qué autoridad implica eso?"

Toda billetera que participa en la gobernanza organizacional debe estar vinculado a una entity. Una entity define el contexto organizacional de la billetera, controla el acceso a los recursos y mantiene la configuración de recuperación que sobrevive a la pérdida de claves o a cambios de liderazgo.

---

Tipos de Entity

ULedgerNET define seis tipos de entity organizados en una jerarquía:

ORGANIZATION
└── DEPARTMENT
    └── PERSONAL
        ├── SERVICE
        ├── DEVICE
        └── AGENT

Tipo	Puede Tener Hijos	Uso Típico
ORGANIZATION	Sí (cualquier tipo)	Una empresa, institución o unidad organizacional de nivel superior.
DEPARTMENT	Sí (cualquier tipo)	Un equipo, división o subunidad dentro de una organización.
PERSONAL	Sí (solo SERVICE, DEVICE, AGENT)	La identidad de un usuario humano.
SERVICE	No (hoja)	Un proceso de servicio automatizado persistente.
DEVICE	No (hoja)	Un dispositivo de hardware o endpoint IoT.
AGENT	No (hoja)	Un proceso de agente de IA autónomo.

Las entities hoja (SERVICE, DEVICE, AGENT) no pueden tener hijos. Representan los sujetos terminales de la jerarquía (las entities que realmente ejecutan acciones).

Las entities PERSONAL solo pueden generar hijos de tipo hoja. La identidad de un usuario humano puede poseer agentes, dispositivos y servicios, pero no puede poseer sub-organizaciones ni sub-departamentos.

---

Estructura de Datos de la Entity

UL_Entity {
    Address         string              // TransactionId of CREATE_ENTITY tx
    Name            string              // Normalized name (3-64 chars, lowercase, alphanumeric+dash)
    EntityType      EntityType          // ORGANIZATION | DEPARTMENT | PERSONAL | SERVICE | DEVICE | AGENT
    Parent          string              // Parent entity address (empty for top-level)
    Owner           string              // Owner wallet address
    Wallets         []EntityWalletLink  // All linked wallets with roles and permissions
    Children        []string            // Child entity addresses
    Enabled         bool
    Metadata        map[string]string   // Custom key-value metadata
    AccessList      AccessList          // Blacklist + Trusted list
    RecoveryConfig  EntityRecoveryConfig
    CreatedBlock    uint64
}

EntityWalletLink {
    WalletAddress  string
    Role           string           // "admin" or "member"
    Permissions    EntityPermission // Fine-grained permission bits (role is stored, not consulted)
}

EntityPermission {
    ManageWallets     bool
    ManageChildren    bool
    ManageAccessList  bool
    ManageMetadata    bool
    TransferOwnership bool
}

---

La Jerarquía Organizacional en la Práctica

Despliegue Típico (Empresa → Equipo → Usuario → Agente)

ORGANIZATION: "acme-corp"
│   Owner: corporate-admin-wallet
│
├── DEPARTMENT: "engineering"
│   │   Owner: eng-lead-wallet
│   │
│   └── PERSONAL: "alice"
│       │   Owner: alice-wallet
│       │
│       ├── AGENT: "alice-research-agent"
│       │       Owner: alice-wallet
│       │       Wallet: alice-research-agent-wallet (held by LLM process)
│       │
│       └── SERVICE: "alice-data-pipeline"
│               Owner: alice-wallet
│               Wallet: pipeline-wallet (held by automated service)
│
└── DEPARTMENT: "compliance"
        Owner: compliance-lead-wallet

En esta estructura:

• La entity de organización acme-corp define la cima del árbol de gobernanza.
• Engineering y compliance son departamentos con su propia gobernanza.
• Alice es una entity personal bajo engineering.
• El agente de investigación de IA de Alice es una entity AGENT hoja bajo Alice.
• La billetera del agente de investigación firma sus propias transactions; su historial se atribuye permanentemente al alcance de gobernanza de Alice.

---

Modelo de Permisos: Basado en Bits, No en Roles

Regla crítica: La autorización en las entities se basa en bits de permiso, no en roles.

Una billetera vinculada con role = "member" y Permissions.ManageWallets = true tiene plena capacidad de gestión de billeteras (igual que un admin). El campo role (admin/member) se almacena con fines de visualización y claridad organizacional, pero nunca se consulta durante las verificaciones de autorización.

Lo que importa es qué bits de permiso están activados en el EntityWalletLink.

Bit de Permiso	Qué Permite
ManageWallets	Vincular/desvincular billeteras a/de esta entity
ManageChildren	Crear, modificar o eliminar entities hijas
ManageAccessList	Agregar/eliminar entradas de la lista negra y de la lista de confianza
ManageMetadata	Actualizar los campos de metadata de la entity
TransferOwnership	Transferir la entity a una nueva billetera propietaria

La billetera propietaria de la entity siempre posee todos los permisos. Las billeteras adicionales se vinculan con el subconjunto de permisos que el propietario otorgue.

---

Creación de Entities

Las entities se crean mediante transactions CREATE_ENTITY.

Creación de una Entity Raíz (Sin Padre)

{
    "name": "acme-corp",
    "entityType": "ORGANIZATION",
    "metadata": { "description": "Acme Corporation" }
}

Requisitos:

• La billetera que envía debe ser una billetera raíz (Parent == "").
• La billetera que envía no debe tener ya una afiliación a una entity (wallet.Entity == "").

Después de la creación, la billetera que envía se convierte en la propietaria de la entity y se vincula como miembro con rol admin y todos los permisos.

Creación de una Entity Hija

{
    "name": "alice-research-agent",
    "entityType": "AGENT",
    "parent": "<parent-entity-address>",
    "metadata": { "description": "Autonomous research assistant" }
}

Requisitos:

• La entity padre debe existir y estar habilitada.
• El tipo de la entity padre debe admitir hijos del tipo solicitado.
• La billetera que envía debe tener ManageChildren = true en la entity padre.

---

Transactions del Ciclo de Vida de la Entity

Transaction	Descripción
CREATE_ENTITY	Crea una nueva entity.
ALTER_ENTITY	Actualiza la metadata o habilita/deshabilita la entity.
TRANSFER_ENTITY	Cambia la billetera propietaria. Se actualiza el vínculo inverso wallet.Entity del nuevo propietario.
LINK_WALLET_TO_ENTITY	Agrega una billetera a la entity con un rol y bits de permiso.
UNLINK_WALLET_FROM_ENTITY	Elimina una billetera de la entity.
SET_ENTITY_ACCESS_LIST	Agrega o elimina entradas de la lista negra o de la lista de confianza.
CONFIGURE_ENTITY_RECOVERY	Establece las billeteras de recuperación y el umbral.
REQUEST_ENTITY_RECOVERY	Inicia un proceso de recuperación.
APPROVE_ENTITY_RECOVERY	Emite un voto de aprobación desde una billetera de recuperación.
EXECUTE_ENTITY_RECOVERY	Ejecuta la recuperación una vez alcanzado el umbral.
CANCEL_ENTITY_RECOVERY	Cancela una recuperación en curso.

Para flujos de trabajo de recuperación detallados, selección de umbrales y escenarios de sucesión, ver Recovery.

---

Ancestría de la Entity y Autorización

Antes de ejecutar cualquier transaction, se valida la cadena de ancestría de la entity:

wallet → wallet.Entity → entity.Parent → grandparent.Parent → ...

Toda entity en la cadena, desde la entity de la billetera hasta la raíz, debe estar habilitada. Si algún ancestro está deshabilitado, se rechazan todas las transactions de las billeteras dentro de ese subárbol.

Esto significa que:

• Deshabilitar una entity ORGANIZATION deshabilita todas las billeteras de todos los departamentos, cuentas personales y agentes bajo ella.
• Deshabilitar una entity PERSONAL deshabilita todas las billeteras de los agentes y servicios pertenecientes a ese usuario.
• Deshabilitar una entity AGENT deshabilita únicamente la o las billeteras de ese agente.

La jerarquía hace cumplir el control organizacional en cada nivel.

---

Metadata de la Entity

Las entities incluyen un campo de metadata de formato libre map[string]string. No hay claves reservadas; la capa de aplicación define el esquema.

{
    "description": "Research assistant for market analysis",
    "pref:budget_monthly": "5000",
    "pref:region": "us-east-1",
    "compliance:data_classification": "internal"
}

La metadata es mutable (mediante ALTER_ENTITY) por parte de las billeteras con el permiso ManageMetadata. Se almacena on-chain y forma parte del registro verificable de la entity.