# Stability Proof Index - Complete Documentation

> Timestamped, verifiable proofs of content creation on the Stability blockchain. Provides bulk JSONL exports, REST-style API, real-time feeds, and comprehensive machine-readable metadata. All data is CC0-1.0 (public domain). Built for AI teams, researchers, and content verification systems.

## Overview

The Stability Proof Index is a blockchain-anchored proof system that provides cryptographic evidence of when content was created. Each proof consists of:

1. **Content Hash** (SHA-256) - The unique identifier of the content
2. **Transaction Hash** - The blockchain transaction that anchored the proof
3. **Timestamp** - When the proof was created (block timestamp)
4. **Creator** - Ethereum address of the creator
5. **Metadata** - Optional descriptive information

**Why this matters:**
- Proves content existed at a specific time without revealing the content itself
- Provides immutable, verifiable timestamps
- Enables training data provenance tracking
- Allows deduplication across datasets
- No gas fees (Stability blockchain is feeless)

**Current Status:**
- Dataset: 2 proofs indexed
- Network: Stability Global Test Network (GTN)
- Update Frequency: Daily (midnight UTC)
- License: CC0-1.0 (Public Domain)

## Quick Integration Examples

### Python - Download & Parse Dataset

```python
import gzip
import json
import requests

# Download latest export
url = "https://www.ouroborus.io/data/proofs-2025-10-28.jsonl.gz"
response = requests.get(url)

with open("proofs.jsonl.gz", "wb") as f:
    f.write(response.content)

# Parse JSONL
with gzip.open("proofs.jsonl.gz", "rt") as f:
    for line in f:
        proof = json.loads(line)
        print(f"{proof['sha256_hex']}: {proof['timestamp']}")
```

### Python - Lookup Single Hash

```python
import requests

hash = "0x4dc89b6485c0db11e8389cc67a9e36966d33b0b3472fc3587dea819dd16ee2d9"
url = f"https://www.ouroborus.io/api/v1/resolve/{hash}.json"

response = requests.get(url)
proof = response.json()

if proof["found"]:
    print(f"Created: {proof['proof']['timestamp']}")
    print(f"TX: {proof['proof']['tx_hash']}")
```

### Bash - Verify Checksum

```bash
# Download dataset and checksum
curl -O https://www.ouroborus.io/data/proofs-2025-10-28.jsonl.gz
curl -O https://www.ouroborus.io/data/proofs-2025-10-28.jsonl.gz.sha256

# Verify integrity
sha256sum -c proofs-2025-10-28.jsonl.gz.sha256
```

### Bash - Monitor for New Proofs

```bash
# Poll feed every 5 minutes
while true; do
  curl -s https://www.ouroborus.io/feed.xml | \
    grep "<title>Proof:" | head -1
  sleep 300
done
```

## Complete API Reference

### GET /api/v1/index.json

Returns overview of all available endpoints.

**Response:**
```json
{
  "name": "Stability Proof Index API",
  "version": "1.0",
  "base_url": "https://www.ouroborus.io/api/v1",
  "endpoints": [...]
}
```

### GET /api/v1/resolve/{hash}.json

Look up a specific content hash.

**Parameters:**
- `hash` (required): SHA-256 hash with 0x prefix

**Response:**
```json
{
  "status": "ok",
  "found": true,
  "proof": {
    "sha256_hex": "0x4dc89b...",
    "ni_uri": "ni:///sha-256;TcibZIXA...",
    "creator_address": "0x6351c3...",
    "timestamp": "2025-10-28T16:36:04.000Z",
    "tx_hash": "0x5cb0b909...",
    "blockchain": "stability",
    "network": "testnet",
    "explorer_url": "https://stability.blockscout.com/tx/0x5cb0b...",
    "permalink": "https://www.ouroborus.io/proof/4dc89b.../",
    "metadata": "Created by : Juliun, Type: Text"
  }
}
```

### GET /api/v1/manifest/latest.json

Get information about the latest dataset export.

**Response:**
```json
{
  "status": "ok",
  "latest_export": {
    "date": "2025-10-28",
    "url": "https://www.ouroborus.io/data/proofs-2025-10-28.jsonl.gz",
    "manifest_url": "https://www.ouroborus.io/data/manifest.json",
    "proof_count": 2
  }
}
```

### GET /api/v1/stats.json

Get dataset statistics.

**Response:**
```json
{
  "status": "ok",
  "stats": {
    "total_proofs": 2,
    "unique_creators": 1,
    "earliest_proof": "2025-10-28T01:24:06.000Z",
    "latest_proof": "2025-10-28T16:36:04.000Z"
  }
}
```

## Complete JSONL Schema

Each line in the JSONL export is a JSON object with these fields:

```json
{
  "sha256_hex": "string (required)",
  "ni_uri": "string (required)",
  "creator_did": "string (currently empty)",
  "creator_address": "string (required)",
  "timestamp": "string ISO 8601 (required)",
  "tx_hash": "string (required)",
  "permalink": "string URL (required)",
  "title": "string (optional)",
  "description": "string (optional)",
  "metadata": "string (optional)",
  "blockchain": "string (always 'stability')",
  "network": "string (currently 'testnet')",
  "explorer_url": "string URL (required)"
}
```

**Field Descriptions:**

- `sha256_hex`: Content hash in hexadecimal with 0x prefix. Primary identifier.
- `ni_uri`: Named Information URI per RFC 6920. Location-independent identifier.
- `creator_did`: Decentralized Identifier (reserved for future use, currently empty)
- `creator_address`: Ethereum address of the creator (0x...)
- `timestamp`: When the proof was created, in ISO 8601 format
- `tx_hash`: Blockchain transaction hash (0x...)
- `permalink`: Permanent URL to the human-readable proof page
- `title`: Short title or metadata from the transaction
- `description`: Longer description (currently mirrors title)
- `metadata`: Raw metadata string from the blockchain transaction
- `blockchain`: Always "stability"
- `network`: "testnet" or "mainnet"
- `explorer_url`: Link to blockchain explorer for verification

## Web Standards Implemented

### JSON-LD (Schema.org)

Every proof page includes structured data:

```json
{
  "@context": "https://schema.org",
  "@type": "DigitalDocument",
  "@id": "https://www.ouroborus.io/proof/{hash}/",
  "name": "Blockchain Proof of Creation: 0x{hash}",
  "identifier": [
    {"@type": "PropertyValue", "propertyID": "content-hash", "value": "0x..."},
    {"@type": "PropertyValue", "propertyID": "ni-uri", "value": "ni:///..."},
    {"@type": "PropertyValue", "propertyID": "transaction-hash", "value": "0x..."}
  ],
  "dateCreated": "2025-10-28T16:36:04.000Z",
  "creator": {"@type": "Person", "identifier": "0x6351c3..."}
}
```

### Linkset (RFC 9264)

Resource relationships in machine-readable format:

```json
{
  "linkset": [{
    "anchor": "https://www.ouroborus.io/proof/{hash}/",
    "item": [
      {
        "href": "https://stability.blockscout.com/tx/{tx}",
        "type": "text/html",
        "rel": "canonical"
      },
      {
        "href": "ni:///sha-256;{base64}",
        "type": "application/octet-stream",
        "rel": "alternate"
      }
    ]
  }]
}
```

### ni: URIs (RFC 6920)

Hash-based permanent identifiers that work even if the domain changes:

```
ni:///sha-256;TcibZIXA2xHoOJzGep42lm0zsLNHL8NYfeqBndFu4tk
```

Can be used for:
- Content-addressable storage
- Distributed systems
- Deduplication
- Verification without relying on DNS

### Sitemaps (Protocol)

Automatic rolling sitemaps that scale to millions of proofs:
- Up to 50,000 URLs per sitemap file
- Automatic sitemap_index.xml generation when needed
- Daily updates

### IndexNow (API)

Push notifications to search engines:
- Bing
- Yahoo
- Yandex

### WebSub (PubSubHubbub)

Real-time feed updates via hub: `https://pubsubhubbub.appspot.com/`

## Verification Process

Every proof can be independently verified:

1. **Get proof data from API:**
   ```bash
   curl https://www.ouroborus.io/api/v1/resolve/{hash}.json
   ```

2. **Visit blockchain explorer:**
   ```
   https://stability.blockscout.com/tx/{tx_hash}
   ```

3. **Verify:**
   - Transaction exists on blockchain ✓
   - Timestamp matches block time ✓
   - Content hash is in transaction input data ✓
   - Creator address matches ✓

## Dataset Manifest Format

The `/data/manifest.json` file provides complete metadata:

```json
{
  "dataset_name": "stability-proofs",
  "version": "2025-10-28",
  "description": "Daily snapshot of on-chain proofs",
  "homepage": "https://www.ouroborus.io",
  "files": [
    {
      "path": "proofs-2025-10-28.jsonl.gz",
      "url": "https://www.ouroborus.io/data/proofs-2025-10-28.jsonl.gz",
      "sha256": "e601ba136668f7fb73c0bb81751aff1d511971c2ece94efbbb4281ce18d02099",
      "rows": 2,
      "format": "jsonl",
      "compression": "gzip"
    }
  ],
  "license": "CC0-1.0",
  "contact": "data@ouroborus.io",
  "proof_count": 2,
  "schema": { /* complete field definitions */ }
}
```

## Use Cases in Detail

### 1. Training Data Provenance

**Problem:** Need to prove when training data was collected.

**Solution:**
```python
# Hash your training dataset
import hashlib
with open("training_data.json", "rb") as f:
    content_hash = hashlib.sha256(f.read()).hexdigest()

# Check if it's already proven
response = requests.get(f"https://www.ouroborus.io/api/v1/resolve/0x{content_hash}.json")
if response.json()["found"]:
    print("Dataset was first seen:", response.json()["proof"]["timestamp"])
```

### 2. Content Deduplication

**Problem:** Avoid processing duplicate content.

**Solution:**
```python
def is_duplicate(content_bytes):
    hash = "0x" + hashlib.sha256(content_bytes).hexdigest()
    response = requests.get(f"https://www.ouroborus.io/api/v1/resolve/{hash}.json")
    return response.json().get("found", False)
```

### 3. Blockchain Timestamping Service

**Problem:** Need tamper-proof timestamps.

**Solution:** Every proof includes an immutable blockchain timestamp that can be independently verified on-chain.

### 4. Dataset Attribution

**Problem:** Track who created what content and when.

**Solution:** Each proof includes creator address and can be linked to identity systems (DIDs in future).

## Enterprise Features (Contact Required)

- **Bulk Mirrors:** Direct S3/GCS bucket access
- **Pre-computed Embeddings:** CLIP, text embeddings for semantic search
- **Webhooks:** Real-time notifications on new proofs
- **Custom Exports:** Parquet, CSV, or custom formats
- **Private Deployments:** Self-hosted instances
- **SLA Guarantees:** Uptime and support agreements

**Contact:** data@ouroborus.io

## Development Roadmap

### Coming Soon
- Embeddings export (CLIP vectors)
- Hugging Face Dataset integration
- Webhook subscription API
- Historical snapshots
- Mainnet deployment

### Future Considerations
- DID (Decentralized Identifier) integration
- C2PA manifest support
- Perceptual hashing for images
- Content-addressable mirrors
- IPFS pinning

## Technical Architecture

**Storage:** SQLite database → Static JSON files on Vercel CDN

**Update Process:**
1. New proof added via `add-proof.js`
2. Static files generated with `generate-static-enhanced.js`
3. Deployed to Vercel (global CDN)
4. Search engines notified via IndexNow + WebSub

**Why Static:**
- Zero server costs
- Instant global distribution
- No runtime dependencies
- Maximum reliability

## License & Legal

**Dataset License:** CC0-1.0 (Public Domain)

You can:
- Use commercially without restriction
- Modify and redistribute
- Train ML models
- No attribution required (but appreciated)

**Data Accuracy:** All proofs are verifiable on-chain. We make no warranties but provide tools for independent verification.

**Privacy:** Only public blockchain data is indexed (addresses, hashes, timestamps). No PII is collected or stored.

## Links & Resources

### Core Documentation
- [Homepage](https://www.ouroborus.io)
- [Dataset Manifest](https://www.ouroborus.io/data/manifest.json)
- [OpenAPI Spec](https://www.ouroborus.io/openapi.json)
- [Dataset Docs](https://www.ouroborus.io/.well-known/dataset.json)

### Data Access
- [Latest JSONL Export](https://www.ouroborus.io/data/proofs-2025-10-28.jsonl.gz)
- [API Index](https://www.ouroborus.io/api/v1/index.json)
- [Statistics](https://www.ouroborus.io/api/v1/stats.json)

### Real-time
- [Atom Feed](https://www.ouroborus.io/feed.xml)
- [Sitemap](https://www.ouroborus.io/sitemap.xml)

### Examples
- [Example Proof 1](https://www.ouroborus.io/proof/4dc89b6485c0db11e8389cc67a9e36966d33b0b3472fc3587dea819dd16ee2d9/)
- [Example Proof 2](https://www.ouroborus.io/proof/7f83b1657ff1fc53b92dc18148a1d65dfc2d4b1fa3d677284addd200126d9069/)
- [Example Linkset](https://www.ouroborus.io/proof/4dc89b6485c0db11e8389cc67a9e36966d33b0b3472fc3587dea819dd16ee2d9/linkset.json)

### Blockchain
- [Stability Blockscout](https://stability.blockscout.com)
- [Example Transaction](https://stability.blockscout.com/tx/0x5cb0b909b6ef95a4d04bba62ec5e6acd605c793e1a3aa2ba002d482cd4fb6ddb)

---

**Last Updated:** 2025-10-28
**Contact:** data@ouroborus.io
**Support:** For questions, bugs, or feature requests