Skip to Content
Reference ImplementationsATL-CoreAPI Reference

API reference

Types and functions exported by ATL-Core.

Prelude

Import common types with a single statement:

use atl_core::prelude::*;

Core types

Receipt

The main structure representing an ATL receipt (.atl file).

pub struct Receipt {
    pub spec_version: String,
    pub upgrade_url: Option<String>,
    pub entry: ReceiptEntry,
    pub proof: ReceiptProof,
    pub super_proof: Option<SuperProof>,
    pub anchors: Vec<ReceiptAnchor>,
}

Methods:

  • Receipt::from_json(&str) — parse receipt from JSON string
  • receipt.to_json() — serialize to JSON string
  • receipt.tier() — get receipt tier (Full, Tsa, Lite)

ReceiptEntry

pub struct ReceiptEntry {
    pub id: Uuid,
    pub payload_hash: String,
    pub metadata_hash: String,
    pub metadata: serde_json::Value,
}

ReceiptProof

pub struct ReceiptProof {
    pub tree_size: u64,
    pub root_hash: String,
    pub inclusion_path: Vec<String>,
    pub leaf_index: u64,
    pub checkpoint: CheckpointJson,
    pub consistency_proof: Option<ReceiptConsistencyProof>,
}

SuperProof

pub struct SuperProof {
    pub genesis_super_root: String,
    pub data_tree_index: u64,
    pub super_tree_size: u64,
    pub super_root: String,
    pub inclusion: Vec<String>,
    pub consistency_to_origin: Vec<String>,
}

ReceiptTier

Receipt completeness levels as defined in the protocol specification:

  • Lite — no super_proof, OR super_proof present but missing RFC 3161 anchor (internal consistency only)
  • Tsa — has super_proof + RFC 3161 anchor (but no Bitcoin OTS) (Receipt-TSA per spec)
  • Full — has super_proof + RFC 3161 + Bitcoin OTS anchors (Receipt-Full per spec)

For maximum trust, receipts should have both RFC 3161 and Bitcoin OTS anchors (tier Full).

Verification

ReceiptVerifier

// Anchor-only verification (recommended)
let verifier = ReceiptVerifier::anchor_only();
 
// With optional signature integrity check
let verifier = ReceiptVerifier::with_key(checkpoint_verifier);
 
// Verify a receipt
let result: VerificationResult = verifier.verify(&receipt);

VerificationResult

pub struct VerificationResult {
    pub is_valid: bool,
    pub leaf_hash: [u8; 32],
    pub root_hash: [u8; 32],
    pub tree_size: u64,
    pub timestamp: u64,
    pub signature_valid: bool,
    pub signature_status: SignatureStatus,
    pub inclusion_valid: bool,
    pub consistency_valid: Option<bool>,
    pub super_inclusion_valid: bool,
    pub super_consistency_valid: bool,
    pub genesis_super_root: [u8; 32],
    pub super_root: [u8; 32],
    pub data_tree_index: u64,
    pub super_tree_size: u64,
    pub anchor_results: Vec<AnchorVerificationResult>,
    pub errors: Vec<VerificationError>,
}

Notes:

  • signature_valid is deprecated; prefer signature_status for detailed outcome.

Methods:

  • result.has_valid_anchor() — at least one anchor verified

SignatureMode

  • Require — signature MUST verify successfully
  • Optional — verify if key provided, skip otherwise (default)
  • Skip — never verify signature, rely only on anchors

SignatureStatus

  • Verified — signature checked and valid
  • Failed — signature checked and invalid
  • Skipped — signature not checked
  • KeyMismatch — provided key doesn’t match checkpoint

Verification functions

Anchor-only (recommended):

let result = verify_receipt_anchor_only(&receipt)?;
let result = verify_receipt_json_anchor_only(json_str)?;

With public key:

let result = verify_receipt_with_key(&receipt, &public_key_bytes)?;
let result = verify_receipt_json_with_key(json_str, &public_key_bytes)?;

Checkpoint

CheckpointVerifier

let verifier = CheckpointVerifier::from_bytes(&public_key_bytes)?;
let checkpoint = Checkpoint::from_json(&checkpoint_json)?;
checkpoint.verify(&verifier)?;

Merkle tree

Hash

pub type Hash = [u8; 32];

Functions

  • compute_leaf_hash(payload_hash, metadata_hash) — compute leaf hash
  • compute_root(leaves) — compute Merkle root from leaves
  • verify_inclusion(...) — verify inclusion proof
  • verify_consistency(...) — verify consistency proof

JCS

let canonical = canonicalize(&json_value);
let hash: Hash = canonicalize_and_hash(&json_value);

Error types

AtlError

Main error enum (selected variants):

  • InvalidHash — invalid hash format or length
  • SignatureInvalid — signature verification failed
  • InvalidSignature — invalid signature format
  • InvalidPublicKey — invalid public key bytes
  • InclusionProofInvalid — inclusion proof verification failed
  • ConsistencyProofInvalid — consistency proof verification failed
  • InvalidProofPath — wrong number of hashes in proof
  • InvalidReceipt — receipt JSON parsing failed / missing required fields
  • UnsupportedReceiptVersion — unsupported spec_version

AtlResult<T>

Type alias for Result<T, AtlError>.

Last updated on
InstallationExamples