@cardananium/cquisitor-lib 0.1.0-beta.46 → 0.1.0-beta.47

package/README.md

@@ -24,7 +24,7 @@ Functions:
 
 ### CBOR Decoder & CDDL Validation
 
-- `cbor_to_json(cbor_hex)` - Converts raw CBOR to JSON with positional information, supporting indefinite arrays/maps and all CBOR types. Each node carries an optional `oddities` array flagging deviations from RFC 8949 deterministic encoding (overlong integers/floats, indefinite length, unsorted/duplicate map keys, non-canonical bignums).
+- `cbor_to_json(cbor_hex)` - Converts raw CBOR to JSON with positional information, supporting indefinite arrays/maps and all CBOR types. Each node carries an optional `oddities` array flagging deviations from RFC 8949 deterministic encoding (overlong integers/floats, indefinite length, unsorted/duplicate map keys, non-canonical bignums). Never throws on malformed input — returns a `{ok, value}` / `{ok: false, error, partial?}` union where `error` is a structured `CborDecodeError` (kind / byte offset / byte span / semantic `path`) and `partial` is the sub-tree decoded before the failure, with every unfinished container flagged `incomplete: true`.
 - `validate_cddl(cddl)` - Parses a CDDL schema and reports structural errors.
 - `validate_cbor_against_cddl(cbor_hex, cddl, rule_name)` - Validates CBOR payload against a CDDL rule with detailed mismatch info.
 
@@ -308,21 +308,34 @@ const possibleTypes = get_possible_types_for_input("e1a...");
 
 ### CBOR Decoder
 
-#### `cbor_to_json(cbor_hex: string): CborValue`
+#### `cbor_to_json(cbor_hex: string): CborDecodeResult`
 
 Converts CBOR to JSON with positional metadata. Each node has `position_info` (byte span of its header) and, for containers/tags, `struct_position_info` (span of the whole subtree). Non-canonical encoding deviations (per RFC 8949 §4.1/§4.2) are flagged locally on the offending node via an optional `oddities: CborOddity[]` field — canonical inputs omit the field entirely.
 
+The function **never throws** on malformed input. On success it returns `{ ok: true, value }`; on failure `{ ok: false, error, partial? }` where `error` is a structured `CborDecodeError` and `partial` is the sub-tree decoded up to the failure point:
+
 ```typescript
-const cbor = cbor_to_json("a26461646472...");
-// Returns structured JSON; each node may carry oddities like:
-//   { kind: "IntNotShortest",     detail: "value 15 uses 2-byte header, shortest is 1" }
-//   { kind: "IndefiniteLength",   detail: "indefinite-length map" }
-//   { kind: "MapKeysNotSorted",   detail: "key at offset 3 sorts after key at offset 5" }
-//   { kind: "DuplicateMapKeys",   detail: "duplicate key at offsets 3 and 6" }
-//   { kind: "BignumForSmallInt",  detail: "unsigned bignum fits in a native CBOR integer" }
+const r = cbor_to_json("a26461646472...");
+if (r.ok) {
+    // r.value — the full positional tree; each node may carry oddities like:
+    //   { kind: "IntNotShortest",    detail: "value 15 uses 2-byte header, shortest is 1" }
+    //   { kind: "IndefiniteLength",  detail: "indefinite-length map" }
+    //   { kind: "MapKeysNotSorted",  detail: "key at offset 3 sorts after key at offset 5" }
+    //   { kind: "DuplicateMapKeys",  detail: "duplicate key at offsets 3 and 6" }
+    //   { kind: "BignumForSmallInt", detail: "unsigned bignum fits in a native CBOR integer" }
+} else {
+    // r.error: { kind, offset?, byte_span?, path, message }
+    //   kind       — machine-readable tag ("invalid_syntax", "unexpected_eof", ...).
+    //   offset     — byte where decoding stopped.
+    //   byte_span  — { offset, length } when the failure pins a range.
+    //   path       — structural location, e.g. "$.entries[1].value[0]".
+    // r.partial (optional) — same shape as a CborValue, but every unfinished
+    //   container carries `incomplete: true`, and partial map entries carry
+    //   `incomplete_at: "key" | "value"` on the half that didn't parse.
+}
 ```
 
-See `CborOddityKind` in the type definitions for the full list.
+See `CborOddityKind` and `CborDecodeErrorKind` in the type definitions for the full lists.
 
 #### `validate_cddl(cddl: string): { valid: boolean, error?: object }`
 

package/browser/cquisitor_lib.d.ts

@@ -102,7 +102,48 @@ export function get_possible_types_for_input(input: string): (string)[];
  * @param {string} cbor_hex
  * @returns {any}
  */
-export function cbor_to_json(cbor_hex: string): CborValue;
+/**
+ * Decodes a CBOR hex string into a positional JSON tree.
+ *
+ * Never throws on malformed input — on failure returns
+ * `{ ok: false, error: CborDecodeError, partial? }`. Structured errors
+ * carry `kind`, `offset`, a `byte_span`, a semantic `path` into the
+ * failing position, and a human `message`.
+ *
+ * When anything was successfully decoded before the failure, `partial`
+ * contains the prefix tree with every un-finished container flagged
+ * `incomplete: true`. Node shape otherwise matches the success value, so
+ * renderers can display it the same way.
+ */
+export function cbor_to_json(cbor_hex: string): CborDecodeResult;
+
+export type CborDecodeResult =
+    | { ok: true; value: CborValue }
+    | { ok: false; error: CborDecodeError; partial?: CborPartialValue };
+
+export type CborDecodeErrorKind =
+    | "invalid_hex"
+    | "invalid_syntax"
+    | "unexpected_eof"
+    | "unexpected_break"
+    | "trailing_data"
+    | "invalid_utf8"
+    | "invalid_chunk"
+    | "int_not_representable"
+    | "non_finite_float"
+    | "io_error";
+
+export interface CborDecodeError {
+    kind: CborDecodeErrorKind;
+    /** Human-readable message. Not stable — use `kind` for branching. */
+    message: string;
+    /** Semantic path into the decoded tree (e.g. `$.entries[1].value[0]`). */
+    path: string;
+    /** Byte offset where decoding failed. Absent only for rare IO fallbacks. */
+    offset?: number;
+    /** Byte range pinned by the failure, when wider than a single byte. */
+    byte_span?: CborPosition;
+}
 
 /**
  * Validates a CDDL schema by parsing it into the intermediate validation tree.
@@ -279,6 +320,63 @@ export type CborValue =
     | CborIndefiniteString
     | CborIndefiniteBytes;
 
+/**
+ * Sub-tree returned alongside a decode error. Structurally identical to
+ * `CborValue`, with two additional flags present **only** on nodes that
+ * couldn't be finished:
+ *
+ *  - `incomplete: true` — on containers (Array / Map / Tag /
+ *    IndefiniteLengthBytes / IndefiniteLengthString) whose body was cut
+ *    short by the failure. For definite-length Array/Map the `items` field
+ *    retains the wire-declared count; `values.length` shows how many slots
+ *    actually decoded.
+ *  - `incomplete_at: "key" | "value"` — on the single map entry where
+ *    decoding stopped; at most one of `key` / `value` on that entry is
+ *    populated, indicating which half had been parsed before the failure.
+ */
+export type CborPartialValue =
+    | CborSimple
+    | CborPartialArray
+    | CborPartialMap
+    | CborPartialTag
+    | CborPartialIndefiniteString
+    | CborPartialIndefiniteBytes;
+
+export interface CborPartialArray extends Omit<CborArray, "values"> {
+    values: CborPartialValue[];
+    incomplete?: true;
+}
+
+export interface CborPartialMap extends Omit<CborMap, "values"> {
+    values: Array<CborPartialMapEntry | { key: CborValue; value: CborValue }>;
+    incomplete?: true;
+}
+
+export interface CborPartialMapEntry {
+    key?: CborPartialValue;
+    value?: CborPartialValue;
+    incomplete: true;
+    incomplete_at: "key" | "value";
+}
+
+export interface CborPartialTag extends Omit<CborTag, "value"> {
+    /** Absent when the inner item could not be parsed at all. */
+    value?: CborPartialValue;
+    incomplete?: true;
+}
+
+export interface CborPartialIndefiniteString
+    extends Omit<CborIndefiniteString, "chunks"> {
+    chunks: CborValue[];
+    incomplete?: true;
+}
+
+export interface CborPartialIndefiniteBytes
+    extends Omit<CborIndefiniteBytes, "chunks"> {
+    chunks: CborValue[];
+    incomplete?: true;
+}
+
 export type CddlValidationResult =
     | { valid: true }
     | { valid: false; error: CddlErrorInfo };

package/browser/cquisitor_lib_bg.js

@@ -28437,6 +28437,12 @@ export function calculate_ex_units_ceil_cost(ex_units, ex_unit_prices) {
 }
 
 /**
+ * Decode CBOR hex into a positional JSON tree.
+ *
+ * Never throws on malformed input — returns a `{ok: false, error: {...}}`
+ * object with a structured decode error: `kind`, `offset`, `byte_span`,
+ * structural `path`, and a human `message`. Successful decodes come back
+ * as `{ok: true, value: <tree>}`.
  * @param {string} cbor_hex
  * @returns {any}
  */

package/browser/cquisitor_lib_bg.wasm.d.ts

@@ -4,7 +4,6 @@ export const memory: WebAssembly.Memory;
 export const decode_specific_type: (a: number, b: number, c: number, d: number, e: any) => [number, number, number];
 export const get_decodable_types: () => [number, number];
 export const get_possible_types_for_input: (a: number, b: number) => [number, number];
-export const check_block_or_tx_signatures: (a: number, b: number) => [number, number, number];
 export const extract_hashes_from_transaction_js: (a: number, b: number) => [number, number, number, number];
 export const get_necessary_data_list_js: (a: number, b: number, c: number, d: number) => [number, number, number, number];
 export const validate_transaction_js: (a: number, b: number, c: number, d: number) => [number, number, number, number];
@@ -16,6 +15,7 @@ export const get_ref_script_bytes: (a: number, b: number, c: number) => [number,
 export const get_utxo_list_from_tx: (a: number, b: number) => [number, number, number, number];
 export const validate_cbor_against_cddl: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number, number];
 export const validate_cddl: (a: number, b: number) => [number, number, number];
+export const check_block_or_tx_signatures: (a: number, b: number) => [number, number, number];
 export const __wbg_bigint_free: (a: number, b: number) => void;
 export const __wbg_certificatesbuilder_free: (a: number, b: number) => void;
 export const __wbg_changeconfig_free: (a: number, b: number) => void;

package/node/cquisitor_lib.d.ts

@@ -102,7 +102,48 @@ export function get_possible_types_for_input(input: string): (string)[];
  * @param {string} cbor_hex
  * @returns {any}
  */
-export function cbor_to_json(cbor_hex: string): CborValue;
+/**
+ * Decodes a CBOR hex string into a positional JSON tree.
+ *
+ * Never throws on malformed input — on failure returns
+ * `{ ok: false, error: CborDecodeError, partial? }`. Structured errors
+ * carry `kind`, `offset`, a `byte_span`, a semantic `path` into the
+ * failing position, and a human `message`.
+ *
+ * When anything was successfully decoded before the failure, `partial`
+ * contains the prefix tree with every un-finished container flagged
+ * `incomplete: true`. Node shape otherwise matches the success value, so
+ * renderers can display it the same way.
+ */
+export function cbor_to_json(cbor_hex: string): CborDecodeResult;
+
+export type CborDecodeResult =
+    | { ok: true; value: CborValue }
+    | { ok: false; error: CborDecodeError; partial?: CborPartialValue };
+
+export type CborDecodeErrorKind =
+    | "invalid_hex"
+    | "invalid_syntax"
+    | "unexpected_eof"
+    | "unexpected_break"
+    | "trailing_data"
+    | "invalid_utf8"
+    | "invalid_chunk"
+    | "int_not_representable"
+    | "non_finite_float"
+    | "io_error";
+
+export interface CborDecodeError {
+    kind: CborDecodeErrorKind;
+    /** Human-readable message. Not stable — use `kind` for branching. */
+    message: string;
+    /** Semantic path into the decoded tree (e.g. `$.entries[1].value[0]`). */
+    path: string;
+    /** Byte offset where decoding failed. Absent only for rare IO fallbacks. */
+    offset?: number;
+    /** Byte range pinned by the failure, when wider than a single byte. */
+    byte_span?: CborPosition;
+}
 
 /**
  * Validates a CDDL schema by parsing it into the intermediate validation tree.
@@ -279,6 +320,63 @@ export type CborValue =
     | CborIndefiniteString
     | CborIndefiniteBytes;
 
+/**
+ * Sub-tree returned alongside a decode error. Structurally identical to
+ * `CborValue`, with two additional flags present **only** on nodes that
+ * couldn't be finished:
+ *
+ *  - `incomplete: true` — on containers (Array / Map / Tag /
+ *    IndefiniteLengthBytes / IndefiniteLengthString) whose body was cut
+ *    short by the failure. For definite-length Array/Map the `items` field
+ *    retains the wire-declared count; `values.length` shows how many slots
+ *    actually decoded.
+ *  - `incomplete_at: "key" | "value"` — on the single map entry where
+ *    decoding stopped; at most one of `key` / `value` on that entry is
+ *    populated, indicating which half had been parsed before the failure.
+ */
+export type CborPartialValue =
+    | CborSimple
+    | CborPartialArray
+    | CborPartialMap
+    | CborPartialTag
+    | CborPartialIndefiniteString
+    | CborPartialIndefiniteBytes;
+
+export interface CborPartialArray extends Omit<CborArray, "values"> {
+    values: CborPartialValue[];
+    incomplete?: true;
+}
+
+export interface CborPartialMap extends Omit<CborMap, "values"> {
+    values: Array<CborPartialMapEntry | { key: CborValue; value: CborValue }>;
+    incomplete?: true;
+}
+
+export interface CborPartialMapEntry {
+    key?: CborPartialValue;
+    value?: CborPartialValue;
+    incomplete: true;
+    incomplete_at: "key" | "value";
+}
+
+export interface CborPartialTag extends Omit<CborTag, "value"> {
+    /** Absent when the inner item could not be parsed at all. */
+    value?: CborPartialValue;
+    incomplete?: true;
+}
+
+export interface CborPartialIndefiniteString
+    extends Omit<CborIndefiniteString, "chunks"> {
+    chunks: CborValue[];
+    incomplete?: true;
+}
+
+export interface CborPartialIndefiniteBytes
+    extends Omit<CborIndefiniteBytes, "chunks"> {
+    chunks: CborValue[];
+    incomplete?: true;
+}
+
 export type CddlValidationResult =
     | { valid: true }
     | { valid: false; error: CddlErrorInfo };

package/node/cquisitor_lib.js

@@ -28663,6 +28663,12 @@ function calculate_ex_units_ceil_cost(ex_units, ex_unit_prices) {
 exports.calculate_ex_units_ceil_cost = calculate_ex_units_ceil_cost;
 
 /**
+ * Decode CBOR hex into a positional JSON tree.
+ *
+ * Never throws on malformed input — returns a `{ok: false, error: {...}}`
+ * object with a structured decode error: `kind`, `offset`, `byte_span`,
+ * structural `path`, and a human `message`. Successful decodes come back
+ * as `{ok: true, value: <tree>}`.
  * @param {string} cbor_hex
  * @returns {any}
  */

package/node/cquisitor_lib_bg.wasm.d.ts

@@ -4,7 +4,6 @@ export const memory: WebAssembly.Memory;
 export const decode_specific_type: (a: number, b: number, c: number, d: number, e: any) => [number, number, number];
 export const get_decodable_types: () => [number, number];
 export const get_possible_types_for_input: (a: number, b: number) => [number, number];
-export const check_block_or_tx_signatures: (a: number, b: number) => [number, number, number];
 export const extract_hashes_from_transaction_js: (a: number, b: number) => [number, number, number, number];
 export const get_necessary_data_list_js: (a: number, b: number, c: number, d: number) => [number, number, number, number];
 export const validate_transaction_js: (a: number, b: number, c: number, d: number) => [number, number, number, number];
@@ -16,6 +15,7 @@ export const get_ref_script_bytes: (a: number, b: number, c: number) => [number,
 export const get_utxo_list_from_tx: (a: number, b: number) => [number, number, number, number];
 export const validate_cbor_against_cddl: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number, number];
 export const validate_cddl: (a: number, b: number) => [number, number, number];
+export const check_block_or_tx_signatures: (a: number, b: number) => [number, number, number];
 export const __wbg_bigint_free: (a: number, b: number) => void;
 export const __wbg_certificatesbuilder_free: (a: number, b: number) => void;
 export const __wbg_changeconfig_free: (a: number, b: number) => void;

package/package.json

@@ -4,7 +4,7 @@
     "Evgenii Lisitskii <evgeniilisitskii@gmail.com>"
   ],
   "description": "Cardano transaction validation library",
-  "version": "0.1.0-beta.46",
+  "version": "0.1.0-beta.47",
   "license": "Apache-2.0",
   "files": [
     "node/cquisitor_lib_bg.wasm",