Skip to main content
Version: Stage 5 - Deliverable Acceptance Check

Verifiable History and Lifecycle Management

Introduction​

This document discusses the need for the GRID operation, GRID Participants and other UNTP implementations to be able address "point-in-time" queries for supply-chain trade transactions. It then derives the design principles to meet this need and presents the chosen design pattern for the GRID.

This document serves to provide a focused explanation of why we need to address history, and how we have chosen to do so. The design pattern explained and described here has also been used in the GRID documentation when relevant.

The document is in two parts:

  • Part 1 presents the need to consider history from a business, legal and audit perspective.

  • Part 2 describes the technical design and blueprint.

Problem Summary​

In cross-border trade, regulatory compliance, and commercial dispute resolution, identity verification is rarely a question of "what is true right now." Commercial transactions operate across extended time horizons: goods take weeks to transport, trade finance facilities take months to settle, and customs audits, tax reviews, or arbitral proceedings frequently occur three to seven years after a shipment took place.

Traditional digital identity frameworks suffer from current-state bias: registries display only today's live status, and standard web identifiers overwrite keys in place. If an Authoritative Registrar rotates its key, suspends a record, or withdraws from the directory, a naive verification check conducted during a future audit will fail—destroying cross-border legal trust.

Document Structure​

This document establishes the normative architecture for Verifiable History across the GRID ecosystem. It is divided into two distinct parts:

  1. Part 1: The Business, Legal, and Audit Rationale (Non-Technical): An accessible analysis of the "Right Now" fallacy, the three independent status dimensions, and the foundational requirements for legal certainty across time.
  2. Part 2: Technical Design Pattern and Implementation Blueprint (Engineering Focus): A detailed technical specification detailing the did:webvh key provenance model, signed directory snapshot manifests, and the deterministic "Latest-Before" verification algorithm.

1.1 The "Right Now" Fallacy in Cross-Border Trade​

Most digital systems are built on a simple premise: a client queries a server, and the server returns the current state of a database. When website URLs are resolved the domain credentials are checked for currency. This model is also present in digital identity and authentication. A relying party asks: "Is this credential active right now?"

In international supply chains, this model risks not satisfying the verification requirement. Consider a routine trade scenario spanning several years:

  1. Year 01 (Transaction Date T_tx): An agricultural exporter issues a digitally signed Commercial Invoice and Compliance Certificate (Phytosanitary, say). The exporter's identity is anchored in a Digital Identity Anchor (DIA) issued by its national business registry. The registry is an active Member of the GRID, and the invoice is financed by a trade bank.

  2. Year 02: The national business registrar undergoes a scheduled cryptographic key rollover, retiring the private key that signed the Year 01 DIA and deploying a new key pair.

  3. Year 03: The exporter undergoes a corporate merger, transitioning its legal form and receiving an updated registration identifier.

  4. Year 04: Due to a shift in national agency responsibilities, the original registrar transfers its registrar authority to a new department and withdraws its legacy registry listing from the active GRID directory.

  5. Year 05 (Audit Date T_audit): A customs authority conducts a post-clearance audit regarding tariff classification, or an arbitral tribunal hears a breach-of-contract dispute. The auditor asks:

    "Was this exporter a legally recognized corporation in good standing on shipment date T_tx in Year 01? Was the national registrar an authoritative source listed in the GRID on that date, and was the signature applied using a key validly authorized on that date?"

If the verification software performs a real-time lookup against live endpoints in Year 05:

  • The GRID active directory reports: Registrar: Withdrawn / Not Found.
  • The Registrar's current public key fails to validate the Year 01 signature.
  • The Registrar's live database reports: Entity: Restructured / Lapsed.

The verifier reaches an erroneous conclusion: that the Year 01 transaction was fraudulent or unverified. This breakdown is the "Right Now" Fallacy. A system that can only attest to current status is incomplete for international commerce.

1.2 The Three Orthogonal Status Dimensions​

A primary cause of architectural failure in digital registry projects is the conflation of different lifecycles into a single binary flag (such as "valid" or "revoked"). In the GRID ecosystem, status is disaggregated into three independent, orthogonal dimensions:

  1. GRID Participation Status

  2. Legal Standing

  3. Verification Key Status

An overview of the separate lifecycles of these dimensions is given in the following subsections.

1. Participation Status (GRID Board Governance)​

Reflects whether an Authoritative Registrar is an admitted member of the GRID.

  • States: Applicant, Member, Suspended, Withdrawn, Delisted, Preserved in Archive.
  • Authority: Governed administratively by the UN Member States through the GRID Board under the Target Operating Model.
  • Separation Rule: Withdrawal from the GRID ends active discovery for new transactions. It does not alter domestic statutory registrations, nor does it extinguish the evidentiary validity of past transactions executed while the Registrar was an active Member.

Reflects whether the Registrar holds legal competence under the national constitution or statutory legislation of its UN Member State.

  • States: Authoritative-Active, Mandate-Suspended, Mandate-Expired.
  • Authority: Governed strictly by national parliaments and sovereign public law.
  • Separation Rule: The GRID possesses zero legal authority to grant, modify, suspend, or terminate a national Registrar's statutory authority. A national register remains legally authoritative under domestic law regardless of its standing with the GRID.

3. Verification Key Status (Cryptographic Lifecycle)​

Reflects the operational security state of the mathematical key pairs used to authenticate records and sign DIAs.

  • States: Active, Rotated, Compromised, Retired.
  • Authority: Managed by the Registrar's technical operators and security officers.
  • Separation Rule: A planned key rotation does not invalidate credentials signed under the retired key. Conversely, a private key compromise invalidates trust retrospectively back to the point of compromise, without implying that the Registrar's legal mandate has ceased.

1.3 Foundational Requirements and Principles​

To resolve these challenges, any compliant implementation of the GRID and DIA architecture must adhere to five core principles:

Principle 1: Deterministic "As-Of" Verification​

A verifier must be able to evaluate the validity of an assertion as it applied to a specific historical point in time (T_tx), rather than evaluating against the present state of the system. Given the authoritative event logs and historical directory archive, the retrospective evaluation of T_tx must be mathematically deterministic and reproducible across all verifiers.

Furthermore, the evaluation must correctly incorporate any authoritative retroactive determinations established in the record—such as a verified cryptographic key compromise timestamp (T_comp) or an administrative or judicial annulment ab initio—where the effective date of invalidation precedes T_tx.

Principle 2: Separation of Rotation from Compromise​

  • Routine Key Rotation: Old public keys remain trusted for signatures created prior to the rotation timestamp. Verifiability is permanently preserved.
  • Key Compromise: If a private key is exposed, an emergency revocation records a verified compromise timestamp (T_comp). All signatures asserted to have been created after T_comp are treated as invalid, while pre-compromise historical evidence is cryptographically segregated.

Principle 3: Partitioned Discovery and Archival​

The directory operates two distinct interfaces:

  • Active Discovery Layer: Displays only currently authorized, active Registrars (participationStatus: Member). Suspended or withdrawn Registrars are excluded immediately to prevent reliance on new transactions.
  • Historical Verification Archive: An append-only, tamper-evident repository containing every past version, release snapshot, and retired key. Withdrawn entries are flagged as Historical Reference Only - Not Active for Current Reliance.

Principle 4: Explicit Indeterminacy (No Inferred State)​

If the available cryptographic logs or directory archives cannot prove the status of a key, registrar, or credential on date T_tx, the verification algorithm must explicitly return INDETERMINATE. A system must never infer that a credential was valid in the past merely because it is active today, nor assume it was invalid merely because an endpoint is currently offline.

Principle 5: Decentralized Provenance without Distributed Ledgers​

Historical verifiability must not depend on commercial blockchain networks, volatile cryptocurrency fees, or heavyweight consensus protocols. Tamper evidence must be achieved using self-certifying data structures, cryptographic hash chains, and standardized web infrastructure.

Part 2: Technical Design Pattern and Implementation Blueprint​

2.1 Architecture and Issuer-Hosted Storage​

Historical verification in the GRID follows the UNTP Issuer-Hosted Model. Each issuing entity publishes, maintains, and cryptographically signs its own records in a trustworthy web space that it controls:

  1. Tier 1 (Global Directory Layer): The GRID publishes signed snapshot manifests and hosts Tier 1 Recognition DIAs for participating Registrars.
  2. Tier 2 (National Registrar Layer): The Authoritative Registrar publishes its cryptographic key history using a did:webvh log, issues Tier 2 Entity DIAs, and maintains its local status mechanisms.
  3. Tier 3 (Commercial Transaction Layer): The trading entity signs business documents using its private key, embedding a reference to its Tier 2 DIA hosted in the national register.

2.2 Key Provenance via did:webvh​

To ensure that a Registrar's verification keys can be reconstructed at any historical point in time without relying on mutable DNS entries or centralized ledgers, the GRID architecture specifies the did:webvh (DID Web with Verifiable History) method1.

Architectural Vulnerability of Plain did:web​

Under standard did:web2, an identifier resolves to a live JSON file hosted at a well-known URL:

  • did:web:example.org resolves to example.org/.well-known/did.json Because web servers are mutable, an operator can overwrite this file at any time. If an attacker compromises a server in 2026, they can back-date a newly injected key to 2021, forge historic corporate attestations, and erase the genuine key history without leaving cryptographic evidence.

The did:webvh Solution​

did:webvh converts the mutable web DID into an immutable, self-certifying event log hosted over standard HTTPS:

  1. Self-Certifying Identifier (SCID): The identifier incorporates a cryptographic hash of its initial inception parameters: did:webvh:{SCID}:example.org Once created, the SCID binds the identifier permanently to its origin state.
  2. Hash-Chained Log File (did.jsonl): Instead of serving only the current DID document, the server hosts an append-only log file: example.org/.well-known/did.jsonl Each line in this file represents a version update. Every entry contains:
    • A version number (versionId).
    • The cryptographic hash of the preceding entry (versionHash).
    • The timestamp of publication (validFrom).
    • The updated DID document state.
    • A cryptographic signature created by the authorized key.
  3. Cryptographic Pre-Rotation (nextKeyHashes): In entry (N), the Registrar commits to the cryptographic hash of the key that will sign entry (N+1). Even if an attacker steals the active private signing key, they cannot forge a valid successor log entry because they cannot produce a key matching the pre-committed hash.

Structure of a did.jsonl Entry​

{
  "versionId": 2,
  "versionHash": "QmZ3K8PrecedingEntryHashValue123456789abcdef",
  "validFrom": "2024-01-15T00:00:00Z",
  "nextKeyHashes": ["E987654321FedcbaHashOfFutureKeyCommitment"],
  "state": {
    "id": "did:webvh:QmOriginSCID12345:registry.example.org",
    "verificationMethod": [{
      "id": "did:webvh:QmOriginSCID12345:registry.example.org#key-2",
      "type": "JsonWebKey2020",
      "controller": "did:webvh:QmOriginSCID12345:registry.example.org",
      "publicKeyJwk": { "kty": "OKP", "crv": "Ed25519", "x": "Def...KeyData" }
    }],
    "assertionMethod": ["did:webvh:QmOriginSCID12345:registry.example.org#key-2"]
  },
  "proof": [{
    "type": "DataIntegrityProof",
    "cryptosuite": "eddsa-jcs-2022",
    "verificationMethod": "did:webvh:QmOriginSCID12345:registry.example.org#key-1",
    "proofValue": "zSignatureOverLogEntry2SignedByKey1"
  }]
}

2.3 Directory Snapshots and Signed Manifests​

To provide reproducible historical evidence at the directory level, the GRID Hub generation pipeline produces an authenticated Snapshot Manifest for each scheduled publication release.

Mechanism​

  1. Periodic Ingestion: The GRID Harvester retrieves authenticated registrar.json metadata from all participating Sovereign Nodes.
  2. Release Artifact Generation: The pipeline compiles the complete directory into machine-readable files (e.g. grid-directory.csv and grid-directory.json).
  3. Manifest Creation: The generator computes the cryptographic hash (SHA-256) of the compiled directory files and wraps them in a signed JSON manifest:
    • release_id: A monotonically increasing release sequence (e.g. Release 2026.04).
    • published_at: Canonical ISO 8601 UTC timestamp.
    • previous_manifest_hash: The SHA-256 hash of the preceding release manifest, establishing a linear tamper-evident chain.
    • directory_hash: The SHA-256 hash of the directory payload.
    • active_members_count: Total active participants.
    • proof: A digital signature generated by the GRID Root Authority key.
  4. Historical Archiving: Every snapshot manifest and directory release is permanently archived at: {GRID_BASE_URL}/archive/{release_id}/manifest.json

Offline relying parties (such as customs border systems operating with intermittent connectivity) download and cache these signed manifests. Verifiers reject any manifest older than their configured maximum cache age to prevent rollback attacks.

2.4 The Point-in-Time Verification Algorithm​

When an auditor or relying party evaluates a business transaction signed on historical date T_tx, the verification software executes a "Latest-Before" Point-in-Time Algorithm:

Algorithmic Step-by-Step Logic​

ALGORITHM: EvaluatePointInTimeTransaction(Document, T_tx)

INPUT: 
  Document: Digitally signed commercial trade payload
  T_tx: ISO 8601 UTC transaction timestamp asserted on Document

OUTPUT: 
  Status: { VERIFIED, INVALID, INDETERMINATE }
  DiagnosticLog: Structured verification evidence report

PROCEDURE:
1. Verify Document Signature:
   - Extract subject DID and signature from Document.
   - Resolve subject DID document at time T_tx.
   - If signature is mathematically invalid, RETURN (INVALID, "Subject signature invalid").

2. Resolve Tier 2 Entity DIA:
   - Dereference the DIA URI linked in the Document from Registrar's trustworthy space.
   - Verify that Document subject DID matches DIA's decentralizedIdentifier.identifier.
   - Verify that DIA authoritativeIdentifier matches national registration claimed.

3. Resolve Registrar Key Provenance at T_tx:
   - Fetch Registrar's did.jsonl from {REGISTRY_URL}/.well-known/did.jsonl.
   - Verify cryptographic hash chain from inception (SCID) to latest entry.
   - Locate the latest log entry where: validFrom <= T_tx.
   - Check for Compromise Declaration:
     * IF log contains compromise notice with T_comp <= T_tx:
         RETURN (INVALID, "Registrar signing key was compromised prior to transaction").
   - Extract public verification key active at T_tx.
   - Verify DIA signature against this historic public key.
   - If DIA signature does not verify, RETURN (INVALID, "DIA signature invalid for historic key").

4. Check Entity DIA Status at T_tx:
   - Resolve Registrar's credentialStatus endpoint.
   - If status mechanism supports historical queries, evaluate state at T_tx.
   - If DIA was REVOKED or SUSPENDED on or before T_tx:
       RETURN (INVALID, "Entity registration was suspended/revoked on transaction date").

5. Check GRID Directory Standing at T_tx:
   - Query GRID Historical Verification Archive for Snapshot Manifest covering T_tx:
     * Find Manifest where: validFrom <= T_tx < validUntil.
   - Verify GRID Hub signature on Manifest.
   - Locate Registrar record in Manifest payload:
     * Confirm participationStatus == "Member".
     * Confirm mandateStatus == "Authoritative-Active".
     * Confirm registered public key / DID matches the key resolved in Step 3.
   - IF Registrar was not an active Member on date T_tx:
       RETURN (INVALID, "Registrar was not an active GRID participant on transaction date").

6. Evaluation Complete:
   - IF all steps confirm valid evidence:
       RETURN (VERIFIED, "Transaction verified with point-in-time certainty as-of T_tx").
   - ELSE IF required historical logs or snapshots are unresolvable:
       RETURN (INDETERMINATE, "Historical records incomplete to establish proof at T_tx").

2.5 Security and Failure Mode Handling​

Routine Key Rotation vs. Key Compromise Handling​

The following normative matrix governs how the GRID and relying parties handle key events:

Event TypeInfrastructure ActionHistorical Signatures (T < T_event)Future Signatures (T >= T_event)
Scheduled Key Rotation1. Generate new key pair in secure HSM.
2. Append update entry to did.jsonl signed with prior key and matching nextKeyHashes.
3. Publish updated metadata to GRID Sovereign Node.		REMAIN VERIFIED. Prior keys are retained in did.jsonl with retired status.Must be signed by the newly activated key.
Suspected Private Key Compromise1. Security Officer executes emergency revocation.
2. Append compromise notice to did.jsonl recording exact timestamp T_comp.
3. Notify GRID Secretariat immediately.
4. GRID flags key status as Compromised in directory releases.		CONDITIONAL. Signatures proven to pre-date T_comp remain verifiable. Signatures post-dating T_comp are INVALID.REJECTED. Compromised key is revoked globally.
Registrar Voluntary Withdrawal1. Registrar provides 30 days' notice to Secretariat.
2. GRID removes Registrar from Active Discovery Layer.
3. Directory pipeline transfers all records, public keys, and past snapshots to Historical Verification Archive.		REMAIN VERIFIED. Relying parties verify past transactions via the Historical Archive using the as-of algorithm.New transactions cannot be verified through GRID active discovery.

3. Conformance and Implementation Checklist for Implementors​

To achieve conformance with the GRID Verifiable History specification, software engineers implementing Sovereign Nodes and Relying Party verifiers must satisfy the following checklist:

  • Sovereign Node / Registrar:

    • DID implementation utilizes did:webvh with an immutable SCID.
    • The did.jsonl log is publicly accessible at /.well-known/did.jsonl over HTTPS.
    • Every key update incorporates a forward cryptographic commitment in nextKeyHashes.
    • Prior public keys are never deleted from did.jsonl following rotation.
    • Entity DIAs issued by the Registrar cite the permanent, dereferenceable URL in the Registrar's space.

  • GRID Hub / Harvester:

    • Ingestion pipeline validates participant did.jsonl logs from origin to tip.
    • Directory generation pipeline signs a Snapshot Manifest for every release.
    • Signed Snapshot Manifests are permanently indexed in the Historical Verification Archive.
    • Withdrawn participants are removed from active discovery but preserved in the archive with Historical Reference Only designations.

  • Relying Party / Verifier Applications:

    • Verification logic parses transaction time T_tx from the business document.
    • Key resolution queries the historic key active at T_tx rather than the live tip of the log.
    • Status evaluation applies the "Latest-Before" logic against historical status logs.
    • Missing or unresolvable historical records explicitly return INDETERMINATE rather than falling back to current state.

Footnotes​

  1. did:webvh method specification v1.0 ↩

  2. did:web method specification ↩