TWIX DATA ATTESTATION DEVICE API v0.2.0
=======================================
Protocol: twix-dap/0.1
Production demo: https://validator.twixchain.com

AUTHENTICATION
--------------
Device authentication is Ed25519, not a shared API password.

A device/gateway stores its private key locally. The platform stores only the
raw 32-byte Ed25519 public key encoded with base64url.

INGEST
------
POST https://validator.twixchain.com/api/ingest.php
Content-Type: application/json
Maximum request body: 64 KiB

Envelope:
{
  "record": {
    "protocol": "twix-dap/0.1",
    "device_id": "meter:facility-a:001",
    "sequence": 1,
    "schema": "energy.meter.reading/1",
    "measured_at": "2026-08-26T20:00:00Z",
    "previous_hash": null,
    "payload": {"value":"14832.771","unit":"kWh"}
  },
  "record_hash": "...",
  "signature": "..."
}

The signature is Ed25519 over the raw 32-byte record_hash.

REPLAY / ORDERING
-----------------
sequence must increase exactly by one. Record 1 has previous_hash=null.
Every later record includes the prior accepted record hash. The gateway state
file is therefore security/continuity state and should be backed up with the
private key. If state is irrecoverably lost, the preferred recovery is to revoke
the old device identity and register a new versioned device identity rather than
silently rewriting history.

PRIVACY
-------
public    = collector may publish full record/proof
hash_only = public commitment, full record retained but not publicly served
private   = record omitted from public record listings

External devices default to hash_only. The reference batcher keeps visibility
classes separate. Restricted public batch views expose the root and manifest hash
but withhold the ordered record-hash list. Encrypt sensitive payloads before
submission if the collector itself must not receive plaintext.

TEST VECTOR
-----------
Canonical JSON:
{"device_id":"meter:test:001","measured_at":"2026-08-26T20:00:00Z","payload":{"unit":"kWh","value":"14832.771"},"previous_hash":null,"protocol":"twix-dap/0.1","schema":"energy.meter.reading/1","sequence":1}

record_hash:
3770ad8a5ff06fb05403926524dae336e3d1bf122ecdb145502822ab8ce03798

METER ADAPTERS
--------------
TDAP is meter-neutral. Modbus, DLMS/COSEM, MQTT, BACnet, serial/pulse, and
vendor APIs feed a gateway adapter. Register maps, OBIS mappings, scale factors,
clock semantics, authentication and calibration must come from the actual meter
manufacturer/profile; TWIX does not guess them.

STORAGE
-------
Signed envelopes can be mirrored on ordinary web hosting, object storage, NAS,
IPFS or archival media. Integrity comes from the hash/signature/Merkle proof;
availability comes from keeping enough copies.
