Cognitive Digital Twins

Tip

The IXO Stack implements a whole-systems approach in which each physical or conceptual entity is represented as a Digital Twin Domain within a graph of inter-connected domains. Clean cooking systems serve as a practical example throughout this guide.

Digital Twin Domains

Different classes of entities have unique configurations of properties. For instance, an Organisational Domain always contains Membership Groups as Sub-domains.

Canonical Domain Classes

Physical Twins

Digital representations of physical devices and sensors (e.g., cooking stoves, IoT monitors, and tracked inventory)

Cognitive Twins

Digital models of Organisational structures (e.g., projects, funders, distribution agents)

Twin Systems

Digital representation of the networks of relationships and interactions between real-world entities

Oracle Twins

AI-enabled agentic services performing evaluations, verification, and intelligent automations

Entity Structure

{
  "did": "did:ixo:entity/device-123",
  "type": "Device",
  "controller": "did:ixo:org/operator",
  "services": [{
    "id": "#data",
    "type": "DataIngestion",
    "endpoint": "https://api.emerging.eco/ingest"
  }],
  "verifiableCredential": [{
    "type": "Certification",
    "issuer": "did:ixo:org/certifier"
  }]
}

from emerging import Entity

# Create a specific device entity
device = Entity.create(
    type="CleanCookingDevice",  # Specific implementation
    controller="did:ixo:org/project-dev",
    services=[{
        "id": "#data",
        "type": "DataIngestion",
        "endpoint": "https://api.emerging.eco/ingest"
    }]
)

Domain Properties

didstringrequired

W3C Decentralized Identifier for unique entity identification

controllerstringrequired

Entity with update permissions

servicesarray

Associated services and endpoints

verifiableCredentialarray

Issued certificates and proofs

Entity Relationships

Generic Implementation

Organisations implement Projects
Projects generate Assets
Assets produce Claims
Oracles verify Claims
Claims become Credentials

Example: Clean Cooking

Organisation implements a Project
Project distributes cookstove Assets and Fuel
Assets produce usage data based on a Protocol
Oracles verify Claims according to the Protocol
Carbon Credit Assets are minted with Verifiable Credentials

Using Protocols

Tip

Protocols are templates that define standard properties and relationships for specific entity types. They can be customized for any domain.

Protocol Structure

{
  "type": "Protocol",
  "properties": {
    "metricOne": "string",
    "metricTwo": "number",
    "measurements": "object"
  },
  "relationships": {
    "verifier": "OracleEntity",
    "operator": "OrganisationEntity"
  }
}

Instantiating Entities

curl -X POST https://api.emerging.eco/v1/entities \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "type": "Device",
    "protocol": "did:ixo:protocol/template",
    "properties": {
      "metricOne": "value",
      "metricTwo": 100
    }
  }'

from emerging import Protocol

# Example using clean cooking protocol
protocol = Protocol.get("did:ixo:protocol/clean-cooking")
stove = protocol.create_entity(
    type="CleanCookingDevice",
    properties={
        "fuel_type": "electric",
        "efficiency": 85
    }
)

Next Steps

Entity Guide

Learn about entity management

Protocol Guide

Create custom protocols

Oracle Guide

Implement verification systems

Integration Guide

Connect physical devices