# Contract

The **machine-readable contract** describes the shape of every message of the
[protocol](protocole.md): an [OpenRPC](https://spec.open-rpc.org/) document whose messages
are written in JSON Schema, with `x-etm-…` extensions for what OpenRPC cannot express —
transport, fallback state machine, named validation rules, tolerances, closed lists.

The engine embeds it, and both its own tests and the conformance suite check it on both
sides. The tables on the [Protocol](protocole.md) page are generated from it.

## Download the contract {#telecharger}

[:material-download: Download `etm-powersync-optimizer-protocol.openrpc.json`](etm-powersync-optimizer-protocol.openrpc.json){ .md-button }

The site serves the file **as is**, byte for byte, from the default branch of the engine
repository. Its record:

<!-- BEGIN GENERATED: __optimizer_contract__ -->

|  | Contract |
|---|---|
| Title | etm-powersync — protocole moteur ↔ optimiseur |
| Protocol version | `1.1` |
| Format | OpenRPC `1.3.2`, JSON Schema in `components.schemas` |
| License | GPL-3.0-or-later |
| File | [`etm-powersync-optimizer-protocol.openrpc.json`](etm-powersync-optimizer-protocol.openrpc.json) |
| Size | 67215 bytes |
| SHA-256 | `29dfe5a3c94a06e94e95042c0ceefd4d6264fcca44265faa676a06fac1c07ded` |
| Methods | `Handshake` · `GetPlan` · `UpdateLearned` |
| Schemas | 47 |
| Semantic rules | 19 |
| Extensions (document) | `x-etm-fallback-machine` · `x-etm-generated` · `x-etm-reason-params` · `x-etm-semantic-rules` · `x-etm-tolerances` · `x-etm-transport` |
| Extensions (methods) | `x-etm-direction` · `x-etm-notification` · `x-etm-timeout-s` |

<!-- END GENERATED -->

## Your box's contract: `NymeaEnergy.GetOptimizerProtocol` {#getoptimizerprotocol}

The contract published here follows the engine's development; your box may carry an
earlier version. To get **the** contract of the installed engine, ask the box: the
JSON-RPC method `NymeaEnergy.GetOptimizerProtocol` returns the one it embeds. That is the
one that is authoritative for an optimiser connected to that box.

The method is described in
[`INTERFACE.md`](https://github.com/etmschurig/etm-powersync-energy-plugin-etm/blob/main/INTERFACE.md),
in the engine repository, along with the other optimiser `NymeaEnergy.*` methods
(endpoint, shared secret, status). Connecting to the API is described on the
[JSON-RPC API](../integrations/jsonrpc-api.md) page.

## Validating messages {#valider}

The engine repository provides a validator, `tools/etm-powersync-schema-check` (Python,
standard library): it checks a single message, a complete recorded session or traces
against the contract, and applies the named validation rules on request.