Conceptos clave

Antes de operar con la DID Registry API conviene tener claros los siguientes términos.

Identificador descentralizado (DID)

Identificador digital único, verificable y resistente que permite a una entidad —persona, organización, dispositivo o servicio— demostrar y controlar su identidad sin depender de autoridades centralizadas. Está asociado a un documento (el DID Document) que publica claves criptográficas y métodos de autenticación.

En ISBE adoptamos el método did:isbe. La parte específica del método incluye:

• modelDeploy — Identificador de la instancia (red) sobre la que está registrado. Cambia entre entornos (uc, uc-pre).
• identifier — Cadena multibase con prefijo z (base58btc) derivada de los últimos 19 bytes del proof de registro (firma ECDSA canónica de keccak256(XY) con la clave privada de control), precedidos del byte de versión 0x00. Es determinista para una clave dada porque elliptic.js usa RFC 6979 (nonce determinista): dado el mismo par de claves, el proof y por tanto el identificador son siempre los mismos. Para verificarlo offline necesitas la clave privada de control original (o el proof de la transacción insertFirstDidDocument).

DID Document

Documento JSON / JSON-LD que describe el estado actual de un DID: contexto, controladores, claves públicas registradas y relaciones de verificación. Se obtiene mediante el endpoint GET /api/v1/identifiers/{identifier}.

Campos relevantes:

• @context — Contextos JSON-LD aplicables (W3C DID y suite criptográficas).
• id — El propio DID.
• controller — DIDs o EOAs autorizadas a modificar el documento.
• verificationMethod — Lista de claves públicas registradas.
• assertionMethod, authentication, keyAgreement, etc. — Relaciones de verificación que indican para qué se puede usar cada clave.
• alsoKnownAs — Identificadores alternativos (p. ej. un urn:oid corporativo).

Campo service

El campo service definido por W3C DID Core no está soportado en la versión actual del DID Registry. Las entidades que necesiten declarar service endpoints (well-known, status list, OIDC4VCI, DIDComm) no podrán hacerlo a través del DID Document.

Claves criptográficas

Formatos de publicKeyType en la API

La DID Registry API acepta dos publicKeyType operativos para registrar claves, que se diferencian en cómo se guarda el material en el contrato, no necesariamente en la curva:

• secp256k1 — La clave se guarda como 64 bytes XY hexadecimales (formato "uncompressed" sin el prefijo 0x04, o con él según endpoint). En este modo el contrato solo soporta la curva secp256k1; la curva la determina el ellipticType = 1 que la API asigna por defecto.

• JsonWebKey2020 — La clave se guarda como JWK serializado a JSON y codificado en hex. La curva real es la que indique el campo crv dentro del JWK (secp256k1, P-256, etc.). El ellipticType = 2 que la API asigna en este modo se ignora en la resolución porque el JWK ya contiene su propia metadata de curva.

Es decir, JsonWebKey2020 es un wrapper genuinamente genérico: puedes registrar una clave secp256k1 o P-256 con el mismo publicKeyType, y lo que decide la curva es el crv del JWK que envuelves. La utilidad did-gen keys -c <curva> genera ambas variantes en formato JWK listo para enviar.

El literal "P-256" está reservado pero no soportado

El enum de la API incluye un tercer valor, "P-256", pensado para registrar P-256 sin envoltura JWK (de la misma manera que secp256k1 registra K1 sin envoltura). Actualmente la API responde con 400 UNSUPPORTED con el mensaje "The 'P-256' publicKeyType is temporarily unsupported." Hasta que se habilite, registra P-256 usando JsonWebKey2020 con crv: "P-256" dentro del JWK.

Roles de las claves

Independientemente del publicKeyType con el que se registren:

• Claves de control (secp256k1) — La EOA derivada firma todas las transacciones on-chain de modificación del DID. La primera clave del DID (la del insertFirstDidDocument) es siempre secp256k1.
• Claves operacionales — Se usan off-chain para firmar credenciales verificables, acreditaciones y otras pruebas (típicamente P-256 con alg: ES256). Una entidad emisora debe registrar al menos una con la relación assertionMethod.

Verification Method

Cada clave registrada en un DID Document se identifica con un vMethodId:

• Es un identificador codificado en base64url de 32 bytes (43 caracteres sin padding).
• Puede generarse aleatoriamente, pero se recomienda usar el thumbprint JWK (RFC 7638) de la clave pública. De esta forma el identificador queda criptográficamente vinculado al material registrado.

Verification Relationship

Una relación de verificación expresa para qué se puede usar una clave registrada. Los valores estándar más utilizados en ISBE son:

Relación	Uso típico
authentication	Autenticarse como el DID.
assertionMethod	Firmar credenciales y acreditaciones verificables.
keyAgreement	Acordar claves para cifrado.
capabilityInvocation	Invocar capacidades delegadas.
capabilityDelegation	Delegar capacidades.

Una clave debe tener al menos una relación activa para poder ser usada operativamente.

Controlador (controller)

Cuenta autorizada a modificar el DID Document de una entidad. Inicialmente el controlador es la EOA derivada de la clave secp256k1 con la que se registró el DID. Se pueden añadir o revocar controladores adicionales mediante la API.

Cadena de confianza

Conjunto de acreditaciones enlazadas criptográficamente que permite a un verificador decidir si una credencial es válida en un contexto. ISBE distingue tres roles dentro de una cadena:

• RTAO (Root Trusted Accreditation Organization) — Origen de la cadena. Solo ISBE emite acreditaciones RTAO.
• TAO (Trusted Accreditation Organization) — Puede extender la cadena emitiendo acreditaciones de TAO o TI.
• TI (Trusted Issuer) — Emisor final de credenciales verificables de los tipos autorizados por la TAO padre.

Las acreditaciones se publican en el TIR (Trusted Issuer Registry).

Dominio

Identificador de dominio en ISBE. Permite segmentar cadenas de confianza para que diferentes propietarios coexistan sin solapes. Cada credencial verificable emitida en ISBE está siempre asociada a un único dominio.

Glosario rápido

Término	Significado
DID	Decentralized Identifier (W3C).
EOA	Externally Owned Account — cuenta de blockchain controlada por una clave privada.
JWK	JSON Web Key (RFC 7517).
JWS	JSON Web Signature.
VC	Verifiable Credential.
TIR	Trusted Issuer Registry.
TA	Trust Anchor — DID raíz del entorno.
RTAO / TAO / TI	Roles dentro de una cadena de confianza.

Arquitectura del DID Registry

Esta sección está dirigida a integradores que necesiten interactuar con el contrato a bajo nivel o auditar la implementación. Para el uso normal de la API REST no es necesaria.

El DID Registry está implementado en Solidity siguiendo el patrón Diamond (EIP-2535). La lógica está repartida en facets independientes (DidController, DidDocumentDetailed, DidVerificationMethod, DidVerificationRelationship) que comparten una única dirección de contrato en la blockchain de ISBE (0x00000000000000000000000000000000000015Be). Cada facet expone un conjunto de selectores y mantiene su propio storage namespaceado por slot fijo (keccak256('isbe.contracts.<nombre>.storage')), lo que aísla cualquier riesgo de colisión entre componentes.

Implicaciones prácticas para integradores:

• Una única dirección de contrato para todas las operaciones del registro. No hay que mantener mapeos de "qué función vive en qué contrato".
• La API REST y la librería @red-isbe/did-isbe-registry abstraen el patrón Diamond; sólo es relevante si se interactúa directamente con el contrato.
• El conjunto de funciones disponibles puede crecer con el tiempo (mediante adición de facets) sin que la dirección del contrato cambie ni se invaliden los DIDs existentes.