Skip to content

ISCC Discovery Protocol#

IEP: 0013
Title: ISCC Discovery Protocol
Author: Titusz Pan tp@iscc.io
Comments: https://github.com/iscc/iscc-ieps/issues/18
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 ISCC Discovery Protocol (IDP), an open and federated protocol that associates content identified by ISCC-CODEs with declaring parties, metadata, and services.

An ISCC-CODE is derived deterministically from digital content. Two parties that process the same content independently derive the same ISCC-CODE. Identity, rights, and provenance information cannot be inferred from the code itself - it has to be declared. The IDP provides the protocol surface for such declarations in a way that is:

  • cryptographically attributable to the declarer (Ed25519 signature);
  • verifiable independently of any single server (signed receipts and transparency logs);
  • replay-protected (hub-bound nonces and hub-issued timestamps).

This document specifies the protocol framework and the message formats IsccNote and IsccNoteDelete. The transparency log is specified in IEP-0014. The ISCC-ID identifier is specified in IEP-0011.

2. Terminology#

Declarer : The entity that creates and signs an IsccNote.

ISCC-HUB : A server that accepts signed declarations, issues ISCC-IDs, and maintains a transparency log.

Gateway : An external service that resolves ISCC-IDs to metadata and service descriptors.

HUB-LIST : The mapping of HUB-IDs to ISCC-HUB base URLs, scoped per realm.

JCS : JSON Canonicalization Scheme as defined in RFC 8785.

Multihash : Self-describing hash format. In this specification, multihash always denotes BLAKE3 with prefix 1e20 followed by 32 digest bytes in lowercase hexadecimal (68 characters total).

Multibase : Self-describing base-encoding format. In this specification, multibase strings use the z prefix indicating base58-btc encoding.

3. Architecture#

The IDP is operated by a federation of independent ISCC-HUBs. Each ISCC-HUB is identified by a HUB-ID within a realm and listed in the HUB-LIST together with its base URL. An ISCC-HUB shall publish its Ed25519 public key as a verification method in the DID document of its domain, resolved via the did:web method. Key rotation and revocation are managed in the DID document in accordance with Controlled Identifiers v1.0.

A declaration proceeds as follows:

  1. The declarer computes an ISCC-CODE and a BLAKE3 datahash for the content.
  2. The declarer selects a target ISCC-HUB from the HUB-LIST and constructs an IsccNote whose nonce is bound to the target HUB-ID.
  3. The declarer canonicalizes and signs the IsccNote and submits it to the ISCC-HUB.
  4. The ISCC-HUB validates the IsccNote, atomically issues an ISCC-ID, and appends the declaration to its transparency log.
  5. The declarer retrieves a signed IsccReceipt as durable proof of the declaration.

ISCC-HUBs do not store descriptive metadata. Metadata is hosted at gateways referenced by the declaration; the declaration may commit to metadata only by hash.

4. Messages#

JSON schemas for IDP messages are published under the http://purl.org/iscc/schema/ namespace. Each message identifies the schema version it conforms to in its $schema field.

4.1 Field Encodings#

The following encodings apply to all message fields:

Encoding Definition
multihash 1e20 followed by 64 lowercase hexadecimal characters (BLAKE3, 256-bit digest)
nonce 32 lowercase hexadecimal characters (128 bits)
timestamp RFC 3339 UTC timestamp YYYY-MM-DDTHH:MM:SS.sssZ with exactly 3-digit milliseconds
multibase z followed by base58-btc encoded bytes
ISCC values canonical form as specified in IEP-0001

4.2 IsccSignature#

An IsccSignature is an ISCC signature object as specified in IEP-0019. Within the IDP, pubkey shall be present (signature types SELF_VERIFYING or IDENTITY_BOUND), so that signed messages remain verifiable from the transparency log alone.

4.3 IsccNote#

An IsccNote is a signed claim by a declarer that an ISCC-CODE applies to the content identified by datahash:

Field Presence Type Definition
$schema mandatory URI Shall equal the published IsccNote schema URI
iscc_code mandatory ISCC-CODE The composite ISCC-CODE being declared
datahash mandatory multihash Hash of the content bytes
nonce mandatory nonce Replay-protection value bound to the target hub
signature mandatory IsccSignature Declarer signature over the canonical IsccNote
timestamp optional timestamp Declarer-supplied UTC timestamp
gateway optional URI Service endpoint for metadata resolution
metahash optional multihash Hash commitment to associated metadata
units recommended array 1 to 4 ISCC-UNITs of the declared ISCC-CODE

An IsccNote shall satisfy the following constraints:

  1. $schema shall equal the URI of a published IsccNote schema.
  2. iscc_code shall be a composite ISCC-CODE, not an individual ISCC-UNIT.
  3. units, if present, shall not include the Instance-Code. The provided units together with the Instance-Code derived from datahash shall reconstruct the declared iscc_code.
  4. gateway, if present, shall be an absolute HTTPS URL or an RFC 6570 URI template using only the variables {iscc_id}, {iscc_code}, and {datahash}, without userinfo, query, or fragment components. Template variables expand to lowercase values without the ISCC: prefix.
  5. metahash, if present, shall equal the Meta-Hash of the seed metadata it commits to, generated according to IEP-0002 - Meta-Hash processing.
  6. Fields not listed above shall not be present.

An IsccNote should include the ISCC-UNITs of the declared iscc_code, each with a length of 256 bits. Services that match or index declarations across ISCC-HUBs may disregard declarations that do not include 256-bit ISCC-UNITs.

NOTE 1: A composite ISCC-CODE carries only truncated ISCC-UNIT digests. Full-length ISCC-UNITs substantially reduce false positives in similarity matching at global scale.

NOTE 2: The metahash commitment cannot be verified by the ISCC-HUB, which does not receive the metadata. Verification is performed by consumers that retrieve the metadata, for example via the gateway.

IsccNote example (live declaration ISCC:MEIGKV5N6NTVF4AB)

{
  "$schema": "http://purl.org/iscc/schema/iscc-note-0.8.0.json",
  "iscc_code": "ISCC:KADT6NPTBFIU53VEUP3BSQ4YHYFYD3C5RT5EQPSTES3V5G2VJ52JAJOPS65J2VAOK5SQ",
  "datahash": "1e20cf97ba9d540e5765f8e47fb42136fb4ff667e8f20d439bcd7ead098fad095a92",
  "metahash": "1e20388260ef011e520c6514f29d68039d8b0c5af12f20b3b72a2f2117068483ea64",
  "nonce": "0010000063727970746f62696f736973",
  "timestamp": "2026-06-30T16:14:39.067Z",
  "gateway": "https://titusz.org/iscc/gateway/{iscc_id}.json",
  "units": [
    "ISCC:AADT6NPTBFIU53VEZGINV746IGBOTLM77N7JXIC7DALQS3N7NWBZEPI",
    "ISCC:CAD2H5QZIOMD4C4BV55BM33UVL3TTI47NSYXNYD2KXGCCQLICVGCK6Q",
    "ISCC:EAD6YXMM7JED4UZECPWP5SS7T3YVDDJYI4WPQJ7BI3HIZ55KQEZ7N6Q",
    "ISCC:GAD3OXU3KVHXJEBFGCDJSCY5R2SRDFDNSTBZ2DBPTRXHLFXMWH3GMEQ"
  ],
  "signature": {
    "version": "ISCC-SIG v1.0",
    "controller": "did:web:titusz.org",
    "keyid": "iscc",
    "pubkey": "z6MkwXToTYfY3rdjWYjD8hvhXWJqsBaghga7QU9PSn3xW9gA",
    "proof": "zYZ1aqJVqBXKKssC1fcwa5gU9TpxC3MUmdt6tyxSyFF1DLfHNTDuyU7HCv8NcJQkqSaFfkf3h66jeZhnvcZrX1qg"
  }
}

4.4 IsccNoteDelete#

An IsccNoteDelete is a signed request to delete a previously committed declaration:

Field Presence Type Definition
$schema mandatory URI Shall equal the published IsccNoteDelete schema URI
iscc_id mandatory ISCC-ID The ISCC-ID being deleted
nonce mandatory nonce Replay-protection value bound to the target hub
signature mandatory IsccSignature Declarer signature over the canonical IsccNoteDelete
timestamp optional timestamp Declarer-supplied UTC timestamp

An IsccNoteDelete shall satisfy the following constraints:

  1. $schema shall equal the URI of a published IsccNoteDelete schema.
  2. signature.pubkey shall equal the signature.pubkey of the original IsccNote that produced the iscc_id.
  3. Fields not listed above shall not be present.

IsccNoteDelete example

{
  "$schema": "http://purl.org/iscc/schema/iscc-note-delete-0.8.0.json",
  "iscc_id": "ISCC:MAIGKJIY75NUVAAB",
  "nonce": "001d17437f53f6899ed01ecb8659118b",
  "timestamp": "2026-05-22T08:15:00.000Z",
  "signature": {
    "version": "ISCC-SIG v1.0",
    "controller": "did:web:example.com",
    "pubkey": "z6MkmeDbeC5BecFmVnTHA5PWEBaVUrGLdB3weGE2KYnXfHso",
    "proof": "z5j9nrpPw3oYSAN4XbCvk2sUtkwrueTD6V2Y35gS1KFTode2ED2YQWokPmoXw6QBYtYEFxtAQfzBhdNyr8PMwP79G"
  }
}

4.5 Canonicalization and Signing#

All signed objects shall be canonicalized with JCS (RFC 8785) and encoded as UTF-8.

An IsccNote or IsccNoteDelete shall be signed and verified in accordance with IEP-0019.

5. Hub Interface#

A conforming ISCC-HUB shall expose the following HTTP endpoints:

Endpoint Function
POST /declaration Submit an IsccNote
GET /declaration/{iscc_id}/receipt Retrieve the signed IsccReceipt for a declaration
DELETE /declaration/{iscc_id} Submit an IsccNoteDelete
GET /{iscc_id} Resolve an ISCC-ID to its declaration record

5.1 Declaration#

Upon receiving an IsccNote, an ISCC-HUB shall:

  1. Validate the structure of the IsccNote against the schema referenced by its $schema field and the constraints of this document.
  2. Verify that the first 12 bits of the nonce equal its own HUB-ID.
  3. Verify the declarer signature.
  4. Verify that the nonce has not been used in a previously accepted message.
  5. Within a single atomic transaction: assign a microsecond timestamp strictly greater than the most recent prior timestamp, compose the ISCC-ID from the timestamp and its HUB-ID in accordance with IEP-0011, and append the declaration to its transparency log with a gapless zero-based sequence number.
  6. Return the assigned ISCC-ID and sequence number.

If any verification step fails, the ISCC-HUB shall reject the submission and shall report an error.

An ISCC-HUB may enforce additional acceptance policies (for example declarer identity verification). Such policies shall only narrow what the published schemas permit.

5.2 Receipt#

An ISCC-HUB shall make a signed IsccReceipt retrievable for every accepted declaration. The IsccReceipt is a W3C Verifiable Credential issued by the ISCC-HUB that contains the sequence number, the assigned ISCC-ID, and the verbatim IsccNote. Any party holding the receipt and the ISCC-HUB public key from the ISCC-HUB's DID document can verify the declaration without contacting the ISCC-HUB.

5.3 Deletion#

Upon receiving an IsccNoteDelete, an ISCC-HUB shall validate it in accordance with this document, verify that its signature.pubkey equals the signature.pubkey of the original declaration, and append a deletion entry to its transparency log. The original declaration entry shall remain in the log. Subsequent resolution of the deleted ISCC-ID shall reflect the deletion.

6. Replay Protection#

The nonce provides replay protection in two dimensions:

  1. Cross-hub: The first 12 bits of the nonce shall equal the HUB-ID of the target ISCC-HUB. A message signed for one ISCC-HUB is therefore not acceptable to any other.
  2. Per-hub: An ISCC-HUB shall reject any message whose nonce was used in a previously accepted message.

Declarers shall generate the remaining 116 bits of the nonce from a cryptographically secure random source.

7. Security Considerations#

Implementations shall use a well-reviewed Ed25519 library and shall reject signatures with malleable encodings (RFC 8032). JCS-canonicalized bytes are the integrity anchor of every signed object; implementations should verify their JCS implementation against the test vectors of RFC 8785. A compromised declarer key permits declaration and deletion on the declarer's behalf; mitigation is key rotation in the declarer's controller document. A compromised ISCC-HUB key permits forged receipts; the transparency log (IEP-0014) and key rotation in the ISCC-HUB's DID document limit the impact.

8. References#

8.1 Normative#

8.2 Informative#