# TWIX Data Attestation Protocol (TDAP) v0.1

Status: Draft reference specification  
Protocol identifier: `twix-dap/0.1`  
Reference network: TWIX Mainnet (`twix-1`, EVM chain ID `1415006552`)

## 1. Purpose

TDAP binds real-world or machine-generated data to a cryptographic device
identity and then anchors batches of those commitments to TWIX Mainnet. Large
or private data remains on inexpensive external storage. TWIX stores only the
compact proof needed to establish integrity and an independent consensus time.

The protocol separates four claims:

1. **Measurement claim** — the device says a measurement occurred at
   `measured_at`.
2. **Device-authenticity claim** — a registered device key signed the exact
   canonical record.
3. **Storage-integrity claim** — the retrieved record hashes to the committed
   record hash and is included in a batch Merkle root.
4. **Blockchain-time claim** — the Merkle root and batch-manifest hash existed
   no later than the TWIX block that committed the anchor transaction.

A TWIX block timestamp does not prove that a physical sensor itself was honest.
It proves that the anchored cryptographic commitment existed by the committed
block time.

## 2. Consensus separation

TDAP MUST NOT change the consensus rules of an individual validator.

A customized TWIX validator installation SHOULD run the meter/attestation
component as an isolated sidecar process:

    electric meter
          |
          v
    twix-meter-agent
      |       |
      |       +----> inexpensive record storage
      |
      +------------> TDAP batch / Merkle root
                         |
                         v
                    TWIX transaction

The agent MUST NOT use the validator consensus private key. A dedicated EVM
account or another purpose-specific transaction signer MUST be used for anchors.

## 3. Device identity

The v0.1 reference signature algorithm is Ed25519.

A registered device consists of:

- `device_id`: stable application-defined identifier
- `public_key`: 32-byte Ed25519 public key, base64url encoded
- `label`: human-readable description
- activation state

Recommended `device_id` namespaces include:

- `meter:twix:site-001`
- `solar:facility-a:inverter-03`
- `sensor:coldchain:truck-148`

Private device keys MUST remain on the device, gateway, HSM or isolated
sidecar. They MUST NOT be published in the proof bundle.

## 4. Signed record

A signed record contains exactly these logical fields:

```json
{
  "protocol": "twix-dap/0.1",
  "device_id": "meter:twix:demo-001",
  "sequence": 1,
  "schema": "energy.meter.reading/1",
  "measured_at": "2026-08-26T18:30:00Z",
  "previous_hash": null,
  "payload": {
    "value": "14832.771",
    "unit": "kWh"
  }
}
```

`sequence` MUST increase by exactly one for each accepted record from a device.
For sequence 1, `previous_hash` MUST be null. For every later record it MUST
equal the accepted `record_hash` immediately preceding it for that device.

Measurements that require decimal precision SHOULD be represented as decimal
strings rather than JSON floating-point numbers.

## 5. Canonical JSON v0.1

The TDAP reference canonicalizer is intentionally small and deterministic:

- UTF-8 JSON
- object member names sorted lexicographically
- arrays retain their original order
- no insignificant whitespace
- strings use normal JSON escaping
- booleans and null use JSON literals
- integers are permitted
- floating-point JSON numbers are rejected
- precise measurements SHOULD use decimal strings

This removes cross-language floating-point ambiguity.

## 6. Record hash and signature

Let `C` be the UTF-8 bytes of the canonical signed record.

The record commitment is:

    record_hash =
      SHA-256(
        UTF8("TWIX-DAP-RECORD-v0.1") ||
        0x00 ||
        C
      )

`record_hash` is represented externally as 64 lowercase hexadecimal
characters.

The Ed25519 signature is produced over the raw 32 bytes of `record_hash`.

The collector verifies:

- device exists and is active
- sequence is exactly the next sequence
- previous hash is correct
- recomputed canonical hash equals the supplied record hash
- Ed25519 signature verifies against the registered device public key

The collector then adds `received_at`. `received_at` is not part of the device
signature and MUST NOT be confused with the device's `measured_at`.

## 7. Storage

A complete signed envelope SHOULD be retained outside the blockchain:

```json
{
  "record": { "...": "..." },
  "record_hash": "64 lowercase hex characters",
  "signature": "base64url Ed25519 signature",
  "received_at": "2026-08-26T18:30:05Z"
}
```

This file can be stored on ordinary web hosting, object storage, a NAS, IPFS,
archival media, or multiple mirrors.

The storage operator is not trusted for integrity. Any modification changes the
record hash or invalidates the device signature/Merkle proof.

Sensitive payloads MAY be encrypted before being placed in `payload`. TDAP
does not require plaintext data to be public.

## 8. Merkle batching

TDAP v0.1 uses SHA-256 with explicit domain separation.

For a record hash `H` (32 raw bytes):

    leaf = SHA-256(0x00 || H)

For two child nodes `L` and `R`:

    parent = SHA-256(0x01 || L || R)

Records are ordered by collector acceptance order. When a level contains an
odd number of nodes, the last node is duplicated before hashing the final pair.
For a one-record batch, the root is the domain-separated leaf.

A Merkle proof is an ordered list from leaf to root:

```json
[
  {"side":"right","hash":"..."},
  {"side":"left","hash":"..."}
]
```

## 9. Batch manifest

A batch manifest includes:

- protocol
- manifest type
- TWIX chain identifiers
- Merkle algorithm identifier
- Merkle root
- record count
- ordered record-hash list
- first/last measurement times
- manifest URI
- creation time

The manifest commitment is:

    manifest_hash =
      SHA-256(
        UTF8("TWIX-DAP-MANIFEST-v0.1") ||
        0x00 ||
        canonical_manifest
      )

Both `merkle_root` and `manifest_hash` are anchored.

## 10. TWIX on-chain anchor

The v0.1 reference Solidity function is:

```solidity
anchor(
    bytes32 merkleRoot,
    bytes32 manifestHash,
    uint64 recordCount,
    uint64 periodStart,
    uint64 periodEnd
)
```

The reference contract refuses duplicate roots, accepts no funds, has no owner,
has no upgrade mechanism, and rejects deployment on a chain other than EVM
chain ID `1415006552`.

The reference selector for the function above is:

    0x39b55dfe

The anchor transaction MUST be signed by a purpose-specific account, not a
validator consensus key.

## 11. Timestamp semantics

TDAP exposes three useful times:

- `measured_at` — device-originated claim
- `received_at` — collector receipt time
- `anchor_block_time` — TWIX consensus block timestamp

The strongest externally verifiable statement is:

> The exact record represented by this proof was cryptographically committed
> into the anchored batch no later than the TWIX anchor block time.

Applications MAY enforce maximum clock drift between measurement and receipt or
between receipt and anchoring.

## 12. Independent verification

A verifier SHOULD:

1. canonicalize `record`
2. recompute `record_hash`
3. verify the device signature
4. compute the leaf
5. fold the supplied Merkle proof to the root
6. compare the computed root with the batch manifest
7. recompute `manifest_hash`
8. retrieve the TWIX anchor transaction
9. confirm the transaction destination is the expected anchor contract
10. decode the calldata and confirm root, manifest hash, count and period
11. confirm transaction success
12. obtain the anchor block timestamp

The cheap-storage copy can disappear without invalidating the on-chain anchor,
but a verifier obviously needs a surviving copy of the record/proof to inspect
it. Important data SHOULD therefore be mirrored.

## 13. Threat model

TDAP detects or limits:

- post-anchor modification of stored records
- forged records without the device private key
- record deletion/reordering inside a proven batch
- device sequence rollback or omission detectable through previous-hash chains
- storage-provider tampering
- false claims that a commitment was anchored earlier than its TWIX block

TDAP alone does not prove:

- sensor calibration
- truth of the physical measurement
- correctness of a compromised device
- trustworthy device wall-clock time
- availability of an off-chain storage provider

Hardware secure elements, meter manufacturer signatures, calibration records,
redundant sensors and independent storage mirrors can strengthen those layers.

## 14. Privacy

Only commitments need to be on-chain. Implementations SHOULD avoid putting
customer names, addresses, meter serials, account identifiers or raw sensitive
telemetry directly into public blockchain calldata.

## 15. Future work

Planned-compatible extensions include:

- secp256k1/EIP-191 device identities
- hardware-backed device certificates
- Modbus, DLMS/COSEM, MQTT and vendor meter adapters
- encrypted payload profiles
- multi-storage manifests
- anchor delegation policies
- batch supersession/correction semantics
- independent verifier libraries
- Cosmos-native anchoring in addition to EVM anchoring
