The did:educreds Method Specification

1. Introduction

1.1 Motivation

Academic credential fraud is a global crisis. Studies estimate that over 40% of job applicants misrepresent their qualifications, costing employers and institutions billions annually. Existing paper-based and siloed digital credential systems are difficult to verify, easy to forge, and not portable across borders.

EduCreds Labs has built a decentralised academic credentialing platform that issues, verifies, and governs digital academic credentials using W3C Verifiable Credentials and Decentralised Identifiers. The did:educreds method provides the identity layer underpinning this platform, enabling:

• Institutions to have cryptographically verifiable, globally resolvable identities linked to their accreditation status and PoIC (Proof of Institutional Credibility) score
• Credentials to carry a DID-based issuer reference that can be independently verified without contacting the issuing institution
• Students to hold self-sovereign wallet-based DIDs that anchor their credential portfolio
• Verifiers to resolve DIDs and confirm issuer legitimacy, credential integrity, and revocation status — independently, without trusting EduCreds as an intermediary

1.2 Conformance

2. Terminology

3. DID Method Syntax

3.1 Method Name

The method name that shall identify this DID method is: educreds

A DID that uses this method MUST begin with the prefix did:educreds:. Per the DID Core specification, this prefix MUST be in lowercase. The remainder of the DID after the prefix is the method-specific identifier described below.

3.2 Method-Specific Identifier

The method-specific identifier is structured as follows:

did:educreds    = "did:educreds:" educreds-specific-idstring
educreds-specific-idstring = subject-type ":" unique-id
subject-type    = "institution" / "credential" / "student"
unique-id       = 1*idchar
idchar          = ALPHA / DIGIT / "-" / "_"

The three subject types serve distinct purposes:

3.3 Examples

# Institution DID
did:educreds:institution:ba5a0d3d-1f72-41b7-b88c-cf25aef18238

# Credential DID
did:educreds:credential:a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4

# Student DID (wallet-based)
did:educreds:student:0xB588E1D7C9B8Cf1C00AE773D91a7fBeCd4CcFF64

4. DID Document

4.1 Structure

A did:educreds DID Document MUST conform to the DID Core specification. The document is stored on IPFS and the IPFS content identifier (CID) is anchored to the Base L2 blockchain via the CredentialIssuer smart contract.

The DID Document MUST include:

• @context — including https://www.w3.org/ns/did/v1
• id — the DID itself
• verificationMethod — at least one public key
• authentication — reference to verification methods used for authentication

The DID Document SHOULD include for institution subjects:

• service — service endpoints for credential issuance API and OID4VC endpoints
• assertionMethod — verification method used to sign Verifiable Credentials
• EduCreds-specific extension: educredsPoIC — current PoIC trust score and tier

4.2 Verification Methods

EduCreds institutions use Ed25519VerificationKey2020 key pairs for signing credentials, with ECDSA P-256 as an alternative for OID4VC flows. Keys are generated at institution registration and stored in an HSM-backed key vault. The public key material is embedded in the DID Document; private keys never leave the institution's controlled key vault environment.

4.3 Service Endpoints

4.4 Example DID Document — Institution

{
  "@context": [
    "https://www.w3.org/ns/did/v1",
    "https://w3id.org/security/suites/ed25519-2020/v1",
    "https://educreds.xyz/ns/did/v1"
  ],
  "id": "did:educreds:institution:ba5a0d3d-1f72-41b7-b88c-cf25aef18238",
  "controller": "did:educreds:institution:ba5a0d3d-1f72-41b7-b88c-cf25aef18238",
  "verificationMethod": [
    {
      "id": "did:educreds:institution:ba5a0d3d-1f72-41b7-b88c-cf25aef18238#key-1",
      "type": "Ed25519VerificationKey2020",
      "controller": "did:educreds:institution:ba5a0d3d-1f72-41b7-b88c-cf25aef18238",
      "publicKeyMultibase": "z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"
    }
  ],
  "authentication": [
    "did:educreds:institution:ba5a0d3d-1f72-41b7-b88c-cf25aef18238#key-1"
  ],
  "assertionMethod": [
    "did:educreds:institution:ba5a0d3d-1f72-41b7-b88c-cf25aef18238#key-1"
  ],
  "service": [
    {
      "id": "did:educreds:institution:ba5a0d3d-1f72-41b7-b88c-cf25aef18238#issuance",
      "type": "CredentialIssuance",
      "serviceEndpoint": "https://api.educreds.xyz/api/v1/standard/certificates/issue"
    },
    {
      "id": "did:educreds:institution:ba5a0d3d-1f72-41b7-b88c-cf25aef18238#evf",
      "type": "CredentialVerification",
      "serviceEndpoint": "https://evf.educreds.xyz/api/v1/evf/verify"
    },
    {
      "id": "did:educreds:institution:ba5a0d3d-1f72-41b7-b88c-cf25aef18238#oid4vci",
      "type": "OID4VCIssuer",
      "serviceEndpoint": "https://oid4vc.educreds.xyz/.well-known/openid-credential-issuer"
    },
    {
      "id": "did:educreds:institution:ba5a0d3d-1f72-41b7-b88c-cf25aef18238#domain",
      "type": "LinkedDomains",
      "serviceEndpoint": "https://educreds.xyz/.well-known/did-configuration.json"
    }
  ],
  "educredsPoIC": {
    "score": 87,
    "tier": "verified",
    "lastEvaluated": "2026-08-01T00:00:00Z",
    "signals": {
      "accreditation": true,
      "governmentRecognised": true,
      "activeIssuance": true,
      "communityReputation": 0.91
    }
  }
}

5. CRUD Operations

5.1 Create

A did:educreds:institution DID is created through the following process:

1. The institution submits a registration request to the EduCreds platform (POST /auth/institution/register) with their verified organisational details.
2. EduCreds platform assigns a UUID v4 as the institution's institutionId. This becomes the unique identifier in the DID: did:educreds:institution:{institutionId}.
3. An Ed25519 key pair is generated for the institution. The private key is stored in an HSM-backed key vault; the public key is embedded in the DID Document.
4. A DID Document is constructed (see Section 4) and published to IPFS. The returned IPFS CID is stored.
5. The DID and IPFS CID are anchored on Base L2 via the CredentialIssuer smart contract transaction. The on-chain record contains: DID (hashed), IPFS CID, institution UUID, and block timestamp.
6. The DID is now resolvable globally.

5.2 Read / Resolve

Resolving a did:educreds DID returns the DID Document. Resolution MUST proceed as follows:

1. The resolver receives the DID string (e.g., did:educreds:institution:ba5a0d3d-...).
2. The resolver queries the EduCreds Verification Framework (EVF) resolution endpoint: GET https://evf.educreds.xyz/did/resolve/{did}.
3. The EVF queries the Base L2 blockchain to retrieve the anchored IPFS CID for the given DID.
4. The EVF fetches the DID Document from IPFS using the CID.
5. The EVF validates the DID Document structure and returns it to the resolver.

# Resolution request
GET https://evf.educreds.xyz/did/resolve/did:educreds:institution:ba5a0d3d-1f72-41b7-b88c-cf25aef18238

# Resolution response
{
  "@context": "https://w3id.org/did-resolution/v1",
  "didDocument": { ... },
  "didDocumentMetadata": {
    "created": "2026-02-15T00:00:00Z",
    "updated": "2026-08-01T00:00:00Z",
    "deactivated": false,
    "versionId": "QmYwAPJzv5CZsnAzt8auV...",
    "nextUpdate": null,
    "equivalentId": ["did:educreds:institution:ba5a0d3d-1f72-41b7-b88c-cf25aef18238"]
  },
  "didResolutionMetadata": {
    "contentType": "application/did+ld+json",
    "retrieved": "2026-08-29T12:00:00Z"
  }
}

Resolvers MAY also use the Universal Resolver once the did:educreds driver has been submitted to the Decentralised Identity Foundation's Universal Resolver repository.

5.3 Update

DID Documents for institution subjects MAY be updated by the DID Controller (the institution admin) via the following process:

1. The institution admin authenticates via POST /auth/institution/login (OTP-based).
2. The admin submits an update request to PATCH /api/institutions/did-profile with the updated fields (e.g., new service endpoints, rotated keys).
3. The platform generates a new DID Document incorporating the changes.
4. The updated DID Document is published to IPFS, producing a new CID.
5. A new on-chain transaction anchors the updated CID against the existing DID.
6. The previous DID Document version is retained on IPFS (immutable history).

5.4 Deactivate

A did:educreds DID MAY be deactivated by the DID Controller or by EduCreds platform governance (e.g., institution loses accreditation). Deactivation is permanent and irreversible.

1. Deactivation is requested via POST /api/institutions/deactivate (requires platform admin authorisation for institution DIDs).
2. An updated DID Document is published with "deactivated": true in the document metadata.
3. A final on-chain transaction records the deactivation CID and timestamp.
4. All credentials issued by a deactivated institution DID remain on IPFS but EVF resolution of those credentials will include a "issuerDeactivated": true flag in the verification result.

6. DID Resolution

The did:educreds method supports two resolution paths:

The EVF resolution endpoint also performs live validation: it checks the on-chain anchor, verifies the IPFS document hash, and returns the current PoIC score alongside the DID Document. This makes did:educreds resolution richer than a plain DID Document fetch — it provides trust context to the verifier in a single call.

7. Security Considerations

7.1 Key Management

Institution signing keys (Ed25519) are generated and stored exclusively in a Hardware Security Module (HSM)-backed secrets vault. Private keys are never exported or transmitted over the network. Key operations (signing) are performed in-place within the key vault — private keys are never exported. EduCreds does not hold copies of institution private keys.

7.2 On-Chain Anchor Integrity

The Base L2 blockchain provides immutability for DID Document anchors. Because the IPFS CID is a content hash, any tampering with a DID Document stored on IPFS would produce a different CID and fail verification against the on-chain anchor. Resolvers MUST verify that the IPFS document's content hash matches the on-chain CID.

7.3 Replay Attack Prevention

All credential issuance and DID update operations include an issuance timestamp and a nonce. The EVF verification framework rejects credentials with timestamps outside a configurable validity window. On-chain transactions include block timestamps that prevent retroactive manipulation.

7.4 DID Enumeration

Because institution UUIDs are the unique-id component of institution DIDs, it is technically possible to enumerate DIDs if UUIDs were sequential. EduCreds uses UUID v4 (randomly generated), making enumeration computationally infeasible. The smart contract does not expose a list of registered DIDs.

7.5 Smart Contract Security

The CredentialIssuer Solidity smart contract is governed by a DAO (via governance/proposals) and upgradeable only through a multi-signature governance vote. Contract updates require a minimum quorum of governance token holders. The contract has been audited internally; a third-party audit is planned for mainnet deployment.

7.6 Denial of Service

DID resolution through the EVF is protected by rate limiting and cloud-layer DDoS protection. IPFS node availability is maintained through redundant pinning (Pinata + self-hosted node). Blockchain read operations are conducted against multiple RPC endpoints to prevent single-node failure.

8. Privacy Considerations

8.1 No PII on Blockchain

The did:educreds method is designed with a strict privacy boundary: no personally identifiable information is ever written to any blockchain or IPFS node. Specifically:

• Student names, email addresses, dates of birth, national ID numbers, and grades are never on-chain
• Credential content is encrypted and stored off-chain; only a SHA-256 hash commitment is anchored on Base L2
• Student DIDs use Ethereum wallet addresses only — no name or identity linkage is stored on-chain
• Institution DIDs expose only: institution name, accreditation number, public key material, and service endpoints — all of which are intended to be public

8.2 Selective Disclosure

EduCreds supports SD-JWT (Selective Disclosure JWT) credentials via the sd-jwt-adapter microservice. Students MAY share partial credential claims (e.g., "I graduated from this university" without revealing GPA) using SD-JWT selective disclosure. The did:educreds DID Documents for credentials support SD-JWT proof types.

8.3 Right to Erasure

Because credential content is stored off-chain, EduCreds can fulfil GDPR and Uganda PDPA 2019 right-to-erasure requests by deleting off-chain data and revoking the on-chain anchor. The on-chain record (a hash with no PII) remains immutable per blockchain design, but without the off-chain content, it reveals nothing about the subject.

8.4 Correlation Risks

Institution DIDs are intended to be public and globally resolvable — correlation is expected and desirable for verification purposes. Student DIDs (wallet addresses) MAY be correlated if the same wallet is used across multiple credentials. Students are encouraged to use unique wallet addresses per institution relationship, which the EduCreds wallet supports natively.

9. Implementation Status

The EduCreds platform is currently deployed as 7 independent microservices — backend, EVF, OID4VC adapter, SD-JWT adapter, Trust Agent, Verifier Agent, and Redis cache. The platform is in active pilot with target institutions in Uganda.

10. References