Skip to content

Digital twin and modes

The twin is the software’s intended behaviour, written as a state machine in the XState document format that xmachines runs. It is built, signed and attested in the same pipeline run as the software, so the build and its twin share one provenance.

Model mode (deploy now) Same-machine mode (target)
The device runs Ordinary code (firmware, a service) that emits events The signed state machine itself, on the xmachines-rs runtime
The twin is An abstraction: the states and transitions the code may take The identical signed definition, on the server
A match means Every observed event is a legal transition from the twin’s current state Exact equality of state, context and emitted events after every step

Same-machine mode gives the strongest evidence, because the comparison is a deterministic replay: any difference is either tampering or a runtime defect. Model mode works for software that cannot be rewritten as a machine, at the cost of checking only what the model describes. Once firmware is converted to a state chart, its own signed definition is the twin, so the twin no longer has to be written and kept in step by hand.

An in-toto statement with its own predicate type (for example https://coreward.dev/attestations/twin/v1), whose subjects are the build’s artifacts by SHA-256 digest. Its predicate holds:

  • the machine definition’s digest, over its exact bytes;
  • the runtime interface it targets (xmachines:runtime@0.3.0) and the engine version;
  • the schema of every event, by codec (JSON, MessagePack, Protobuf or Avro);
  • the mapping from MQTT topics to machine events, and from machine emits back to topics;
  • the verification level, per event or per snapshot;
  • the allowed divergences, if any. Tolerances are signed with the build, so a server cannot loosen them on its own.

A twin must be deterministic, or the server cannot tell drift from noise.

  • No clock and no randomness inside guards or actions. Time arrives as an event, so the server sees the same time the device saw.
  • Side effects are declared, not performed, by the twin. The device performs them; the twin records that they were requested.
  • Every input the device acted on is itself an event on the wire, so the server can replay it.
  • Keep arithmetic in integers or fixed point, so the device and the server give identical results.
  • COSE_Sign1 (RFC 9052). Each event or snapshot is wrapped as a COSE_Sign1 message. Its protected header carries the device ID, the build digest, the twin digest, a monotonic counter from the secure element and the hash of the previous event.
  • COSE_Encrypt0 (RFC 9052). When the payload is confidential, the signed message is wrapped again for the server’s key: sign, then encrypt. The broker and Kafka carry ciphertext only; the routing fields stay in an unencrypted but authenticated header.
  • EAT (RFC 9711). On connecting, the device presents an Entity Attestation Token from the secure element. It claims the measured build digest, so the server can check that the running build is the one Sigstore attested.

Checking every event is optional. The level is chosen per device class and written into the twin attestation.

Level The secure element signs The server checks Divergence is found Fits
Per event Each event Each event At the event that diverged Low-rate, high-assurance devices
Per snapshot, events sent A snapshot: state, context digest, counter range, hash of the events since the last one Replays the events from the last verified snapshot and compares the state reached Within one snapshot interval High-rate streams, small secure elements
Snapshot only A snapshot, as above That the new state is reachable from the last verified one Only as “this state cannot follow that one” Bandwidth-limited devices, or private events

A snapshot is the machine’s persisted state, the same thing the runtime restores from. After a gap, the twin restores from the next verified snapshot instead of waiting for missing events.

Kafka keeps the signed events, so a new twin version can be replayed over a fleet’s history before release. A twin that would flag yesterday’s normal traffic is caught before it ships, and a regression in the software shows up as new divergence.