@bcts/dcbor 1.0.0-alpha.8 → 1.0.0-beta.0

package/package.json

@@ -1,18 +1,18 @@
 {
   "name": "@bcts/dcbor",
-  "version": "1.0.0-alpha.8",
+  "version": "1.0.0-beta.0",
   "type": "module",
   "description": "Blockchain Commons Deterministic CBOR (dCBOR) for TypeScript",
   "license": "BSD-2-Clause-Patent",
-  "author": "Leonardo Custodio <leonardo@custodio.me>",
-  "homepage": "https://github.com/leonardocustodio/bcts",
+  "author": "Parity Technologies <admin@parity.io> (https://parity.io)",
+  "homepage": "https://bcts.dev",
   "repository": {
     "type": "git",
-    "url": "https://github.com/leonardocustodio/bcts",
+    "url": "https://github.com/paritytech/bcts",
     "directory": "packages/dcbor"
   },
   "bugs": {
-    "url": "https://github.com/leonardocustodio/bcts/issues"
+    "url": "https://github.com/paritytech/bcts/issues"
   },
   "main": "dist/index.cjs",
   "module": "dist/index.mjs",
@@ -33,11 +33,8 @@
   ],
   "scripts": {
     "build": "tsdown",
-    "dev": "tsdown --watch",
     "test": "vitest run",
     "test:watch": "vitest",
-    "test:cli": "vitest run tests/cli.test.ts",
-    "test:examples": "npm run build && node scripts/test-examples.js",
     "lint": "eslint 'src/**/*.ts' 'tests/**/*.ts'",
     "lint:fix": "eslint 'src/**/*.ts' 'tests/**/*.ts' --fix",
     "typecheck": "tsc --noEmit",
@@ -61,16 +58,17 @@
   "devDependencies": {
     "@bcts/eslint": "^0.1.0",
     "@bcts/tsconfig": "^0.1.0",
-    "@eslint/js": "^9.39.1",
+    "@eslint/js": "^10.0.1",
     "@types/collections": "^5.1.5",
-    "@typescript-eslint/eslint-plugin": "^8.49.0",
-    "@typescript-eslint/parser": "^8.49.0",
-    "eslint": "^9.39.1",
+    "@types/node": "^25.6.0",
+    "@typescript-eslint/eslint-plugin": "^8.59.0",
+    "@typescript-eslint/parser": "^8.59.0",
+    "eslint": "^10.2.1",
     "ts-node": "^10.9.2",
-    "tsdown": "^0.17.2",
-    "typedoc": "^0.28.15",
-    "typescript": "^5.9.3",
-    "vitest": "^3.2.4"
+    "tsdown": "^0.21.0",
+    "typedoc": "^0.28.19",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.5"
   },
   "dependencies": {
     "byte-data": "^19.0.1",

package/src/bignum.ts

@@ -0,0 +1,347 @@
+/**
+ * Copyright © 2023-2026 Blockchain Commons, LLC
+ * Copyright © 2025-2026 Parity Technologies
+ *
+ *
+ * CBOR bignum (tags 2 and 3) support.
+ *
+ * This module provides conversion between CBOR and JavaScript BigInt types,
+ * implementing RFC 8949 §3.4.3 (Bignums) with dCBOR/CDE canonical encoding rules.
+ *
+ * Encoding:
+ * - `biguintToCbor` always encodes as tag 2 (positive bignum) with a byte
+ *   string content.
+ * - `bigintToCbor` encodes as tag 2 for non-negative values or tag 3
+ *   (negative bignum) for negative values.
+ * - No numeric reduction is performed: values are always encoded as bignums,
+ *   even if they would fit in normal CBOR integers.
+ *
+ * Decoding:
+ * - Accepts CBOR integers (major types 0 and 1) and converts them to bigints.
+ * - Accepts tag 2 (positive bignum) and tag 3 (negative bignum) with byte
+ *   string content.
+ * - Enforces shortest-form canonical representation for bignum magnitudes.
+ * - Rejects floating-point values.
+ *
+ * @module bignum
+ */
+
+import { type Cbor, MajorType, toTaggedValue } from "./cbor";
+import { CborError } from "./error";
+
+// CBOR tag values (local constants matching tags.ts, avoiding circular import)
+const TAG_2_POSITIVE_BIGNUM = 2;
+const TAG_3_NEGATIVE_BIGNUM = 3;
+
+/**
+ * Validates that a bignum magnitude byte string is in shortest canonical form.
+ *
+ * Matches Rust's `validate_bignum_magnitude()`.
+ *
+ * Rules:
+ * - For positive bignums (tag 2): empty byte string represents zero;
+ *   non-empty must not have leading zero bytes.
+ * - For negative bignums (tag 3): byte string must not be empty
+ *   (magnitude zero is encoded as `0x00`); must not have leading zero bytes
+ *   except when the magnitude is zero (single `0x00`).
+ *
+ * @param bytes - The magnitude byte string to validate
+ * @param isNegative - Whether this is for a negative bignum (tag 3)
+ * @throws CborError with type NonCanonicalNumeric on validation failure
+ */
+export function validateBignumMagnitude(bytes: Uint8Array, isNegative: boolean): void {
+  if (isNegative) {
+    // Tag 3: byte string must not be empty
+    if (bytes.length === 0) {
+      throw new CborError({ type: "NonCanonicalNumeric" });
+    }
+    // No leading zeros unless the entire magnitude is zero (single 0x00 byte)
+    if (bytes.length > 1 && bytes[0] === 0) {
+      throw new CborError({ type: "NonCanonicalNumeric" });
+    }
+  } else {
+    // Tag 2: empty byte string is valid (represents zero)
+    // Non-empty must not have leading zeros
+    if (bytes.length > 0 && bytes[0] === 0) {
+      throw new CborError({ type: "NonCanonicalNumeric" });
+    }
+  }
+}
+
+/**
+ * Strips leading zero bytes from a byte array, returning the minimal
+ * representation.
+ *
+ * Matches Rust's `strip_leading_zeros()`.
+ *
+ * @param bytes - The byte array to strip
+ * @returns A subarray with leading zeros removed
+ */
+export function stripLeadingZeros(bytes: Uint8Array): Uint8Array {
+  let start = 0;
+  while (start < bytes.length && bytes[start] === 0) {
+    start++;
+  }
+  return bytes.subarray(start);
+}
+
+/**
+ * Convert a non-negative bigint to a big-endian byte array.
+ *
+ * Zero returns an empty Uint8Array.
+ *
+ * @param value - A non-negative bigint value
+ * @returns Big-endian byte representation
+ */
+export function bigintToBytes(value: bigint): Uint8Array {
+  if (value === 0n) return new Uint8Array(0);
+  const hex = value.toString(16);
+  const padded = hex.length % 2 !== 0 ? `0${hex}` : hex;
+  const bytes = new Uint8Array(padded.length / 2);
+  for (let i = 0; i < bytes.length; i++) {
+    bytes[i] = parseInt(padded.substring(i * 2, i * 2 + 2), 16);
+  }
+  return bytes;
+}
+
+/**
+ * Convert a big-endian byte array to a bigint.
+ *
+ * Empty array returns 0n.
+ *
+ * @param bytes - Big-endian byte representation
+ * @returns The bigint value
+ */
+export function bytesToBigint(bytes: Uint8Array): bigint {
+  if (bytes.length === 0) return 0n;
+  let result = 0n;
+  for (const byte of bytes) {
+    result = (result << 8n) | BigInt(byte);
+  }
+  return result;
+}
+
+/**
+ * Encode a non-negative bigint as a CBOR tag 2 (positive bignum).
+ *
+ * Matches Rust's `From<BigUint> for CBOR`.
+ *
+ * The value is always encoded as a bignum regardless of size.
+ * Zero is encoded as tag 2 with an empty byte string.
+ *
+ * @param value - A non-negative bigint (must be >= 0n)
+ * @returns CBOR tagged value
+ * @throws CborError with type OutOfRange if value is negative
+ */
+export function biguintToCbor(value: bigint): Cbor {
+  if (value < 0n) {
+    throw new CborError({ type: "OutOfRange" });
+  }
+  const bytes = bigintToBytes(value);
+  const stripped = stripLeadingZeros(bytes);
+  return toTaggedValue(TAG_2_POSITIVE_BIGNUM, stripped);
+}
+
+/**
+ * Encode a bigint as a CBOR tag 2 or tag 3 bignum.
+ *
+ * Matches Rust's `From<BigInt> for CBOR`.
+ *
+ * - Non-negative values use tag 2 (positive bignum).
+ * - Negative values use tag 3 (negative bignum), where the encoded
+ *   magnitude is `|value| - 1` per RFC 8949.
+ *
+ * @param value - Any bigint value
+ * @returns CBOR tagged value
+ */
+export function bigintToCbor(value: bigint): Cbor {
+  if (value >= 0n) {
+    return biguintToCbor(value);
+  }
+  // Negative: use tag 3 with magnitude = |value| - 1
+  // For value = -1, magnitude = 1, so n = 0 -> encode as 0x00
+  // For value = -2, magnitude = 2, so n = 1 -> encode as 0x01
+  const magnitude = -value;
+  const n = magnitude - 1n;
+  const bytes = bigintToBytes(n);
+  const stripped = stripLeadingZeros(bytes);
+  // For n = 0 (value = -1), bigintToBytes returns empty, but we need 0x00
+  const contentBytes = stripped.length === 0 ? new Uint8Array([0]) : stripped;
+  return toTaggedValue(TAG_3_NEGATIVE_BIGNUM, contentBytes);
+}
+
+/**
+ * Decode a BigUint from an untagged CBOR byte string.
+ *
+ * Matches Rust's `biguint_from_untagged_cbor()`.
+ *
+ * This function is intended for use in tag summarizers where the tag has
+ * already been stripped. It expects a CBOR byte string representing the
+ * big-endian magnitude of a positive bignum (tag 2 content).
+ *
+ * Enforces canonical encoding: no leading zero bytes (except empty for zero).
+ *
+ * @param cbor - A CBOR value that should be a byte string
+ * @returns Non-negative bigint
+ * @throws CborError with type WrongType if not a byte string
+ * @throws CborError with type NonCanonicalNumeric if encoding is non-canonical
+ */
+export function biguintFromUntaggedCbor(cbor: Cbor): bigint {
+  if (cbor.type !== MajorType.ByteString) {
+    throw new CborError({ type: "WrongType" });
+  }
+  const bytes = cbor.value;
+  validateBignumMagnitude(bytes, false);
+  return bytesToBigint(bytes);
+}
+
+/**
+ * Decode a BigInt from an untagged CBOR byte string for a negative bignum.
+ *
+ * Matches Rust's `bigint_from_negative_untagged_cbor()`.
+ *
+ * This function is intended for use in tag summarizers where the tag has
+ * already been stripped. It expects a CBOR byte string representing `n` where
+ * the actual value is `-1 - n` (tag 3 content per RFC 8949).
+ *
+ * Enforces canonical encoding: no leading zero bytes (except single `0x00`
+ * for -1).
+ *
+ * @param cbor - A CBOR value that should be a byte string
+ * @returns Negative bigint
+ * @throws CborError with type WrongType if not a byte string
+ * @throws CborError with type NonCanonicalNumeric if encoding is non-canonical
+ */
+export function bigintFromNegativeUntaggedCbor(cbor: Cbor): bigint {
+  if (cbor.type !== MajorType.ByteString) {
+    throw new CborError({ type: "WrongType" });
+  }
+  const bytes = cbor.value;
+  validateBignumMagnitude(bytes, true);
+  const n = bytesToBigint(bytes);
+  const magnitude = n + 1n;
+  return -magnitude;
+}
+
+/**
+ * Convert CBOR to a non-negative bigint.
+ *
+ * Matches Rust's `TryFrom<CBOR> for BigUint`.
+ *
+ * Accepts:
+ * - Major type 0 (unsigned integer)
+ * - Tag 2 (positive bignum) with canonical byte string
+ *
+ * Rejects:
+ * - Major type 1 (negative integer) -> OutOfRange
+ * - Tag 3 (negative bignum) -> OutOfRange
+ * - Floating-point values -> WrongType
+ * - Non-canonical bignum encodings -> NonCanonicalNumeric
+ *
+ * @param cbor - The CBOR value to convert
+ * @returns Non-negative bigint
+ * @throws CborError
+ */
+export function cborToBiguint(cbor: Cbor): bigint {
+  switch (cbor.type) {
+    case MajorType.Unsigned:
+      return BigInt(cbor.value);
+    case MajorType.Negative:
+      throw new CborError({ type: "OutOfRange" });
+    case MajorType.Tagged: {
+      // bigint-aware comparison: avoids `Number(tag)` precision loss for
+      // tag values > MAX_SAFE_INTEGER.
+      if (tagEquals(cbor.tag, TAG_2_POSITIVE_BIGNUM)) {
+        const inner = cbor.value;
+        if (inner.type !== MajorType.ByteString) {
+          throw new CborError({ type: "WrongType" });
+        }
+        const bytes = inner.value;
+        validateBignumMagnitude(bytes, false);
+        return bytesToBigint(bytes);
+      } else if (tagEquals(cbor.tag, TAG_3_NEGATIVE_BIGNUM)) {
+        throw new CborError({ type: "OutOfRange" });
+      }
+      throw new CborError({ type: "WrongType" });
+    }
+    case MajorType.ByteString:
+    case MajorType.Text:
+    case MajorType.Array:
+    case MajorType.Map:
+    case MajorType.Simple:
+      throw new CborError({ type: "WrongType" });
+  }
+}
+
+/**
+ * Compare a CBOR tag value (which may be `number` or `bigint`) against a
+ * small numeric literal. Avoids the `Number(tag) === literal` precision
+ * loss for huge bigint tags.
+ */
+function tagEquals(tag: number | bigint, literal: number): boolean {
+  return typeof tag === "bigint" ? tag === BigInt(literal) : tag === literal;
+}
+
+/**
+ * Convert CBOR to a bigint (any sign).
+ *
+ * Matches Rust's `TryFrom<CBOR> for BigInt`.
+ *
+ * Accepts:
+ * - Major type 0 (unsigned integer)
+ * - Major type 1 (negative integer)
+ * - Tag 2 (positive bignum) with canonical byte string
+ * - Tag 3 (negative bignum) with canonical byte string
+ *
+ * Rejects:
+ * - Floating-point values -> WrongType
+ * - Non-canonical bignum encodings -> NonCanonicalNumeric
+ *
+ * @param cbor - The CBOR value to convert
+ * @returns A bigint value
+ * @throws CborError
+ */
+export function cborToBigint(cbor: Cbor): bigint {
+  switch (cbor.type) {
+    case MajorType.Unsigned:
+      return BigInt(cbor.value);
+    case MajorType.Negative: {
+      // CBOR negative: value stored is n where actual = -1 - n
+      const n = BigInt(cbor.value);
+      const magnitude = n + 1n;
+      return -magnitude;
+    }
+    case MajorType.Tagged: {
+      if (tagEquals(cbor.tag, TAG_2_POSITIVE_BIGNUM)) {
+        const inner = cbor.value;
+        if (inner.type !== MajorType.ByteString) {
+          throw new CborError({ type: "WrongType" });
+        }
+        const bytes = inner.value;
+        validateBignumMagnitude(bytes, false);
+        const mag = bytesToBigint(bytes);
+        if (mag === 0n) {
+          return 0n;
+        }
+        return mag;
+      } else if (tagEquals(cbor.tag, TAG_3_NEGATIVE_BIGNUM)) {
+        const inner = cbor.value;
+        if (inner.type !== MajorType.ByteString) {
+          throw new CborError({ type: "WrongType" });
+        }
+        const bytes = inner.value;
+        validateBignumMagnitude(bytes, true);
+        const n = bytesToBigint(bytes);
+        const magnitude = n + 1n;
+        return -magnitude;
+      }
+      throw new CborError({ type: "WrongType" });
+    }
+    case MajorType.ByteString:
+    case MajorType.Text:
+    case MajorType.Array:
+    case MajorType.Map:
+    case MajorType.Simple:
+      throw new CborError({ type: "WrongType" });
+  }
+}

package/src/byte-string.ts

@@ -1,4 +1,8 @@
 /**
+ * Copyright © 2023-2026 Blockchain Commons, LLC
+ * Copyright © 2025-2026 Parity Technologies
+ *
+ *
  * Byte string utilities for dCBOR.
  *
  * Represents a CBOR byte string (major type 2).
@@ -44,7 +48,7 @@ import { CborError } from "./error";
  * ```
  */
 export class ByteString {
-  #data: Uint8Array;
+  private _data: Uint8Array;
 
   /**
    * Creates a new `ByteString` from a Uint8Array or array of bytes.
@@ -62,9 +66,9 @@ export class ByteString {
    */
   constructor(data: Uint8Array | number[]) {
     if (Array.isArray(data)) {
-      this.#data = new Uint8Array(data);
+      this._data = new Uint8Array(data);
     } else {
-      this.#data = new Uint8Array(data);
+      this._data = new Uint8Array(data);
     }
   }
 
@@ -103,7 +107,7 @@ export class ByteString {
    * ```
    */
   data(): Uint8Array {
-    return this.#data;
+    return this._data;
   }
 
   /**
@@ -121,7 +125,7 @@ export class ByteString {
    * ```
    */
   len(): number {
-    return this.#data.length;
+    return this._data.length;
   }
 
   /**
@@ -139,7 +143,7 @@ export class ByteString {
    * ```
    */
   isEmpty(): boolean {
-    return this.#data.length === 0;
+    return this._data.length === 0;
   }
 
   /**
@@ -160,10 +164,10 @@ export class ByteString {
    */
   extend(other: Uint8Array | number[]): void {
     const otherArray = Array.isArray(other) ? new Uint8Array(other) : other;
-    const newData = new Uint8Array(this.#data.length + otherArray.length);
-    newData.set(this.#data, 0);
-    newData.set(otherArray, this.#data.length);
-    this.#data = newData;
+    const newData = new Uint8Array(this._data.length + otherArray.length);
+    newData.set(this._data, 0);
+    newData.set(otherArray, this._data.length);
+    this._data = newData;
   }
 
   /**
@@ -184,7 +188,7 @@ export class ByteString {
    * ```
    */
   toUint8Array(): Uint8Array {
-    return new Uint8Array(this.#data);
+    return new Uint8Array(this._data);
   }
 
   /**
@@ -211,7 +215,7 @@ export class ByteString {
    * ```
    */
   iter(): Iterator<number> {
-    return this.#data.values();
+    return this._data.values();
   }
 
   /**
@@ -233,7 +237,7 @@ export class ByteString {
    * ```
    */
   toCbor(): Cbor {
-    return toCbor(this.#data);
+    return toCbor(this._data);
   }
 
   /**
@@ -272,7 +276,7 @@ export class ByteString {
    * @returns Byte at index or undefined
    */
   at(index: number): number | undefined {
-    return this.#data[index];
+    return this._data[index];
   }
 
   /**
@@ -282,9 +286,9 @@ export class ByteString {
    * @returns true if equal
    */
   equals(other: ByteString): boolean {
-    if (this.#data.length !== other.#data.length) return false;
-    for (let i = 0; i < this.#data.length; i++) {
-      if (this.#data[i] !== other.#data[i]) return false;
+    if (this._data.length !== other._data.length) return false;
+    for (let i = 0; i < this._data.length; i++) {
+      if (this._data[i] !== other._data[i]) return false;
     }
     return true;
   }

package/src/cbor-codable.ts

@@ -1,4 +1,8 @@
 /**
+ * Copyright © 2023-2026 Blockchain Commons, LLC
+ * Copyright © 2025-2026 Parity Technologies
+ *
+ *
  * CBOR Encoding and Decoding Interfaces.
  *
  * These interfaces provide functionality for converting between TypeScript types and

package/src/cbor-tagged-codable.ts

@@ -1,4 +1,8 @@
 /**
+ * Copyright © 2023-2026 Blockchain Commons, LLC
+ * Copyright © 2025-2026 Parity Technologies
+ *
+ *
  * Tagged CBOR encoding and decoding support.
  *
  * This module provides the `CborTaggedCodable` interface, which serves as a

package/src/cbor-tagged-decodable.ts

@@ -1,4 +1,8 @@
 /**
+ * Copyright © 2023-2026 Blockchain Commons, LLC
+ * Copyright © 2025-2026 Parity Technologies
+ *
+ *
  * Tagged CBOR decoding support.
  *
  * This module provides the `CborTaggedDecodable` interface, which enables types to
@@ -15,6 +19,7 @@ import { type Cbor, MajorType } from "./cbor";
 import type { CborTagged } from "./cbor-tagged";
 import type { Tag } from "./tag";
 import { CborError } from "./error";
+import { decodeCbor } from "./decode";
 
 /**
  * Interface for types that can be decoded from CBOR with a specific tag.
@@ -154,15 +159,16 @@ export const validateTag = (cbor: Cbor, expectedTags: Tag[]): Tag => {
     throw new CborError({ type: "WrongType" });
   }
 
-  const expectedValues = expectedTags.map((t) => t.value);
   const tagValue = cbor.tag;
-
   const matchingTag = expectedTags.find((t) => t.value === tagValue);
   if (matchingTag === undefined) {
-    const expectedStr = expectedValues.join(" or ");
+    // Mirror Rust's `Error::WrongTag(expected, actual)` — produce the
+    // structured WrongTag variant rather than a stringly-typed Custom
+    // error so callers can branch on `error.type === "WrongTag"`.
     throw new CborError({
-      type: "Custom",
-      message: `Wrong tag: expected ${expectedStr}, got ${tagValue}`,
+      type: "WrongTag",
+      expected: expectedTags[0],
+      actual: { value: tagValue },
     });
   }
 
@@ -182,3 +188,25 @@ export const extractTaggedContent = (cbor: Cbor): Cbor => {
   }
   return cbor.value;
 };
+
+/**
+ * Default `fromTaggedCborData()` implementation — `decodeCbor(data)` then
+ * delegate to the decodable's `fromTaggedCbor()`.
+ *
+ * Mirrors Rust's default `from_tagged_cbor_data` impl on
+ * `CBORTaggedDecodable`.
+ */
+export function fromTaggedCborData<T>(decodable: CborTaggedDecodable<T>, data: Uint8Array): T {
+  return decodable.fromTaggedCbor(decodeCbor(data));
+}
+
+/**
+ * Default `fromUntaggedCborData()` implementation — `decodeCbor(data)`
+ * then delegate to the decodable's `fromUntaggedCbor()`.
+ *
+ * Mirrors Rust's default `from_untagged_cbor_data` impl on
+ * `CBORTaggedDecodable`.
+ */
+export function fromUntaggedCborData<T>(decodable: CborTaggedDecodable<T>, data: Uint8Array): T {
+  return decodable.fromUntaggedCbor(decodeCbor(data));
+}

package/src/cbor-tagged-encodable.ts

@@ -1,4 +1,8 @@
 /**
+ * Copyright © 2023-2026 Blockchain Commons, LLC
+ * Copyright © 2025-2026 Parity Technologies
+ *
+ *
  * Tagged CBOR encoding support.
  *
  * This module provides the `CborTaggedEncodable` interface, which enables types to
@@ -136,3 +140,14 @@ export const createTaggedCbor = (encodable: CborTaggedEncodable): Cbor => {
     value: untagged,
   });
 };
+
+/**
+ * Default `taggedCborData()` implementation — `taggedCbor().toData()`.
+ *
+ * Mirrors Rust's default `tagged_cbor_data()` impl on
+ * `CBORTaggedEncodable`. TypeScript interfaces don't carry method bodies,
+ * so this helper plays the role of the Rust trait default; concrete types
+ * call it from their own `taggedCborData()` if they don't need to override.
+ */
+export const taggedCborData = (encodable: CborTaggedEncodable): Uint8Array =>
+  (encodable.taggedCbor() as { toData(): Uint8Array }).toData();

package/src/cbor-tagged.ts

@@ -1,4 +1,8 @@
 /**
+ * Copyright © 2023-2026 Blockchain Commons, LLC
+ * Copyright © 2025-2026 Parity Technologies
+ *
+ *
  * Base trait for types that have associated CBOR tags.
  *
  * CBOR allows values to be "tagged" with semantic information using tag
@@ -95,10 +99,16 @@ export interface CborTagged {
 }
 
 // Re-export interfaces and functions from separate modules for convenience
-export { type CborTaggedEncodable, createTaggedCbor } from "./cbor-tagged-encodable";
+export {
+  type CborTaggedEncodable,
+  createTaggedCbor,
+  taggedCborData,
+} from "./cbor-tagged-encodable";
 export {
   type CborTaggedDecodable,
   validateTag,
   extractTaggedContent,
+  fromTaggedCborData,
+  fromUntaggedCborData,
 } from "./cbor-tagged-decodable";
 export { type CborTaggedCodable } from "./cbor-tagged-codable";