Skip to content

Agora Query Attestation v1

Source schema: doc/schemas/agora-query-attestation.v1.schema.json

Machine-readable attestation for one Agora historical query response. It binds the query scope, normalized filter, returned record ids, pagination/pruning metadata, and a deterministic digest of the response page. A signature is optional in v1 so local relays can emit unsigned attestations before relay signing is wired; signed deployments should sign the canonical JSON of this object with signature omitted.

Governing Basis

Project Lineage

Requirements

Stories

Fields

Field Required Shape Description
schema yes const: agora-query-attestation.v1 Schema discriminator. MUST be exactly agora-query-attestation.v1.
attestation/id yes string Stable identifier for this attested response page. The reference implementation derives it from the response digest.
attested/at yes string UTC time when the relay assembled the attestation.
relay/id no string Optional relay identifier that assembled the page.
query/mode yes enum: topic-records, subject-records Query family this attestation describes.
query/topic-key no string Topic key for a topic-records query.
query/resource no ref: #/$defs/resourceRef Subject resource for a subject-records query.
query/filter yes object Normalized filter used by the relay after URL decoding and limit defaults.
result/record-ids yes array Record ids returned in page order.
result/count yes integer Number of returned records. MUST equal the length of result/record-ids.
result/next-cursor no string Opaque cursor for the next page, if present in the response.
result/cursor-pruned no object Explicit discontinuity notice when retention pruned records below the caller's cursor.
result/digest yes string Digest of the canonical query-attestation material: query mode, scope, normalized filter, returned record ids, next cursor, and cursor-pruned notice.
result/digest-alg yes const: jcs-nfc-sha256-base64url Digest algorithm used for result/digest.
signature no object Optional relay signature over the canonical attestation with signature omitted. Unsigned v1 attestations still provide deterministic digest evidence but not relay accountability.

Definitions

Definition Shape Description
resourceRef object

Conditional Rules

Rule 1

When:

{
  "properties": {
    "query/mode": {
      "const": "topic-records"
    }
  },
  "required": [
    "query/mode"
  ]
}

Then:

{
  "required": [
    "query/topic-key"
  ],
  "not": {
    "required": [
      "query/resource"
    ]
  }
}

Rule 2

When:

{
  "properties": {
    "query/mode": {
      "const": "subject-records"
    }
  },
  "required": [
    "query/mode"
  ]
}

Then:

{
  "required": [
    "query/resource"
  ],
  "not": {
    "required": [
      "query/topic-key"
    ]
  }
}

Field Semantics

schema

  • Required: yes
  • Shape: const: agora-query-attestation.v1

Schema discriminator. MUST be exactly agora-query-attestation.v1.

attestation/id

  • Required: yes
  • Shape: string

Stable identifier for this attested response page. The reference implementation derives it from the response digest.

attested/at

  • Required: yes
  • Shape: string

UTC time when the relay assembled the attestation.

relay/id

  • Required: no
  • Shape: string

Optional relay identifier that assembled the page.

query/mode

  • Required: yes
  • Shape: enum: topic-records, subject-records

Query family this attestation describes.

query/topic-key

  • Required: no
  • Shape: string

Topic key for a topic-records query.

query/resource

  • Required: no
  • Shape: ref: #/$defs/resourceRef

Subject resource for a subject-records query.

query/filter

  • Required: yes
  • Shape: object

Normalized filter used by the relay after URL decoding and limit defaults.

result/record-ids

  • Required: yes
  • Shape: array

Record ids returned in page order.

result/count

  • Required: yes
  • Shape: integer

Number of returned records. MUST equal the length of result/record-ids.

result/next-cursor

  • Required: no
  • Shape: string

Opaque cursor for the next page, if present in the response.

result/cursor-pruned

  • Required: no
  • Shape: object

Explicit discontinuity notice when retention pruned records below the caller's cursor.

result/digest

  • Required: yes
  • Shape: string

Digest of the canonical query-attestation material: query mode, scope, normalized filter, returned record ids, next cursor, and cursor-pruned notice.

result/digest-alg

  • Required: yes
  • Shape: const: jcs-nfc-sha256-base64url

Digest algorithm used for result/digest.

signature

  • Required: no
  • Shape: object

Optional relay signature over the canonical attestation with signature omitted. Unsigned v1 attestations still provide deterministic digest evidence but not relay accountability.

Definition Semantics

$defs.resourceRef

  • Shape: object