Key Concepts

Before operating with the DID Registry API, it is convenient to have a clear understanding of the following terms.

Decentralized Identifier (DID)

A unique, verifiable, and persistent digital identifier that allows an entity — person, organization, device, or service — to prove and control its identity without relying on centralized authorities. It is associated with a document (the DID Document) that publishes cryptographic keys and authentication methods.

In ISBE we adopt the did:isbe method. The method-specific part includes:

• modelDeploy — Identifier of the instance (network) on which it is registered. It changes between environments (uc, uc-pre).
• identifier — A multibase string with a z prefix (base58btc) derived from the last 19 bytes of the registration proof (canonical ECDSA signature of keccak256(XY) with the control private key), prepended with version byte 0x00. Deterministic for a given key pair because elliptic.js uses RFC 6979 (deterministic nonce): given the same key pair, the proof — and therefore the identifier — are always the same. To verify it offline you need the original control private key (or the proof from the insertFirstDidDocument transaction).

DID Document

A JSON / JSON-LD document describing the current state of a DID: context, controllers, registered public keys, and verification relationships. It is obtained through the GET /api/v1/identifiers/{identifier} endpoint.

Relevant fields:

• @context — Applicable JSON-LD contexts (W3C DID and cryptographic suites).
• id — The DID itself.
• controller — DIDs or EOAs authorized to modify the document.
• verificationMethod — List of registered public keys.
• assertionMethod, authentication, keyAgreement, etc. — Verification relationships indicating what each key can be used for.
• alsoKnownAs — Alternative identifiers (e.g., a corporate urn:oid).

service field

The service field defined by W3C DID Core is not supported in the current version of the DID Registry. Entities that need to declare service endpoints (well-known, status list, OIDC4VCI, DIDComm) will not be able to do so through the DID Document.

Cryptographic Keys

Formats of publicKeyType in the API

The DID Registry API accepts two operational publicKeyType values to register keys, which differ in how the material is saved in the contract, not necessarily in the curve:

• secp256k1 — The key is saved as 64 XY hexadecimal bytes ("uncompressed" format without the 0x04 prefix, or with it depending on the endpoint). In this mode, the contract only supports the secp256k1 curve; the curve is determined by the ellipticType = 1 that the API assigns by default.

• JsonWebKey2020 — The key is saved as a JWK serialized to JSON and encoded in hex. The actual curve is the one indicated by the crv field inside the JWK (secp256k1, P-256, etc.). The ellipticType = 2 that the API assigns in this mode is ignored during resolution because the JWK already contains its own curve metadata.

That is, JsonWebKey2020 is a genuinely generic wrapper: you can register a secp256k1 or P-256 key with the same publicKeyType, and what decides the curve is the crv of the wrapped JWK. The did-gen keys -c <curve> utility generates both variants in JWK format ready to send.

The "P-256" literal is reserved but not supported

The API enum includes a third value, "P-256", designed to register P-256 without a JWK wrapper (in the same way that secp256k1 registers K1 without a wrapper). Currently, the API responds with 400 UNSUPPORTED with the message "The 'P-256' publicKeyType is temporarily unsupported." Until it is enabled, register P-256 using JsonWebKey2020 with crv: "P-256" inside the JWK.

Key Roles

Regardless of the publicKeyType with which they are registered:

• Control keys (secp256k1) — The derived EOA signs all on-chain transactions to modify the DID. The initial key of the DID (the one in insertFirstDidDocument) is always secp256k1.
• Operational keys — Used off-chain to sign verifiable credentials, accreditations, and other proofs (typically P-256 with alg: ES256). An issuing entity must register at least one with the assertionMethod relationship.

Verification Method

Each key registered in a DID Document is identified by a vMethodId:

• It is a base64url encoded 32-byte identifier (43 characters without padding).
• It can be generated randomly, but it is recommended to use the JWK thumbprint (RFC 7638) of the public key. This way, the identifier remains cryptographically linked to the registered material.

Verification Relationship

A verification relationship expresses what a registered key can be used for. The standard values most used in ISBE are:

Relationship	Typical Use
authentication	Authenticate as the DID.
assertionMethod	Sign verifiable credentials and accreditations.
keyAgreement	Agree keys for encryption.
capabilityInvocation	Invoke delegated capabilities.
capabilityDelegation	Delegate capabilities.

A key must have at least one active relationship to be used operationally.

Controller

An account authorized to modify the DID Document of an entity. Initially, the controller is the EOA derived from the secp256k1 key with which the DID was registered. Additional controllers can be added or revoked through the API.

Trust Chain

A set of cryptographically linked accreditations that allows a verifier to decide if a credential is valid in a context. ISBE distinguishes three roles within a chain:

• RTAO (Root Trusted Accreditation Organization) — Origin of the chain. Only ISBE issues RTAO accreditations.
• TAO (Trusted Accreditation Organization) — Can extend the chain by issuing TAO or TI accreditations.
• TI (Trusted Issuer) — Final issuer of verifiable credentials of the types authorized by the parent TAO.

Accreditations are published in the TIR (Trusted Issuers Registry).

Domain

Domain identifier in ISBE. It allows segmenting trust chains so that different owners co-exist without overlaps. Each verifiable credential issued in ISBE is always associated with a single domain.

Quick Glossary

Term	Meaning
DID	Decentralized Identifier (W3C).
EOA	Externally Owned Account — blockchain account controlled by a private key.
JWK	JSON Web Key (RFC 7517).
JWS	JSON Web Signature.
VC	Verifiable Credential.
TIR	Trusted Issuers Registry.
TA	Trust Anchor — root DID of the environment.
RTAO / TAO / TI	Roles within a trust chain.

DID Registry Architecture

This section is aimed at integrators who need to interact with the contract at a low level or audit the implementation. For normal use of the REST API, it is not necessary.

The DID Registry is implemented in Solidity following the Diamond (EIP-2535) pattern. The logic is divided into independent facets (DidController, DidDocumentDetailed, DidVerificationMethod, DidVerificationRelationship) that share a single contract address on the ISBE blockchain (0x00000000000000000000000000000000000015Be). Each facet exposes a set of selectors and maintains its own storage namespaced by a fixed slot (keccak256('isbe.contracts.<name>.storage')), isolating any collision risk between components.

Practical implications for integrators:

• A single contract address for all registry operations. No need to maintain mappings of "which function lives in which contract".
• The REST API and the @red-isbe/did-isbe-registry library abstract the Diamond pattern; it is only relevant if interacting directly with the contract.
• The set of available functions can grow over time (by adding facets) without changing the contract address or invalidating existing DIDs.