Digital Identifiers

​

Product Overview

The Emerging platform’s Digital Identifier system provides a standardized way to uniquely identify and authenticate all entities in your cookstove projects. Built on decentralized identifier (DID) technology through the Impact Hub public blockchain network, this system enables:

• Unified Entity Registry: Create globally unique identifiers for households, devices, projects, and distribution agents
• Self-Sovereign Control: Maintain full ownership and control of your identifiers without central authority
• Verifiable Credentials: Issue and verify claims about entities in your project ecosystem
• Digital Twin Creation: Generate blockchain-based digital representations (NFTs) of real-world entities
• Secure Authentication: Cryptographically verify the identity of entities interacting with your project

This documentation explains how cookstove project implementers can interact with the platform to generate and manage identifiers and credentials for all project participants and assets.

​

User Personas

​

Use Cases / User Stories

​

Project Registration

As a Project Manager, I want to register my cookstove project on the Emerging platform so that I can create a verifiable digital record of my project activities.

• Acceptance Criteria:
  • Project receives a unique DID in the format did:ixo:entity:[unique-identifier]
  • Project metadata is securely stored and linked to the DID
  • Project appears in the Organisation’s dashboard after registration

​

Household Registration

As a Field Agent, I want to register households participating in the cookstove program so that I can track their participation and impact.

• Acceptance Criteria:
  • Each household receives a unique DID
  • No personally identifiable information (PII) is stored on the blockchain
  • Household registration can be done online or offline with later synchronization
  • Household appears in the project’s registry after registration

​

Device Registration

As a Field Agent, I want to register cookstoves distributed to households so that I can track their usage and performance.

• Acceptance Criteria:
  • Each device receives a unique DID
  • Device is linked to the household DID
  • Device specifications and distribution date are recorded
  • QR code or other identifier can be generated for physical tagging

​

Agent Authentication

As a Project Manager, I want to authenticate field agents so that only authorized personnel can register households and devices.

• Acceptance Criteria:
  • Each agent receives a unique DID
  • Agents can authenticate using mobile devices
  • Agent activities are tracked and linked to their DID
  • Agent permissions can be managed by project administrators

​

Functional Requirements

​

Unified Registry Identifiers (DIDs)

The Emerging platform implements standard, globally unique identifiers for all entities in the dMRV system. Decentralized identifiers (DIDs) are generated by the decentralized registry (Impact Hub public blockchain network) for each household, device, project, and agency.

​

Key Features:

• Globally Unique: Each DID follows the format did:ixo:entity:[unique-identifier]
• Self-Sovereign: DIDs are issued and controlled by the Organisation that creates them
• Persistent: DIDs remain valid for the lifetime of the entity they identify
• Resolvable: DIDs can be looked up to retrieve associated information
• Verifiable: DIDs enable cryptographic verification of associated claims

​

Digital Twin NFTs

When a DID is created, the IXO Protocol blockchain creates a Digital Twin NFT (non-fungible token) for each real-world entity. This means:

• Data, services, rights, accounts, and claims associated with the DID can be owned and controlled by the DID owner
• The cryptographic keys associated with a DID enable authentication by its controller
• Verifiable claims can be submitted, and verifiable credentials can be issued, using the identifier as the subject

​

Registering an Entity

To register a DID using the platform, you can use either the web interface or the API:

​

Using the Web Interface:

1. Navigate to the “Registry” section in the platform dashboard
2. Select “Create New Entity”
3. Choose the entity type (Project, Household, Device, or Agent)
4. Complete the required metadata fields
5. Submit the registration request

The platform handles all blockchain interactions and covers transaction fees through your platform subscription.

​

Using the API:

For programmatic registration, use the msgCreateEntity function:

{
  "id": "did:ixo:entity:[unique-identifier]",
  "type": "[EntityType]",
  "controller": "[ControllerDID]",
  "credentials": [],
  "metadata": {
    "startDate": "2024-01-01T00:00:00Z",
    "endDate": null,
    "status": "Active"
  }
}

When using the API directly, a small transaction fee (gas) in IXO tokens is required to add this record to the blockchain.

​

Success Response:

Upon successful creation, you’ll receive a response similar to:

{
  "height": "123456",
  "txhash": "ABCDEF1234567890",
  "data": {
    "id": "did:ixo:entity:[unique-identifier]",
    "type": "[EntityType]",
    "status": "Active"
  }
}

​

Entity Metadata

Each entity in the registry contains metadata that provides additional information and context:

​

Required Metadata:

• Entity Type: Specifies the category (Project, Household, Device, Agent)
• Controller: The DID of the entity that controls this identifier
• Status: Current state (Active, Inactive, Suspended)

​

Optional Metadata:

• Validity Period: Start and end dates for the entity’s validity
• Credentials: Array of credential identifiers associated with the entity
• Location: Geographic coordinates (for physical entities)
• Custom Properties: Additional fields specific to the entity type

​

Verified Status

The entity metadata includes a verified status (True or False) which may only be set by the Market Relayer account of the platform operator.

​

Verification Process:

1. Entity is registered with initial verified status set to False
2. Platform operator (Market Relayer) reviews the entity according to established criteria
3. If approved, the Platform Operator sets verified status to True
4. Verified status is visible in entity queries and can be used by applications

The criteria and process for verifying entities, as well as the governance procedures, are determined by the Platform Operator, which typically operates as a decentralized autonomous Organisation (DAO).

​

Editing an Entity’s Domain Record

The entity domain record (DID Document) can only be modified by a Controller account:

​

Using the Web Interface:

1. Navigate to the entity details page
2. Select “Edit Entity”
3. Modify the desired fields
4. Submit the update request

​

Using the API:

To update an entity’s domain record, use the msgEditEntity function:

{
  "id": "did:ixo:entity:[unique-identifier]",
  "controller": "[ControllerDID]",
  "metadata": {
    "status": "Inactive"
  }
}

Only the fields included in the request will be updated; omitted fields remain unchanged.

​

Entity Accounts

Each Digital Twin Domain entity has one or more accounts that may hold digital assets:

​

Key Features:

• Asset Ownership: Entity accounts can hold tokens, NFTs, and other digital assets
• Delegated Control: Entity owner can authorize other accounts to operate the entity accounts
• Granular Permissions: Controls can be set for spend amounts, token types, and time periods
• Ownership Transfer: When entity ownership is transferred, all assets move with the entity

​

Adding an Entity Account:

To add a new entity account, use the msgCreateEntityAccount function:

{
  "entityId": "did:ixo:entity:[unique-identifier]",
  "name": "Operating Account",
  "accountType": "token",
  "permissions": [
    {
      "delegateDid": "did:ixo:entity:[delegate-id]",
      "maxTokens": "1000",
      "denominations": ["uxio"],
      "validUntil": "2025-01-01T00:00:00Z"
    }
  ]
}

​

Adding or Removing Entity Controllers

Entity controllers have full authority to manage the entity’s domain record and accounts:

​

Adding a Controller:

1. Navigate to the entity details page
2. Select “Manage Controllers”
3. Add the DID of the new controller
4. Specify controller permissions
5. Submit the update

​

Removing a Controller:

1. Navigate to the entity details page
2. Select “Manage Controllers”
3. Select the controller to remove
4. Confirm the removal
5. Submit the update

Note that an entity must always have at least one controller. A controller may include a Group Account, which may have governance rights over the entity.

​

Transferring Domain Ownership

To transfer ownership of an entity to another controller:

​

Using the Web Interface:

1. Navigate to the entity details page
2. Select “Transfer Ownership”
3. Enter the DID of the new owner
4. Confirm the transfer
5. Sign and submit the request

​

Using the API:

Use the msgTransferEntity function:

{
  "id": "did:ixo:entity:[unique-identifier]",
  "fromDid": "did:ixo:entity:[current-owner]",
  "toDid": "did:ixo:entity:[new-owner]"
}

Upon successful transfer, all entity accounts and assets are transferred to the new owner.

​

Authenticating an Entity

Authentication verifies that an interaction is authorized by the entity controller:

​

Authentication Methods:

• Key-based: Using the cryptographic keys associated with the controller
• Credential-based: Using verifiable credentials issued to the entity
• Multi-factor: Combining multiple authentication methods for higher security

​

Authentication Process:

1. Client application requests authentication from entity
2. Entity provides authentication proof using one of the registered methods
3. Platform verifies the proof against the entity’s domain record
4. If valid, the authentication is confirmed and access is granted

​

Non-functional Requirements

​

Security

• All DIDs must be cryptographically secure and tamper-proof
• Private keys must never be transmitted or stored unencrypted
• Authentication must use industry-standard protocols

​

Performance

• Entity registration should complete within 30 seconds
• DID resolution should occur in under 3 seconds

​

Scalability

• The registry must support millions of entities
• Performance should not degrade significantly as the registry grows

​

Privacy

• No personally identifiable information (PII) should be stored on the blockchain
• All sensitive data must be encrypted and stored off-chain
• Access to entity data must be controlled by the entity owner

​

Compliance

• The system must comply with relevant data protection regulations
• All transactions must be auditable and traceable

​

Assumptions & Constraints

​

Assumptions

• Users have basic understanding of digital identifiers and blockchain concepts
• Internet connectivity is available for synchronizing offline registrations
• Project implementers have the necessary permissions to register entities
• Mobile devices are available for field agents to register households and devices

​

Constraints

• Blockchain transaction fees (gas) may apply for direct API usage
• Internet connectivity may be limited in some field locations
• Entity registration requires cryptographic key management
• Some operations may require approval from multiple controllers

​

Appendices

​

Glossary of Terms

• DID (Decentralized Identifier): A globally unique identifier that doesn’t require a centralized registration authority
• Digital Twin: A digital representation of a real-world entity
• NFT (Non-Fungible Token): A unique digital asset that represents ownership of a specific item
• Controller: An entity that has the authority to manage a DID
• Verifiable Credential: A tamper-evident credential with authorship that can be cryptographically verified
• dMRV: Decentralized Measurement, Reporting, and Verification

​

Related Documentation