Receipts & Proofs Guide

Understand cryptographic verification and integrity checking in NOBLEID.

Receipt Structure

Every work version gets a cryptographic receipt for verification

{
  "ark": "ark:/nobleid/20092025/7X9K2Q",
  "version": 1,
  "receipt_id": "rcpt_2025_01_15_abc123",
  "timestamp": "2025-01-15T10:30:00Z",
  "content_hash": "sha256:a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3",
  "metadata_hash": "sha256:b775a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae4",
  "signature": {
    "algorithm": "Ed25519",
    "public_key": "302a300506032b657003210033d4aa063f7a2c8b4e3d...",
    "signature": "5d41402abc4b2a76b9719d911017c592..."
  },
  "fixity_status": "verified",
  "chain_proof": {
    "block_height": 12345,
    "merkle_root": "c775a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae5",
    "inclusion_proof": ["hash1", "hash2", "hash3"]
  }
}

Key Fields

• content_hash - SHA-256 of the actual content file
• metadata_hash - SHA-256 of the structured metadata
• signature - Ed25519 signature over the receipt
• fixity_status - Current integrity verification status
• chain_proof - Merkle tree inclusion proof

Signature Verification

Verify receipt authenticity and content integrity

# Verify receipt signature
curl -X POST https://api.nobleid.org/v1/receipts/verify \
  -H "Content-Type: application/json" \
  -d '{
    "receipt_id": "rcpt_2025_01_15_abc123",
    "content_hash": "sha256:a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3"
  }'

# Response:
{
  "valid": true,
  "verified_at": "2025-01-15T11:00:00Z",
  "signature_valid": true,
  "content_match": true,
  "chain_verified": true
}

Verification Process

Fetch current content from content_url
Calculate SHA-256 hash of fetched content
Compare with content_hash in receipt
Verify Ed25519 signature using NOBLEID public key
Check Merkle tree inclusion proof

Fixity Status Meanings

Understanding what each status means for content integrity

verified

Content hash matches, signature valid, chain verified

Content is authentic and unmodified

pending

Recently submitted, verification in progress

Check again in a few minutes

failed

Content hash mismatch or signature invalid

Content may have been modified or corrupted

unreachable

Cannot fetch content for verification

Content URL may be temporarily unavailable

Detailed Proofs

Access comprehensive verification data and provenance chains

# Get detailed proofs
curl https://api.nobleid.org/v1/proofs/ark:/nobleid/20092025/7X9K2Q/v1

# Response includes:
{
  "content_proofs": {
    "sha256": "a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3",
    "sha512": "b775a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae4",
    "fixity_checks": [
      {
        "timestamp": "2025-01-15T10:30:00Z",
        "status": "verified",
        "method": "remote_fetch"
      }
    ]
  },
  "provenance_chain": [...],
  "signatures": [...]
}

Proof Types

• Content Proofs - Multiple hash algorithms, fixity check history
• Provenance Chain - Complete version history with timestamps
• Signatures - All cryptographic signatures and public keys
• Merkle Proofs - Blockchain inclusion proofs

Best Practices

How to implement robust verification in your applications

Implementation Guidelines

✓ Always verify receipts before trusting content
✓ Cache verification results with appropriate TTL
✓ Handle network failures gracefully
✓ Display verification status to users
✓ Log verification attempts for audit trails
✓ Use HTTPS for all verification API calls
✓ Implement retry logic with exponential backoff

Security Considerations

• Never trust content without verifying its receipt
• Store NOBLEID public keys securely
• Validate certificate chains for HTTPS connections
• Use constant-time comparison for hash verification