Link Revision

A Link Revision creates verifiable connections between separate revision chains. It allows you to establish relationships, dependencies, or references between different objects, effectively creating a graph structure of interconnected chains. Link revisions are essential for composing complex data structures and maintaining provenance across multiple chains.

Overview

Link revisions enable:

• Chain Composition: Connect multiple independent chains together
• Dependency Tracking: Express that one chain depends on others
• Multi-Party Collaboration: Combine contributions from different parties
• Provenance Graphs: Build complex data relationship structures
• Verification Aggregation: Group related chains for batch verification

Schema Structure

Fields

Field Details

link_verification_hashes

• Type: Array of hex strings
• Format: Each element is a lowercase hex string prefixed with 0x
• Purpose: References to other revision chains
• Minimum: Can be empty array (though typically contains at least one link)
• Maximum: No strict limit, but practical limits depend on implementation
• Order: Order may be significant depending on use case

Example

Basic Link Revision

Linking to two other chains:

1{
2  "previous_revision": "0x3f8a7b2c9d1e4f5a6b8c0d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a",
3  "revision_type": "link",
4  "nonce": "0x7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f",
5  "local_timestamp": 1704067200,
6  "version": "https://aqua-protocol.org/docs/v4/schema",
7  "method": "scalar",
8  "hash_type": "FIPS_202-SHA3-256",
9  "link_verification_hashes": [
10    "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
11    "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
12  ]
13}

Single Link

Linking to a single chain:

1{
2  "previous_revision": "0x9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f",
3  "revision_type": "link",
4  "nonce": "0x5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a",
5  "local_timestamp": 1704070800,
6  "version": "https://aqua-protocol.org/docs/v4/schema",
7  "method": "scalar",
8  "hash_type": "FIPS_202-SHA3-256",
9  "link_verification_hashes": [
10    "0x8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d"
11  ]
12}

Multiple Links (Aggregation)

Aggregating many chains:

1{
2  "previous_revision": "0x1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c",
3  "revision_type": "link",
4  "nonce": "0xa1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
5  "local_timestamp": 1704074400,
6  "version": "https://aqua-protocol.org/docs/v4/schema",
7  "method": "scalar",
8  "hash_type": "FIPS_202-SHA3-256",
9  "link_verification_hashes": [
10    "0x1111111111111111111111111111111111111111111111111111111111111111",
11    "0x2222222222222222222222222222222222222222222222222222222222222222",
12    "0x3333333333333333333333333333333333333333333333333333333333333333",
13    "0x4444444444444444444444444444444444444444444444444444444444444444",
14    "0x5555555555555555555555555555555555555555555555555555555555555555"
15  ]
16}

Validation Rules

A Link Revision is valid if:

1. Structure: Contains all required fields with correct types
2. Revision Type: The revision_type is exactly "link"
3. Previous Revision: References a valid existing revision
4. Link Array: link_verification_hashes is a valid array
5. Link Format: Each element in the array is a valid hex string with 0x prefix
6. Link Targets: Each referenced revision should exist and be verifiable (optional strict validation)
7. No Duplicates: Typically shouldn't contain duplicate hashes (application-specific)
8. Hash Verification: The computed hash of the link revision is correct

Common Use Cases

1. Document Dependencies

Link a document to its source materials:

2. Multi-Party Signing

Combine independent signatures:

3. Bill of Materials

Link a product to its components:

Each component has its own provenance chain.

4. Credential Bundling

Group related credentials:

5. Supply Chain Aggregation

Combine supply chain events:

6. Academic Citation

Link a paper to cited works:

7. Version History

Link to previous versions:

8. Approval Workflow Merge

Merge parallel approval processes:

Link Patterns

Pattern 1: Linear Dependency Chain

Each object depends on the previous one.

Pattern 2: Star Pattern (Aggregation)

One link revision references multiple chains.

Pattern 3: Tree Pattern

Hierarchical structure using links.

Pattern 4: Graph Pattern

Complex graph with cycles and multiple connections.

Implementation Notes

Creating a Link Revision

1. Identify the chains to link
2. Get the head (latest) revision hash from each chain
3. Collect hashes into link_verification_hashes array
4. Determine the previous_revision for this link
5. Generate nonce and timestamp
6. Create the link revision structure
7. Compute and verify the hash

Verifying a Link Revision

Basic Verification

Deep Verification

Link Resolution

When traversing links:

Advanced Topics

Cyclic References

Links can create cycles:

Handling:

• Detect cycles during traversal
• Use visited set to prevent infinite loops
• Cycles may be valid depending on use case

Temporal Ordering

Links create a temporal relationship:

Validation:

• Linked revisions should have timestamps < link timestamp
• Prevents linking to "future" revisions

Partial vs Complete References

Complete Reference: Link to final revision of a chain

Partial Reference: Link to intermediate revision

Link Updates

To update links over time:

Each link revision chains to the previous, tracking changes.

Link Metadata

While the standard link revision doesn't include metadata, you can add it by:

1. Creating an object revision with link metadata
2. Following it with a link revision

Relationship with Other Revisions

• Object Revisions: Can be linked, and can precede link revisions
• Signature Revisions: Can be linked (e.g., aggregating signatures)
• Witness Revisions: Can be linked, or can follow link revisions
• Template Revisions: Typically not linked (they're standalone)

Security Considerations

1. Link Validation

Verify Existence: Ensure linked revisions actually exist before creating link Verify Integrity: Validate linked chains are not corrupted

2. Circular Dependencies

Detection: Implement cycle detection in verification Policy: Decide if cycles are allowed in your application

3. Link Spam

Prevention: Validate that links are meaningful and authorized Rate Limiting: Prevent excessive linking in systems

4. Temporal Consistency

Timestamp Checking: Ensure links don't reference "future" revisions Causality: Maintain causal ordering of events

5. Authorization

Link Permission: Verify the creator has rights to link to target chains Privacy: Linking may reveal relationships between otherwise private chains

Performance Considerations

Link Depth

Deep link hierarchies impact verification time:

Optimization: Cache verified chains, use lazy loading

Link Width

Wide links (many references) increase storage and bandwidth:

Optimization: Paginate links, use link batching

Verification Strategy

Lazy: Only verify linked chains when accessed Eager: Verify all linked chains upfront Selective: Verify critical paths only

Comparison with Other Approaches

vs Direct References

Direct Reference (in object payload):

1{
2  "payload": {
3    "dependencies": ["0xabc...", "0xdef..."]
4  }
5}

Link Revision:

1{
2  "link_verification_hashes": ["0xabc...", "0xdef..."]
3}

Advantages of Link Revision:

• Explicit in protocol (not application-specific)
• Verifiable without parsing payload
• Consistent structure across applications
• Can be signed and witnessed separately

vs Witness Batching

Witness Batching: Uses Merkle tree for efficient blockchain anchoring Link Revision: Creates explicit relationships between chains

Key Difference: Witness is about timestamping, Link is about relationships.

Best Practices

1. Use Descriptive Ordering

Order links meaningfully:

2. Link to Stable Points

Link to revisions that are finalized (signed/witnessed):

3. Document Link Semantics

Precede link with an object explaining the relationships:

4. Consider Verification Cost

Limit link depth and width for practical verification times.

5. Use Links for Cross-Chain Only

Don't use links for intra-chain references (use previous_revision instead).

See Also

• Object Revision - Often linked
• Signature Revision - Can aggregate via links
• Witness Revision - Often follows links
• Graph Theory - Mathematical foundation for link structures