[AIR-3][AIS-3][BPC-3][RES-3]

Read First Always Principle in Web5

Overview

Add a brief overview of this document here.

Table of Contents

Introduction

This document provides an overview of the Read First Always principle implementation in the Web5 components of the Anya Core project. This implementation enhances data integrity and consistency in decentralized systems by ensuring that all write operations are preceded by reads of the current state.

Implementation Files

The Read First Always principle is implemented across the following files:

  1. lib/src/core/web5/metrics.react: Metrics tracking for Read First compliance
  2. lib/src/core/web5/read_first_dwn.react: DWN wrapper that enforces the Read First principle
  3. lib/src/core/web5/web5_service.react: Updated service with Read First principle integration
  4. lib/src/core/storage/dwn_store.react: Storage implementation with Read First principle compliance
  5. docs/READ_FIRST_ALWAYS.md: Comprehensive documentation of the principle
  6. test/web5/read_first_test.dart: Test suite for Read First functionality

Key Features

1. Read First Enforcement

All operations that modify data are required to first read the current state:

  • Create operations: Query for similar records before creating new ones
  • Update operations: Read the current record before updating
  • Delete operations: Verify record exists before deleting

2. Metrics Collection

Detailed metrics are collected to monitor compliance:

  • Read count: Number of read operations performed
  • Write count: Number of write operations performed
  • Violation count: Number of writes without preceding reads
  • Compliance rate: Percentage of writes that comply with Read First

3. Logging

Comprehensive logging is implemented for:

  • All read and write operations
  • Potential violations of the Read First principle
  • Periodic metrics summaries

Integration With Bitcoin Anchoring

The Read First Always principle is particularly important for Bitcoin-anchored Web5 operations:

  1. It ensures that all operations verify the current blockchain state before making changes
  2. It prevents potential conflicts in credential issuance and verification
  3. It maintains consistency between on-chain and off-chain data

Usage Examples

Basic Usage

// Get the Web5Service instance
final web5Service = await Web5Service.connect();

// All operations automatically follow Read First Always principle
await web5Service.createRecord(
  collection: 'credentials',
  data: credentialData,
  schema: 'https://schema.org/VerifiableCredential',
);

// Get compliance metrics
final metrics = web5Service.getReadFirstMetrics();
print('Compliance rate: ${metrics['compliance_rate']}%');

Direct DWN Manager Usage

// Access the ReadFirstDwnManager
final web5Client = web5.Web5Client();
final dwnManager = ReadFirstDwnManager(web5Client);

// Operations will follow Read First Always principle
await dwnManager.createRecord(
  web5.CreateRecordOptions(
    data: jsonEncode(data),
    dataFormat: 'application/json',
    schema: schema,
  ),
);

Testing

The Read First principle implementation includes comprehensive tests that verify:

  1. All write operations are preceded by reads
  2. Metrics are correctly tracked and reported
  3. Exceptions are properly thrown for invalid operations
  4. Read/write order is maintained in all cases

Run the tests with:

flutter test test/web5/read_first_test.dart

Conclusion

The Read First Always principle is a critical component of the Anya Core Web5 implementation, ensuring data consistency and integrity across decentralized operations. By enforcing reads before writes, we maintain the reliability of our Web5 and Bitcoin-anchored services.

See Also