Digital twins

A digital twin is a domain that represents a real-world thing: a device, an organisation, a project or an oracle service. On IXO, each physical or conceptual thing you need to track is represented as a digital twin domain within a graph of connected domains.

Read this page when you are deciding how to model your own system. It explains the classes of twin, what a twin's record holds, how twins relate to each other and how a protocol shapes them. Clean cooking is the example throughout. The page is about the domain as a whole. For the entity at a domain's core and its on-chain messages, see Manage entities.

Note

Illustrative example. The JSON, Python and curl samples on this page show the shape of a twin and of the calls that create one. They are not a tested sequence you can run as written.

Classes of twin

Each class of domain has its own configuration of properties. An organisational domain, for instance, always contains membership groups as sub-domains.

Class	What it represents
Physical twins	Physical devices and sensors, for example cooking stoves, IoT monitors and tracked inventory
Cognitive twins	Organisational structures, for example projects, funders and distribution agents
Twin systems	The networks of relationships and interactions between real-world things
Oracle twins	AI-enabled agentic services that perform evaluations, verification and automation

What a twin's record holds

{
  "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"
    }]
)

didstringrequired

The twin's W3C Decentralized Identifier (DID), which identifies it uniquely

controllerstringrequired

The party with permission to update the record

servicesarray

Associated services and endpoints

verifiableCredentialarray

Issued certificates and proofs

How twins relate

In general	In a clean cooking programme
Organisations implement projects	An `Organisation` implements a `Project`
Projects generate assets	The `Project` distributes cookstove `Assets` and fuel
Assets produce claims	`Assets` produce usage data based on a `Protocol`
Oracles verify claims	`Oracles` verify claims according to the `Protocol`
Claims become credentials	Carbon credit `Assets` are minted with verifiable credentials

Protocols

A protocol is a template that defines the standard properties and relationships for a specific type of domain. A protocol can be customised.

Protocol structure

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

Create a twin from a protocol

The first sample is a generic request. The second creates a stove from a clean cooking protocol.

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

Manage entities

Create the entity at a twin's core, transfer it and manage its accounts.

The request, the parameters and the verification step for a new domain.

Design a Blueprint

Plan a protocol of your own.

Build an agentic oracle with QiForge

The build guide for agentic oracle services.