Skip to main content

Proof Generator

The ProofGenerator module creates cryptographic proofs for delivered content.

Overview​

ProofGenerator provides:

  • Content hashing (Keccak256)
  • Delivery proof generation (AIP-4)
  • URL content fetching with SSRF protection
  • Proof verification

Methods​

hashContent()​

Hash deliverable content using Keccak256.

// Level 2: Advanced API - Direct protocol control
import { ProofGenerator } from '@agirails/sdk';

const proofGen = new ProofGenerator();

// Hash string content
const hash1 = proofGen.hashContent('Hello, World!');
console.log('String hash:', hash1);

// Hash buffer content
const buffer = Buffer.from([0x01, 0x02, 0x03]);
const hash2 = proofGen.hashContent(buffer);
console.log('Buffer hash:', hash2);

Returns: string - Keccak256 hash (bytes32, 0x-prefixed)

generateDeliveryProof()​

Generate a complete delivery proof per AIP-4.

// Level 2: Advanced API - Direct protocol control
const proof = proofGen.generateDeliveryProof({
  txId: '0x1234...', // Transaction ID
  deliverable: 'Your AI-generated content here',
  deliveryUrl: 'ipfs://QmHash...', // Optional: permanent storage URL
  metadata: {
    mimeType: 'application/json',
    // Note: size is computed automatically
  },
});

console.log('Proof:', proof);
// {
//   type: 'delivery.proof',
//   txId: '0x1234...',
//   contentHash: '0xabc...',
//   timestamp: 1703779200000,
//   deliveryUrl: 'ipfs://QmHash...',
//   metadata: {
//     size: 35,
//     mimeType: 'application/json'
//   }
// }

Parameters:

ParameterTypeDescription
txIdstringTransaction ID
deliverablestring | BufferContent to hash
deliveryUrlstring?IPFS/Arweave URL
metadataobject?Additional metadata

Returns:

interface DeliveryProof {
  type: 'delivery.proof';
  txId: string;
  contentHash: string;     // Keccak256 of deliverable
  timestamp: number;       // Unix timestamp (ms)
  deliveryUrl?: string;    // Permanent storage URL
  metadata: {
    size: number;          // Computed content size
    mimeType: string;      // Content type
    [key: string]: any;    // User metadata
  };
}

verifyDeliverable()​

Verify deliverable content matches expected hash.

// Level 2: Advanced API - Direct protocol control
const deliverable = 'Content from provider';
const expectedHash = '0xabc123...';

const isValid = proofGen.verifyDeliverable(deliverable, expectedHash);

if (isValid) {
  console.log('Content matches proof!');
} else {
  console.log('Content tampered or wrong!');
}

hashFromUrl()​

Fetch content from URL and generate hash. Includes SSRF protection.

// Level 2: Advanced API - Direct protocol control
// Hash content from IPFS
const hash = await proofGen.hashFromUrl('https://ipfs.io/ipfs/QmHash...');

// Hash content from Arweave
const hash2 = await proofGen.hashFromUrl('https://arweave.net/TxId...');

Security features:

  • HTTPS-only by default
  • Hostname blocklist (metadata services, private IPs)
  • Size limits (10MB default)
  • Request timeout (30 seconds)

encodeProof()​

Encode proof for on-chain submission.

// Level 2: Advanced API - Direct protocol control
const encoded = proofGen.encodeProof(proof);
// Returns ABI-encoded bytes for smart contract

decodeProof()​

Decode proof from on-chain data.

// Level 2: Advanced API - Direct protocol control
const decoded = proofGen.decodeProof(encodedData);
console.log('Decoded txId:', decoded.txId);
console.log('Decoded hash:', decoded.contentHash);
console.log('Decoded time:', decoded.timestamp);

URL Validation Config​

Configure URL fetching security:

// Level 2: Advanced API - Direct protocol control
const proofGen = new ProofGenerator({
  allowedProtocols: ['https:'],      // HTTPS only (default)
  allowLocalhost: false,             // Block localhost
  maxSize: 10 * 1024 * 1024,        // 10MB limit
  timeout: 30000,                    // 30 second timeout
  blockedHosts: [
    'metadata.google.internal',      // Cloud metadata
    '169.254.169.254',              // AWS/GCP metadata
  ],
});

Development mode:

// Level 2: Advanced API - Direct protocol control
// For local testing, allow HTTP and localhost
const devProofGen = new ProofGenerator({
  allowedProtocols: ['https:', 'http:'],
  allowLocalhost: true,
});

Example: Complete Delivery​

// Level 2: Advanced API - Direct protocol control
import {
  ACTPClient,
  ProofGenerator,
  EASHelper,
  State,
} from '@agirails/sdk';

async function deliver(txId: string, result: string) {
  const client = await ACTPClient.create({
    mode: 'testnet',
    privateKey: process.env.PRIVATE_KEY!,
  });

  const proofGen = new ProofGenerator();

  // 1. Upload to IPFS (optional, for permanent storage)
  const ipfsUrl = await uploadToIPFS(result);

  // 2. Generate delivery proof
  const proof = proofGen.generateDeliveryProof({
    txId,
    deliverable: result,
    deliveryUrl: ipfsUrl,
    metadata: {
      mimeType: 'application/json',
      version: '1.0',
    },
  });

  console.log('Content hash:', proof.contentHash);
  console.log('Size:', proof.metadata.size, 'bytes');

  // 3. Create EAS attestation (optional, for on-chain proof)
  const eas = new EASHelper(client.signer, EAS_CONFIG);
  const tx = await client.advanced.getTransaction(txId);
  const attestation = await eas.attestDeliveryProof(proof, tx.requester);

  // 4. Anchor and transition
  await client.advanced.anchorAttestation(txId, attestation.uid);
  await client.advanced.transitionState(txId, State.DELIVERED);

  console.log('Delivered with proof!');
  return proof;
}

Best Practices​

  1. Always hash the actual deliverable - Don't hash summaries or descriptions
  2. Use IPFS/Arweave for permanence - Decentralized storage ensures availability
  3. Include mimeType - Helps consumers process the content correctly
  4. Verify before accepting - Consumers should verify hash matches content

Next Steps​

Last updated on