indelible/utils & indelible/constants¶

Off-chain cryptographic utilities and protocol constants used throughout the library. These functions have no network dependencies and run synchronously unless otherwise noted.

Constants — indelible/constants¶

import {
    TAANQ_ADDRESS,
    ENS_INDELIBLE_ADDRESS,
    ENS_REGISTRY_ADDRESS,
    MERKLE_SPLIT,
    RESULT_CODE,
} from 'indelible/constants';

Contract addresses¶

Pass these directly to viem's readContract / writeContract when building custom integrations on top of the ABIs.

MERKLE_SPLIT¶

MERKLE_SPLIT // 46

The fixed character length of each chunk when splitting text for a Merkle quote proof tree. All chunks except the last will be exactly MERKLE_SPLIT characters. The buildTree utility uses this value automatically.

RESULT_CODE¶

RESULT_CODE.NOT_FOUND   // No attestation found for the given CID
RESULT_CODE.VERIFIED    // Attestation found and is not revoked
RESULT_CODE.UNVERIFIED  // Content hash does not match any attestation
RESULT_CODE.REVOKED     // Attestation was found but has been revoked
RESULT_CODE.WARNING     // Attestation found but requires additional scrutiny

Compare VerificationResult.code against these values for machine-readable status checks:

import { RESULT_CODE } from 'indelible/constants';
import { verifyCid } from 'indelible/verify';

const result = await verifyCid(publicClient, cid);

if (result.code === RESULT_CODE.VERIFIED) {
    // Show a verified badge
} else if (result.code === RESULT_CODE.REVOKED) {
    // Warn the user
}

RESULT_CODE_INFO¶

Metadata object for each result code: a human-readable label, a CSS class hint, and a numeric priority.

import { RESULT_CODE_INFO } from 'indelible/constants';

RESULT_CODE_INFO[RESULT_CODE.VERIFIED]
// { label: 'Verified', cssClass: 'result-verified', priority: 4 }

RESULT_CODE_INFO[RESULT_CODE.REVOKED]
// { label: 'Revoked', cssClass: 'result-revoked', priority: 1 }

Priority values: UNVERIFIED (0) > REVOKED (1) > NOT_FOUND (2) > WARNING (3) > VERIFIED (4).

RESULT_CODE_PRIORITY¶

The result codes sorted by ascending priority — i.e. most important first. Derived automatically from RESULT_CODE_INFO.

import { RESULT_CODE_PRIORITY } from 'indelible/constants';

RESULT_CODE_PRIORITY // [2, 3, 0, 4, 1] — [UNVERIFIED, REVOKED, NOT_FOUND, WARNING, VERIFIED]

Type: number[]

Use this array together with getPrimaryResultCode when you need to reduce a multi-code result to a single display state.

getPrimaryResultCode(codes)¶

Picks the highest-priority (most important) result code from an array of codes.

import { getPrimaryResultCode, RESULT_CODE } from 'indelible/constants';

getPrimaryResultCode([RESULT_CODE.VERIFIED, RESULT_CODE.WARNING]);
// RESULT_CODE.WARNING  (warning outranks verified)

getPrimaryResultCode([RESULT_CODE.UNVERIFIED, RESULT_CODE.REVOKED]);
// RESULT_CODE.UNVERIFIED  (unverified has highest priority)

Returns: number | undefined — the highest-priority code, or undefined if the array is empty.

getResultCodeCssClass(code)¶

Returns the CSS class string for a given result code.

import { getResultCodeCssClass, RESULT_CODE } from 'indelible/constants';

getResultCodeCssClass(RESULT_CODE.VERIFIED);   // 'result-verified'
getResultCodeCssClass(RESULT_CODE.REVOKED);    // 'result-revoked'
getResultCodeCssClass(RESULT_CODE.NOT_FOUND);  // 'result-not-found'

Returns: string | undefined

Equivalent to RESULT_CODE_INFO[code]?.cssClass. Useful when applying dynamic classes to result badge elements.

Utilities — indelible/utils¶

import {
    hashContent,
    hexHashContent,
    createRawCIDv1,
    getCIDFromHash,
    getCIDFromRawDigest,
    decodeCidToIpfsHash,
    buildTree,
    dnsEncodeName,
    prettifyTimestamp,
    downloadJson,
} from 'indelible/utils';

Hashing¶

hashContent(data)¶

Returns the SHA-256 digest of the input as a Uint8Array.

const digest = hashContent('Hello, world.');
// Uint8Array(32) [ ... ]

Returns: Uint8Array

hexHashContent(data)¶

Returns the SHA-256 digest of the input as a lowercase hex string (no 0x prefix).

const hex = hexHashContent('Hello, world.');
// 'b94d27b9934d3e08a52e52d7da7dabfac484efe04294e576...'

Returns: string

CID encoding¶

createRawCIDv1(data)¶

Computes the base32-encoded CIDv1 of the given content — the same identifier that IPFS would assign if you added the content with raw (raw) codec.

const cid = createRawCIDv1('Hello, world.');
// 'bafkrei...'

Returns: string

This is the CID you pass to commitAttestation (via the content parameter, which the library hashes internally) and to all verification lookups.

getCIDFromHash(hash)¶

Converts a SHA-256 hex string into a base32 CIDv1 string.

const cid = getCIDFromHash(hexHash);

Returns: string

getCIDFromRawDigest(bytes)¶

Converts a raw 32-byte SHA-256 digest into a base32 CIDv1 string.

const cid = getCIDFromRawDigest(digest);

Returns: string

decodeCidToIpfsHash(cidStr)¶

Extracts the bytes32 hex value from a CIDv1 string. This is the format the TAANQ contract stores and expects for ipfsHash.

const ipfsHash = decodeCidToIpfsHash('bafkrei...');
// '0x...' — 32-byte hex string

Returns: string — a 0x-prefixed 32-byte hex string.

Use this when calling viem's readContract or writeContract directly with the contract ABIs and you need to convert a human-readable CID into the on-chain format.

Merkle trees¶

buildTree(text)¶

Splits text into fixed-size chunks of MERKLE_SPLIT characters and returns an OpenZeppelin StandardMerkleTree instance. The tree's root is used as the qvHash in an attestation.

const tree = buildTree(articleText);
const qvHash = tree.root; // bytes32 hex — store in the attestation

Returns: StandardMerkleTree (from @openzeppelin/merkle-tree)

Each leaf is a ['string', 'string'] tuple of [index, chunkText]. This matches the format expected by verifyQuoteProof and the quote verification protocol.

ENS helpers¶

dnsEncodeName(name)¶

Encodes an ENS name into DNS wire format (length-prefixed labels). Required when calling the ENS registry and resolver contracts directly.

const encoded = dnsEncodeName('alice.eth');
// Uint8Array [ 5, 97, 108, 105, 99, 101, 3, 101, 116, 104, 0 ]

Returns: Uint8Array

Display helpers¶

prettifyTimestamp(ts)¶

Formats a Unix timestamp (seconds) into a human-readable local date/time string.

prettifyTimestamp(1714000000n);
// e.g. 'April 25, 2024, 9:46 AM'

Returns: string

Formatting follows the runtime's locale. Suitable for display in UIs but not for machine processing.

downloadJson(data, filename)¶

Triggers a browser file download for a JSON-serializable object. Browser only — throws in Node.js environments.

downloadJson(proofJson, 'quote-proof.json');

Also exported from indelible/publish for convenience.

extractPageData(doc?)¶

Reads Indelible attestation data from a marked HTML document. Browser only (defaults to the global document).

const page = extractPageData();

if (!page) {
    // No [data-indelible] root element found
}

const { attestation, text, quotes } = page;

Pass an alternative Document object to parse a fetched or sandboxed document:

const page = extractPageData(iframe.contentDocument);

Returns: { attestation, text, quotes } | null

Returns null when no [data-indelible] root element is present.

Pass the returned text to buildTree to reconstruct the Merkle tree, or feed attestation and quotes directly to the verification helpers.