@cashscript/utils 0.13.0-next.7 → 0.13.0-next.9

package/dist/artifact.d.ts

@@ -1,5 +1,6 @@
 export interface CompilerOptions {
     enforceFunctionParameterTypes?: boolean;
+    enforceLocktimeGuard?: boolean;
 }
 export interface AbiInput {
     name: string;
@@ -46,5 +47,6 @@ export interface Artifact {
         options?: CompilerOptions;
     };
     updatedAt: string;
+    fingerprint?: string;
 }
 export declare function formatArtifact(artifact: Artifact, format: 'json' | 'ts'): string;

package/dist/artifact.js

@@ -1,37 +1,65 @@
 export function formatArtifact(artifact, format) {
     if (format === 'ts') {
-        // We remove any undefined values to make the artifact serializable using stringifyAsTs
+        // We remove any undefined values to make the artifact serializable
         const normalisedArtifact = JSON.parse(JSON.stringify(artifact));
-        return `export default ${stringifyAsTs(normalisedArtifact)} as const;\n`;
+        return `export default ${stringify(normalisedArtifact, 'ts')} as const;\n`;
     }
-    return JSON.stringify(artifact, null, 2);
+    return stringify(artifact, 'json');
 }
 const indent = (level) => '  '.repeat(level);
-function stringifyAsTs(obj, indentationLevel = 1) {
-    // For strings we use JSON.stringify to handle escaping, but we want to use single quotes instead of double quotes
-    // around string values inside objects, to match regular TS style
-    if (typeof obj === 'string') {
-        return `'${JSON.stringify(obj).replace(/'/g, "\\'").replace(/\\"/g, '"').slice(1, -1)}'`;
-    }
-    // Numbers and booleans are just converted to strings
-    if (typeof obj === 'number' || typeof obj === 'boolean') {
+// Objects with this many or more properties are always expanded onto multiple lines, to keep
+// generated `.artifact.ts` files compliant with the `object-curly-newline` lint rule (minProperties: 4)
+const MAX_INLINE_OBJECT_PROPERTIES = 3;
+// Recursively serialises an artifact to JSON or TS. Small records that are elements of an array
+// (e.g. `requires`, `constructorInputs`, `abi` inputs) are kept on a single line so list-like data
+// stays compact, while standalone objects assigned to a property (e.g. `compiler.options`) keep
+// their values expanded one per line.
+function stringify(obj, format, indentationLevel = 1, isArrayElement = false) {
+    if (typeof obj === 'string')
+        return formatString(obj, format);
+    // Numbers, booleans and null are represented identically in JSON and TS
+    if (obj === null || typeof obj === 'number' || typeof obj === 'boolean') {
         return JSON.stringify(obj);
     }
-    // Arrays are recursively formatted with indentation
-    if (Array.isArray(obj)) {
-        if (obj.length === 0)
-            return '[]';
-        const formattedItems = obj.map((item) => `${indent(indentationLevel)}${stringifyAsTs(item, indentationLevel + 1)}`);
-        return `[\n${formattedItems.join(',\n')},\n${indent(indentationLevel - 1)}]`;
-    }
-    // Objects are recursively formatted with indentation
-    if (typeof obj === 'object') {
-        const entries = Object.entries(obj);
-        if (entries.length === 0)
-            return '{}';
-        const formattedEntries = entries.map(([key, value]) => (`${indent(indentationLevel)}${key}: ${stringifyAsTs(value, indentationLevel + 1)}`));
-        return `{\n${formattedEntries.join(',\n')},\n${indent(indentationLevel - 1)}}`;
-    }
+    if (Array.isArray(obj))
+        return formatArray(obj, format, indentationLevel, isArrayElement);
+    if (typeof obj === 'object')
+        return formatObject(obj, format, indentationLevel, isArrayElement);
     throw new Error(`Unsupported type: ${typeof obj}`);
 }
+function formatString(value, format) {
+    // JSON strings use standard double-quoted escaping
+    if (format === 'json')
+        return JSON.stringify(value);
+    // TS strings use single quotes instead of double quotes around string values, to match regular TS style
+    return `'${JSON.stringify(value).replace(/'/g, "\\'").replace(/\\"/g, '"').slice(1, -1)}'`;
+}
+function formatArray(array, format, indentationLevel, isArrayElement) {
+    if (array.length === 0)
+        return '[]';
+    const items = array.map((item) => stringify(item, format, indentationLevel + 1, true));
+    if (isArrayElement && canInline(array))
+        return `[${items.join(', ')}]`;
+    const lines = items.map((item) => `${indent(indentationLevel)}${item}`).join(',\n');
+    const trailingComma = format === 'ts' ? ',' : '';
+    return `[\n${lines}${trailingComma}\n${indent(indentationLevel - 1)}]`;
+}
+function formatObject(obj, format, indentationLevel, isArrayElement) {
+    const entries = Object.entries(obj).filter(([, value]) => value !== undefined);
+    if (entries.length === 0)
+        return '{}';
+    const formatKey = (key) => (format === 'json' ? JSON.stringify(key) : key);
+    const formatted = entries.map(([key, value]) => `${formatKey(key)}: ${stringify(value, format, indentationLevel + 1)}`);
+    if (isArrayElement && entries.length <= MAX_INLINE_OBJECT_PROPERTIES && canInline(obj)) {
+        return `{ ${formatted.join(', ')} }`;
+    }
+    const lines = formatted.map((entry) => `${indent(indentationLevel)}${entry}`).join(',\n');
+    const trailingComma = format === 'ts' ? ',' : '';
+    return `{\n${lines}${trailingComma}\n${indent(indentationLevel - 1)}}`;
+}
+// A container can be inlined when none of its values are themselves a non-empty object or array
+function canInline(container) {
+    const values = Array.isArray(container) ? container : Object.values(container);
+    return values.every((value) => (value === undefined || value === null || typeof value !== 'object' || Object.keys(value).length === 0));
+}
 //# sourceMappingURL=artifact.js.map

package/dist/bitauth-script.js

@@ -1,7 +1,7 @@
 import { range } from './data.js';
 import { scriptToBitAuthAsm } from './script.js';
 import { parseSourceTags, sourceMapToLocationData } from './source-map.js';
-import { PositionHint } from './types.js';
+import { PositionHint, SourceTagKind } from './types.js';
 export function buildLineToOpcodesMap(bytecode, sourceMapOrLocationData) {
     const locationData = typeof sourceMapOrLocationData === 'string' ? sourceMapToLocationData(sourceMapOrLocationData) : sourceMapOrLocationData;
     return locationData.reduce((lineToOpcodeMap, singleLocation, index) => {
@@ -43,14 +43,38 @@ function getDisplayLine(singleLocation) {
 function escapeCommentChars(text) {
     return text.replaceAll('/*', '\\/*').replaceAll('*/', '*\\/');
 }
+// Compiler-injected prologue checks: emitted before the function body but executing at its top.
+const PROLOGUE_KINDS = [
+    SourceTagKind.LOCKTIME_GUARD,
+    SourceTagKind.PARAMETER_VALIDATION,
+];
 function buildInsertions(locationData, sourceLines, sourceTags) {
     const tags = (sourceTags ? parseSourceTags(sourceTags) : []);
     return tags.map((tag) => {
-        const annotation = deriveTagLabel(tag, locationData, sourceLines);
-        const insertAfterLine = getDisplayLine(locationData[Math.max(tag.startIndex - 1, 0)]);
+        const { insertAfterLine, indent } = deriveAnchor(tag, tags, locationData, sourceLines);
+        const annotation = `${indent}${tagDescription(tag, locationData, sourceLines)}`;
         return { insertAfterLine, annotation, startIndex: tag.startIndex, endIndex: tag.endIndex };
     });
 }
+function deriveAnchor(tag, tags, locationData, sourceLines) {
+    if (PROLOGUE_KINDS.includes(tag.kind)) {
+        const prologueTags = tags.filter((t) => PROLOGUE_KINDS.includes(t.kind));
+        // The prologue is one contiguous opcode block at the function's start
+        const lastPrologueOpcode = Math.max(...prologueTags.map((t) => t.endIndex));
+        const firstBodyOpcode = lastPrologueOpcode + 1;
+        const firstBodyLine = getDisplayLine(locationData[firstBodyOpcode]);
+        return {
+            // `insertAfterLine` splices *after* a line, so `firstBodyLine - 1` lands all the prologue
+            // annotations directly above the first body statement, at its indentation.
+            insertAfterLine: firstBodyLine - 1,
+            indent: lineIndent(sourceLines, firstBodyLine),
+        };
+    }
+    return {
+        insertAfterLine: getDisplayLine(locationData[Math.max(tag.startIndex - 1, 0)]),
+        indent: deriveIndent(getDisplayLine(locationData[tag.startIndex]), sourceLines),
+    };
+}
 function spliceSyntheticSourceLines(sourceLines, insertions) {
     return insertions.reduceRight((lines, ins) => [...lines.slice(0, ins.insertAfterLine), ins.annotation, ...lines.slice(ins.insertAfterLine)], sourceLines);
 }
@@ -80,19 +104,36 @@ const getUpdatedLineNumber = (currentLineNumber, insertion, opcodeIndex) => {
         return currentLineNumber + 1;
     return currentLineNumber;
 };
-/** Derive the annotation text (e.g. ">>> for-loop update (i = i + 1)") for a source tag. */
-function deriveTagLabel(tag, locationData, sourceLines) {
+// e.g. ">>> for-loop update (i = i + 1)"
+function tagDescription(tag, locationData, sourceLines) {
+    switch (tag.kind) {
+        case SourceTagKind.LOCKTIME_GUARD:
+            return '>>> tx.locktime guard (auto-injected)';
+        case SourceTagKind.PARAMETER_VALIDATION: {
+            const parameter = deriveSourceText(tag, locationData, sourceLines);
+            return `>>> parameter type check${parameter ? ` (${parameter})` : ''}`;
+        }
+        case SourceTagKind.FOR_UPDATE:
+        default:
+            return `>>> for-loop update (${deriveSourceText(tag, locationData, sourceLines)})`;
+    }
+}
+function deriveIndent(headerLine, sourceLines) {
+    const bodyLine = sourceLines.slice(headerLine).find((l) => l.trim().length > 0);
+    return bodyLine?.match(/^(\s*)/)?.[1] ?? '';
+}
+function lineIndent(sourceLines, line) {
+    return sourceLines[line - 1]?.match(/^(\s*)/)?.[1] ?? '';
+}
+function deriveSourceText(tag, locationData, sourceLines) {
     const headerLine = getDisplayLine(locationData[tag.startIndex]);
-    // Find the column span of the update expression using single-line locations in the tag range
     const singleLineLocations = range(tag.startIndex, tag.endIndex)
         .map((idx) => locationData[idx].location)
-        .filter((loc) => loc.start.line === loc.end.line);
+        .filter((loc) => loc.start.line === loc.end.line && loc.start.column !== loc.end.column);
+    if (singleLineLocations.length === 0)
+        return '';
     const startCol = Math.min(...singleLineLocations.map((loc) => loc.start.column));
     const endCol = Math.max(...singleLineLocations.map((loc) => loc.end.column));
-    const expression = sourceLines[headerLine - 1].substring(startCol, endCol);
-    // Indentation: use first non-empty line after header
-    const bodyLine = sourceLines.slice(headerLine).find((l) => l.trim().length > 0);
-    const indent = bodyLine?.match(/^(\s*)/)?.[1] ?? '';
-    return `${indent}>>> for-loop update (${expression})`;
+    return sourceLines[headerLine - 1].substring(startCol, endCol).trim();
 }
 //# sourceMappingURL=bitauth-script.js.map

package/dist/fingerprint.d.ts

@@ -0,0 +1,5 @@
+import { Op, Script } from './script.js';
+export declare function computeBytecodePattern(bytecode: Uint8Array): Uint8Array;
+export declare function computeBytecodeFingerprint(bytecode: Uint8Array): string;
+export declare function computeBytecodeFingerprintWithConstructorArgs(bytecodeScript: Script, constructorArgsCount: number): string;
+export declare function isPushOpcode(opcode: Op): boolean;

package/dist/fingerprint.js

@@ -0,0 +1,50 @@
+import { binToHex, decodeAuthenticationInstructions, encodeDataPush, flattenBinArray, isPushOperation, } from '@bitauth/libauth';
+import { encodeInt } from './data.js';
+import { sha256 } from './hash.js';
+import { generateContractBytecodeScript, Op, scriptToBytecode } from './script.js';
+// Transform locking bytecode into the normalized "pattern" form: every run of
+// consecutive push instructions is replaced by a single push of the run length.
+// See: https://gitlab.com/0353F40E/smart-contract-fingerprinting/
+export function computeBytecodePattern(bytecode) {
+    const opcodes = decodeAuthenticationInstructions(bytecode).map((instruction) => instruction.opcode);
+    const chunks = groupByPushRun(opcodes).map((run) => (isPushOpcode(run[0]) ? encodePushCount(run.length) : Uint8Array.from(run)));
+    return flattenBinArray(chunks);
+}
+// Split opcodes into consecutive runs that are either all pushes or all non-pushes.
+function groupByPushRun(opcodes) {
+    return opcodes.reduce((opcodeRuns, opcode) => {
+        const lastOpcodeRun = opcodeRuns.at(-1);
+        // If there are no runs yet, start a new run with the current opcode
+        if (!lastOpcodeRun)
+            return [[opcode]];
+        // If the last run is the same type of opcode as the current opcode, add the current opcode to the last run
+        // Else, start a new run with the current opcode
+        if (isPushOpcode(lastOpcodeRun[0]) === isPushOpcode(opcode)) {
+            lastOpcodeRun.push(opcode);
+        }
+        else {
+            opcodeRuns.push([opcode]);
+        }
+        return opcodeRuns;
+    }, []);
+}
+// Compute the SHA256 fingerprint of the normalized bytecode pattern, returned as hex.
+export function computeBytecodeFingerprint(bytecode) {
+    return binToHex(sha256(computeBytecodePattern(bytecode)));
+}
+// Add placeholder constructor arguments to the bytecode script and compute the fingerprint.
+export function computeBytecodeFingerprintWithConstructorArgs(bytecodeScript, constructorArgsCount) {
+    const placeholderConstructorArgs = new Array(constructorArgsCount).fill(0);
+    const bytecodeWithConstructorArgs = generateContractBytecodeScript(bytecodeScript, placeholderConstructorArgs);
+    return computeBytecodeFingerprint(scriptToBytecode(bytecodeWithConstructorArgs));
+}
+// Note: libauth's isPushOperation also matches OP_RESERVED (0x50) — the spec excludes it.
+export function isPushOpcode(opcode) {
+    return isPushOperation(opcode) && opcode !== Op.OP_RESERVED;
+}
+// Encode a push count using the smallest possible push encoding.
+// libauth's encodeDataPush minimally encodes VM Numbers in the -1..16 range as OP_N.
+function encodePushCount(count) {
+    return encodeDataPush(encodeInt(BigInt(count)));
+}
+//# sourceMappingURL=fingerprint.js.map

package/dist/index.d.ts

@@ -2,6 +2,7 @@ export * from './artifact.js';
 export * from './bip68.js';
 export * from './bitauth-script.js';
 export * from './data.js';
+export * from './fingerprint.js';
 export * from './hash.js';
 export * from './script.js';
 export * from './source-map.js';

package/dist/index.js

@@ -2,6 +2,7 @@ export * from './artifact.js';
 export * from './bip68.js';
 export * from './bitauth-script.js';
 export * from './data.js';
+export * from './fingerprint.js';
 export * from './hash.js';
 export * from './script.js';
 export * from './source-map.js';

package/dist/script.js

@@ -37,6 +37,8 @@ export function bytecodeToScript(bytecode) {
 export function asmToBytecode(asm) {
     // Remove any duplicate whitespace
     asm = asm.replace(/\s+/g, ' ').trim();
+    if (asm === '')
+        return new Uint8Array();
     // Convert the ASM tokens to AuthenticationInstructions
     const instructions = asm.split(' ').map((token) => {
         // Even though the OpcodesBch type allows for { [key: number]: string }, we know that the keys are always the opcodes

package/dist/types.d.ts

@@ -52,7 +52,9 @@ export declare enum PositionHint {
     END = 1
 }
 export declare enum SourceTagKind {
-    FOR_UPDATE = "fu"
+    FOR_UPDATE = "fu",
+    LOCKTIME_GUARD = "lg",
+    PARAMETER_VALIDATION = "pv"
 }
 export interface SourceTagEntry {
     startIndex: number;

package/dist/types.js

@@ -191,10 +191,11 @@ export var PositionHint;
     PositionHint[PositionHint["START"] = 0] = "START";
     PositionHint[PositionHint["END"] = 1] = "END";
 })(PositionHint || (PositionHint = {}));
-// Semantic tags for opcodes that need special treatment in debugging output (e.g. synthetic labels).
-// Currently used for loop constructs where opcode order diverges from source line order.
+// Semantic tags for compiler-injected opcodes that have no (or misleading) user source
 export var SourceTagKind;
 (function (SourceTagKind) {
     SourceTagKind["FOR_UPDATE"] = "fu";
+    SourceTagKind["LOCKTIME_GUARD"] = "lg";
+    SourceTagKind["PARAMETER_VALIDATION"] = "pv";
 })(SourceTagKind || (SourceTagKind = {}));
 //# sourceMappingURL=types.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cashscript/utils",
-  "version": "0.13.0-next.7",
+  "version": "0.13.0-next.9",
   "description": "CashScript utilities and types",
   "keywords": [
     "bitcoin cash",
@@ -48,5 +48,5 @@
     "typescript": "^5.9.2",
     "vitest": "^4.0.15"
   },
-  "gitHead": "4e8e91589e1218a7c04db1a4772f625efb0140e9"
+  "gitHead": "1bbda54a000f6744bdb67a6379c7bfb0b784dceb"
 }