Skip to main content
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

​
did
string
required
W3C Decentralized Identifier for unique entity identification
​
controller
string
required
Entity with update permissions
​
services
array
Associated services and endpoints
​
verifiableCredential
array
Issued certificates and proofs

​
Entity Relationships

  • Organisations implement Projects
  • Projects generate Assets
  • Assets produce Claims
  • Oracles verify Claims
  • Claims become Credentials
  • 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

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