UIP-1: Permanent Proofs via Arweave

[lightsing]

UIP-1: Permanent Proofs via Arweave

Field	Value
UIP	1
Title	Permanent Proofs via Arweave
Author	@lightsing
Status	Review
Type	Standards Track
Created	2026-03-13

Abstract

This proposal introduces a mechanism to permanently store and retrieve Universal/OpenTimestamps (OTS) proofs using the Arweave decentralized storage network. By leveraging the currently available free < 100KiB unsigned data upload service provided by Turbo gateways, clients can permanently back up their timestamp proofs. This proposal acknowledges that decentralized network economic models may be subject to governance changes, and thus designs the upload threshold as a configurable parameter. It defines a new attestation type, ArweaveAttest, and outlines the standard procedures for proof permanentization (upload) and retrieval based on GraphQL tag indexing.

Motivation

In the standard OpenTimestamps architecture, the proof of existence is bound to a localized .ots file. Losing this file results in the permanent loss of the proof, primarily due to the following design choices:

1. Privacy-Preserving Nonce: The default client implementation appends a random nonce to the original file's hash to preserve privacy.
2. Commitment Structure: The calendar server only receives and stores the aggregated Merkle tree, where the leaves are the commitments (the hash of the client-submitted digest combined with the undeniable signature).

Consequently, if the .ots file is lost, the client loses the nonce and the exact cryptographic path. It becomes mathematically impossible to reconstruct the commitment and retrieve the Merkle path from the calendar server, even if the user still possesses the original file.

Since a fully upgraded .ots proof is extremely compact, it currently fits perfectly within the free-tier threshold of Arweave's Turbo gateway. This UIP proposes a method to utilize this public good, enabling a "recover proof solely from the original file hash" user experience, provided the user is willing to explicitly trade off privacy for permanence.

Specification

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

1. New Attestation Type: ArweaveAttest

A new attestation type MUST be introduced to represent that the proof has been permanently anchored to the Arweave network.

• TAG: Evaluated as the first 8 bytes of the SHA-256 hash of the string "UniversalTimestamps.ArweaveAttest".

TAG = sha256("UniversalTimestamps.ArweaveAttest")[:8] = e1ab7267b0e6ee1b

• Data Payload: The payload MUST be the 32-byte raw binary representation of the Arweave Data Item ID.

2. Procedure of Permanentize (Upload)

To upgrade a local .ots proof into a permanent Arweave-backed proof, the client software MUST execute the following procedure:

Pre-flight Checks:

1. Explicit UI/UX Consent: The client MUST implement a standardized UI/UX consent flow. Displaying a simple warning is insufficient; the client MUST require the user to perform an explicit affirmative action (e.g., typing "I UNDERSTAND" or checking a specific, non-default checkbox). The prompt MUST clearly state that:

• The correlation between the file content and the timestamp event will be permanently and publicly auditable.
• This action effectively strips the anonymity of the timestamping event relative to the file content.

2. Proof State: The user MUST provide the original file and a fully upgraded proof. The client MUST verify that the proof was generated with keepPending = false (all pending attestations must be resolved and purged).
3. Redundancy Elimination: The uploaded payload MUST NOT be a DetachedTimestamp. The client MUST strip the digest header, uploading only the bare Timestamp tree payload. The original digest is completely redundant as it is already fully represented via the Content-Hash and Content-Hash-Algorithm tags.
4. Dynamic Size Constraint: The client SHOULD verify that the binary size of the stripped .ots proof is within the gateway's dynamically configured free-tier threshold (currently <= 100KiB). Since this threshold is a property of the Turbo gateway implementation and not the Arweave protocol itself, clients MUST treat this limit as a configurable variable to ensure forward compatibility.

Upload Execution:
The SDK MUST issue an HTTP POST request to the Turbo gateway with the following specifications:

• Headers:

• Content-Type: application/octet-stream

• x-data-item-tags: A JSON-stringified array of key-value pairs representing ANS-104 Data Item tags. It MUST include:

  • {"name": "App-Name", "value": "UniversalTimestamps"}
  • {"name": "Content-Type", "value": "application/vnd.opentimestamps.v1"}
  • {"name": "Content-Hash-Algorithm", "value": "$digest_algorithm"}
    • To ensure interoperability, $digest_algorithm MUST be strictly mapped to one of the following exact string identifiers aligned with the core OTS protocol: "SHA1", "SHA256", "RIPEMD160", "KECCAK256".
  • {"name": "Content-Hash", "value": "$lower_hex_digest"}

• Body: The binary encoded stripped Timestamp proof payload.

Post-Upload Modification:
Upon receiving a 200 OK response containing the JSON payload with the id, the SDK MUST decode the Base64URL id into 32 bytes, fork the OTS AST at the root level, and prepend an ArweaveAttest alongside the existing entries.

3. Procedure of Retrieve (Download)

To retrieve a lost proof using only the original file, the client SDK MUST query an Arweave GraphQL gateway using the predefined tags.

GraphQL Query:

query {
  transactions(tags: [
    { name: "App-Name", values: ["UniversalTimestamps"] },
    { name: "Content-Type", values: ["application/vnd.opentimestamps.v1"] },
    { name: "Content-Hash-Algorithm", values: ["$digest_algorithm"] },
    { name: "Content-Hash", values: ["$lower_hex_digest"] }
  ]) {
    edges {
      node {
        id
        block {
          timestamp
          height
        }
      }
    }
  }
}

Resolution Logic:
For the returned edges, the client MUST:

1. Sort the results by node.block.timestamp in ascending order.
2. Iterate through the results and download the payload via https://arweave.net/<id>.
3. Reconstruct the DetachedTimestamp in memory by prepending the digest header mathematically derived from the file and tags.
4. Validate the reconstructed .ots proof mathematically against the user's local file.
5. Upon the first valid proof encountered, prepend the ArweaveAttest to the AST root, save it as a local .ots file, and gracefully terminate the loop.

Rationale

• Why Unsigned Raw Upload? Utilizing Turbo's unsigned endpoint removes the necessity for Web3 wallet integration, keeping the client lightweight.
• Why Tag-Based Indexing? Arweave's native GraphQL tag indexing enables an $O(1)$ lookup capability, fulfilling the primary objective of restoring the proof using nothing but the original file's hash.
• Why Strip the Digest Header? Removing the DetachedTimestamp header minimizes byte-size to comfortably fit within gateway free-tier limits, while the required Content-Hash-Algorithm and Content-Hash tags provide the exact same context for reconstruction.

Security and Privacy Considerations

1. Privacy Degradation and Anonymity Loss: As explicitly stated in the procedure, publishing the hash of the file to Arweave completely neutralizes the privacy benefits of the OTS nonce. Implementations MUST adhere strictly to the explicit UI/UX consent flow to ensure users are fully aware of this permanent, public cryptographic linkage.
2. Data Availability Risk (Confirmation Window): While Arweave provides probabilistic permanence, a non-zero time window exists between the gateway acknowledging the upload (returning an id) and the transaction being fully replicated and mined into a block. Clients and users MUST be aware that the proof data might not be immediately retrievable via standard decentralized gateways (or GraphQL nodes) until sufficient block confirmation has occurred.
3. Gateway Dependency: The upload process relies on the availability and the continued free-tier policy of the ardrive.io Turbo gateway. If the service limits change, the upload mechanism may fail. However, retrieval remains entirely decentralized.

[CatSouta]

Once the feature is completed, an example can be added to explain to users the extent of privacy loss involved in exchange for this permanent proof.