HashVerificationStrategy

Overview

The HashVerificationStrategy verifies data integrity by comparing SHA-256 hashes of fetched data against trusted gateway digest headers. This strategy provides fast, cryptographically secure verification for high-throughput applications.

Important

Verification methods require that the gateway being used has the relevant transaction data indexed locally. Gateways cannot proxy out verification requests to other sources, as this would compromise the security and reliability of the verification process. If a gateway doesn't have the required data indexed, verification will fail.

How It Works

Fetch Data: Retrieve content from the selected gateway
Compute Hash: Calculate the SHA-256 hash of the received data
Request Digest: Get the digest from trusted gateways via HTTP headers using HEAD/GET requests
Compare: Verify that both hashes match exactly
Result: Pass or fail based on hash comparison

Configuration

Basic Usage

import { HashVerificationStrategy } from '@ar.io/wayfinder-core'

const strategy = new HashVerificationStrategy({
  trustedGateways: [new URL('https://arweave.net')],
})

Advanced Configuration

const strategy = new HashVerificationStrategy({
  trustedGateways: [
    new URL('https://arweave.net'),
    new URL('https://permagate.io'),
  ],
  maxConcurrency: 2, // Process multiple gateway requests concurrently
  logger: customLogger, // Optional custom logger
})

Parameters

← Swipe to see more →

Parameter	Type	Default	Description
trustedGateways	URL[]	Required	Array of trusted gateway URLs for hash comparison
maxConcurrency	number	1	Maximum number of concurrent requests to gateways
logger	Logger	defaultLogger	Custom logger instance for debugging

← Swipe to see more →

Integration Examples

With Wayfinder

import { Wayfinder, HashVerificationStrategy } from '@ar.io/wayfinder-core'

const wayfinder = new Wayfinder({
  gatewaysProvider: gatewaysProvider,
  verificationSettings: {
    enabled: true,
    strategy: new HashVerificationStrategy({
      trustedGateways: [new URL('https://arweave.net')],
    }),
    strict: true,
  },
})

// Verification happens automatically
const response = await wayfinder.request('ar://transaction-id')
const data = await response.text()

With Event Monitoring

const wayfinder = new Wayfinder({
  gatewaysProvider: gatewaysProvider,
  verificationSettings: {
    enabled: true,
    strategy: new HashVerificationStrategy({
      trustedGateways: [new URL('https://arweave.net')],
    }),
    events: {
      onVerificationSucceeded: (event) => {
        console.log('✅ Hash verification passed:', {
          txId: event.txId,
        })
      },
      onVerificationFailed: (error) => {
        console.error('❌ Hash verification failed:', {
          error: error.message,
        })
      },
    },
  },
})

Standalone Usage

const strategy = new HashVerificationStrategy({
  trustedGateways: [new URL('https://arweave.net')],
})

// Manual verification
try {
  await strategy.verifyData({
    data: dataBuffer,
    txId: 'transaction-id',
  })
  console.log('Verification passed!')
} catch (error) {
  console.error('Verification failed:', error.message)
}

How Digest Fetching Works

The strategy uses a sophisticated approach to get digest headers from trusted gateways:

HEAD Request: First tries a HEAD request to get the digest header
GET Request: If HEAD fails, performs a GET request to hydrate the gateway's cache
Second HEAD Request: Makes another HEAD request to get the cached digest
Sandbox URLs: Uses subdomain sandboxing for security (e.g., txid.arweave.net)

This ensures that even if a gateway doesn't have the data cached initially, it will fetch and cache it, then provide the digest header.

Use Cases

High-Throughput Applications

Perfect for applications that need fast verification:

const strategy = new HashVerificationStrategy({
  trustedGateways: [new URL('https://arweave.net')],
  maxConcurrency: 3, // Higher concurrency for speed
})

Development and Testing

Quick verification for development environments:

const devStrategy = new HashVerificationStrategy({
  trustedGateways: [new URL('https://arweave.net')],
  logger: debugLogger, // Detailed logging for development
})

Production with Multiple Gateways

Reliable verification with fallback options:

const prodStrategy = new HashVerificationStrategy({
  trustedGateways: [
    new URL('https://arweave.net'),
    new URL('https://permagate.io'),
  ],
  maxConcurrency: 2, // Use multiple gateways concurrently
})

Best Practices

Use Multiple Trusted Gateways: Increases reliability and provides fallback options
Set Appropriate Concurrency: Balance between performance and gateway load
Monitor Verification Events: Track success rates and failure reasons
Handle Network Failures: Implement proper error handling for gateway requests
Use Reputable Gateways: Choose gateways with reliable data indexing and caching

Comparison with Other Strategies

← Swipe to see more →

Aspect	Hash Verification	Signature Verification	Data Root Verification
Security	High	Very High	Highest
Performance	Fastest	Fast	Slower
Best For	High-throughput applications	Financial or legal documents	Production applications

← Swipe to see more →

The HashVerificationStrategy provides an excellent balance of security and performance, making it ideal for most applications that need fast, reliable data integrity verification.