Skip to content

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

Read First Always Principle

Table of Contents

Overview

The Read First Always principle is a fundamental data consistency and integrity pattern implemented across the Anya Core project, particularly in Web5 components. This principle ensures that any operation that modifies data first reads the current state before making changes, preventing race conditions and maintaining data integrity in decentralized systems.

Core Concepts

  1. Read Before Write: Any operation that modifies data (create, update, delete) must first read the current state of that data.
  2. Metrics Tracking: All read and write operations are tracked to ensure compliance with the Read First principle.
  3. Violation Detection: The system detects and logs situations where a write occurs without a preceding read.
  4. Automatic Enforcement: The system is designed to automatically enforce this principle through middleware layers.

Implementation Details

Web5 DWN Operations

In Web5 Decentralized Web Node (DWN) operations, the Read First Always principle is implemented through:

  1. ReadFirstDwnManager: A wrapper around standard DWN operations that enforces reads before writes.
  2. Metrics Collection: Tracking of read/write operations, timing, and compliance rate.
  3. Logging: Comprehensive logging of all operations and potential violations.

Example: Creating a Record

// Before the Read First Always implementation
await web5.dwn.records.create(options);

// With Read First Always implementation
// 1. First reads similar records
await readFirstDwnManager.queryRecords(
  QueryRecordOptions(schema: options.schema)
);
// 2. Then creates the record
await readFirstDwnManager.createRecord(options);

Example: Updating a Record

// Before the Read First Always implementation
await web5.dwn.records.update(recordId, options);

// With Read First Always implementation
// 1. First reads the existing record
final existingRecord = await readFirstDwnManager.readRecord(recordId);
// 2. Then updates the record
await readFirstDwnManager.updateRecord(recordId, options);

Benefits

  1. Prevents Race Conditions: Ensures all operations have the latest data state.
  2. Improves Data Consistency: Maintains integrity across distributed systems.
  3. Enables Conflict Detection: Allows early detection of conflicting changes.
  4. Simplifies Debugging: Provides clear operation sequences for troubleshooting.
  5. Enhances Security: Prevents malicious data corruption through unauthorized writes.

Metrics and Monitoring

The Read First Always implementation includes comprehensive metrics:

  1. Read Count: Total number of read operations.
  2. Write Count: Total number of write operations.
  3. Violation Count: Number of writes performed without preceding reads.
  4. Compliance Rate: Percentage of writes that followed the Read First principle.

These metrics are accessible through:

final metrics = web5Service.getReadFirstMetrics();
web5Service.logMetrics(); // Logs current metrics to the console

Integration with Bitcoin Anchoring

The Read First Always principle is particularly important when working with Bitcoin-anchored data in Web5:

  1. Transaction Verification: Ensures all Bitcoin transactions are verified before any modification.
  2. Credential Validation: Validates all credentials are properly anchored to Bitcoin before updates.
  3. Revocation Checks: Verifies credential revocation status on Bitcoin before allowing operations.

Best Practices

  1. Always Use Provided Managers: Use ReadFirstDwnManager instead of direct DWN operations.
  2. Monitor Compliance Metrics: Regularly check and act on Read First Always violation metrics.
  3. Include in Testing: Add specific tests to verify Read First compliance in your code.
  4. Log Violations: Set up alerts for Read First violations in production systems.

Testing

The Read First Always principle can be tested using the following approaches:

  1. Unit Tests: Test individual components for Read First compliance.
  2. Integration Tests: Ensure end-to-end flows maintain the Read First principle.
  3. Metrics Validation: Verify metrics are correctly tracking reads and writes.
  4. Violation Simulation: Purposely attempt to violate the principle to test detection.

Conclusion

The Read First Always principle is a cornerstone of data integrity in decentralized systems like Web5. By strictly following this pattern, the Anya Core project maintains consistency and reliability in all data operations, particularly those anchored to the Bitcoin blockchain.

See Also