@cardananium/cquisitor-lib 0.1.0-beta.54 → 0.1.0-beta.55

package/browser/cquisitor_lib.d.ts

@@ -258,7 +258,57 @@ export function cddl_format(cddl: string): string;
 
 /** One entry from `map_cbor_to_cddl`: a single position of a CBOR
  *  node, the type that matched it, and the path it ends up at in the
- *  output of `decode_cbor_against_cddl`. */
+ *  output of `decode_cbor_against_cddl`.
+ *
+ *  ## `decoded_path` conventions
+ *
+ *  Every node addressable in the JSON tree returned by
+ *  `decode_cbor_against_cddl` has at least one entry here — including
+ *  the synthetic keys the decoder inserts when the data shape doesn't
+ *  fit a plain JSON object. UI consumers can right-click any tree row
+ *  and look up `entries.find(e => e.decoded_path === path)` to find
+ *  the matching CBOR + CDDL spans.
+ *
+ *  Synthetic-key paths:
+ *
+ *  * `<wrapper>["@tag"]` — the tag-number row of an unspecialised
+ *    tagged value (decoder represents these as `{@tag, @value}`).
+ *    `cbor_byte_span` covers just the tag header bytes (`d9 0102`,
+ *    not the whole `Tag(258, …)` extent); `cddl_byte_span` covers the
+ *    `#6.NNN(...)` form. Tags 0/2/3 are specialised to scalars and
+ *    don't get this row.
+ *  * `<wrapper>["@value"]` — the inner value of an unspecialised tag.
+ *    Resolves to the inner type's CDDL location.
+ *  * `<arr>["@positional"]` — wrapper row over the unlabelled slots
+ *    of a mixed (labelled + unlabelled) tuple. No `cddl_byte_span`.
+ *    `cbor_byte_span` / `cbor_anchor_span` cover the unlabelled items'
+ *    combined byte extent.
+ *  * `<arr>["@positional"][N]` — individual unlabelled slot at array
+ *    index N (kept under `@positional` because the named slots
+ *    occupy the object level).
+ *  * `<arr>["@extra"]` — wrapper row over array items past the schema
+ *    cursor (overlong arrays). No `cddl_byte_span`. `<arr>["@extra"][N]`
+ *    addresses each leftover item.
+ *  * `<map>["@extra"]` — wrapper row over map keys not declared in
+ *    the schema (object form only). `<map>["@extra"][<key>]`
+ *    addresses each leftover entry's value.
+ *  * `<map>["@entries"]` — wrapper row over the wire-order array form
+ *    used when the map has complex keys or duplicate keys (see
+ *    `decode_cbor_against_cddl` docs). No `cddl_byte_span`.
+ *  * `<map>["@entries"][N]` — each pair as a single addressable row
+ *    (covers key+value bytes, `cbor_type: "map_entry"`, `cddl_byte_span`
+ *    = matched MemberKey's declaration if any).
+ *  * `<map>["@entries"][N]["key"]` — key bytes of the Nth pair.
+ *    `entry_role: "key"`.
+ *  * `<map>["@entries"][N]["value"]` — value bytes of the Nth pair,
+ *    plus deeper rows under it walking the matched member's value
+ *    type.
+ *
+ *  Wrapper rows (`@entries`, `@positional`, `@extra`) carry a
+ *  `cbor_type` like `"map_entries"` / `"array_positional"` /
+ *  `"map_extra"` / `"array_extra"` and intentionally omit
+ *  `cddl_byte_span` — they are JSON-shape artefacts with no CDDL
+ *  counterpart. */
 export interface CborCddlMapEntry {
     /** Path into the *raw* CBOR tree (numeric map keys are bracketed). */
     cbor_path: string;
@@ -267,7 +317,10 @@ export interface CborCddlMapEntry {
      *  because decoded JSON has only string keys; identifier-safe keys
      *  use dot notation (`.name`). For unspecialised tags (anything
      *  except 0 / 2 / 3) the inner gets an extra `["@value"]` segment
-     *  to match the `{@tag, @value}` wrapper the decoder emits. */
+     *  to match the `{@tag, @value}` wrapper the decoder emits.
+     *
+     *  See the interface comment for the full list of synthetic-key
+     *  segments (`@tag`, `@value`, `@positional`, `@extra`, `@entries`). */
     decoded_path: string;
     /** Whether this entry describes the value at `cbor_path`, or the
      *  *key* of a map entry at that path. Map entries with named keys
@@ -280,11 +333,17 @@ export interface CborCddlMapEntry {
     cbor_byte_span: { offset: number; length: number };
     /** Whole-structure byte range (= `cbor_byte_span` for scalars). */
     cbor_anchor_span: { offset: number; length: number };
-    /** Byte range in the CDDL source describing this position. */
-    cddl_byte_span: SourceSpan;
+    /** Byte range in the CDDL source describing this position. Omitted
+     *  on synthetic wrapper rows (`@entries`, `@positional`, `@extra`)
+     *  which have no CDDL counterpart. */
+    cddl_byte_span?: SourceSpan;
     /** Name of the CDDL rule that matched, if a rule boundary was crossed. */
     rule_name?: string;
-    /** CBOR node's wire type (`U8`, `Bytes`, `Map`, `Array`, `Tag`, …). */
+    /** CBOR node's wire type (`U8`, `Bytes`, `Map`, `Array`, `Tag`, …),
+     *  or — for synthetic wrapper rows — a label describing the
+     *  wrapper's role: `"map_entries"`, `"map_extra"`,
+     *  `"array_positional"`, `"array_extra"`, `"map_entry"` (per-pair
+     *  row in `@entries` form). */
     cbor_type?: string;
 }
 

package/browser/cquisitor_lib_bg.wasm.d.ts

@@ -4,11 +4,9 @@ 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 decode_plutus_program_pretty_uplc: (a: number, b: number) => [number, number, number, number];
-export const decode_plutus_program_uplc_json: (a: number, b: number) => [number, number, number];
-export const execute_tx_scripts: (a: number, b: number, c: any, d: any) => [number, number, number];
-export const get_ref_script_bytes: (a: number, b: number, c: number) => [number, number, number, number];
-export const get_utxo_list_from_tx: (a: number, b: number) => [number, number, number, number];
+export const check_block_or_tx_signatures: (a: number, b: 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];
 export const cbor_to_json: (a: number, b: number) => [number, number, number];
 export const cddl_format: (a: number, b: number) => [number, number, number, number];
 export const cddl_outline: (a: number, b: number) => [number, number, number];
@@ -19,9 +17,11 @@ export const map_cbor_to_cddl: (a: number, b: number, c: number, d: number, e: n
 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 extract_hashes_from_transaction_js: (a: number, b: number) => [number, number, number, number];
-export const check_block_or_tx_signatures: (a: number, b: 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];
+export const decode_plutus_program_pretty_uplc: (a: number, b: number) => [number, number, number, number];
+export const decode_plutus_program_uplc_json: (a: number, b: number) => [number, number, number];
+export const execute_tx_scripts: (a: number, b: number, c: any, d: any) => [number, number, number];
+export const get_ref_script_bytes: (a: number, b: number, c: number) => [number, number, number, number];
+export const get_utxo_list_from_tx: (a: number, b: number) => [number, number, number, number];
 export const validate_cbor_from_slice: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number, number];
 export const validate_json_from_str: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number, number];
 export const cddl_from_str: (a: number, b: number) => [number, number, number];

package/node/cquisitor_lib.d.ts

@@ -258,7 +258,57 @@ export function cddl_format(cddl: string): string;
 
 /** One entry from `map_cbor_to_cddl`: a single position of a CBOR
  *  node, the type that matched it, and the path it ends up at in the
- *  output of `decode_cbor_against_cddl`. */
+ *  output of `decode_cbor_against_cddl`.
+ *
+ *  ## `decoded_path` conventions
+ *
+ *  Every node addressable in the JSON tree returned by
+ *  `decode_cbor_against_cddl` has at least one entry here — including
+ *  the synthetic keys the decoder inserts when the data shape doesn't
+ *  fit a plain JSON object. UI consumers can right-click any tree row
+ *  and look up `entries.find(e => e.decoded_path === path)` to find
+ *  the matching CBOR + CDDL spans.
+ *
+ *  Synthetic-key paths:
+ *
+ *  * `<wrapper>["@tag"]` — the tag-number row of an unspecialised
+ *    tagged value (decoder represents these as `{@tag, @value}`).
+ *    `cbor_byte_span` covers just the tag header bytes (`d9 0102`,
+ *    not the whole `Tag(258, …)` extent); `cddl_byte_span` covers the
+ *    `#6.NNN(...)` form. Tags 0/2/3 are specialised to scalars and
+ *    don't get this row.
+ *  * `<wrapper>["@value"]` — the inner value of an unspecialised tag.
+ *    Resolves to the inner type's CDDL location.
+ *  * `<arr>["@positional"]` — wrapper row over the unlabelled slots
+ *    of a mixed (labelled + unlabelled) tuple. No `cddl_byte_span`.
+ *    `cbor_byte_span` / `cbor_anchor_span` cover the unlabelled items'
+ *    combined byte extent.
+ *  * `<arr>["@positional"][N]` — individual unlabelled slot at array
+ *    index N (kept under `@positional` because the named slots
+ *    occupy the object level).
+ *  * `<arr>["@extra"]` — wrapper row over array items past the schema
+ *    cursor (overlong arrays). No `cddl_byte_span`. `<arr>["@extra"][N]`
+ *    addresses each leftover item.
+ *  * `<map>["@extra"]` — wrapper row over map keys not declared in
+ *    the schema (object form only). `<map>["@extra"][<key>]`
+ *    addresses each leftover entry's value.
+ *  * `<map>["@entries"]` — wrapper row over the wire-order array form
+ *    used when the map has complex keys or duplicate keys (see
+ *    `decode_cbor_against_cddl` docs). No `cddl_byte_span`.
+ *  * `<map>["@entries"][N]` — each pair as a single addressable row
+ *    (covers key+value bytes, `cbor_type: "map_entry"`, `cddl_byte_span`
+ *    = matched MemberKey's declaration if any).
+ *  * `<map>["@entries"][N]["key"]` — key bytes of the Nth pair.
+ *    `entry_role: "key"`.
+ *  * `<map>["@entries"][N]["value"]` — value bytes of the Nth pair,
+ *    plus deeper rows under it walking the matched member's value
+ *    type.
+ *
+ *  Wrapper rows (`@entries`, `@positional`, `@extra`) carry a
+ *  `cbor_type` like `"map_entries"` / `"array_positional"` /
+ *  `"map_extra"` / `"array_extra"` and intentionally omit
+ *  `cddl_byte_span` — they are JSON-shape artefacts with no CDDL
+ *  counterpart. */
 export interface CborCddlMapEntry {
     /** Path into the *raw* CBOR tree (numeric map keys are bracketed). */
     cbor_path: string;
@@ -267,7 +317,10 @@ export interface CborCddlMapEntry {
      *  because decoded JSON has only string keys; identifier-safe keys
      *  use dot notation (`.name`). For unspecialised tags (anything
      *  except 0 / 2 / 3) the inner gets an extra `["@value"]` segment
-     *  to match the `{@tag, @value}` wrapper the decoder emits. */
+     *  to match the `{@tag, @value}` wrapper the decoder emits.
+     *
+     *  See the interface comment for the full list of synthetic-key
+     *  segments (`@tag`, `@value`, `@positional`, `@extra`, `@entries`). */
     decoded_path: string;
     /** Whether this entry describes the value at `cbor_path`, or the
      *  *key* of a map entry at that path. Map entries with named keys
@@ -280,11 +333,17 @@ export interface CborCddlMapEntry {
     cbor_byte_span: { offset: number; length: number };
     /** Whole-structure byte range (= `cbor_byte_span` for scalars). */
     cbor_anchor_span: { offset: number; length: number };
-    /** Byte range in the CDDL source describing this position. */
-    cddl_byte_span: SourceSpan;
+    /** Byte range in the CDDL source describing this position. Omitted
+     *  on synthetic wrapper rows (`@entries`, `@positional`, `@extra`)
+     *  which have no CDDL counterpart. */
+    cddl_byte_span?: SourceSpan;
     /** Name of the CDDL rule that matched, if a rule boundary was crossed. */
     rule_name?: string;
-    /** CBOR node's wire type (`U8`, `Bytes`, `Map`, `Array`, `Tag`, …). */
+    /** CBOR node's wire type (`U8`, `Bytes`, `Map`, `Array`, `Tag`, …),
+     *  or — for synthetic wrapper rows — a label describing the
+     *  wrapper's role: `"map_entries"`, `"map_extra"`,
+     *  `"array_positional"`, `"array_extra"`, `"map_entry"` (per-pair
+     *  row in `@entries` form). */
     cbor_type?: string;
 }
 

package/node/cquisitor_lib_bg.wasm.d.ts

@@ -4,11 +4,9 @@ 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 decode_plutus_program_pretty_uplc: (a: number, b: number) => [number, number, number, number];
-export const decode_plutus_program_uplc_json: (a: number, b: number) => [number, number, number];
-export const execute_tx_scripts: (a: number, b: number, c: any, d: any) => [number, number, number];
-export const get_ref_script_bytes: (a: number, b: number, c: number) => [number, number, number, number];
-export const get_utxo_list_from_tx: (a: number, b: number) => [number, number, number, number];
+export const check_block_or_tx_signatures: (a: number, b: 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];
 export const cbor_to_json: (a: number, b: number) => [number, number, number];
 export const cddl_format: (a: number, b: number) => [number, number, number, number];
 export const cddl_outline: (a: number, b: number) => [number, number, number];
@@ -19,9 +17,11 @@ export const map_cbor_to_cddl: (a: number, b: number, c: number, d: number, e: n
 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 extract_hashes_from_transaction_js: (a: number, b: number) => [number, number, number, number];
-export const check_block_or_tx_signatures: (a: number, b: 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];
+export const decode_plutus_program_pretty_uplc: (a: number, b: number) => [number, number, number, number];
+export const decode_plutus_program_uplc_json: (a: number, b: number) => [number, number, number];
+export const execute_tx_scripts: (a: number, b: number, c: any, d: any) => [number, number, number];
+export const get_ref_script_bytes: (a: number, b: number, c: number) => [number, number, number, number];
+export const get_utxo_list_from_tx: (a: number, b: number) => [number, number, number, number];
 export const validate_cbor_from_slice: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number, number];
 export const validate_json_from_str: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number, number];
 export const cddl_from_str: (a: number, b: number) => [number, number, number];

package/package.json

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