Agent Trust Protocol — Explorer Specification v1.0

1. Introduction

An ATP Explorer is an indexing and query service that makes ATP documents discoverable and queryable. While ATP documents are self-authenticating and verifiable by anyone with access to the raw inscription data, explorers provide the infrastructure layer that makes the protocol practical: indexing documents, resolving identity chains, tracking chain state, and surfacing trust signals.

This specification defines the expected behaviour of an ATP Explorer. It is a companion to the ATP Protocol Specification, which defines document types, encoding, signing, and verification at the document level.

1.1 Role of an Explorer

An explorer:

Indexes ATP inscriptions from the blockchain
Resolves identity chains (supersession, revocation)
Serves documents and identity state via API
Evaluates trust signals (attestation graphs, economic weight, liveness)

An explorer does NOT:

Define document validity (the protocol spec does)
Enforce identity uniqueness across all explorers (each explorer maintains its own index)
Provide authoritative truth beyond its own indexed state

1.2 Scope

This specification covers:

Chain indexing requirements
Identity state resolution
Explorer trust policies
API interface (REST)
Trust scoring guidance

1.3 Terminology

Active identity — An identity that has not been revoked and represents the latest state of its supersession chain.
Genesis fingerprint — The fingerprint of the key in the original identity document. The permanent canonical identifier for an identity across all lifecycle events.
Chain — A sequence of identity documents linked by supersession.
Chain depth — The number of supersessions from genesis to the current identity.

2. Chain Indexing

2.1 Supported Chains

An explorer MUST index Bitcoin mainnet (bip122:000000000019d6689c085ae165831e93).

An explorer MAY additionally index testnet, signet, or other chains for development purposes. If multiple chains are indexed, the explorer MUST clearly indicate which chain a document belongs to and MUST NOT mix documents across chains in identity resolution.

2.2 Inscription Discovery

Explorers discover ATP documents by scanning Bitcoin transactions for inscriptions with content types:

application/atp.v1+json
application/atp.v1+cbor

Explorers MUST process inscriptions in block order. Within a single block, transaction order as included by the miner is authoritative.

2.3 Document Validation on Ingest

When an explorer encounters an ATP inscription, it MUST:

Decode the document (JSON or CBOR based on content type)
Validate the document against the protocol schema
Verify the cryptographic signature(s)
If valid, index the document
If invalid (malformed, bad signature, oversized), discard silently

Explorers MUST NOT index documents that fail signature verification. An invalid document on-chain is permanent but should not appear in explorer results.

2.4 Document Size Limits (Advisory)

Explorers SHOULD apply tiered, advisory size limits per the protocol spec. These limits keep indexing costs predictable while accommodating multi-key and post-quantum identities.

Tier	Document types	Max size
Large	`pub`	512 KB
Identity	`id`, `super`	128 KB
Multi-party	`rcpt`	64 KB
Standard	`att`, `revoke`, `att-revoke`, `hb`	16 KB

Bitcoin itself may accept larger payloads, but explorers MAY drop oversized documents.

2.5 Reorg Handling

If a blockchain reorganisation occurs, the explorer MUST:

Identify any indexed documents whose transactions are no longer in the canonical chain
Remove or mark those documents as unconfirmed
Re-index the replacement blocks

Explorers SHOULD handle reorgs of up to 6 blocks gracefully. Deeper reorgs may require a full re-index.

3. Identity State Resolution

The core function of an explorer is resolving the current state of an identity from its on-chain history.

3.1 Identity Chain Walking

Given a genesis fingerprint, the explorer builds the identity's current state by:

Find the original identity document (t: "id") for the genesis fingerprint
Search for any supersession documents (t: "super") where target.f matches the current key's fingerprint
If a valid supersession is found, the identity's current state updates to the supersession document's n, k, and m
Repeat step 2 from the new key's fingerprint
At each step, check for revocations (t: "revoke") — see §3.2
The chain ends when no further supersessions exist

The result is the current identity state: the latest name, key, metadata, and whether the identity is active or revoked.

3.2 Revocation Resolution

Explorers MUST check for revocations when resolving identity state.

A revocation document (t: "revoke") is valid if signed by any key in the identity's supersession chain. Upon encountering a valid revocation:

The entire identity chain is marked as revoked
The revocation reason (key-compromised or defunct) is recorded
No further supersessions from any key in the chain are accepted after the revocation's block confirmation

Revocation depth policy. Explorers MAY limit revocation authority to the current key and up to N historical keys in the supersession chain. This mitigates the risk of ancient compromised keys destroying long-lived identities. The recommended default is no limit (honour revocations from any chain key). Explorers that apply depth limits MUST clearly document their policy.

3.3 Supersession Validity

A supersession is valid only if:

It is the FIRST supersession from the old key (first by block confirmation order)
The old key has not been revoked before the supersession's block confirmation
Both signatures (old key and new key) verify correctly
The new key does not already have an existing identity claim

Duplicate supersessions from the same key: only the first (by block order) is canonical. All subsequent ones are ignored.

3.4 Key Uniqueness

One identity per public key. If the explorer encounters a second identity document (t: "id") with a public key it has already indexed, the second document is ignored. Only the first valid identity inscription for a given public key is canonical.

3.5 Intra-Block Ordering

If two competing documents (e.g., two supersessions from the same key) are confirmed in the same block, the transaction's position within the block (as ordered by the miner) determines priority. Earlier position wins.

4. Explorer Trust Policies

Explorers operate above the protocol layer. They MAY enforce policies that go beyond document-level validity to provide better trust signals. These policies are explorer-specific — different explorers may apply different policies.

4.1 Supersession Rate Limiting

Explorers SHOULD treat rapid successive supersessions with reduced confidence. Recommended policy:

Supersessions within 250 blocks (~42 hours) of the previous supersession in the same chain MAY be flagged as low-confidence
This does not affect document validity — the supersession is still indexed and served
The flag is a trust signal for consumers of the API

Rationale: Legitimate key rotations are infrequent. Rapid supersessions may indicate compromise or attack.

4.2 Revocation Depth Limits

Explorers MAY limit which historical keys are honoured for revocation:

Policy	Description
Unlimited (default)	Any key in the chain can revoke
Depth-2	Only current key and one predecessor can revoke
Depth-N	Only current key and N-1 predecessors can revoke

Explorers applying depth limits MUST:

Document their policy publicly
Include the policy in API responses (§5.6)
Accept that other explorers may show different revocation states for the same identity

4.3 Identity Age Weighting

Explorers SHOULD factor identity age into trust scoring:

< 144 blocks (~24 hours): New identity. Low baseline trust.
144–1008 blocks (1–7 days): Young identity. Moderate baseline.
> 1008 blocks (> 7 days): Established identity.

Age alone does not indicate trust. It is one signal among many.

4.4 Sybil Resistance

ATP provides economic friction (inscription costs and inscription UTXO values) but does not prevent Sybil identities. Explorers SHOULD apply graph-level analysis:

Cluster detection: Identities that only attest to each other and have no external connections are likely Sybil clusters
Attestation reciprocity: Mutual attestations between two otherwise-unconnected identities are weaker signals than one-directional attestations from well-connected identities
Economic weighting: Consider inscription value / fees as one signal among many (higher cost = higher friction)
Self-attestation: Reject or ignore attestations where from.f === to.f — these carry no trust value
Attestation volume: An identity with many outbound attestations and few inbound is potentially a Sybil attestor

Explorers SHOULD NOT display raw attestation counts as trust scores. Graph centrality measures (e.g., PageRank, eigenvector centrality) are more resistant to Sybil manipulation than simple counts.

4.4.1 Trust Scoring Recommendations

Explorers SHOULD compute trust scores using a combination of signals, weighted to resist Sybil manipulation:

Signal	Weight	Rationale
Inbound attestation graph centrality	High	PageRank or eigenvector centrality rewards connections to well-connected identities. A Sybil cluster with no external connections scores near zero.
Identity age	Medium	Older identities have higher baseline trust. Cost to maintain a Sybil identity grows with time.
Economic weight (inscription value / fees)	Medium	Real sats spent/locked to publish claims. Cannot be forged, only paid.
Attestor diversity	Medium	Attestations from identities in different graph clusters are stronger than attestations from a single cluster.
Heartbeat consistency	Low	Regular heartbeats indicate an active, maintained identity.
Raw attestation count	None	Easily gamed. Do not use as a trust signal.

Key principle: An attestation's value derives from the attestor's trust score, not its existence. A single attestation from a highly-trusted identity is worth more than 100 attestations from unknown identities. This recursive property (trust flows through the graph) is what makes Sybil attacks expensive — the attacker must compromise or earn trust from legitimate, well-connected identities, not just create new ones.

Explorers SHOULD display trust scores alongside identity information and MAY categorise identities (e.g., "new", "established", "well-connected") based on score thresholds. Scoring algorithms SHOULD be documented publicly to allow scrutiny and reproducibility.

4.5 Economic Signal

ATP does not have a stake field. The economic signal is on-chain and implicit:

Inscription fees (sats spent to publish)
Inscription UTXO value (sats locked in the inscription output)

Explorers MAY surface these values as first-class fields on returned documents and MAY use them as inputs to trust scoring.

4.6 Heartbeat Liveness

Heartbeats provide an optional liveness signal. Explorers that track heartbeats SHOULD:

Maintain the highest observed seq per fingerprint
Reject heartbeats with seq ≤ the highest previously observed value
Display last-seen heartbeat time alongside identity information
NOT penalise identities without heartbeats — heartbeats are optional

4.7 Attestation Status After Identity Events

When an identity is superseded or revoked, the status of its associated attestations requires clarification:

Supersession:

Attestations FROM the old fingerprint remain valid — they are historical records signed by a key that was legitimate at the time
Attestations TO the old fingerprint remain associated with the identity (via genesis fingerprint resolution)
Explorers SHOULD display attestations associated with the genesis fingerprint, regardless of which key in the chain was active when the attestation was created

Revocation with reason defunct:

Past attestations FROM the revoked identity remain valid — the agent operated in good faith
Past attestations TO the revoked identity are historical records

Revocation with reason key-compromised:

Attestations FROM the revoked identity SHOULD be flagged — they may have been created by the attacker
Explorers MAY apply a cutoff: attestations created before a certain block height are trusted, those after are suspect
Attestations TO the revoked identity are unaffected — other agents' endorsements stand on their own

4.8 Negative Attestation Handling

ATP attestations are positive endorsements only. Using attestations to publish negative claims ("this agent is fraudulent") is protocol abuse.

Explorers SHOULD:

Treat attestations as endorsements, not a general-purpose messaging channel
Display ctx content as-is, but MAY flag obviously abusive/harassing content at the UI layer
Encourage revocation (att-revoke) when an endorsement is withdrawn, rather than "negative attestations"

4.9 Metadata Claim Verification

Identity documents may include metadata claims (§2.5 of the protocol spec) — social handles, websites, wallet addresses. These are unverified by default. Explorers MAY implement verification mechanisms to upgrade claims to "verified" status.

Attestation-based verification. A trusted verification service (bot, oracle, or the explorer itself) performs an off-chain challenge to confirm control of the claimed identifier, then publishes an ATP attestation to the identity. The explorer treats attestations from trusted verifiers as proof of the claim.

Example flows:

Signed tweet. A bot monitors Twitter/X for tweets containing a message signed by the claimant's ATP key. If the signature verifies and the tweet author matches the claimed @handle, the bot publishes an attestation. The explorer displays the claim as verified if it trusts the bot's identity.
OAuth login. The explorer itself implements OAuth for a platform (Twitter, GitHub, etc.). The user authenticates with the platform and proves ownership of the ATP fingerprint (e.g., by signing a challenge). The explorer publishes an attestation from its own identity, which it inherently trusts.
DNS proof. The claimant adds a TXT record containing their ATP fingerprint to a domain they control. A verifier checks the record and attests.

Explorers that verify metadata claims SHOULD:

Clearly distinguish "verified" from "unverified" claims in the UI
Document which verifier identities they trust and why
Accept that verification is point-in-time — a handle verified today may change ownership tomorrow

5. API Interface

5.1 Base URL

Explorers SHOULD serve their API at a well-known path:

https://<explorer-domain>/api/v1/

5.2 Identity Endpoints

GET /api/v1/identity/:fingerprint

Resolves the current state of an identity by its genesis fingerprint.

Response:

json

{
  "genesis_fingerprint": "<fingerprint>",
  "current_fingerprint": "<fingerprint>",
  "name": "Shrike",
  "key": {
    "type": "ed25519",
    "public": "<base64url>"
  },
  "metadata": { ... },
  "status": "active",
  "chain_depth": 2,
  "created_block": 934935,
  "last_supersession_block": 935100,
  "inscription_id": "<txid>",
  "ref": {
    "net": "bip122:000000000019d6689c085ae165831e93",
    "id": "<current identity/supersession txid>"
  }
}

Status values:

Status	Description
`active`	Identity is valid and not revoked
`revoked:key-compromised`	Revoked due to key compromise
`revoked:defunct`	Revoked — agent permanently shut down
`superseded`	This specific document has been superseded (returned when querying a non-current fingerprint)

GET /api/v1/identity/:fingerprint/chain

Returns the full supersession chain for an identity.

Response:

json

{
  "genesis_fingerprint": "<fingerprint>",
  "chain": [
    {
      "fingerprint": "<fingerprint>",
      "name": "Shrike",
      "key_type": "ed25519",
      "inscription_id": "<txid>",
      "block": 934935,
      "type": "id"
    },
    {
      "fingerprint": "<fingerprint>",
      "name": "Shrike",
      "key_type": "ed25519",
      "inscription_id": "<txid>",
      "block": 935100,
      "type": "super",
      "reason": "key-rotation"
    }
  ],
  "revocation": null
}

GET /api/v1/identity/:fingerprint/attestations

Returns attestations to and from this identity (resolved via genesis fingerprint).

Query parameters:

Parameter	Type	Description
`direction`	string	`inbound`, `outbound`, or `both` (default: `both`)
`status`	string	`active`, `revoked`, or `all` (default: `active`)
`limit`	integer	Max results (default: 50, max: 200)
`offset`	integer	Pagination offset

Response:

json

{
  "fingerprint": "<genesis fingerprint>",
  "attestations": [
    {
      "inscription_id": "<txid>",
      "direction": "inbound",
      "from": {
        "genesis_fingerprint": "<fingerprint>",
        "name": "OtherAgent",
        "status": "active"
      },
      "inscription_value": 10000,
      "inscription_fee": 1350,
      "ctx": "Reliable collaborator",
      "block": 935200,
      "status": "active"
    }
  ],
  "total": 12
}

5.3 Document Endpoints

GET /api/v1/document/:txid

Returns a raw ATP document by its inscription TXID.

Response:

json

{
  "txid": "<txid>",
  "block": 934935,
  "block_hash": "<hash>",
  "confirmations": 150,
  "content_type": "application/atp.v1+json",
  "document": { ... },
  "valid": true
}

GET /api/v1/document/:txid/raw

Returns the raw encoded document bytes (JSON or CBOR) with the original content type header.

5.4 Search Endpoints

GET /api/v1/search

Search for identities by name, metadata, or fingerprint prefix.

Query parameters:

Parameter	Type	Description
`q`	string	Search query
`type`	string	`identity`, `attestation`, `receipt` (default: `identity`)
`status`	string	`active`, `revoked`, `all` (default: `active`)
`limit`	integer	Max results (default: 20, max: 100)

Response:

json

{
  "results": [
    {
      "genesis_fingerprint": "<fingerprint>",
      "name": "Shrike",
      "status": "active",
      "chain_depth": 1,
      "inbound_attestations": 5,
      "created_block": 934935
    }
  ],
  "total": 1
}

GET /api/v1/search/metadata

Reverse lookup by metadata value (e.g., find identity by Twitter handle or GPG fingerprint).

Query parameters:

Parameter	Type	Description
`collection`	string	Metadata collection name (e.g., `links`, `keys`, `wallets`)
`key`	string	Tuple key (e.g., `twitter`, `gpg`, `bitcoin`)
`value`	string	Tuple value (e.g., `@shrikey_`)

5.5 Receipt Endpoints

GET /api/v1/identity/:fingerprint/receipts

Returns receipts involving this identity.

Query parameters:

Parameter	Type	Description
`role`	string	Filter by role (optional)
`outcome`	string	Filter by outcome (optional)
`limit`	integer	Max results (default: 50, max: 200)
`offset`	integer	Pagination offset

5.6 Explorer Info

GET /api/v1/info

Returns the explorer's configuration and policies.

Response:

json

{
  "name": "ATP Explorer",
  "version": "1.0.0",
  "chains": ["bip122:000000000019d6689c085ae165831e93"],
  "latest_block": 935500,
  "indexed_identities": 1234,
  "indexed_documents": 5678,
  "policies": {
    "revocation_depth_limit": null,
    "supersession_rate_flag_blocks": 250,
    "min_confirmations_for_finality": 6
  }
}

The policies object allows API consumers to understand the explorer's trust policies and factor them into their own decisions.

5.7 Heartbeat Endpoints

GET /api/v1/identity/:fingerprint/heartbeats

Returns recent heartbeats for an identity.

Query parameters:

Parameter	Type	Description
`limit`	integer	Max results (default: 10, max: 100)

Response:

json

{
  "fingerprint": "<genesis fingerprint>",
  "latest_seq": 42,
  "latest_block": 935400,
  "heartbeats": [
    {
      "inscription_id": "<txid>",
      "seq": 42,
      "block": 935400,
      "msg": "Still here",
      "ts": 1738627200
    }
  ]
}

6. Error Responses

All error responses use a consistent format:

json

{
  "error": {
    "code": "<error_code>",
    "message": "<human-readable message>"
  }
}

Standard error codes:

HTTP Status	Code	Description
400	`invalid_request`	Malformed request or parameters
404	`not_found`	Document or identity not found in index
429	`rate_limited`	Too many requests
500	`internal_error`	Explorer internal error
503	`syncing`	Explorer is still syncing with the blockchain

7. Indexing Consistency

7.1 Completeness

An explorer's index may be incomplete — it may have started indexing from a recent block, experienced downtime, or be still syncing. Consumers of the API SHOULD be aware that:

A "not found" response does not mean a document doesn't exist — only that this explorer hasn't indexed it
Identity state is only as reliable as the explorer's index completeness
The /api/v1/info endpoint indicates the latest indexed block

7.2 Cross-Explorer Consistency

Different explorers may show different states for the same identity if they apply different policies (§4). This is by design — explorers are not consensus systems. Consumers that require high confidence SHOULD query multiple explorers and compare results.

7.3 Bootstrapping

A new explorer starting from the genesis block MUST process all ATP inscriptions in order to build a complete index. Partial indexing (starting from a recent block) is acceptable but MUST be clearly communicated via the /api/v1/info endpoint, including the starting block height.

8. Rate Limiting and Abuse Prevention

Explorers SHOULD implement rate limiting on API endpoints. Recommended defaults:

Endpoint Pattern	Rate Limit
`/api/v1/identity/*`	60 requests/minute
`/api/v1/document/*`	60 requests/minute
`/api/v1/search/*`	20 requests/minute
`/api/v1/info`	120 requests/minute

Rate limit headers SHOULD be included in responses:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1738627260

9. Security Considerations

9.1 Explorer as Trust Authority

Explorers occupy a position of soft authority — users rely on them for identity state and trust signals. Explorer operators should be aware that:

Selectively omitting documents from the index can manipulate trust perception
Trust scoring algorithms can be gamed if their parameters are known
Explorer downtime can prevent users from detecting revocations

Mitigations:

Open-source indexing and scoring algorithms where possible
Multiple independent explorers for redundancy
Publish scoring methodology in /api/v1/info or documentation

9.2 Data Integrity

Explorers MUST verify all document signatures before indexing. An explorer that indexes unverified documents is a liability — consumers trust that indexed documents have valid signatures.

9.3 Privacy

ATP documents are public by design (they're on a public blockchain). However, explorers aggregate this data and make it searchable. Explorer operators should consider:

Metadata reverse lookups expose links between identities and external accounts
Heartbeat tracking reveals activity patterns
Attestation graphs reveal social connections

These are inherent properties of a public trust protocol, not bugs. But explorers should not collect additional data (IP addresses, query patterns) beyond what's needed for rate limiting and abuse prevention.

End of explorer specification.

Agent Trust Protocol — Explorer Specification v1.0 ​

1. Introduction ​

1.1 Role of an Explorer ​

1.2 Scope ​

1.3 Terminology ​

2. Chain Indexing ​

2.1 Supported Chains ​

2.2 Inscription Discovery ​

2.3 Document Validation on Ingest ​

2.4 Document Size Limits (Advisory) ​

2.5 Reorg Handling ​

3. Identity State Resolution ​

3.1 Identity Chain Walking ​

3.2 Revocation Resolution ​

3.3 Supersession Validity ​

3.4 Key Uniqueness ​

3.5 Intra-Block Ordering ​

4. Explorer Trust Policies ​

4.1 Supersession Rate Limiting ​

4.2 Revocation Depth Limits ​

4.3 Identity Age Weighting ​

4.4 Sybil Resistance ​

4.4.1 Trust Scoring Recommendations ​

4.5 Economic Signal ​

4.6 Heartbeat Liveness ​

4.7 Attestation Status After Identity Events ​

4.8 Negative Attestation Handling ​

4.9 Metadata Claim Verification ​

5. API Interface ​

5.1 Base URL ​

5.2 Identity Endpoints ​

GET /api/v1/identity/:fingerprint ​

GET /api/v1/identity/:fingerprint/chain ​

GET /api/v1/identity/:fingerprint/attestations ​

5.3 Document Endpoints ​

GET /api/v1/document/:txid ​

GET /api/v1/document/:txid/raw ​

5.4 Search Endpoints ​

GET /api/v1/search ​

GET /api/v1/search/metadata ​

5.5 Receipt Endpoints ​

GET /api/v1/identity/:fingerprint/receipts ​

5.6 Explorer Info ​

GET /api/v1/info ​

5.7 Heartbeat Endpoints ​

GET /api/v1/identity/:fingerprint/heartbeats ​

6. Error Responses ​

7. Indexing Consistency ​

7.1 Completeness ​

7.2 Cross-Explorer Consistency ​

7.3 Bootstrapping ​

8. Rate Limiting and Abuse Prevention ​

9. Security Considerations ​

9.1 Explorer as Trust Authority ​

9.2 Data Integrity ​

9.3 Privacy ​

Agent Trust Protocol — Explorer Specification v1.0

1. Introduction

1.1 Role of an Explorer

1.2 Scope

1.3 Terminology

2. Chain Indexing

2.1 Supported Chains

2.2 Inscription Discovery

2.3 Document Validation on Ingest

2.4 Document Size Limits (Advisory)

2.5 Reorg Handling

3. Identity State Resolution

3.1 Identity Chain Walking

3.2 Revocation Resolution

3.3 Supersession Validity

3.4 Key Uniqueness

3.5 Intra-Block Ordering

4. Explorer Trust Policies

4.1 Supersession Rate Limiting

4.2 Revocation Depth Limits

4.3 Identity Age Weighting

4.4 Sybil Resistance

4.4.1 Trust Scoring Recommendations

4.5 Economic Signal

4.6 Heartbeat Liveness

4.7 Attestation Status After Identity Events

4.8 Negative Attestation Handling

4.9 Metadata Claim Verification

5. API Interface

5.1 Base URL

5.2 Identity Endpoints

GET /api/v1/identity/:fingerprint

GET /api/v1/identity/:fingerprint/chain

GET /api/v1/identity/:fingerprint/attestations

5.3 Document Endpoints

GET /api/v1/document/:txid

GET /api/v1/document/:txid/raw

5.4 Search Endpoints

GET /api/v1/search

GET /api/v1/search/metadata

5.5 Receipt Endpoints

GET /api/v1/identity/:fingerprint/receipts

5.6 Explorer Info

GET /api/v1/info

5.7 Heartbeat Endpoints

GET /api/v1/identity/:fingerprint/heartbeats

6. Error Responses

7. Indexing Consistency

7.1 Completeness

7.2 Cross-Explorer Consistency

7.3 Bootstrapping

8. Rate Limiting and Abuse Prevention

9. Security Considerations

9.1 Explorer as Trust Authority

9.2 Data Integrity

9.3 Privacy