Attestation

Permanent attestation of entity versions to Arweave for independent verification.

Overview

Arke permanently attests entity versions to Arweave, a decentralized permanent storage network. This ensures that:

Full manifests (not just hashes) are stored permanently
The network can be reconstructed from Arweave alone
Third parties can independently verify content integrity

How It Works

Entity version is created or updated
The full manifest is queued for attestation via D1's attestation_queue table
A background worker uploads the manifest to Arweave (asynchronous)
The Arweave transaction ID is indexed in KV (attest:{pi}:{ver})
The prev_cid chain provides ordering guarantees across versions

Attestation Endpoints

Get Latest Attestation

Retrieve the Arweave attestation for the current (latest) version of an entity.

GET /entities/{id}/attestation
Authorization: Bearer <token>  # Optional - for private entities

Response (200 - Attestation Found):

{
  "pi": "01KDETYWYWM0MJVKM8DK3AEXPY",
  "ver": 3,
  "cid": "bafybei...",
  "arweave_tx": "Rxv_BpobNBUr0x5DstsAEUVxCO12hKxv7cnHnGLYp2c",
  "arweave_url": "https://arweave.net/Rxv_BpobNBUr0x5DstsAEUVxCO12hKxv7cnHnGLYp2c",
  "ts": 1704455200000
}

Response (202 - Attestation Pending):

If the attestation upload is still in progress:

{
  "pi": "01KDETYWYWM0MJVKM8DK3AEXPY",
  "ver": 3,
  "cid": "bafybei...",
  "attestation_status": "pending",
  "message": "Attestation upload in progress"
}

Get Version Attestation

Retrieve the Arweave attestation for a specific version of an entity.

GET /versions/{id}/{ver}/attestation
Authorization: Bearer <token>  # Optional - for private entities

Response (200):

{
  "pi": "01KDETYWYWM0MJVKM8DK3AEXPY",
  "ver": 2,
  "cid": "bafybei...",
  "arweave_tx": "abc123xyz...",
  "arweave_url": "https://arweave.net/abc123xyz...",
  "ts": 1704455100000
}

Returns 404 if the version doesn't exist or the attestation hasn't been uploaded yet.

Get Chain Head

Retrieve the latest attestation transaction ID on the network.

GET /attestations/head

Response (200):

{
  "seq": 784,
  "tx": "Rxv_BpobNBUr0x5DstsAEUVxCO12hKxv7cnHnGLYp2c",
  "arweave_url": "https://arweave.net/Rxv_BpobNBUr0x5DstsAEUVxCO12hKxv7cnHnGLYp2c"
}

Verify Attestation

Fetch an attestation from Arweave and verify the CID matches the manifest content. This is a public endpoint - anyone can verify attestations without authentication.

GET /attestations/verify/{tx}

Response (200):

{
  "arweave_tx": "Rxv_BpobNBUr0x5DstsAEUVxCO12hKxv7cnHnGLYp2c",
  "attestation": {
    "pi": "01KDETYWYWM0MJVKM8DK3AEXPY",
    "ver": 3,
    "cid": "bafybei...",
    "op": "U",
    "vis": "pub",
    "prev_cid": "bafybei...",
    "ts": 1704455200000
  },
  "cid_valid": true,
  "manifest_preview": {
    "type": "collection"
  }
}

The op field indicates the operation type: C for Create, U for Update. The vis field indicates visibility at the time of operation: pub or priv.

Version History with Attestations

When listing version history via GET /versions/{id}, each version includes attestation information if available:

{
  "entity_id": "01KDETYWYWM0MJVKM8DK3AEXPY",
  "versions": [
    {
      "ver": 3,
      "cid": "bafybei...",
      "ts": "2024-01-05T10:00:00.000Z",
      "edited_by": { "pi": "01USER...", "type": "user" },
      "arweave_tx": "abc123",
      "arweave_url": "https://arweave.net/abc123"
    },
    {
      "ver": 2,
      "cid": "bafybei...",
      "ts": "2024-01-04T10:00:00.000Z",
      "edited_by": { "pi": "01USER...", "type": "user" },
      "arweave_tx": "def456",
      "arweave_url": "https://arweave.net/def456"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Third-Party Verification

Anyone can verify an entity's history by:

Querying Arweave directly for the entity's attestation records using GraphQL
Verifying the content hash matches the CID
Following the prev_cid chain to reconstruct the full version history

Query All Arke Manifests from Arweave

curl 'https://arweave.net/graphql' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "{ transactions(tags: [{name: \"App-Name\", values: [\"Arke\"]}, {name: \"Type\", values: [\"manifest\"]}], first: 100) { edges { node { id tags { name value } } } } }"
  }'

Query Specific Entity History

curl 'https://arweave.net/graphql' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "{ transactions(tags: [{name: \"App-Name\", values: [\"Arke\"]}, {name: \"PI\", values: [\"01KDETYWYWM0MJVKM8DK3AEXPY\"]}], first: 100) { edges { node { id tags { name value } } } } }"
  }'

Chain Integrity

The prev_cid chain structure provides ordering guarantees:

Cannot insert into past: Would require re-hashing everything after the insertion point
Cannot backdate: Each timestamp must be greater than or equal to the previous timestamp
Cannot remove versions: Breaking any link invalidates the entire chain
Order is provable: The prev_cid chain is the canonical ordering

Arweave block timestamps provide an external bound: "This data existed no later than when this block was mined."

On this page