ecash-lib 4.7.0 → 4.9.0

package/src/index.ts

@@ -31,4 +31,5 @@ export * from './token/empp.js';
 export * from './token/slp.js';
 export * from './token/slp.parse.js';
 export * from './parse/opreturn.js';
+export * from './inputData.js';
 export * as payment from './payment';

package/src/inputData.ts

@@ -0,0 +1,109 @@
+// Copyright (c) 2026 The Bitcoin developers
+// Distributed under the MIT software license, see the accompanying
+// file COPYING or http://www.opensource.org/licenses/mit-license.php.
+
+import { Bytes } from './io/bytes.js';
+import { readOp, isPushOp } from './op.js';
+import { shaRmd160 } from './hash.js';
+import { Address } from './address/address.js';
+import { OP_CHECKSIGVERIFY, OP_EQUAL, OP_EQUALVERIFY } from './opcode.js';
+
+/**
+ * Result of decoding a P2SH input that uses the Agora-style input-data format.
+ *
+ * Format follows ecash-agora ad script (ad.ts parseAdScriptSig, partial.ts adScript):
+ * - scriptSig = <lokad> <data> <sig> <pubkey> <redeemScript>
+ * - lokad first for chronik lokadId indexing
+ * - Redeem script: OP_CHECKSIGVERIFY pushBytes(data) OP_EQUALVERIFY pushBytes(lokad) OP_EQUAL
+ */
+export interface DecodedInputData {
+    /** 4-byte lokad ID (for chronik indexing) */
+    lokadId: Uint8Array;
+    /** Arbitrary data bytes */
+    data: Uint8Array;
+    /** Sender's P2PKH address (from pubkey in scriptSig) */
+    address: string;
+}
+
+/**
+ * Decode scriptSig from a P2SH input that uses the Agora-style input-data format.
+ *
+ * Built: scriptSig = [lokad, data, sig, pubkey, redeemScript]
+ * Redeem script: OP_CHECKSIG pushBytes(data) OP_EQUALVERIFY pushBytes(lokad) OP_EQUAL
+ *
+ * @param scriptSig - The scriptSig bytes from the spending input
+ * @param prefix - Address prefix (default 'ecash')
+ * @returns Decoded lokadId, data, and address, or undefined if the format doesn't match
+ */
+export function decodeInputData(
+    scriptSig: Uint8Array,
+    prefix = 'ecash',
+): DecodedInputData | undefined {
+    const pushes: Uint8Array[] = [];
+    const bytes = new Bytes(scriptSig);
+
+    while (bytes.data.length - bytes.idx > 0) {
+        try {
+            const op = readOp(bytes);
+            if (isPushOp(op)) {
+                pushes.push(op.data);
+            }
+        } catch {
+            return undefined;
+        }
+    }
+
+    // scriptSig = <lokad> <data> <sig> <pubkey> <redeemScript>
+    if (pushes.length < 5) {
+        return undefined;
+    }
+    const lokadId = pushes[0];
+    if (lokadId.length !== 4) {
+        return undefined;
+    }
+    const data = pushes[1];
+    const pubkey = pushes[pushes.length - 2];
+    const redeemScript = pushes[pushes.length - 1];
+
+    if (pubkey.length !== 33 && pubkey.length !== 65) {
+        return undefined;
+    }
+
+    // Redeem script: OP_CHECKSIGVERIFY pushBytes(data) OP_EQUALVERIFY pushBytes(lokad) OP_EQUAL
+    const redeemBytes = new Bytes(redeemScript);
+    try {
+        if (readOp(redeemBytes) !== OP_CHECKSIGVERIFY) {
+            return undefined;
+        }
+        const dataOp = readOp(redeemBytes);
+        if (!isPushOp(dataOp)) {
+            return undefined;
+        }
+        if (
+            dataOp.data.length !== data.length ||
+            dataOp.data.some((b, i) => b !== data[i])
+        ) {
+            return undefined;
+        }
+        if (readOp(redeemBytes) !== OP_EQUALVERIFY) {
+            return undefined;
+        }
+        const lokadOp = readOp(redeemBytes);
+        if (!isPushOp(lokadOp) || lokadOp.data.length !== 4) {
+            return undefined;
+        }
+        if (lokadOp.data.some((b, i) => b !== lokadId[i])) {
+            return undefined;
+        }
+        if (readOp(redeemBytes) !== OP_EQUAL) {
+            return undefined;
+        }
+    } catch {
+        return undefined;
+    }
+
+    const pkh = shaRmd160(pubkey);
+    const address = Address.p2pkh(pkh, prefix).toString();
+
+    return { lokadId, data, address };
+}

package/src/op.ts

@@ -2,11 +2,14 @@
 // Distributed under the MIT software license, see the accompanying
 // file COPYING or http://www.opensource.org/licenses/mit-license.php.
 
+import { MAX_SCRIPTNUM_BYTE_SIZE } from './consts.js';
 import { Bytes } from './io/bytes.js';
 import { Writer } from './io/writer.js';
 import {
     OP_0,
+    OP_1,
     OP_1NEGATE,
+    OP_16,
     OP_PUSHDATA1,
     OP_PUSHDATA2,
     OP_PUSHDATA4,
@@ -28,6 +31,106 @@ export interface PushOp {
     data: Uint8Array;
 }
 
+/**
+ * Check if bytes are a minimally encoded script number (not arbitrary data).
+ * See CScriptNum::IsMinimallyEncoded in script/script.cpp.
+ */
+function isMinimallyEncoded(data: Uint8Array): boolean {
+    if (data.length === 0) return true;
+    // Check that the number is encoded with the minimum possible number of bytes.
+    // If the most-significant-byte (excluding the sign bit) is zero then we're not minimal.
+    // This also rejects the negative-zero encoding, 0x80.
+    const last = data[data.length - 1]!;
+    if ((last & 0x7f) === 0) {
+        // One exception: if there's more than one byte and the most significant bit of the
+        // second-to-last byte is set, it would conflict with the sign bit. E.g. +-255
+        // encode to 0xff00 and 0xff80 respectively.
+        if (data.length <= 1 || (data[data.length - 2]! & 0x80) === 0) {
+            return false;
+        }
+    }
+    return true;
+}
+
+/**
+ * Decode a minimally-encoded script number from bytes (little-endian, sign-magnitude).
+ * Validates size and minimal encoding; callers can rely on returned value being valid.
+ * Always returns bigint for type safety and full 64-bit range (matches CScriptNum::getint).
+ * Empty byte array decodes to 0.
+ * @throws Error if data exceeds max size or is not minimally encoded
+ */
+function decodeScriptNum(data: Uint8Array): bigint {
+    if (data.length === 0) {
+        return 0n;
+    }
+    if (data.length > MAX_SCRIPTNUM_BYTE_SIZE) {
+        throw new Error(
+            `Script number exceeds maximum size (${data.length} > ${MAX_SCRIPTNUM_BYTE_SIZE} bytes)`,
+        );
+    }
+    if (!isMinimallyEncoded(data)) {
+        throw new Error('Script number is not minimally encoded');
+    }
+    let result = 0n;
+    for (let i = 0; i < data.length; i++) {
+        result |= BigInt(data[i]!) << BigInt(8 * i);
+    }
+    if (data[data.length - 1]! & 0x80) {
+        const mask = ~(0x80n << BigInt(8 * (data.length - 1)));
+        result &= mask;
+        result = -result;
+    }
+    return result;
+}
+
+/**
+ * Check if the PushOp uses minimal push encoding for its data length.
+ * pushNumberOp always produces minimal pushes.
+ */
+function isMinimalPushOp(pushOp: PushOp): boolean {
+    const len = pushOp.data.length;
+    if (len === 0) return pushOp.opcode === OP_0;
+    if (len >= 1 && len <= 0x4b) return pushOp.opcode === len;
+    if (len >= 0x4c && len <= 0xff) return pushOp.opcode === OP_PUSHDATA1;
+    if (len >= 0x100 && len <= 0xffff) return pushOp.opcode === OP_PUSHDATA2;
+    if (len >= 0x10000 && len <= 0xffffffff)
+        return pushOp.opcode === OP_PUSHDATA4;
+    return false;
+}
+
+/**
+ * Parse a number from a script op.
+ * Inverse of pushNumberOp: handles OP_0 (0), OP_1NEGATE (-1), OP_1 through OP_16,
+ * single-byte push data, and multi-byte minimal script number encoding (up to 64-bit).
+ * Always returns bigint for type safety (matches CScriptNum::getint).
+ * @throws Error with descriptive message if the op does not encode a number
+ */
+export function parseNumberFromOp(op: Op): bigint {
+    if (typeof op === 'number') {
+        if (op === OP_0) {
+            return 0n;
+        }
+        if (op === OP_1NEGATE) {
+            return -1n;
+        }
+        if (op >= OP_1 && op <= OP_16) {
+            return BigInt(op - 0x50);
+        }
+        throw new Error(
+            `Opcode 0x${op.toString(16)} does not encode a number (expected OP_0, OP_1NEGATE, or OP_1-OP_16)`,
+        );
+    }
+    if (!isPushOp(op)) {
+        throw new Error('Op is not a push op');
+    }
+    if (!isMinimalPushOp(op)) {
+        throw new Error(
+            `Push uses non-minimal encoding (opcode 0x${op.opcode.toString(16)} for ${op.data.length} bytes)`,
+        );
+    }
+    return decodeScriptNum(op.data);
+}
+
 /** Returns true if the given object is a `PushOp` */
 export function isPushOp(op: any): op is PushOp {
     if (!op || typeof op !== 'object') {

package/src/payment/action.ts

@@ -76,6 +76,20 @@ export interface Action {
     feePerKb?: bigint;
     /** Maximum tx sersize to be used for tx(s) of this action, defaults to MAX_TX_SERSIZE */
     maxTxSersize?: number;
+    /**
+     * Data encoded in a P2SH redeem script, revealed when the input is spent.
+     * Creates a chained tx: prep tx sends to P2SH, main tx spends it.
+     * Works for any tx type (XEC-only, SLP, ALP). Redeem script includes
+     * sender pubkey, so P2PKH address derivable from the spending input.
+     *
+     * Format follows ecash-agora ad script for chronik indexing:
+     * - lokad: 4-byte identifier (indexed by chronik as lokadId)
+     * - data: arbitrary bytes (like Agora covenant consts, minus covenant variant)
+     *
+     * scriptSig = <lokad> <data> <sig> <pubkey> <redeemScript>
+     * Redeem script: OP_CHECKSIGVERIFY pushBytes(data) OP_EQUALVERIFY pushBytes(lokad) OP_EQUAL
+     */
+    p2shInputData?: { lokad: Uint8Array; data: Uint8Array };
 }
 
 /**
@@ -156,6 +170,7 @@ export interface BurnAction {
 /**
  * Arbitrary data push to be included for token types that support EMPP
  * Not associated with PaymentOutput[]
+ * Only supported for ALP_TOKEN_TYPE_STANDARD (EMPP in OP_RETURN)
  */
 export interface DataAction {
     type: 'DATA';