Europeum

We express our gratitude to the Europeum team for the collaborative engagement that enabled the execution of this Smart Contract Security Assessment.

The project implements an EVM-based Decentralized Identifier (DID) registry that conforms to the W3C DID Data Model, allowing users to register on-chain DID documents and manage their controllers, verification methods, and verification relationships. Access to mutating operations is gated by DID controllership or, alternatively, by policies resolved through an external policy registry contract.

The system users should acknowledge all the risks summed up in the risks section of the report

Documentation quality

• Functional requirements is partially missed.

• • Project overview is suficient.

  • All roles in the system are not described..

  • Use cases are  not described.

• Technical description is provided.

• • Run instructions are provided.

  • Technical specification is provided.

  • NatSpec is insufficient and partially missing for core functions.

  • Inline comments are present

Code quality

• The code leverages OpenZeppelin 5.6.1 (Initializable) and shared in-house primitives (Pagination, ImplementationInitSelector), and follows the established beacon-proxy upgradeable pattern with a reserved storage gap.

• The codebase is well-structured and clearly organized, with a clean split between the entry contract, interfaces, and storage-struct libraries.

• The development environment is configured.

Test coverage

Code coverage of the project is 91.78% (statement coverage).

• Deployment and basic user interactions are covered with 38 passing tests.

• The test  suite exercises the protocol's core end-to-end features covering both success and revert paths for document insertion, controller add/revoke with the 10-controller cap, verification method add/revoke/expire/roll, relationships, pagination, and policy-based authorization via a mocked policy registry.

The system is built around a single upgradeable facade contract, DidRegistry, which is intended to be deployed behind a beacon proxy. Upgrade safety is provided through OpenZeppelin's Initializable pattern, with the constructor disabling initializers via _disableInitializers, an initialize function performing one-time setup, a storage __gap reserved for future variables, and the ImplementationInitSelector mechanism exposing the initializer selector through getImplementationInitSelector. The contract holds three internal storage structures (DidDocuments, Controllers, and VRelationships) whose types are declared in the interface files, and business logic is delegated to three external libraries bound to these structures through using ... for directives. This library-based composition keeps the facade thin while isolating document, controller, and relationship logic into dedicated modules.

State-changing operations follow a consistent pattern in which DidRegistry performs authorization, delegates to the relevant library, and emits an event. Authorization is enforced by the internal onlyControllerOrAuth routine, which first checks whether msg.sender maps to an active capabilityInvocation verification method of one of the DID's controllers, and otherwise queries the external IPolicyRegistry contract via checkPolicy to determine whether the caller is authorized for a named policy attribute. This creates a cross-contract dependency between the registry and an externally deployed policy registry supplied at initialization. Read operations expose paginated views of DIDs, DIDs by controller, and DIDs by verification relationship using the external Pagination utility, and support point-in-time document resolution by filtering verification methods and relationships against a supplied timestamp.

The subsystems are organized by concern. The document subsystem, driven by DidDocumentLib, manages the lifecycle of DID documents, verification methods, and verification relationships, including insertion, updates, key rolling, revocation, and expiry, and derives EVM addresses from secp256k1 public keys. The controller subsystem, driven by ControllersLib, maintains reverse indexes linking controllers to the DIDs they control. The verification relationship subsystem, driven by VRelationshipsLib, maintains time-bounded relationship records indexed by a hash of relationship name and verification method identifier. Supported relationship types follow the W3C DID vocabulary, namely authentication, assertionMethod, keyAgreement, capabilityInvocation, and capabilityDelegation. String comparison across all modules is centralized in UtilsLib.

Files in Scope

• DidRegistry.sol: Upgradeable facade contract that stores DID document, controller, and verification relationship state, and exposes external functions such as insertDidDocument, updateBaseDocument, addController, revokeController, addVerificationMethod, addVerificationRelationship, revokeVerificationMethod, expireVerificationMethod, and rollVerificationMethod. It enforces authorization through onlyControllerOrAuth and _checkController, provides paginated and timestamp-based read views, and integrates with an external policy registry.

• DidDocumentLib.sol: Core library operating on the DidDocuments storage structure that handles DID document creation and mutation, including insertDidDocument, updateBaseDocument, addController, revokeController, addVerificationMethod, addVerificationRelationship, revokeVerificationMethod, expireVerificationMethod, and rollVerificationMethod. It also builds timestamp-filtered document views via getDidDocumentByTimestamp, validates relationship names via isValidRelationshipName, and derives addresses from public keys through getAddress and sanitizePublicKey. It defines the MAX_CONTROLLERS constant of 10.

• ControllersLib.sol: Library that maintains the controller-to-DID reverse index, providing linkDidToController to append a DID under a controller and unlinkDidFromController to remove it using swap-and-pop with index remapping.

• VRelationshipsLib.sol: Library that manages time-bounded verification relationship records keyed by a relationship identifier, exposing addVerificationRelationship to append a DID with its validity period and updateVerificationRelationship to adjust the notAfter timestamp of an existing entry.

• UtilsLib.sol: Utility library providing the equalStrings helper, which compares two strings by length and keccak256 hash for use across the other modules.

Privileged roles

DidRegistry.sol

• DID Controller: An address that holds an active capabilityInvocation verification method belonging to the target DID or any of its linked controller DIDs, validated through _checkController inside the onlyControllerOrAuth gate. Authorized to modify a DID document it controls.

• • Can call updateBaseDocument to replace the base document of the DID.

  • Can call addController to link an additional controller DID.

  • Can call revokeController to unlink a controller DID.

  • Can call addVerificationMethod to register a new verification method.

  • Can call addVerificationRelationship to register a new verification relationship.

  • Can call revokeVerificationMethod to revoke a verification method with a past notAfter.

  • Can call expireVerificationMethod to set a future notAfter expiry on a verification method.

  • Can call rollVerificationMethod to rotate a verification method to a new key while migrating its relationships.

• Policy-Authorized Caller: An address that is not a DID controller but is approved by policyRegistryContract via checkPolicy for the specific tprAttribute string of the invoked function, evaluated in the onlyControllerOrAuth gate. Granted the same document-modification powers as the DID Controller.

• • Can call updateBaseDocument when authorized for policy DID:updateBaseDocument.

  • Can call addController when authorized for policy DID:addController.

  • Can call revokeController when authorized for policy DID:revokeController.

  • Can call addVerificationMethod when authorized for policy DID:addVerificationMethod.

  • Can call addVerificationRelationship when authorized for policy DID:addVerificationRelationship.

  • Can call revokeVerificationMethod when authorized for policy DID:revokeVerificationMethod.

  • Can call expireVerificationMethod when authorized for policy DID:expireVerificationMethod.

  • Can call rollVerificationMethod when authorized for policy DID:rollVerificationMethod.

Note: insertDidDocument is permissionless (any caller may register a new DID, provided the first verification method is flagged as secp256k1).

The scope of the project includes the following smart contracts from the provided repository:

Assets in Scope