# DAG-TAT Attestation Chain: Canonicalization and Verification Specification, v1

Status: normative for every block whose `schema` is `dag-tat-v1` and every head, anchor and
export record named below. Published 2026-09-04 by AgWaterAI Inc. Version 1 describes the
chains as they exist; any change to a rule in sections 2 to 7 requires a new `domain_separator`,
a new `schema` value and a new version of this document. The reference implementation of this
specification is `verify_dag_tat.py`, published beside it. The algorithms can be applied independently to an authorized artifact set.
Remote tenant envelopes require a farm-authorized session.

Where this document is published:

| Copy | Location |
|---|---|
| Open URL (specification) | `https://agwaterai.com/verify/dag-tat-canonicalization-v1.md` |
| Open URL (reference verifier) | `https://agwaterai.com/verify/verify_dag_tat.py` |
| Manifest link | `specification` and `reference_verifier` in `https://agwaterai.com/api/v1/verify/{farm}` |
| Anchor bucket, beside the public keys | `spec/dag-tat-canonicalization-v1.md` and `spec/verify_dag_tat.py` in each tenant's anchor bucket, next to `keys/v1.pem` (write-once, under the bucket's locked retention; bucket names are given to authorised parties with the artifact set) |
| Source repository | `cloud/dag-tat-sealer/spec/` in the AgWaterAI backend repository |

This public copy is privacy-redacted. Historical write-once bucket copies are unchanged;
the manifest lists the public document digest separately from the historical copy.

## 1. Scope and what a verifier can and cannot conclude

A chain is a sequence of signed blocks, one chain per tenant (identified only in authorized artifacts). Each block
commits to its content (`event_data`) and to the previous block. A verifier can establish:

1. that each block was signed by the holder of the tenant's private key (section 5);
2. that no block was altered, reordered, inserted or removed after signing (section 4);
3. given the sealed content, that the content matches the commitment (section 6);
4. given a time anchor, that every block up to the anchored number existed by the anchor time (section 7).

A verifier cannot establish, from these artifacts, that the underlying field measurement was
correct or that every reading taken in the field was sealed. The chain proves order and
integrity of what was sealed. Block-level coverage statements (`site_count_live`,
`site_count_stale`, `row_count`, `coverage`) are honest self-reports of the sealer and are
inside the signed content, so they cannot be altered after the fact; they are not independent
evidence that the sealer saw everything.

Two verification surfaces exist:

| Surface | Serves | Proves |
|---|---|---|
| Authenticated envelope API: `https://agwaterai.com/api/v1/verify/{farm}` | the block envelope (section 4.2) without `event_data`, the public keys, the head, the anchors | signature, linkage, contiguity, tenant isolation, head agreement, time anchor |
| Artifact set (bucket objects, an export bundle, or a disclosed copy) | full blocks including `event_data` | everything above plus recomputation of `payload_hash`, Merkle roots, DAG node hashes and diamonds |

The envelope surface deliberately withholds `event_data` because it names a customer's sites and
volumes. `payload_hash` therefore cannot be recomputed from the envelope surface; the reference
verifier reports `payload_hash_recomputable_publicly: 0` rather than pretending otherwise.

## 2. Canonical JSON

Every hash in this system is computed over the canonical JSON form of a JSON object:

- object keys sorted lexicographically by Unicode code point, recursively;
- no whitespace: item separator `,`, key separator `:`;
- non-ASCII characters escaped as `\uXXXX` (ASCII output only);
- numbers as their shortest JSON form (integers without a decimal point; `1.0` stays `1.0`);
- booleans `true` / `false`, null `null`;
- the UTF-8 encoding of the resulting string is what is hashed.

This is exactly Python's `json.dumps(obj, sort_keys=True, separators=(",", ":"), ensure_ascii=True)`.
Array order is significant and is never changed by canonicalization; the sealer sorts arrays
where the specification says so (sections 6.1 and 6.2), and a verifier checks that order.

## 3. Hash

`H(x)` is SHA-256 over the UTF-8 bytes of the string `x`, written as 64 lowercase hex characters.
When two hex digests are combined (section 6.1) their hex STRINGS are concatenated and the
concatenation is hashed as text: `H(a_hex + b_hex)`, 128 characters in, not 64 raw bytes.

## 4. Block layout

### 4.1 Payload: the nine fields that enter the hash

```
payload = {
  "domain_separator": <exact version label from the authorized sealed block>,
  "block_number":     <integer, 0 for genesis, +1 per block>,
  "event_type":       <"genesis" | "irrimax_batch" | "mqtt_batch" | ...>,
  "event_data":       <object, the sealed content, section 6>,
  "sealed_at":        <ISO 8601 UTC with microseconds and "+00:00", the sealer's own clock>,
  "prev_hash":        <payload_hash of block N-1; 64 zeros for block 0>,
  "tenant_id":        <exact tenant identifier from the authorized sealed block>,
  "key_epoch":        <integer, 1>,
  "key_version":      <Cloud KMS key version resource name, section 5>
}
payload_hash = H(canonical_json(payload))
```

Exactly these nine keys, no others. Copy `domain_separator` byte-for-byte from the
sealed payload; never substitute a tenant identifier or a synthetic example. It is a
version label, not the tenant separator. Tenant isolation uses `tenant_id` and its key.

### 4.2 Envelope: the stored block

The stored block object is the payload plus four fields that do not enter the hash:

| Field | Value |
|---|---|
| `payload_hash` | as computed in 4.1 |
| `signature_alg` | `EC_SIGN_P256_SHA256` |
| `signature` | section 5 |
| `schema` | `dag-tat-v1` |

Blocks are stored write-once at `blocks/<block_number as 10 digits, zero padded>.json`.
`genesis.json` is a byte-identical copy of `blocks/0000000000.json`.

### 4.3 Head

`head.json` is overwritten on every append and holds exactly:

```
{"block_number": N, "payload_hash": ..., "sealed_at": ..., "event_type": ..., "tenant_id": ..., "schema": "dag-tat-head-v1"}
```

The public head endpoint serves the same six fields. The head is what a time anchor digests
(section 7), so its field set is part of this specification.

### 4.4 Chain rules

- `prev_hash` of block N equals `payload_hash` of block N-1 for every N >= 1; block 0 has
  `prev_hash` of 64 ASCII zeros.
- Block numbers are contiguous from 0 to the head. A missing number is a withheld block.
- Every block on a chain carries the same `tenant_id`.
- Two consecutive blocks further apart in `sealed_at` than the sealing cadence (daily for
  `irrimax_batch`, ten minutes for `mqtt_batch`) are a sealing gap. Gaps are visible from the
  public envelope alone and are not hidden by the chain.

## 5. Signature and key format

- Algorithm: ECDSA on curve P-256 (secp256r1) with SHA-256, Cloud KMS name `EC_SIGN_P256_SHA256`.
- Message: the signature is over the 32 raw bytes of `payload_hash` (hex decoded), as a
  pre-hashed digest. It is NOT over the JSON text, and it is not a JWS, JWT or COSE structure.
- Encoding: the DER-encoded ECDSA signature (`SEQUENCE { r INTEGER, s INTEGER }`), then
  base64url (RFC 4648 section 5) with the `=` padding removed.
- Key: one P-256 key per tenant, generated and held in Google Cloud KMS at
  `projects/agwater-ai/locations/us-central1/keyRings/tat-{tenant}/cryptoKeys/attestation-signer`;
  `key_version` names its version. The private key is non-exportable. Its protection level is
  `SOFTWARE` (Google's software key store inside Cloud KMS, not a hardware security module);
  export bundles state this level as read from KMS at generation time.
- Public key: SubjectPublicKeyInfo PEM (`-----BEGIN PUBLIC KEY-----`), served at
  `keys/v{epoch}.pem` in the anchor bucket and at
  `https://agwaterai.com/api/v1/verify/{farm}/keys/v{epoch}`. `key_epoch` selects the file;
  both chains are at epoch 1 and no rotation has occurred.

Verification in Python with the `cryptography` package:

```python
pub.verify(b64url_decode(block["signature"]), bytes.fromhex(block["payload_hash"]),
           ec.ECDSA(Prehashed(hashes.SHA256())))
```

## 6. Sealed content (`event_data`) and what is recomputable

`event_data` is an object whose keys depend on `event_type`. Genesis blocks carry a migration
statement and no leaves. Batch blocks (`irrimax_batch`, `mqtt_batch`) carry, among plain
descriptive fields (`schema_version`, `source_system`, `source_record_locator`,
`reporting_window_start`, `reporting_window_end`, coverage counts):

| Key | Meaning |
|---|---|
| `leaves` | array of leaf objects, one per site or meter, each with `leaf_hash` and clear-text identifiers and summary fields |
| `leaf_count` | `len(leaves)` |
| `merkle_root` | section 6.1 |
| `dag_nodes` | every node of every diamond, section 6.2 |
| `dag_diamonds` | one diamond record per leaf, section 6.3 |
| `dag_node_count`, `dag_diamond_count`, `dag_acyclic`, `dag_kahn_topological_sort` | counts and a topological order of `dag_nodes` |

### 6.1 Leaves and Merkle root

`leaves` is sorted ascending by `leaf_hash` (byte order of the hex string) before the root is
built. The root is a binary Merkle tree over the ordered `leaf_hash` values:

```
level = [leaf_hash_1, ..., leaf_hash_n]        # sorted
while len(level) > 1:
    pair up (level[i], level[i+1]); if the level has odd length, pair the last with itself
    next_level.append(H(a_hex + b_hex))         # hex strings concatenated, section 3
merkle_root = level[0]                          # H("") for an empty leaf list
```

### 6.2 DAG node hash

Each leaf is the convergence node of a four-node diamond built for one data point
(`datapoint_id`, for example `<tenant_id>/<site_id>@<fetched_at>`). Every node is stored with
`node_type`, `datapoint_id`, `body`, `parent_token_hashes`, `sealed_at` and `hash`, where

```
hash = H(canonical_json({
  "datapoint_id": datapoint_id,
  "node_type": node_type,
  "parent_token_hashes": sorted(parent_token_hashes),
  "body": body,
  "sealed_at": sealed_at            # the diamond's build time, identical on its four nodes
}))
```

Node bodies:

| `node_type` | parents | `body` |
|---|---|---|
| `sensor_read` | none | `{"data_hash": H(canonical_json(raw_data))}` |
| `validator` | `sensor_read` | `{"check": "integrity", "ref_hash": data_hash, "signals": quality_signals, "passed": bool}` |
| `quality` | `sensor_read` | `{"quality_hash": H(canonical_json(quality_signals)), "score": float}` |
| `attestation` | `validator`, `quality` | `{"converged": true, "attested": bool, "validator_ref": validator.hash, "quality_ref": quality.hash}` |

`leaf_hash` equals the `attestation` node's `hash`. `raw_data` itself (the per-site reading
summary; source-file-aware batch schemas include the SHA-256
of the complete 24 hour source file and its row count) is not stored in the block; a party
holding `raw_data` recomputes `data_hash` and so binds a source file to a leaf.

Nodes sealed before 2026-07-27 were stored without `sealed_at` although it was in the preimage.
Their hashes are committed by the block and cannot be recomputed from the stored node; the
reference verifier counts them as `dag_node_hash_not_recomputable_no_sealed_at`, never as
passed. Every node from that date on carries `sealed_at` and recomputes.

### 6.3 Diamond record

```
{"ancestor_hash": sensor_read.hash,
 "left_path":  [sensor_read.hash, validator.hash],
 "right_path": [sensor_read.hash, quality.hash],
 "convergence_hash": attestation.hash,
 "consistent": true, "attested": bool}
```

A diamond is valid when both paths start at the same ancestor, end at two different nodes whose
only parent is that ancestor, and the convergence node's parents are exactly those two nodes.
The set of `leaf_hash` values equals the set of `convergence_hash` values.

## 7. Time anchor format

`sealed_at` is the sealing job's own clock, covered by the signature but attested by nobody.
A time anchor binds the chain head to a witness the key holder does not control.

Records are write-once objects under the anchor bucket, listed after authentication at
`https://agwaterai.com/api/v1/verify/{farm}/anchors` and served at `.../anchor/{n}`:

| Object | Meaning |
|---|---|
| `anchors/ots/<n:010d>.json` | OpenTimestamps proof, `status: pending` (calendar attestation) |
| `anchors/ots/<n:010d>.upgraded.json` | the same proof completed with a Bitcoin block-header attestation |
| `anchors/rfc3161/<n:010d>.json` | RFC 3161 TimeStampToken, used only when fewer than two calendars answered |

Record fields (`schema: dag-tat-time-anchor-v1`):

```
tenant_id, anchored_object ("head.json"), anchored_head (the head, section 4.3),
anchored_bytes_sha256 = H(canonical_json(anchored_head)),
anchored_block_number, anchored_payload_hash, anchor_method ("opentimestamps" | "rfc3161"),
submitted_at, plain_words, and the proof:
  opentimestamps: calendars, ots_proof_b64 (serialized .ots, base64), status, attestations
  rfc3161:        tsa_url, tsa_certificate_pem, tsa_ca_pem, nonce, tst_der_b64, tsa_time, status
```

Verification of an anchor:

1. `anchored_bytes_sha256 == H(canonical_json(anchored_head))`, and `anchored_head.block_number`,
   `anchored_head.payload_hash` equal `anchored_block_number`, `anchored_payload_hash`.
2. `anchored_payload_hash` equals `payload_hash` of block `anchored_block_number` in your walk.
3. The proof commits to `anchored_bytes_sha256`:
   - OpenTimestamps: the `.ots` file digest is that value (the proof's first operation appends a
     random 16 byte nonce and hashes, so calendars never saw the bare digest); a completed proof
     ends in a Bitcoin block-header attestation whose message, byte-reversed, is that block's
     Merkle root. Check it against any Bitcoin block-header source. A `pending` proof is the
     calendar's promise, not yet a Bitcoin fact; report it as pending.
   - RFC 3161: verify the TimeStampToken over the digest and nonce with the TSA certificate
     stored in the record; `tsa_time` is the attested time.

Because every block commits to its predecessor, one valid anchor at block n bounds the creation
time of blocks 0 to n. The intended cadence is one anchor per tenant per day; a listing with
`count: 0` means no anchor has been recorded and step 8 below cannot be completed for that tenant.

## 8. Verification procedure

The eight steps published in the manifest, restated with this document's rule references:

1. Download `keys/v{epoch}.pem` for every `key_epoch` seen (section 5).
2. Fetch blocks 0 to head in order (section 4.2).
3. Verify each block's signature over `payload_hash` (section 5). With `event_data` in hand,
   also recompute `payload_hash` (section 4.1) and the content (section 6).
4. `prev_hash[N] == payload_hash[N-1]` for N >= 1; `prev_hash[0]` is 64 zeros (section 4.4).
5. Block numbers contiguous from 0 to head (section 4.4).
6. One `tenant_id` throughout (section 4.4).
7. The chain is authentic iff every check passed for every block; `head.json` names the highest
   block's number, `payload_hash`, `sealed_at`, `event_type` and `tenant_id` (section 4.3).
8. Fetch the newest anchor and verify it (section 7).

`verify_dag_tat.py --public {farm}` performs steps 1, 2, 4 to 8 and the signature half of 3 from
the authenticated endpoints; `verify_dag_tat.py --dir DIR --tenant {farm}` performs all eight against
an artifact set. Set `AGWATER_VERIFY_TOKEN` to a farm-authorized Bearer credential
for remote mode; never put the token in a URL. The API allows 120 requests per client address per 15 minutes; a block
is one request.

## 9. Worked examples

Tenant-linked signed examples are available only in authorized artifact sets. This
public specification deliberately contains no real tenant, signature, key or chain URL.
Do not rewrite identifiers in a signed example: that invalidates its content hash.

## 10. Stated limits of version 1

- Source measurements are not disclosed on the envelope surface. Sources include an
  authenticated vendor API and latest-state files that are overwritten; past leaves
  cannot always be re-derived from the source today. The chain proves the sealer's
  commitment, not the reading.
- Identity is a vendor-asserted name string (an IrriMAX logger name or an MQTT topic). No well,
  parcel, device key or coordinate is bound cryptographically.
- One key epoch per tenant, no rotation exercised, no revocation list. A compromised key would
  require a new epoch and a new genesis statement; that procedure is not yet published.
- `domain_separator` does not separate tenants (section 4.1).
- No beta export bundle was ever delivered outside the company; no erratum is required for them.
  Export bundles generated from the 2026-07-28 build onward state the key protection level as
  read from KMS.
