Object Revision

An Object Revision is the primary data-carrying revision type in Aqua Protocol v4. It stores arbitrary structured data that conforms to a template schema. Object revisions are typically the first revision in a chain (genesis) or follow other object revisions.

Overview

Object revisions serve as containers for application data. Each object revision:

• References a template (via revision_type field) that defines its schema
• Contains a payload with the actual data
• Can be the genesis revision (no previous_revision) or link to a previous revision
• Must conform to the validation rules defined by its template

Schema Structure

Fields

Field Details

previous_revision

• Format: Lowercase hex string prefixed with 0x (e.g., 0x3f8a...)
• Length: Variable (typically 64 characters for SHA3-256 hashes)
• Omitted: Only in genesis revisions (the first revision in a chain)
• Purpose: Creates the chain linkage and ensures revision ordering

revision_type

• Format: Hash reference pointing to a Template Revision
• Purpose: Identifies which template validates this object's payload
• Example: 0x1234abcd... (hash of a template revision)
• Validation: The template's schema must validate the payload

payload

• Type: JSON object
• Validation: Must conform to the JSON Schema defined in the referenced template
• Flexibility: Can contain any structured data as long as it matches the template
• Size: Depends on the method:
  • scalar: Entire payload is hashed directly
  • tree: Payload is broken into leaves for merkle tree construction

Methods

Scalar Method

The scalar method treats the entire object as a single unit. The payload is serialized, canonicalized, and hashed as one block.

Best for:

• Small to medium-sized objects
• When you need to verify the entire object at once
• Simple use cases

Tree Method

The tree method breaks the payload into leaves using JSON pointers, creating a merkle tree structure.

Best for:

• Large objects where partial verification is needed
• When you want to prove specific fields without revealing the entire object
• Advanced use cases requiring selective disclosure

Examples

Example 1: Genesis Object Revision (File)

This is a genesis revision (first in chain) using the File template:

1{
2  "revision_type": "0x742b74c87ccd7bfc76eaec416027a0bc039b59b9c2d452ea55a5c0e9b0e3f08e",
3  "nonce": "0x3fa8b1c2d3e4f5a67b8c9d0e1f2a3b4c",
4  "local_timestamp": 1704067200,
5  "version": "https://aqua-protocol.org/docs/v4/schema",
6  "method": "scalar",
7  "hash_type": "FIPS_202-SHA3-256",
8  "payload": {
9    "payload_type": "application/pdf",
10    "hash": "0x9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
11    "hash_type": "FIPS_202-SHA3-256",
12    "descriptor": "Important Contract Document"
13  }
14}

Note: No previous_revision field because this is a genesis revision.

Example 2: Subsequent Object Revision (Domain Claim)

This revision follows another revision in the chain:

1{
2  "previous_revision": "0x3f8a7b2c9d1e4f5a6b8c0d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a",
3  "revision_type": "0x8b3e4c7d9f1a2b5c6e8f0a3b4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3",
4  "nonce": "0x7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f",
5  "local_timestamp": 1704070800,
6  "version": "https://aqua-protocol.org/docs/v4/schema",
7  "method": "scalar",
8  "hash_type": "FIPS_202-SHA3-256",
9  "payload": {
10    "domain": "example.com",
11    "wallet_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb8"
12  }
13}

Example 3: Object with Tree Method

Using the tree method for a larger object:

1{
2  "previous_revision": "0x1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b",
3  "revision_type": "0x4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a",
4  "nonce": "0x9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b",
5  "local_timestamp": 1704074400,
6  "version": "https://aqua-protocol.org/docs/v4/schema",
7  "method": "tree",
8  "hash_type": "FIPS_202-SHA3-256",
9  "payload": {
10    "name": "John Doe",
11    "email": "john@example.com",
12    "phone": "+1234567890",
13    "address": {
14      "street": "123 Main St",
15      "city": "Anytown",
16      "country": "USA"
17    },
18    "metadata": {
19      "created": "2024-01-01",
20      "verified": true
21    }
22  }
23}

With tree method: Each field (using JSON pointers like /name, /email, /address/city) becomes a leaf in the merkle tree.

Validation Rules

An Object Revision is valid if:

1. Structure: Contains all required fields with correct types
2. Version: The version field matches "https://aqua-protocol.org/docs/v4/schema"
3. Method: The method is either "scalar" or "tree"
4. Hash Type: The hash_type is a recognized algorithm (e.g., "FIPS_202-SHA3-256")
5. Nonce: Is a valid 16-byte hex string prefixed with 0x
6. Timestamp: Is a valid Unix timestamp
7. Previous Revision:
   • Must be absent for genesis revisions
   • Must be present and valid for non-genesis revisions
   • Must reference an existing revision
8. Revision Type: Must reference a valid template revision
9. Payload: Must conform to the JSON Schema defined in the referenced template
10. Hash Verification: The computed hash matches what's expected

Common Use Cases

Document Storage

Store file metadata with hash references:

1{
2  "payload": {
3    "payload_type": "application/pdf",
4    "hash": "0x...",
5    "hash_type": "FIPS_202-SHA3-256",
6    "descriptor": "Legal Agreement 2024"
7  }
8}

Identity Claims

Store verifiable claims about entities:

1{
2  "payload": {
3    "domain": "company.com",
4    "wallet_address": "0x742d35Cc..."
5  }
6}

Credential Data

Store structured credential information:

1{
2  "payload": {
3    "credential_type": "EmailVerification",
4    "subject": "user@example.com",
5    "issuer": "0x...",
6    "issued_at": 1704067200
7  }
8}

Relationship with Other Revisions

After creating an Object Revision, you typically:

1. Sign it - Add a Signature Revision to prove authenticity
2. Witness it - Add a Witness Revision for timestamped proof
3. Update it - Create a new Object Revision that references this one
4. Link it - Create a Link Revision to connect to other chains

Implementation Notes

Creating an Object Revision

When implementing object revision creation:

1. Validate payload against the template schema first
2. Generate a random 16-byte nonce
3. Capture the current timestamp
4. Include previous_revision only if not genesis
5. Serialize according to the chosen method
6. Compute the hash for verification

Verifying an Object Revision

To verify an object revision:

1. Check all required fields are present
2. Validate field types and formats
3. Verify the referenced template exists
4. Validate payload against template schema
5. Recompute the hash and compare
6. If not genesis, verify previous_revision exists and is valid

See Also

• Template Revision - Defines the schema for object payloads
• Signature Revision - Sign object revisions
• Witness Revision - Add timestamped proof
• Link Revision - Connect to other chains