Gestionar un Service DID

Una vez registrado, el DID paraguas puede modificar sus Service DIDs en cualquier momento: cambiar sus campos libres, rotar su clave, cambiar su caducidad o desactivarlo.

Cómo se hace cualquier cambio

Todos los cambios siguen el mismo flujo que el alta (ver Registrar un Service DID, pasos 4 a 7):

1. Pedir la transacción a la operación correspondiente de la Service DID Registry API.
2. Guardar la respuesta en unsigned-tx.json.
3. Firmarla con el keystore del DID paraguas:

   did-gen sign-tx --keystore ./identity.keystore.json --tx-file unsigned-tx.json > signed.hex

4. Enviarla con POST /api/v1/transactions/send y {"signedRawTransaction": "<contenido de signed.hex>"}.
5. Comprobar el cambio resolviendo el Service DID.

En todas las operaciones, from es la EOA del DID paraguas.

Quién puede hacer cambios

Solo una cuenta con capacidad de invocación activa en el DID paraguas. La clave del propio servicio no puede modificar su Service DID.

Un Service DID desactivado ya no admite ningún cambio.

Cambiar los campos libres

POST /api/v1/contract/updateServiceDocument

{
  "serviceDid": "did:isbe:svc:uc-pre:z1MsSK9H41YvdCrJPmPycEqijYbk:3",
  "from": "0xB8172459924a1e81E511D6473f923E531f7B3a5B",

  "name": "Servicio de Facturación Electrónica",
  "version": "2.2.0",
  "service": [
    {
      "id": "#api",
      "type": "InvoicingAPI",
      "serviceEndpoint": "https://api.facturacion.ejemplo.es/v3"
    }
  ]
}

Todo lo que pongas además de serviceDid y from son los nuevos campos libres.

Los campos se sustituyen enteros

Los campos nuevos reemplazan a todos los anteriores: no se mezclan. Si quieres conservar un campo, vuelve a incluirlo. Para borrar todos los campos libres, envía solo serviceDid y from.

Se aplican las mismas reglas que en el alta: máximo 4096 bytes y sin campos reservados (ver Campos libres).

Rotar la clave del servicio

Cambia la clave de firma del servicio por otra. Es lo que tienes que hacer si sospechas que la clave del servicio se ha visto comprometida.

1. Genera una clave nueva:

   did-gen keys --out ./keys/facturacion-2.keystore.json

2. Pide la transacción:

POST /api/v1/contract/rotateSigningKey

{
  "serviceDid": "did:isbe:svc:uc-pre:z1MsSK9H41YvdCrJPmPycEqijYbk:3",
  "newPublicKey": "0x04<nueva clave pública del servicio>",
  "publicKeyType": "secp256k1",
  "from": "0xB8172459924a1e81E511D6473f923E531f7B3a5B"
}

La clave nueva tiene que cumplir las mismas reglas que en el alta (ver La clave del servicio), y no puede ser la que ya tiene el servicio.

Después de rotarla, el verificationMethod del DID Document muestra la clave nueva. La antigua sigue ligada a tu organización: ningún servicio de otro paraguas podrá usarla nunca.

Cambiar la caducidad

POST /api/v1/contract/updateExpiry

{
  "serviceDid": "did:isbe:svc:uc-pre:z1MsSK9H41YvdCrJPmPycEqijYbk:3",
  "newExpiresAt": 1830297600,
  "from": "0xB8172459924a1e81E511D6473f923E531f7B3a5B"
}

• newExpiresAt es la nueva fecha de caducidad en segundos Unix. Puedes calcularla con epochconverter.com.
• Tiene que ser una fecha futura, o 0 para que no caduque nunca.
• También sirve para ampliar la vida de un servicio que ya ha caducado: mientras no esté desactivado, puedes darle una fecha nueva.

Desactivar un Service DID

POST /api/v1/contract/deactivateServiceDid

{
  "serviceDid": "did:isbe:svc:uc-pre:z1MsSK9H41YvdCrJPmPycEqijYbk:3",
  "from": "0xB8172459924a1e81E511D6473f923E531f7B3a5B"
}

Al resolverlo, el DID Document mostrará "deactivated": true y "reason": "deactivated".

La desactivación es definitiva

Un Service DID desactivado no se puede reactivar ni modificar. Si más adelante necesitas ese servicio, registra uno nuevo.

Consultar Service DIDs

Estas operaciones son de solo lectura: no hace falta firmar nada.

Operación	Para qué sirve
GET /api/v1/identifiers/{serviceDid}	Resuelve el DID Document W3C del servicio, con sus campos libres. Si ya no es válido, incluye deactivated y reason.
GET /api/v1/service-dids/{serviceDid}	Devuelve el registro del servicio tal como está en la cadena: clave, dirección de firma, nonce, caducidad, si está desactivado y fechas de alta y última modificación.
GET /api/v1/service-dids?controller={DID paraguas}	Lista todos los Service DIDs de un paraguas, paginados (page y pageSize). El DID tiene que ir codificado en la URL.

Errores frecuentes

Además de los del registro:

Error	Causa	Solución
500 — transaction execution reverted al modificar	El servicio está desactivado, la nueva caducidad no es futura, o la nueva clave no se puede usar (es la del paraguas, la de un servicio de otra organización o la que ya tiene el servicio).	Revisa el estado del servicio con GET /api/v1/service-dids/{serviceDid} y los datos que envías.
404 NOT_FOUND al consultar	El Service DID no existe en este entorno.	Revisa el identificador y que estás usando la API del entorno correcto.