@parity/product-sdk-bulletin 0.1.0 → 0.2.0

package/src/cid.ts

@@ -1,126 +1,62 @@
-import { blake2b256, bytesToHex, hexToBytes } from "@parity/product-sdk-crypto";
-import { createLogger } from "@parity/product-sdk-logger";
+/**
+ * CID helpers for converting between on-chain hex hashes and CIDs.
+ *
+ * Upstream `@parity/bulletin-sdk` exposes `calculateCid` (data → CID),
+ * `parseCid` (string → CID), `cidFromBytes` (full-encoded → CID), and
+ * `cidToBytes` (CID → full-encoded). The helpers here add a thin layer
+ * for the `0x`-prefixed hex shape that on-chain `TransactionInfo` uses,
+ * so callers don't need to do the digest plumbing themselves.
+ *
+ * Both helpers default to the chain default (blake2b-256, raw codec).
+ * Pass `HashAlgorithm` and `CidCodec` for other configurations
+ * (sha2-256, dag-pb, etc.).
+ */
 import { CID } from "multiformats/cid";
 import * as Digest from "multiformats/hashes/digest";
 
 import { BulletinCidError } from "./errors.js";
 
-const log = createLogger("bulletin");
-
 /**
  * Hash algorithms supported by the Bulletin Chain.
  *
- * Values are multihash codes as defined in the
- * {@link https://github.com/multiformats/multicodec multicodec table}.
+ * Values are multihash codes from the multicodec table.
  */
 export const HashAlgorithm = {
-    /** BLAKE2b-256 — default for product-sdk and the chain SDK. */
+    /** BLAKE2b-256 — chain default. */
     Blake2b256: 0xb220,
-    /** SHA2-256 — default for bulletin-deploy. */
+    /** SHA2-256. */
     Sha2_256: 0x12,
     /** Keccak-256 — Ethereum compatibility. */
     Keccak256: 0x1b,
 } as const;
-
-/** A multihash code supported by the Bulletin Chain. */
 export type HashAlgorithm = (typeof HashAlgorithm)[keyof typeof HashAlgorithm];
 
 /**
  * CID codecs supported by the Bulletin Chain.
- *
- * Values are multicodec codes.
  */
 export const CidCodec = {
     /** Raw binary — default for single-chunk data. */
     Raw: 0x55,
-    /** DAG-PB — used for multi-chunk manifests / directory structures. */
+    /** DAG-PB — used for multi-chunk manifests / IPFS UnixFS. */
     DagPb: 0x70,
     /** DAG-CBOR — alternative DAG encoding. */
     DagCbor: 0x71,
 } as const;
-
-/** A multicodec code supported by the Bulletin Chain. */
 export type CidCodec = (typeof CidCodec)[keyof typeof CidCodec];
 
 const SUPPORTED_HASH_CODES = new Set<number>(Object.values(HashAlgorithm));
 const SUPPORTED_CODEC_CODES = new Set<number>(Object.values(CidCodec));
-const EXPECTED_HEX_LENGTH = 66; // "0x" + 64 hex chars = 32 bytes
-
-/**
- * Compute the CIDv1 (blake2b-256, raw codec) for arbitrary data.
- * Deterministic: same input always produces the same CID.
- */
-export function computeCid(data: Uint8Array): string {
-    const hash = blake2b256(data);
-    return CID.createV1(CidCodec.Raw, Digest.create(HashAlgorithm.Blake2b256, hash)).toString();
-}
-
-/**
- * Extract the content hash digest from a CIDv1 string and return it as a
- * `0x`-prefixed hex string — the preimage key format used by the host API.
- *
- * Accepts CIDv1 with any hash algorithm supported by the Bulletin Chain
- * (blake2b-256, sha2-256, keccak-256).
- *
- * @param cid - CIDv1 base32 string (as produced by {@link computeCid} or {@link hashToCid}).
- * @returns `0x`-prefixed hex string of the 32-byte hash digest.
- * @throws If the CID is not CIDv1 or uses an unsupported hash algorithm.
- */
-export function cidToPreimageKey(cid: string): `0x${string}` {
-    const parsed = CID.parse(cid);
-    if (parsed.version !== 1) {
-        throw new BulletinCidError(`Expected CIDv1, got CIDv${parsed.version}`, cid);
-    }
-    if (!SUPPORTED_HASH_CODES.has(parsed.multihash.code)) {
-        throw new BulletinCidError(
-            `Unsupported hash algorithm 0x${parsed.multihash.code.toString(16)}; ` +
-                `expected one of: ${[...SUPPORTED_HASH_CODES].map((c) => `0x${c.toString(16)}`).join(", ")}`,
-            cid,
-        );
-    }
-    return `0x${bytesToHex(parsed.multihash.digest)}`;
-}
+const EXPECTED_HEX_LENGTH = 66; // "0x" + 64 hex chars (32-byte digest)
 
 /**
- * Reconstruct a CIDv1 from a `0x`-prefixed hex hash stored on-chain.
- *
- * This is the inverse of {@link cidToPreimageKey}: given a 32-byte content hash
- * and the CID configuration used when the data was stored, it rebuilds the
- * original CIDv1 so you can construct IPFS gateway URLs.
- *
- * The Bulletin Chain supports multiple hash algorithms and codecs — pass the
- * values that match the on-chain `TransactionInfo` to get the correct CID.
- * When omitted, defaults match {@link computeCid} (blake2b-256, raw).
- *
- * @param hexHash   - `0x`-prefixed hex string of a 32-byte hash digest
- *   (66 characters total: `"0x"` + 64 hex chars).
- * @param hashCode  - Multihash code of the hashing algorithm (default: blake2b-256 `0xb220`).
- *   Use {@link HashAlgorithm} for the supported values.
- * @param codec     - Multicodec code of the CID codec (default: raw `0x55`).
- *   Use {@link CidCodec} for the supported values.
- * @returns Base32-lower CIDv1 string.
- * @throws If `hexHash` is not exactly 66 characters, or if the hash/codec is unsupported.
+ * Reconstruct a CIDv1 from a `0x`-prefixed 32-byte hex hash.
  *
- * @example
- * ```ts
- * import { hashToCid, HashAlgorithm, CidCodec, gatewayUrl, getGateway } from "@parity/product-sdk-bulletin";
+ * Useful when reading on-chain `TransactionInfo.content_hash` and you need
+ * the CID to look up content via an IPFS gateway.
  *
- * // Default (blake2b-256, raw) — matches computeCid output
- * const cid = hashToCid(onChainHash);
- *
- * // SHA2-256 content stored via bulletin-deploy
- * const cid2 = hashToCid(onChainHash, HashAlgorithm.Sha2_256);
- *
- * // DAG-PB manifest with blake2b-256
- * const cid3 = hashToCid(manifestHash, HashAlgorithm.Blake2b256, CidCodec.DagPb);
- *
- * const url = gatewayUrl(cid, getGateway("paseo"));
- * ```
- *
- * @see {@link cidToPreimageKey} for the reverse direction (CID → hex hash).
- * @see {@link computeCid} for computing a CID from raw data.
- * @see {@link HashAlgorithm} for supported hash algorithms.
- * @see {@link CidCodec} for supported CID codecs.
+ * @param hexHash  - 66-char `0x`-prefixed hex of a 32-byte digest.
+ * @param hashCode - Multihash code (default: blake2b-256).
+ * @param codec    - Multicodec code (default: raw).
  */
 export function hashToCid(
     hexHash: `0x${string}`,
@@ -133,6 +69,11 @@ export function hashToCid(
                 `got ${hexHash.length} chars`,
         );
     }
+    if (!/^0x[0-9a-fA-F]{64}$/.test(hexHash)) {
+        throw new BulletinCidError(
+            `Invalid hash format: expected 0x-prefixed 32-byte hex string, got: ${hexHash}`,
+        );
+    }
     if (!SUPPORTED_HASH_CODES.has(hashCode)) {
         throw new BulletinCidError(
             `Unsupported hash algorithm 0x${hashCode.toString(16)}; ` +
@@ -145,194 +86,129 @@ export function hashToCid(
                 `expected one of: ${[...SUPPORTED_CODEC_CODES].map((c) => `0x${c.toString(16)}`).join(", ")}`,
         );
     }
-    const digest = hexToBytes(hexHash.slice(2));
-    const cid = CID.createV1(codec, Digest.create(hashCode, digest)).toString();
-    log.debug("hashToCid", { hexHash, hashCode, codec, cid });
-    return cid;
+    const digest = hexToBytes(hexHash);
+    return CID.createV1(codec, Digest.create(hashCode, digest)).toString();
 }
 
-if (import.meta.vitest) {
-    const { describe, test, expect } = import.meta.vitest;
+/**
+ * Extract the 32-byte content hash digest from a CIDv1 and return it as a
+ * `0x`-prefixed hex string.
+ *
+ * Useful for matching a CID against on-chain `TransactionInfo.content_hash`.
+ */
+export function cidToPreimageKey(cid: string): `0x${string}` {
+    let parsed;
+    try {
+        parsed = CID.parse(cid);
+    } catch {
+        throw new BulletinCidError(`Invalid CID: ${cid}`, cid);
+    }
+    if (parsed.version !== 1) {
+        throw new BulletinCidError(`Expected CIDv1, got CIDv${parsed.version}`, cid);
+    }
+    if (!SUPPORTED_HASH_CODES.has(parsed.multihash.code)) {
+        throw new BulletinCidError(
+            `Unsupported hash algorithm 0x${parsed.multihash.code.toString(16)}; ` +
+                `expected one of: ${[...SUPPORTED_HASH_CODES].map((c) => `0x${c.toString(16)}`).join(", ")}`,
+            cid,
+        );
+    }
+    return `0x${bytesToHex(parsed.multihash.digest)}` as `0x${string}`;
+}
 
-    describe("computeCid", () => {
-        test("produces known CID for known input", () => {
-            const data = new TextEncoder().encode("hello bulletin");
-            const cid = computeCid(data);
-            expect(cid).toBe(computeCid(new TextEncoder().encode("hello bulletin")));
-            expect(cid).toMatch(/^b[a-z2-7]+$/);
-        });
+function hexToBytes(hex: `0x${string}`): Uint8Array {
+    const out = new Uint8Array(32);
+    for (let i = 0; i < 32; i++) {
+        out[i] = Number.parseInt(hex.slice(2 + i * 2, 4 + i * 2), 16);
+    }
+    return out;
+}
 
-        test("deterministic — same input, same output", () => {
-            const data = new Uint8Array([1, 2, 3, 4, 5]);
-            expect(computeCid(data)).toBe(computeCid(data));
-        });
+function bytesToHex(bytes: Uint8Array): string {
+    let s = "";
+    for (let i = 0; i < bytes.length; i++) {
+        s += bytes[i]!.toString(16).padStart(2, "0");
+    }
+    return s;
+}
 
-        test("different inputs produce different CIDs", () => {
-            const a = computeCid(new Uint8Array([1]));
-            const b = computeCid(new Uint8Array([2]));
-            expect(a).not.toBe(b);
-        });
+if (import.meta.vitest) {
+    const { describe, test, expect } = import.meta.vitest;
 
-        test("empty input produces valid CID", () => {
-            const cid = computeCid(new Uint8Array(0));
-            expect(cid).toMatch(/^b[a-z2-7]+$/);
-        });
+    describe("hashToCid", () => {
+        const sampleHex = `0x${"ab".repeat(32)}` as `0x${string}`;
 
-        test("matches reference implementation (manual varint)", () => {
-            const data = new TextEncoder().encode("test");
-            const cid = computeCid(data);
-            expect(cid[0]).toBe("b");
+        test("produces valid base32-lower CIDv1 (default: blake2b-256, raw)", () => {
+            const cid = hashToCid(sampleHex);
+            expect(cid).toMatch(/^b[a-z2-7]+$/);
             const parsed = CID.parse(cid);
             expect(parsed.version).toBe(1);
             expect(parsed.code).toBe(CidCodec.Raw);
+            expect(parsed.multihash.code).toBe(HashAlgorithm.Blake2b256);
         });
-    });
 
-    describe("cidToPreimageKey", () => {
-        test("round-trips with computeCid — returns 0x-prefixed 64-char hex", () => {
-            const data = new TextEncoder().encode("hello bulletin");
-            const cid = computeCid(data);
-            const key = cidToPreimageKey(cid);
-            expect(key).toMatch(/^0x[0-9a-f]{64}$/);
+        test("supports sha2-256", () => {
+            const cid = hashToCid(sampleHex, HashAlgorithm.Sha2_256);
+            expect(CID.parse(cid).multihash.code).toBe(HashAlgorithm.Sha2_256);
         });
 
-        test("deterministic — same CID always yields same key", () => {
-            const cid = computeCid(new Uint8Array([1, 2, 3]));
-            expect(cidToPreimageKey(cid)).toBe(cidToPreimageKey(cid));
+        test("supports dag-pb codec", () => {
+            const cid = hashToCid(sampleHex, HashAlgorithm.Blake2b256, CidCodec.DagPb);
+            expect(CID.parse(cid).code).toBe(CidCodec.DagPb);
         });
 
-        test("matches raw blake2b-256 hash", () => {
-            const data = new TextEncoder().encode("test");
-            const cid = computeCid(data);
-            const key = cidToPreimageKey(cid);
-            const hash = blake2b256(data);
-            const expected = `0x${bytesToHex(hash)}`;
-            expect(key).toBe(expected);
+        test("throws on short hex", () => {
+            expect(() => hashToCid("0xabcd" as `0x${string}`)).toThrow(BulletinCidError);
         });
 
-        test("accepts CIDv1 with sha2-256", () => {
-            const hash = new Uint8Array(32).fill(0xcd);
-            const cidV1 = CID.createV1(CidCodec.Raw, Digest.create(HashAlgorithm.Sha2_256, hash));
-            const key = cidToPreimageKey(cidV1.toString());
-            expect(key).toMatch(/^0x[0-9a-f]{64}$/);
-            expect(key).toBe(`0x${bytesToHex(hash)}`);
+        test("throws on long hex", () => {
+            const tooLong = `0x${"aa".repeat(33)}` as `0x${string}`;
+            expect(() => hashToCid(tooLong)).toThrow(BulletinCidError);
         });
 
-        test("accepts CIDv1 with keccak-256", () => {
-            const hash = new Uint8Array(32).fill(0xef);
-            const cidV1 = CID.createV1(CidCodec.Raw, Digest.create(HashAlgorithm.Keccak256, hash));
-            const key = cidToPreimageKey(cidV1.toString());
-            expect(key).toBe(`0x${bytesToHex(hash)}`);
+        test("throws on non-hex characters", () => {
+            const bad = `0x${"zz".repeat(32)}` as `0x${string}`;
+            expect(() => hashToCid(bad)).toThrow(BulletinCidError);
         });
 
-        test("throws BulletinCidError for CIDv0 input", () => {
-            const hash = new Uint8Array(32).fill(0xab);
-            const cidV0 = CID.create(0, 0x70, Digest.create(HashAlgorithm.Sha2_256, hash));
-            expect(() => cidToPreimageKey(cidV0.toString())).toThrow(BulletinCidError);
+        test("throws on unsupported hash algorithm", () => {
+            expect(() => hashToCid(sampleHex, 0x99 as HashAlgorithm)).toThrow(BulletinCidError);
         });
 
-        test("throws BulletinCidError for CIDv1 with unsupported hash algorithm", () => {
-            const unsupportedCode = 0x99;
-            const hash = new Uint8Array(32).fill(0xab);
-            const cidV1 = CID.createV1(CidCodec.Raw, Digest.create(unsupportedCode, hash));
-            expect(() => cidToPreimageKey(cidV1.toString())).toThrow(BulletinCidError);
+        test("throws on unsupported codec", () => {
+            expect(() => hashToCid(sampleHex, HashAlgorithm.Blake2b256, 0x99 as CidCodec)).toThrow(
+                BulletinCidError,
+            );
         });
     });
 
-    describe("hashToCid", () => {
-        test("round-trips with cidToPreimageKey — hex → CID → hex", () => {
-            const data = new TextEncoder().encode("hello bulletin");
-            const originalCid = computeCid(data);
-            const hex = cidToPreimageKey(originalCid);
-            const reconstructed = hashToCid(hex);
-            expect(reconstructed).toBe(originalCid);
-        });
-
-        test("full cycle: data → CID → hex → CID", () => {
-            const data = new Uint8Array([10, 20, 30, 40, 50]);
-            const cid1 = computeCid(data);
-            const hex = cidToPreimageKey(cid1);
-            const cid2 = hashToCid(hex);
-            expect(cid2).toBe(cid1);
-        });
-
-        test("deterministic — same hex always yields same CID", () => {
-            const hex = cidToPreimageKey(computeCid(new Uint8Array([1, 2, 3])));
-            expect(hashToCid(hex)).toBe(hashToCid(hex));
-        });
-
-        test("produces valid base32-lower CIDv1 (default: blake2b-256, raw)", () => {
-            const hex = cidToPreimageKey(computeCid(new TextEncoder().encode("test")));
-            const cid = hashToCid(hex);
-            expect(cid).toMatch(/^b[a-z2-7]+$/);
-            const parsed = CID.parse(cid);
-            expect(parsed.version).toBe(1);
-            expect(parsed.code).toBe(CidCodec.Raw);
-            expect(parsed.multihash.code).toBe(HashAlgorithm.Blake2b256);
-        });
-
-        test("sha2-256 produces different CID from blake2b-256 for same hash", () => {
-            const hex = `0x${"ab".repeat(32)}` as `0x${string}`;
-            const blake = hashToCid(hex, HashAlgorithm.Blake2b256);
-            const sha = hashToCid(hex, HashAlgorithm.Sha2_256);
-            expect(blake).not.toBe(sha);
-            // Both should be valid CIDv1
-            expect(CID.parse(blake).version).toBe(1);
-            expect(CID.parse(sha).version).toBe(1);
-        });
-
-        test("sha2-256 round-trips through cidToPreimageKey", () => {
+    describe("cidToPreimageKey", () => {
+        test("round-trip with hashToCid", () => {
             const hex = `0x${"cd".repeat(32)}` as `0x${string}`;
-            const cid = hashToCid(hex, HashAlgorithm.Sha2_256);
-            const extracted = cidToPreimageKey(cid);
-            expect(extracted).toBe(hex);
+            const cid = hashToCid(hex);
+            expect(cidToPreimageKey(cid)).toBe(hex);
         });
 
-        test("keccak-256 round-trips through cidToPreimageKey", () => {
+        test("round-trip with sha2-256", () => {
             const hex = `0x${"ef".repeat(32)}` as `0x${string}`;
-            const cid = hashToCid(hex, HashAlgorithm.Keccak256);
-            const extracted = cidToPreimageKey(cid);
-            expect(extracted).toBe(hex);
-        });
-
-        test("dag-pb codec produces different CID from raw for same hash", () => {
-            const hex = `0x${"ab".repeat(32)}` as `0x${string}`;
-            const rawCid = hashToCid(hex, HashAlgorithm.Blake2b256, CidCodec.Raw);
-            const dagPbCid = hashToCid(hex, HashAlgorithm.Blake2b256, CidCodec.DagPb);
-            expect(rawCid).not.toBe(dagPbCid);
-            expect(CID.parse(dagPbCid).code).toBe(CidCodec.DagPb);
-        });
-
-        test("dag-cbor codec works", () => {
-            const hex = `0x${"ab".repeat(32)}` as `0x${string}`;
-            const cid = hashToCid(hex, HashAlgorithm.Blake2b256, CidCodec.DagCbor);
-            expect(CID.parse(cid).code).toBe(CidCodec.DagCbor);
-        });
-
-        test("throws BulletinCidError for hex that is too short", () => {
-            expect(() => hashToCid("0xabcd" as `0x${string}`)).toThrow(BulletinCidError);
-        });
-
-        test("throws BulletinCidError for hex that is too long", () => {
-            const tooLong = `0x${"aa".repeat(33)}` as `0x${string}`;
-            expect(() => hashToCid(tooLong)).toThrow(BulletinCidError);
+            const cid = hashToCid(hex, HashAlgorithm.Sha2_256);
+            expect(cidToPreimageKey(cid)).toBe(hex);
         });
 
-        test("throws for non-hex characters", () => {
-            const bad = `0x${"zz".repeat(32)}` as `0x${string}`;
-            expect(() => hashToCid(bad)).toThrow();
+        test("throws on invalid CID string", () => {
+            expect(() => cidToPreimageKey("not-a-cid")).toThrow(BulletinCidError);
         });
 
-        test("throws BulletinCidError for unsupported hash algorithm", () => {
-            const hex = `0x${"ab".repeat(32)}` as `0x${string}`;
-            expect(() => hashToCid(hex, 0x99 as HashAlgorithm)).toThrow(BulletinCidError);
+        test("throws on CIDv0 input", () => {
+            const hash = new Uint8Array(32).fill(0xab);
+            const cidV0 = CID.create(0, 0x70, Digest.create(HashAlgorithm.Sha2_256, hash));
+            expect(() => cidToPreimageKey(cidV0.toString())).toThrow(BulletinCidError);
         });
 
-        test("throws BulletinCidError for unsupported codec", () => {
-            const hex = `0x${"ab".repeat(32)}` as `0x${string}`;
-            expect(() => hashToCid(hex, HashAlgorithm.Blake2b256, 0x99 as CidCodec)).toThrow(
-                BulletinCidError,
-            );
+        test("throws on unsupported hash algorithm", () => {
+            const hash = new Uint8Array(32).fill(0xab);
+            const cidV1 = CID.createV1(CidCodec.Raw, Digest.create(0x99, hash));
+            expect(() => cidToPreimageKey(cidV1.toString())).toThrow(BulletinCidError);
         });
     });
 }