DataRootVerificationStrategy

Overview

The DataRootVerificationStrategy provides the highest level of data integrity verification by validating data using Arweave's Merkle tree proofs. This strategy ensures maximum security by verifying that the data matches the cryptographic data root stored in the transaction, providing mathematical proof of data integrity.

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

Compute Data Root: Chunk the received content and build a Merkle tree
Calculate Root Hash: Compute the root hash of the Merkle tree
Fetch Trusted Root: Get the data root from trusted gateways via /tx/{txId}/data_root
Compare Roots: Verify the calculated root matches the trusted data root
Result: Pass or fail based on data root validation

Important Limitation

ANS-104 Data Items Not Supported: This strategy currently only works with regular Arweave transactions, not ANS-104 bundled data items. If you attempt to verify an ANS-104 data item, it will throw an error.

Configuration

Basic Usage

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

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

Advanced Configuration

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

Parameters

← Swipe to see more →

Parameter	Type	Default	Description
trustedGateways	URL[]	Required	Array of trusted gateway URLs for data root fetching
maxConcurrency	number	1	Maximum number of concurrent requests to gateways
logger	Logger	defaultLogger	Custom logger instance for debugging
classifier	DataClassifier	GqlClassifier	Data classifier to determine transaction type

← Swipe to see more →

Integration Examples

With Wayfinder

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

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

// Maximum security 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 DataRootVerificationStrategy({
      trustedGateways: [new URL('https://arweave.net')],
    }),
    events: {
      onVerificationSucceeded: (event) => {
        console.log('✅ Data root verification passed:', {
          txId: event.txId,
        })
      },
      onVerificationFailed: (error) => {
        console.error('❌ Data root verification failed:', {
          error: error.message,
        })
      },
    },
  },
})

Standalone Usage

const strategy = new DataRootVerificationStrategy({
  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 Merkle Tree Processing Works

The strategy uses Arweave's standard Merkle tree implementation:

Chunking Process

Chunk Size: Uses Arweave's standard chunk sizes (MAX_CHUNK_SIZE and MIN_CHUNK_SIZE)
Smart Chunking: Automatically adjusts chunk sizes to avoid small remainder chunks
Sequential Processing: Processes data streams chunk by chunk

Merkle Tree Construction

Generate Leaves: Creates Merkle tree leaves from data chunks
Build Layers: Constructs the full Merkle tree structure
Compute Root: Calculates the final root hash

Data Root Fetching

Fetches data root from trusted gateways via /tx/{txId}/data_root endpoint
Uses concurrent requests with configurable concurrency limits
Returns first successful response from any gateway

Use Cases

Maximum Security Applications

Perfect for applications requiring the highest level of verification:

const strategy = new DataRootVerificationStrategy({
  trustedGateways: [
    new URL('https://arweave.net'),
    new URL('https://permagate.io'),
  ],
  maxConcurrency: 2, // Use multiple gateways for reliability
})

Legal and Financial Documents

Critical document verification:

const legalStrategy = new DataRootVerificationStrategy({
  trustedGateways: [new URL('https://arweave.net')],
  logger: auditLogger, // Detailed logging for compliance
})

Production vs Development

// Production - multiple gateways for maximum reliability
const prodStrategy = new DataRootVerificationStrategy({
  trustedGateways: [
    new URL('https://arweave.net'),
    new URL('https://permagate.io'),
  ],
  maxConcurrency: 2,
})

// Development - single gateway with debug logging
const devStrategy = new DataRootVerificationStrategy({
  trustedGateways: [new URL('https://arweave.net')],
  logger: debugLogger,
})

Error Handling

ANS-104 Data Items

try {
  await strategy.verifyData({
    data: dataBuffer,
    txId: 'ans104-data-item-id',
  })
} catch (error) {
  if (error.message.includes('ANS-104 data is not supported')) {
    console.log('This is an ANS-104 data item, use a different strategy')
    // Fall back to signature verification or hash verification
  }
}

Data Root Mismatch

try {
  await strategy.verifyData({
    data: dataBuffer,
    txId: 'transaction-id',
  })
} catch (error) {
  if (error.message.includes('Data root does not match')) {
    console.error('Data integrity verification failed:', {
      computedDataRoot: error.cause?.computedDataRoot,
      trustedDataRoot: error.cause?.trustedDataRoot,
    })
  }
}

Best Practices

Use Multiple Trusted Gateways: Increases reliability for data root fetching
Set Appropriate Concurrency: Balance between performance and gateway load
Monitor for ANS-104: Check transaction types before verification
Handle Large Files: Be aware that Merkle tree computation can be resource-intensive
Use for Critical Data: Reserve for applications requiring maximum security

Comparison with Other Strategies

← Swipe to see more →

Aspect	Data Root Verification	Hash Verification	Signature Verification
Security	Highest	High	Very High
Performance	Slower	Fastest	Fast
ANS-104 Support	❌ No	✅ Yes	✅ Yes
Best For	Production applications	High-throughput applications	Financial or legal documents

← Swipe to see more →

The DataRootVerificationStrategy provides the highest level of security by using Arweave's native Merkle tree structure. It's ideal for applications where data integrity is absolutely critical and performance is secondary to security. However, note that it currently only supports regular Arweave transactions, not ANS-104 bundled data items.