@cardananium/cquisitor-lib 0.1.0-beta.44 → 0.1.0-beta.45

package/README.md

@@ -22,9 +22,11 @@ Functions:
 - `decode_specific_type(hex, type_name, params)` - Decode specific Cardano type
 - `get_possible_types_for_input(hex)` - Suggests types that can decode given input
 
-### CBOR Decoder
+### 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.
+- `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).
+- `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.
 
 ### Plutus Script Decoder
 
@@ -104,7 +106,8 @@ import {
 
 // Step 1: Parse transaction and identify required data
 const txHex = "84a400..."; // Your transaction in hex format
-const necessaryDataJson = get_necessary_data_list_js(txHex);
+const networkType = "mainnet"; // or "preview" | "preprod"
+const necessaryDataJson = get_necessary_data_list_js(txHex, networkType);
 const necessaryData = JSON.parse(necessaryDataJson);
 
 console.log('Required UTXOs:', necessaryData.utxos);
@@ -177,7 +180,7 @@ import {
 async function validateTransaction(txHex: string): Promise<boolean> {
     try {
         // Parse transaction
-        const necessaryDataJson = get_necessary_data_list_js(txHex);
+        const necessaryDataJson = get_necessary_data_list_js(txHex, "mainnet");
         const necessaryData = JSON.parse(necessaryDataJson);
         
         // Fetch required blockchain data
@@ -226,12 +229,12 @@ async function validateTransaction(txHex: string): Promise<boolean> {
 
 ### Transaction Validation
 
-#### `get_necessary_data_list_js(tx_hex: string): string`
+#### `get_necessary_data_list_js(tx_hex: string, network_type: "mainnet" | "preview" | "preprod"): string`
 
-Extracts required blockchain data for validation.
+Extracts required blockchain data for validation. `network_type` determines the bech32 prefix used when deriving stake/reward addresses for `accounts`, `pools`, and `dReps`.
 
 ```typescript
-const necessaryData = JSON.parse(get_necessary_data_list_js(txHex));
+const necessaryData = JSON.parse(get_necessary_data_list_js(txHex, "mainnet"));
 // Returns: { utxos, accounts, pools, dReps, govActions, ... }
 ```
 
@@ -248,6 +251,23 @@ const result = JSON.parse(validate_transaction_js(txHex, JSON.stringify(context)
 
 Extracts all UTxO references (inputs + collateral + reference inputs) from transaction.
 
+#### `get_ref_script_bytes(tx_hex: string, output_index: number): string`
+
+Returns the hex-encoded CBOR bytes of the reference script embedded in `outputs[output_index]`. Returns an empty string if the output has no reference script or the index is out of range.
+
+```typescript
+const scriptHex = get_ref_script_bytes(txHex, 0);
+```
+
+#### `extract_hashes_from_transaction_js(tx_hex: string): string`
+
+Returns a JSON-serialized `ExtractedHashes` with every script / datum / redeemer / metadata / auxiliary-data hash referenced by the transaction (witness set, outputs with inline scripts/datums, auxiliary data). Useful for building indexers or caches.
+
+```typescript
+const hashes = JSON.parse(extract_hashes_from_transaction_js(txHex));
+// { witness_native_script_hashes, witness_plutus_scripts, witness_datum_hashes, ... }
+```
+
 ### Universal Decoder
 
 #### `get_decodable_types(): string[]`
@@ -290,11 +310,36 @@ const possibleTypes = get_possible_types_for_input("e1a...");
 
 #### `cbor_to_json(cbor_hex: string): CborValue`
 
-Converts CBOR to JSON with positional metadata.
+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.
 
 ```typescript
 const cbor = cbor_to_json("a26461646472...");
-// Returns structured JSON with position info for each element
+// 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" }
+```
+
+See `CborOddityKind` in the type definitions for the full list.
+
+#### `validate_cddl(cddl: string): { valid: boolean, error?: object }`
+
+Parses a CDDL schema and reports whether it is well-formed. Returns `{ valid: true }` on success or `{ valid: false, error: { kind, ... } }` with a structured error on failure.
+
+```typescript
+const result = validate_cddl("thing = {n: uint}");
+// { valid: true }
+```
+
+#### `validate_cbor_against_cddl(cbor_hex: string, cddl: string, rule_name: string): { valid: boolean, error?: object }`
+
+Validates a CBOR payload against a specific rule in a CDDL schema. On mismatch the error carries `kind`, `expected`, and location info.
+
+```typescript
+const result = validate_cbor_against_cddl("01", "thing = tstr", "thing");
+// { valid: false, error: { kind: "mismatch", expected: "tstr", ... } }
 ```
 
 ### Plutus Script Decoder