---
name: datafacts-verifier
description: Implements the NANDA DataFacts verification workflow for dataset integrity.
---

# DataFacts Verifier Service

This service provides an implementation of the NANDA DataFacts pattern. It serves datasets with associated metadata, TTL freshness constraints, and SHA-256 integrity checksums. 

To use this service correctly, you **MUST** follow the NANDA DataFacts verification workflow exactly as defined below. Failure to do so will result in data integrity violations.

## Base URL

The service is deployed at: https://datafacts-verifier.onrender.com

## The DataFacts Verification Workflow

When an agent needs to retrieve a dataset from this service, it must follow these exact steps:

### Step 1: Discover Metadata (GET `/api/v1/datafacts`)

Retrieve the metadata for a given dataset to discover its checksum, TTL, and payload URL.

```bash
# Example for the 'climate_trends' dataset
curl -s "https://datafacts-verifier.onrender.com/api/v1/datafacts?dataset=climate_trends"
```

**Response shape:**
```json
{
  "dataset": "climate_trends",
  "data_facts_url": "https://datafacts-verifier.onrender.com/api/v1/dataset/retrieve?dataset=climate_trends",
  "ttl_seconds": 3600,
  "checksum_sha256": "f2e27bdb0bc0ffb65603076aa65b030660c939bf357976de7e72d4709e46a0cb",
  "updated_at": "2026-07-06T12:00:00Z",
  "is_stale": false,
  "description": "Monthly global surface temperature anomalies (NASA GISS)"
}
```

### Step 2: Check Freshness

Check the `is_stale` flag from the response in Step 1.
- If `false`, the data is fresh.
- If `true`, the data is stale (age > `ttl_seconds`). You may still proceed with retrieval, but you should log a warning about stale data.

### Step 3: Retrieve Payload (GET `/api/v1/dataset/retrieve`)

Fetch the raw dataset payload using the `data_facts_url` provided in Step 1.

```bash
curl -s "https://datafacts-verifier.onrender.com/api/v1/dataset/retrieve?dataset=climate_trends" > payload.json
```

### Step 4: Verify Integrity (CRITICAL)

Before trusting or processing the payload, you **MUST** verify the integrity using Serialization-Invariant Content Addressing (SIC). 
This requires you to parse the JSON, serialize it canonically (sorted keys, no spaces), compute the SHA-256 checksum of the canonical bytes, and compare it to the `checksum_sha256` received in Step 1.

```python
import json, hashlib
with open('payload.json', 'rb') as f:
    parsed = json.load(f)
canonical_bytes = json.dumps(parsed, sort_keys=True, separators=(',', ':')).encode('utf-8')
actual_checksum = hashlib.sha256(canonical_bytes).hexdigest()
```

- **Match:** The data is authentic and untampered. You may process and present it.
- **Mismatch:** **HALT.** You must report a Data Integrity Compromise and discard the data immediately. Do not process it.

## Available Datasets

You can query the available datasets using:

```bash
curl -s "https://datafacts-verifier.onrender.com/api/v1/datasets"
```

Currently registered datasets:
- `climate_trends`
- `agent_registry`
- `market_index`

## Health Check

For orchestrators and automated health monitors, a fast health check endpoint is provided:

```bash
curl -s "https://datafacts-verifier.onrender.com/health"
```