Skip to content

ISCC Transparency Log#

IEP: 0014
Title: ISCC Transparency Log
Author: Titusz Pan tp@iscc.io
Comments: https://github.com/iscc/iscc-ieps/issues/19
Status: Draft
Type: Core
Standard: IEP
License: CC-BY-4.0
Created: 2022-09-28
Updated: 2026-07-03

Note

This document is a DRAFT intended as input to ISO TC 46/SC 9/WG 18 for a future revision of ISO 24138.

1. Introduction#

This proposal defines the transparency log maintained by an ISCC-HUB. The log records the declaration and deletion messages of the ISCC Discovery Protocol (IEP-0013) and commits to them with a cryptographic structure that any party can verify independently of the ISCC-HUB.

The log exists so that the existence and ordering of a declaration can be proven after the fact - for audits or disputes - without trusting the ISCC-HUB's continued good behavior or existence. The design therefore reuses standard transparency-log primitives: a single append-only RFC 6962 Merkle tree per ISCC-HUB, hashed with SHA-256, published as static tiles over HTTP in accordance with the tlog-tiles specification, and committed by a signed checkpoint. Existing transparency-log clients can verify the log with little or no modification.

2. Log Records#

A log record is the unit committed as one leaf of the Merkle tree. A log record shall be the JCS-canonicalized (RFC 8785), UTF-8 encoded form of a log entry with the following fields:

Field Presence Type Definition
$schema mandatory URI Shall equal the published entry schema
iscc_id mandatory ISCC-ID The ISCC-ID this entry refers to
note mandatory IsccNote or IsccNoteDelete The signed message

JSON schemas for log entries are published under the http://purl.org/iscc/schema/ namespace. A log entry identifies the schema version it conforms to in its $schema field.

A log entry shall satisfy the following constraints:

  1. $schema shall equal the URI of a published log entry schema.
  2. note shall contain the signed IsccNote or IsccNoteDelete (IEP-0013) with all members unaltered. Whether an entry is a declaration or a deletion is derived from note.$schema.
  3. An ISCC-HUB shall not alter or remove a record after it has been committed. A deletion is expressed as a new record whose note is an IsccNoteDelete.
  4. Records shall be assigned dense, gapless, zero-based sequence numbers: the record committed when the tree has size N receives sequence number N.

NOTE: Signatures are computed over the JCS-canonical bytes of the signed message (IEP-0019), and JCS serialization is deterministic. The canonical record bytes therefore embed the exact bytes signed by the declarer, and a verifier can re-verify the declarer's signature from the log entry alone.

3. Merkle Tree#

The log shall use the Merkle tree defined in RFC 6962 section 2 with SHA-256 as the hash function:

  1. The hash of a leaf holding record bytes r shall be SHA-256(0x00 || r).
  2. The hash of an interior node with children l and r shall be SHA-256(0x01 || l || r).
  3. The hash of the empty tree shall be SHA-256("").

The tree is never split into shards and never reset; a record's sequence number is its permanent index.

4. Tiles#

The tree and its records shall be published as tiles in accordance with the tlog-tiles specification with the tile height fixed at 8 (256 entries per tile):

  1. A hash tile at level L and index K shall hold the 32-byte SHA-256 node hashes at the corresponding tree positions. A full hash tile is 8192 bytes.
  2. An entry bundle at index K shall hold the 256 length-prefixed records whose leaf hashes occupy the level-0 hash tile at index K.
  3. Partial tiles and bundles shall be addressed with the .p/<W> suffix defined by tlog-tiles.
  4. Full tiles and bundles are immutable; an ISCC-HUB shall serve them as immutable resources.

5. Checkpoint#

A checkpoint commits to the tree at a specific size. It shall use the C2SP checkpoint and signed-note formats. The checkpoint body shall consist of exactly three lines:

  1. the origin — the ISCC-HUB's stable identity string derived from its domain;
  2. the decimal tree size N;
  3. the base64-encoded SHA-256 Merkle tree hash over the first N records.

Checkpoint example (ISCC-HUB iscc.id at tree size 1)

iscc.id/log
1
lRQg0Ieuf/GsgUCRASrGiolzbw8Tf3TGLc51A92uu4A=

— iscc.id/log aMO4mgVFw503i9hLY/N+R/C2IROspOdr37AVDY5mxUGIMS4bXWpbc0mLCUi+S+h2JuIZph/eMGoQmEBHo3N3ImCFtQg=

A checkpoint shall carry the ISCC-HUB's Ed25519 signature as a signed-note signature line and may carry additional witness signatures. A verifier shall reject a checkpoint whose ISCC-HUB signature does not verify against the Ed25519 public key published in the ISCC-HUB's DID document (IEP-0013).

An ISCC-HUB shall publish checkpoints with monotonically non-decreasing tree sizes and shall not publish two inconsistent checkpoints. An ISCC-HUB should republish its checkpoint at a fixed cadence (recommended: 10 seconds).

6. HTTP Interface#

An ISCC-HUB shall expose the following read endpoints. All endpoints return static, cacheable content; a verifier computes proofs locally from tiles.

Endpoint Returns
GET /log/checkpoint The latest signed checkpoint
GET /log/tile/{L}/{K} The hash tile at level L, index K
GET /log/tile/entries/{K} The entry bundle at index K

Path encodings for indices and partial tiles shall follow the tlog-tiles specification. An ISCC-HUB shall return 404 for a tile that is not yet published and may return 410 for tile data pruned under a retention policy, provided the checkpoints required to verify retained records remain available.

7. Verification#

7.1 Inclusion#

To verify inclusion of record i against a trusted checkpoint with size N and root R (i < N), a verifier shall:

  1. Fetch the entry bundle at the index given by i divided by 256, discarding the remainder, and extract the record at offset i mod 256.
  2. Confirm the record bytes match the expected canonical bytes, if a record value is being checked.
  3. Compute the leaf hash and combine it with the sibling hashes from the covering hash tiles in accordance with RFC 6962 section 2.1.1.
  4. Accept if and only if the computed root equals R.

7.2 Consistency#

To verify consistency between checkpoints of sizes M and N (M ≤ N), a verifier shall compute the RFC 6962 consistency proof (section 2.1.2) from the covering hash tiles and confirm that it relates the two roots. Checkpoints that fail consistency verification are evidence of a split view.

8. Hub Operations#

  1. When an ISCC-HUB accepts a declaration or deletion, it shall — within a single atomic transaction — assign the next sequence number, form the canonical record bytes, and persist the record durably.
  2. Hash tiles, entry bundles, and the checkpoint are a deterministic function of the committed records and may be materialized lazily. The record store, not the tile cache, is the source of truth.
  3. An ISCC-HUB shall not assert that a declaration is logged before the record is committed by a published checkpoint.

9. Security Considerations#

A malicious ISCC-HUB could present different histories to different audiences (a split view). Detection relies on independent monitors that fetch, verify, and compare checkpoints; the checkpoint format reserves space for witness cosignatures to strengthen detection. All evidentiary value flows from the ISCC-HUB's signing key: the key should be held in an isolated signer, and the ISCC-HUB's DID document supports key rotation. Because key resolution depends on the availability of the ISCC-HUB's domain, monitors should archive observed DID documents so that records remain verifiable after an ISCC-HUB ceases operation. Suppressing a declaration from an ISCC-HUB's own resolution responses is a local policy control; it writes no log record and does not propagate to log consumers. Removing a declaration from the verifiable log is only possible via a signed deletion record.

10. References#

10.1 Normative#

10.2 Informative#