Decentralized Identity System (DID)

note

Prerequisites: It is recommended to have read the Core Components to understand how roles integrate with DIDs.

Audience: For those needing to integrate identity and permissions.

Usage Context: When implementing business logic that requires institutional identity verification.

ISBE uses decentralized identities (DIDs) based on the W3C standard, adapted for permissioned environments with institutional verification.

What is a DID

A DID is a unique identifier representing a verified organization on ISBE. It allows multiple wallets (employees, devices) to operate under the same corporate identity.

did:isbe:0x1234567890abcdef...

Advantages vs Addresses Only

Ethereum Addresses	ISBE DIDs
One address = one account	One DID = multiple wallets of an organization
Change wallet = lose history	Rotate wallets while maintaining identity
No verified metadata	Verified corporate information
No delegated management	Authorized controllers

DID Creation (Onboarding)

Important: DIDs ARE NOT self-registered. ISBE creates them after verifying corporate identity.

Onboarding Flow:

1. Organization requests access to ISBE.
2. Institutional verification (qualified certificates, legal documentation).
3. Signing of contractual agreements.
4. ISBE admin creates the DID with the ISBE_ROLE role.
5. Authorized controllers (legal representatives) are designated.

// Only ISBE admin
function insertFirstDidDocument(
    bytes32 did,
    string memory baseDocument,
    bytes memory signature
) external onlyRole(ISBE_ROLE);

DID Components

1. Controllers

Who can modify the DID: Authorized legal representatives of the organization.

// Add controller
function addController(bytes32 did, bytes32 newController) external;

// Revoke controller  
function revokeController(bytes32 did, bytes32 controller) external;

// Query control
function checkController(bytes32 did, address account) external view returns (bool);

2. Verification Methods (Keys/Wallets)

Employee wallets associated with the corporate DID.

// Add employee wallet
function addVerificationMethod(
    bytes32 did,
    bytes32 vMethodId,
    bytes memory publicKey
) external;

// Revoke wallet
function revokeVerificationMethod(bytes32 did, bytes32 vMethodId) external;

// Rotate wallet (replace old with new)
function rollVerificationMethod(
    bytes32 did,
    bytes32 oldVMethodId,
    bytes32 newVMethodId,
    bytes memory newPublicKey
) external;

3. Verification Relationships (Purposes)

Defines what each key is for:

• authentication: Login/authentication
• assertionMethod: Document signing
• keyAgreement: Encryption
• capabilityInvocation: Permit invocation

// Assign purpose to a key
function addVerificationRelationship(
    bytes32 did,
    bytes32 vMethodId,
    string memory relationship,
    uint256 notBefore,
    uint256 notAfter
) external;

Queries

// Is this address registered?
function isKnownDid(address account) external view returns (bool);

// What DID does this address have?
function didOf(address account) external view returns (bytes32);

// Get current DID Document
function getDidDocument(bytes32 did) external view returns (DidDocument memory);

// Get historical DID Document
function getDidDocumentByTimestamp(bytes32 did, uint256 timestamp) external view 
    returns (DidDocument memory);

// List all DIDs (paginated)
function getDids(uint256 page, uint256 pageSize) external view 
    returns (bytes32[] memory);

Integration with Access Control

ISBE integrates DIDs with RBAC, allowing roles to be assigned to identities (not just addresses).

Automatic Fallback:

When a role is verified:

1. Does the address have the role? → Allow
2. If not, get the DID of that address.
3. Does the DID have the role? → Allow
4. If neither → Deny

function hasRole(bytes32 role, address account) public view returns (bool) {
    // 1. Verify by address
    if (_hasRoleByAddress(role, account)) return true;
    
    // 2. Get DID
    bytes32 did = didRegistry.didOf(account);
    if (did == bytes32(0)) return false;
    
    // 3. Verify by DID
    return _hasRoleByDid(role, did);
}

Advantages:

• Multiwallet: One DID, multiple employees with access.
• Key rotation: Change wallet without losing roles.
• Recovery: Add a new wallet if one is lost.

Example: One DID, Three Wallets

Corporate DID: did:isbe:company-abc
  ├─ CEO Wallet: 0x123...
  ├─ CFO Wallet: 0x456...
  └─ Manager Wallet: 0x789...

OPERATOR role assigned to the DID
→ All 3 wallets have the role automatically

Identity System Summary

Component	Description
DID	Unique and verified corporate identity
Onboarding	ISBE creates DIDs after institutional verification
Controllers	Legal representatives managing the DID
Verification Methods	Employee wallets associated with the DID
Verification Relationships	Purposes of each wallet (auth, signing, etc.)
Queries	Address → DID resolution
RBAC Integration	Roles assigned to identities, not just addresses

The ISBE DID system combines the flexibility of decentralized identities with the institutional verification required in regulated environments.

---

Other technical reference topics:

• Core Components
• Diamond Pattern (EIP-2535)
• Governance System