@hazbase/simplicity 0.0.1

package/dist/core/executor.js

@@ -0,0 +1,664 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.inspectContractCall = inspectContractCall;
+exports.executeContractCall = executeContractCall;
+exports.findContractUtxos = findContractUtxos;
+exports.executeGaslessContractCall = executeGaslessContractCall;
+const promises_1 = require("node:fs/promises");
+const node_os_1 = require("node:os");
+const node_path_1 = __importDefault(require("node:path"));
+const errors_1 = require("./errors");
+const summary_1 = require("./summary");
+const templating_1 = require("./templating");
+const presets_1 = require("./presets");
+const toolchain_1 = require("./toolchain");
+const DEFAULT_FEE_SAT = 100;
+const DEFAULT_SEQUENCE = 4294967293;
+const DUST_MARGIN_SAT = 600;
+function btcStringToSatNumber(btcStr) {
+    const x = Number(btcStr);
+    if (!Number.isFinite(x))
+        throw new errors_1.ValidationError(`Invalid BTC amount: ${btcStr}`);
+    return Math.round(x * 1e8);
+}
+function satToBtcNumber(sat) {
+    return Number((sat / 1e8).toFixed(8));
+}
+function satToBtcStringFromNumber(sat) {
+    const value = BigInt(sat);
+    const whole = value / 100000000n;
+    const frac = value % 100000000n;
+    return `${whole}.${frac.toString().padStart(8, "0")}`;
+}
+function getArtifactLocktime(artifact) {
+    const legacyMinHeight = artifact.legacy?.params?.minHeight;
+    if (typeof legacyMinHeight === "number" && Number.isFinite(legacyMinHeight) && legacyMinHeight >= 0) {
+        return Math.trunc(legacyMinHeight);
+    }
+    const templateVars = artifact.source.templateVars ?? {};
+    const candidate = templateVars.MIN_HEIGHT ?? templateVars.TIMEOUT_HEIGHT;
+    if (typeof candidate === "number" && Number.isFinite(candidate) && candidate >= 0) {
+        return Math.trunc(candidate);
+    }
+    if (typeof candidate === "string" && candidate.trim().length > 0) {
+        const parsed = Number(candidate);
+        if (Number.isFinite(parsed) && parsed >= 0) {
+            return Math.trunc(parsed);
+        }
+    }
+    return 0;
+}
+function parseSimcWitness(output) {
+    const lines = output
+        .split("\n")
+        .map((line) => line.trim())
+        .filter(Boolean);
+    for (const line of lines) {
+        if (line.startsWith("Witness:")) {
+            const rest = line.slice("Witness:".length).trim();
+            if (rest)
+                return rest;
+        }
+    }
+    const nextLineIndex = lines.findIndex((line) => line === "Witness:");
+    if (nextLineIndex >= 0 && lines[nextLineIndex + 1]) {
+        return lines[nextLineIndex + 1];
+    }
+    throw new errors_1.ExecutionError("Could not parse Witness from simc output", { output });
+}
+function normalizeRawTx(maybeJsonOrHex) {
+    const value = String(maybeJsonOrHex).trim();
+    if (value.startsWith("{") || value.startsWith("[")) {
+        const parsed = JSON.parse(value);
+        const hex = parsed.hex ?? parsed.rawtx ?? parsed.rawTx ?? parsed.rawTransactionHex;
+        if (hex)
+            return hex.trim();
+    }
+    if (value.startsWith('"') && value.endsWith('"')) {
+        const parsed = JSON.parse(value);
+        return parsed.trim();
+    }
+    return value;
+}
+function chooseUtxo(utxos, minSat, policy) {
+    const sortCandidates = (entries) => entries.sort((left, right) => {
+        if (policy === "largest")
+            return right.sat - left.sat;
+        if (policy === "newest")
+            return (right.height ?? 0) - (left.height ?? 0);
+        return left.sat - right.sat;
+    });
+    const confirmed = sortCandidates(utxos.filter((utxo) => utxo.confirmed).filter((utxo) => utxo.sat >= minSat));
+    if (confirmed[0])
+        return confirmed[0];
+    const unconfirmed = sortCandidates(utxos.filter((utxo) => !utxo.confirmed).filter((utxo) => utxo.sat >= minSat));
+    return unconfirmed[0] ?? null;
+}
+async function findContractUtxosInMempool(elementsCliPath, contractAddress) {
+    const mempool = await (0, toolchain_1.runCommand)(elementsCliPath, ["getrawmempool"]);
+    const txids = JSON.parse(mempool.stdout);
+    const matches = [];
+    for (const txid of txids) {
+        const tx = await (0, toolchain_1.runCommand)(elementsCliPath, ["getrawtransaction", txid, "true"]);
+        const parsed = JSON.parse(tx.stdout);
+        for (const output of parsed.vout ?? []) {
+            if (output.scriptPubKey?.address !== contractAddress)
+                continue;
+            matches.push({
+                txid,
+                vout: output.n,
+                scriptPubKey: output.scriptPubKey?.hex ?? "",
+                asset: output.asset ?? "",
+                sat: btcStringToSatNumber(String(output.value ?? 0)),
+                confirmed: false,
+            });
+        }
+    }
+    return matches;
+}
+async function scanUtxosByAddress(elementsCliPath, contractAddress) {
+    const pattern = `["addr(${contractAddress})"]`;
+    const result = await (0, toolchain_1.runCommand)(elementsCliPath, ["scantxoutset", "start", pattern]);
+    const parsed = JSON.parse(result.stdout);
+    if (!parsed.success || !Array.isArray(parsed.unspents)) {
+        throw new errors_1.ExecutionError("scantxoutset failed", parsed);
+    }
+    const confirmed = parsed.unspents.map((utxo) => ({
+        txid: utxo.txid,
+        vout: utxo.vout,
+        scriptPubKey: utxo.scriptPubKey,
+        asset: utxo.asset,
+        sat: btcStringToSatNumber(String(utxo.amount)),
+        height: utxo.height,
+        confirmed: true,
+    }));
+    const mempool = confirmed.length === 0 ? await findContractUtxosInMempool(elementsCliPath, contractAddress) : [];
+    return [...confirmed, ...mempool];
+}
+async function decodePsbt(elementsCliPath, psetBase64, wallet) {
+    const result = await (0, toolchain_1.runCommand)(elementsCliPath, [`-rpcwallet=${wallet}`, "decodepsbt", psetBase64]);
+    return JSON.parse(result.stdout);
+}
+async function getAddressInfo(elementsCliPath, wallet, address) {
+    const result = await (0, toolchain_1.runCommand)(elementsCliPath, [`-rpcwallet=${wallet}`, "getaddressinfo", address]);
+    const parsed = JSON.parse(result.stdout);
+    if (!parsed.scriptPubKey) {
+        throw new errors_1.ExecutionError(`Could not get scriptPubKey from address: ${address}`);
+    }
+    return { scriptPubKey: parsed.scriptPubKey, unconfidential: parsed.unconfidential };
+}
+async function allocateWalletAddress(elementsCliPath, wallet) {
+    const result = await (0, toolchain_1.runCommand)(elementsCliPath, [`-rpcwallet=${wallet}`, "getnewaddress"]);
+    const address = result.stdout.trim();
+    const info = await getAddressInfo(elementsCliPath, wallet, address);
+    return {
+        address: info.unconfidential ?? address,
+        scriptPubKey: info.scriptPubKey,
+    };
+}
+async function listWalletUtxos(elementsCliPath, wallet) {
+    const result = await (0, toolchain_1.runCommand)(elementsCliPath, [`-rpcwallet=${wallet}`, "listunspent", "0", "9999999", "[]", "true"]);
+    const parsed = JSON.parse(result.stdout);
+    return parsed.map((entry) => ({
+        txid: entry.txid,
+        vout: entry.vout,
+        amountSat: btcStringToSatNumber(String(entry.amount)),
+        asset: entry.asset,
+        isExplicit: !entry.amountblinder || /^0+$/.test(entry.amountblinder),
+    }));
+}
+function chooseSponsorUtxo(utxos, feeSat) {
+    const candidates = utxos
+        .filter((entry) => entry.amountSat >= feeSat)
+        .sort((left, right) => {
+        if (left.isExplicit !== right.isExplicit) {
+            return left.isExplicit ? -1 : 1;
+        }
+        return left.amountSat - right.amountSat;
+    });
+    return candidates[0] ?? null;
+}
+function buildPsetSummary(decoded, meta) {
+    const inputs = Array.isArray(decoded.inputs)
+        ? decoded.inputs.map((entry) => ({
+            txid: entry.previous_txid ?? null,
+            vout: entry.previous_vout ?? null,
+            sequence: entry.sequence ?? null,
+        }))
+        : [];
+    const outputs = Array.isArray(decoded.outputs)
+        ? decoded.outputs.map((entry, index) => ({
+            n: index,
+            value: entry.amount ?? null,
+            asset: entry.asset ?? null,
+            address: entry.script?.address ?? null,
+            scriptPubKeyHex: entry.script?.hex ?? null,
+            isFee: entry.script?.type === "fee" || entry.script?.is_fee === true || entry.script?.fee === true,
+        }))
+        : [];
+    return {
+        network: meta.network,
+        purpose: meta.purpose,
+        bondDefinitionId: meta.bondDefinitionId ?? null,
+        periodId: meta.periodId ?? null,
+        contract: {
+            address: meta.contractAddress,
+            cmr: meta.cmr,
+            internalKey: meta.internalKey,
+            program: meta.program,
+            minHeight: meta.minHeight,
+        },
+        expectedLiquidReceiver: meta.expectedLiquidReceiver ?? null,
+        inputs,
+        outputs,
+        fee: decoded.fees ?? decoded.fee ?? null,
+    };
+}
+async function getScriptPubKeyHexFromAddress(elementsCliPath, address) {
+    const result = await (0, toolchain_1.runCommand)(elementsCliPath, ["getaddressinfo", address]);
+    const parsed = JSON.parse(result.stdout);
+    if (!parsed.scriptPubKey) {
+        throw new errors_1.ExecutionError(`Could not get scriptPubKey from address: ${address}`);
+    }
+    return parsed.scriptPubKey.toLowerCase();
+}
+async function assertSummaryPolicy(elementsCliPath, summary, expectedLiquidReceiver) {
+    if (!expectedLiquidReceiver)
+        return;
+    const expectedSpk = await getScriptPubKeyHexFromAddress(elementsCliPath, expectedLiquidReceiver);
+    const normalOutputs = summary.outputs.filter((output) => output.isFee !== true);
+    const found = normalOutputs.some((output) => (output.scriptPubKeyHex ?? "").toLowerCase() === expectedSpk);
+    if (!found) {
+        throw new errors_1.ExecutionError("Expected receiver not found in non-fee outputs", {
+            expectedLiquidReceiver,
+            expectedSpk,
+            outputs: normalOutputs,
+        });
+    }
+}
+async function buildExecutionState(config, artifact, input) {
+    const elementsCliPath = config.toolchain.elementsCliPath ?? "eltc";
+    await (0, toolchain_1.runCommand)(elementsCliPath, [`-rpcwallet=${input.wallet}`, "getwalletinfo"]);
+    const feeSat = input.feeSat ?? config.defaults?.feeSat ?? DEFAULT_FEE_SAT;
+    const minSat = feeSat + DUST_MARGIN_SAT;
+    const utxoPolicy = input.utxoPolicy ?? config.defaults?.utxoPolicy ?? "smallest_over";
+    const recipientInfo = await getAddressInfo(elementsCliPath, input.wallet, input.toAddress);
+    const recipientAddress = recipientInfo.unconfidential ?? input.toAddress;
+    const utxos = await scanUtxosByAddress(elementsCliPath, artifact.compiled.contractAddress);
+    const contractUtxo = chooseUtxo(utxos, minSat, utxoPolicy);
+    if (!contractUtxo) {
+        throw new errors_1.UtxoNotFoundError(`No contract UTXO found for address=${artifact.compiled.contractAddress} satisfying minSat=${minSat}`);
+    }
+    const sendSat = input.sendAmount
+        ? Math.round(input.sendAmount * 1e8)
+        : contractUtxo.sat - feeSat;
+    if (!Number.isFinite(sendSat) || sendSat <= 0) {
+        throw new errors_1.ExecutionError("Invalid send amount after fee calculation", {
+            utxoSat: contractUtxo.sat,
+            feeSat,
+            sendSat,
+        });
+    }
+    const inputsJson = JSON.stringify([
+        {
+            txid: contractUtxo.txid,
+            vout: contractUtxo.vout,
+            sequence: input.sequence ?? DEFAULT_SEQUENCE,
+        },
+    ]);
+    const outputsJson = JSON.stringify([{ [recipientAddress]: satToBtcNumber(sendSat) }, { fee: satToBtcNumber(feeSat) }]);
+    const pset1 = await (0, toolchain_1.runCommand)(elementsCliPath, [
+        "createpsbt",
+        inputsJson,
+        outputsJson,
+        String(getArtifactLocktime(artifact)),
+        "true",
+    ]);
+    const psetUpdated = await (0, toolchain_1.runCommand)(elementsCliPath, ["utxoupdatepsbt", pset1.stdout]);
+    const utxoSpec = `${contractUtxo.scriptPubKey}:${contractUtxo.asset}:${satToBtcStringFromNumber(contractUtxo.sat)}`;
+    const updateJson = (await (0, toolchain_1.runHalUpdateInput)(config.toolchain.halSimplicityPath, psetUpdated.stdout, 0, utxoSpec, artifact.compiled.cmr, artifact.compiled.internalKey));
+    const pset2 = updateJson.pset;
+    if (!pset2) {
+        throw new errors_1.ExecutionError("update-input did not return a pset", updateJson);
+    }
+    const decoded = await decodePsbt(elementsCliPath, pset2, input.wallet);
+    const summary = buildPsetSummary(decoded, {
+        network: artifact.network,
+        purpose: input.purpose ?? "sdk_execute",
+        bondDefinitionId: input.bondDefinitionId,
+        periodId: input.periodId,
+        expectedLiquidReceiver: input.expectedLiquidReceiver ?? recipientAddress,
+        contractAddress: artifact.compiled.contractAddress,
+        cmr: artifact.compiled.cmr,
+        internalKey: artifact.compiled.internalKey,
+        program: artifact.compiled.program,
+        minHeight: getArtifactLocktime(artifact) || undefined,
+    });
+    const { canonicalJson: summaryCanonicalJson, hash: summaryHash } = (0, summary_1.summarize)(summary);
+    return {
+        pset2,
+        decoded,
+        summary,
+        summaryHash,
+        summaryCanonicalJson,
+        contractUtxo,
+        sendSat,
+    };
+}
+async function inspectContractCall(config, artifact, input) {
+    const state = await buildExecutionState(config, artifact, input);
+    return {
+        mode: "inspect",
+        summary: state.summary,
+        summaryHash: state.summaryHash,
+        summaryCanonicalJson: state.summaryCanonicalJson,
+        psetBase64: state.pset2,
+        contractUtxo: state.contractUtxo,
+        warnings: [],
+    };
+}
+async function executeContractCall(config, artifact, input) {
+    const elementsCliPath = config.toolchain.elementsCliPath ?? "eltc";
+    const state = await buildExecutionState(config, artifact, input);
+    await assertSummaryPolicy(elementsCliPath, state.summary, input.expectedLiquidReceiver);
+    const finalizedPset = await signContractInput(config, artifact, state.pset2, input.signer.privkeyHex, input.witness);
+    const finalized = { pset: finalizedPset };
+    if (!finalized.pset) {
+        throw new errors_1.ExecutionError("finalize did not return a pset", finalized);
+    }
+    const rawTxHex = normalizeRawTx(await (0, toolchain_1.runHalExtract)(config.toolchain.halSimplicityPath, finalized.pset));
+    let txId;
+    if (input.broadcast) {
+        const mempool = await (0, toolchain_1.runCommand)(elementsCliPath, ["testmempoolaccept", `["${rawTxHex}"]`]);
+        const mempoolParsed = JSON.parse(mempool.stdout);
+        if (!Array.isArray(mempoolParsed) || mempoolParsed[0]?.allowed !== true) {
+            throw new errors_1.ExecutionError("testmempoolaccept rejected transaction", mempoolParsed);
+        }
+        const sendTx = await (0, toolchain_1.runCommand)(elementsCliPath, ["sendrawtransaction", rawTxHex]);
+        txId = sendTx.stdout.trim();
+    }
+    return {
+        mode: "execute",
+        summary: state.summary,
+        summaryHash: state.summaryHash,
+        summaryCanonicalJson: state.summaryCanonicalJson,
+        psetBase64: finalized.pset,
+        rawTxHex,
+        txId,
+        broadcasted: Boolean(input.broadcast),
+        contractUtxo: state.contractUtxo,
+    };
+}
+async function findContractUtxos(config, artifact) {
+    const elementsCliPath = config.toolchain.elementsCliPath ?? "eltc";
+    return scanUtxosByAddress(elementsCliPath, artifact.compiled.contractAddress);
+}
+async function executeGaslessContractCall(config, artifact, input) {
+    if (input.relayer) {
+        return executeRelayedGaslessContractCall(config, artifact, input, input.relayer);
+    }
+    const elementsCliPath = config.toolchain.elementsCliPath ?? "eltc";
+    const wallet = input.wallet ?? config.rpc.wallet ?? "simplicity-test";
+    if (!input.sponsorWallet) {
+        throw new errors_1.ValidationError("sponsorWallet is required when relayer is not provided");
+    }
+    await (0, toolchain_1.runCommand)(elementsCliPath, [`-rpcwallet=${wallet}`, "getwalletinfo"]);
+    await (0, toolchain_1.runCommand)(elementsCliPath, [`-rpcwallet=${input.sponsorWallet}`, "getwalletinfo"]);
+    const contractUtxos = await scanUtxosByAddress(elementsCliPath, artifact.compiled.contractAddress);
+    const contractUtxo = chooseUtxo(contractUtxos, input.sendAmount ? Math.round(input.sendAmount * 1e8) : 1, input.utxoPolicy ?? config.defaults?.utxoPolicy ?? "smallest_over");
+    if (!contractUtxo) {
+        throw new errors_1.UtxoNotFoundError(`No contract UTXO found for address=${artifact.compiled.contractAddress}`);
+    }
+    const feeSat = input.feeSat ?? config.defaults?.feeSat ?? DEFAULT_FEE_SAT;
+    const sendSat = input.sendAmount ? Math.round(input.sendAmount * 1e8) : contractUtxo.sat;
+    if (sendSat <= 0 || sendSat > contractUtxo.sat) {
+        throw new errors_1.ValidationError("sendAmount must be positive and no greater than the contract UTXO amount");
+    }
+    let contractChangeAddress;
+    let contractChangeScriptPubKey;
+    const contractChangeSat = contractUtxo.sat - sendSat;
+    if (contractChangeSat > 0) {
+        if (!input.contractChangeAddress) {
+            throw new errors_1.ValidationError("contractChangeAddress is required when sendAmount is smaller than the contract UTXO");
+        }
+        const changeInfo = await getAddressInfo(elementsCliPath, wallet, input.contractChangeAddress);
+        contractChangeAddress = changeInfo.unconfidential ?? input.contractChangeAddress;
+        contractChangeScriptPubKey = changeInfo.scriptPubKey;
+    }
+    const sponsorUtxos = await listWalletUtxos(elementsCliPath, input.sponsorWallet);
+    const sponsorInput = chooseSponsorUtxo(sponsorUtxos, feeSat);
+    if (!sponsorInput) {
+        throw new errors_1.UtxoNotFoundError(`No sponsor UTXO found in wallet=${input.sponsorWallet} for feeSat=${feeSat}`);
+    }
+    const sponsorChangeSat = sponsorInput.amountSat - feeSat;
+    let sponsorChangeAddress;
+    let sponsorChangeScriptPubKey;
+    if (sponsorChangeSat > 0) {
+        if (input.sponsorChangeAddress) {
+            const info = await getAddressInfo(elementsCliPath, input.sponsorWallet, input.sponsorChangeAddress);
+            sponsorChangeAddress = info.unconfidential ?? input.sponsorChangeAddress;
+            sponsorChangeScriptPubKey = info.scriptPubKey;
+        }
+        else {
+            const allocated = await allocateWalletAddress(elementsCliPath, input.sponsorWallet);
+            sponsorChangeAddress = allocated.address;
+            sponsorChangeScriptPubKey = allocated.scriptPubKey;
+        }
+    }
+    const recipientInfo = await getAddressInfo(elementsCliPath, wallet, input.toAddress);
+    const recipientAddress = recipientInfo.unconfidential ?? input.toAddress;
+    const outputs = [{ [recipientAddress]: satToBtcNumber(sendSat) }];
+    if (contractChangeSat > 0 && contractChangeAddress) {
+        outputs.push({ [contractChangeAddress]: satToBtcNumber(contractChangeSat) });
+    }
+    if (sponsorChangeSat > 0 && sponsorChangeAddress) {
+        outputs.push({ [sponsorChangeAddress]: satToBtcNumber(sponsorChangeSat) });
+    }
+    outputs.push({ fee: satToBtcNumber(feeSat) });
+    const inputsJson = JSON.stringify([
+        { txid: contractUtxo.txid, vout: contractUtxo.vout, sequence: DEFAULT_SEQUENCE },
+        { txid: sponsorInput.txid, vout: sponsorInput.vout, sequence: DEFAULT_SEQUENCE },
+    ]);
+    const outputsJson = JSON.stringify(outputs);
+    const pset1 = await (0, toolchain_1.runCommand)(elementsCliPath, [
+        "createpsbt",
+        inputsJson,
+        outputsJson,
+        String(getArtifactLocktime(artifact)),
+        "true",
+    ]);
+    const psetUpdated = await (0, toolchain_1.runCommand)(elementsCliPath, ["utxoupdatepsbt", pset1.stdout]);
+    const contractSpec = `${contractUtxo.scriptPubKey}:${contractUtxo.asset}:${satToBtcStringFromNumber(contractUtxo.sat)}`;
+    const contractUpdated = (await (0, toolchain_1.runHalUpdateInput)(config.toolchain.halSimplicityPath, psetUpdated.stdout, 0, contractSpec, artifact.compiled.cmr, artifact.compiled.internalKey));
+    if (!contractUpdated.pset) {
+        throw new errors_1.ExecutionError("update-input did not return a pset", contractUpdated);
+    }
+    const decoded = await decodePsbt(elementsCliPath, contractUpdated.pset, input.sponsorWallet);
+    const summary = buildPsetSummary(decoded, {
+        network: artifact.network,
+        purpose: "sdk_gasless_execute",
+        contractAddress: artifact.compiled.contractAddress,
+        cmr: artifact.compiled.cmr,
+        internalKey: artifact.compiled.internalKey,
+        program: artifact.compiled.program,
+        minHeight: getArtifactLocktime(artifact) || undefined,
+        expectedLiquidReceiver: recipientAddress,
+    });
+    const { canonicalJson: summaryCanonicalJson, hash: summaryHash } = (0, summary_1.summarize)(summary);
+    const contractSignedPset = await signContractInput(config, artifact, contractUpdated.pset, input.signer.privkeyHex, input.witness);
+    const sponsorSigned = await (0, toolchain_1.runCommand)(elementsCliPath, [
+        `-rpcwallet=${input.sponsorWallet}`,
+        "walletprocesspsbt",
+        contractSignedPset,
+        "true",
+        "ALL",
+        "true",
+    ]);
+    const sponsorSignedParsed = JSON.parse(sponsorSigned.stdout);
+    if (!sponsorSignedParsed.psbt) {
+        throw new errors_1.ExecutionError("walletprocesspsbt did not return a sponsor-signed pset", sponsorSignedParsed);
+    }
+    const finalized = await (0, toolchain_1.runCommand)(elementsCliPath, ["finalizepsbt", sponsorSignedParsed.psbt, "true"]);
+    const finalizedParsed = JSON.parse(finalized.stdout);
+    if (!finalizedParsed.complete || !finalizedParsed.hex) {
+        throw new errors_1.ExecutionError("PSET was not complete after sponsor signing", finalizedParsed);
+    }
+    let txId;
+    if (input.broadcast) {
+        const mempool = await (0, toolchain_1.runCommand)(elementsCliPath, ["testmempoolaccept", `[\"${finalizedParsed.hex}\"]`]);
+        const mempoolParsed = JSON.parse(mempool.stdout);
+        if (!Array.isArray(mempoolParsed) || mempoolParsed[0]?.allowed !== true) {
+            throw new errors_1.ExecutionError("testmempoolaccept rejected transaction", mempoolParsed);
+        }
+        const sent = await (0, toolchain_1.runCommand)(elementsCliPath, ["sendrawtransaction", finalizedParsed.hex]);
+        txId = sent.stdout.trim();
+    }
+    return {
+        mode: "gasless-execute",
+        summary,
+        summaryHash,
+        summaryCanonicalJson,
+        psetBase64: sponsorSignedParsed.psbt,
+        rawTxHex: finalizedParsed.hex,
+        txId,
+        broadcasted: Boolean(input.broadcast),
+        contractUtxo,
+        sponsorInput: {
+            txid: sponsorInput.txid,
+            vout: sponsorInput.vout,
+            amountSat: sponsorInput.amountSat,
+        },
+    };
+}
+async function signContractInput(config, artifact, psetBase64, privkeyHex, witnessConfig) {
+    assertArtifactExecutionSupport(artifact, "direct");
+    const signatures = await buildSignatureMap(config, artifact, psetBase64, privkeyHex, witnessConfig);
+    const workDir = await (0, promises_1.mkdtemp)(node_path_1.default.join((0, node_os_1.tmpdir)(), "simplicity-sdk-gasless-"));
+    const witnessPath = node_path_1.default.join(workDir, "witness.json");
+    await (0, promises_1.writeFile)(witnessPath, JSON.stringify(buildWitnessJson(artifact, signatures, witnessConfig), null, 2), "utf8");
+    const simfSourcePath = artifact.legacy?.simfTemplatePath ?? artifact.source.simfPath;
+    if (!simfSourcePath) {
+        throw new errors_1.ExecutionError("Artifact does not include a source simf path for witness generation");
+    }
+    const simfTemplate = await (0, promises_1.readFile)(simfSourcePath, "utf8");
+    const simfRendered = (0, templating_1.renderTemplate)(simfTemplate, artifact.source.templateVars ?? {});
+    const simfRenderedPath = node_path_1.default.join(workDir, "program.simf");
+    await (0, promises_1.writeFile)(simfRenderedPath, simfRendered, "utf8");
+    const witnessOutput = await (0, toolchain_1.runSimcWithWitness)(config.toolchain.simcPath, simfRenderedPath, witnessPath);
+    const witness = parseSimcWitness(witnessOutput);
+    const contractFinalized = (await (0, toolchain_1.runHalFinalize)(config.toolchain.halSimplicityPath, psetBase64, 0, artifact.compiled.program, witness));
+    if (!contractFinalized.pset) {
+        throw new errors_1.ExecutionError("finalize did not return a pset", contractFinalized);
+    }
+    return contractFinalized.pset;
+}
+async function buildSignatureMap(config, artifact, psetBase64, privkeyHex, witnessConfig) {
+    const primary = (await (0, toolchain_1.runHalSighash)(config.toolchain.halSimplicityPath, psetBase64, 0, artifact.compiled.cmr, privkeyHex));
+    if (!primary.signature) {
+        throw new errors_1.ExecutionError("sighash did not return a signature", primary);
+    }
+    const signatures = {
+        SIGNATURE: primary.signature,
+    };
+    for (const [name, signer] of Object.entries(witnessConfig?.signers ?? {})) {
+        if (signer.type !== "schnorrPrivkeyHex") {
+            throw new errors_1.UnsupportedFeatureError(`Unsupported witness signer type for '${name}'`);
+        }
+        const result = (await (0, toolchain_1.runHalSighash)(config.toolchain.halSimplicityPath, psetBase64, 0, artifact.compiled.cmr, signer.privkeyHex));
+        if (!result.signature) {
+            throw new errors_1.ExecutionError(`sighash did not return a signature for witness signer '${name}'`, result);
+        }
+        signatures[`SIGNATURE:${name}`] = result.signature;
+    }
+    return signatures;
+}
+function replaceSignaturePlaceholders(value, signatures) {
+    return value.replace(/\$\{SIGNATURE(?::([A-Z0-9_]+))?\}/g, (_match, name) => {
+        const key = name ? `SIGNATURE:${name}` : "SIGNATURE";
+        const signature = signatures[key];
+        if (!signature) {
+            throw new errors_1.PresetExecutionError(`Missing signature placeholder binding for '${key}'`);
+        }
+        return `0x${signature}`;
+    });
+}
+function buildWitnessJson(artifact, signatures, witnessConfig) {
+    if (witnessConfig?.source) {
+        throw new errors_1.UnsupportedFeatureError("witness.source is not supported in v0.1.0; use witness.values because simc currently expects JSON witness input");
+    }
+    const assignments = new Map();
+    for (const [name, assignment] of Object.entries(witnessConfig?.values ?? {})) {
+        assignments.set(name, {
+            type: assignment.type,
+            value: replaceSignaturePlaceholders(assignment.value, signatures),
+        });
+    }
+    const presetId = artifact.source.preset;
+    const requiredWitnessFields = presetId
+        ? (0, presets_1.getPresetOrThrow)(presetId).executionProfile.requiredWitnessFields
+        : ["SIGNER_SIGNATURE"];
+    const preset = presetId ? (0, presets_1.getPresetOrThrow)(presetId) : null;
+    if (preset) {
+        (0, presets_1.validateWitnessConfig)(preset, witnessConfig);
+    }
+    if (requiredWitnessFields.length === 1 &&
+        requiredWitnessFields[0] === "SIGNER_SIGNATURE" &&
+        !assignments.has("SIGNER_SIGNATURE")) {
+        assignments.set("SIGNER_SIGNATURE", { type: "Signature", value: `0x${signatures.SIGNATURE}` });
+    }
+    for (const field of requiredWitnessFields) {
+        if (!assignments.has(field)) {
+            throw new errors_1.PresetExecutionError(`Missing witness value for required field '${field}'`, {
+                preset: presetId,
+                requiredWitnessFields,
+            });
+        }
+    }
+    const witnessJson = {};
+    for (const [name, assignment] of Array.from(assignments.entries()).sort(([a], [b]) => a.localeCompare(b))) {
+        witnessJson[name] = assignment;
+    }
+    return witnessJson;
+}
+function assertArtifactExecutionSupport(artifact, mode) {
+    if (artifact.source.mode !== "preset" || !artifact.source.preset)
+        return;
+    const preset = (0, presets_1.getPresetOrThrow)(artifact.source.preset);
+    const supported = mode === "direct"
+        ? preset.executionProfile.supportsDirectExecute
+        : preset.executionProfile.supportsRelayerExecute;
+    if (!supported) {
+        throw new errors_1.PresetExecutionError(`Preset '${preset.id}' does not support ${mode === "direct" ? "direct execute" : "relayer-backed execute"} in v0.1.0`, {
+            preset: preset.id,
+            requiredWitnessFields: preset.executionProfile.requiredWitnessFields,
+        });
+    }
+}
+async function executeRelayedGaslessContractCall(config, artifact, input, relayer) {
+    assertArtifactExecutionSupport(artifact, "relayer");
+    if (!input.fromLabel) {
+        throw new errors_1.ValidationError("fromLabel is required when relayer is provided");
+    }
+    const request = await relayer.requestSimplicityExecution({
+        fromLabel: input.fromLabel,
+        artifact: {
+            compiled: artifact.compiled,
+            source: artifact.source,
+            legacy: { params: { minHeight: getArtifactLocktime(artifact) || undefined } },
+            network: artifact.network,
+        },
+        toAddress: input.toAddress,
+        sendAmount: input.sendAmount,
+        feeSat: input.feeSat,
+    });
+    const signedPsetBase64 = await signContractInput(config, artifact, request.psetBase64, input.signer.privkeyHex, input.witness);
+    const submit = await relayer.submitSimplicityExecution({
+        requestId: request.requestId,
+        signedPsetBase64,
+    });
+    return {
+        mode: "gasless-execute",
+        summary: {
+            network: artifact.network,
+            purpose: "sdk_gasless_execute_relayer",
+            bondDefinitionId: null,
+            periodId: null,
+            contract: {
+                address: request.detailedSummary.contract.contractAddress,
+                cmr: request.detailedSummary.contract.cmr,
+                internalKey: request.detailedSummary.contract.internalKey,
+                program: request.detailedSummary.contract.program,
+                minHeight: getArtifactLocktime(artifact) || undefined,
+            },
+            expectedLiquidReceiver: request.detailedSummary.expectedReceiver,
+            inputs: request.detailedSummary.inputs,
+            outputs: request.detailedSummary.outputs.map((output) => ({
+                n: output.n,
+                value: output.amount,
+                asset: output.asset,
+                address: output.address,
+                scriptPubKeyHex: output.scriptPubKeyHex,
+                isFee: output.isFee,
+            })),
+            fee: request.detailedSummary.fee,
+        },
+        summaryHash: submit.summaryHash,
+        summaryCanonicalJson: request.summaryCanonicalJson,
+        psetBase64: signedPsetBase64,
+        rawTxHex: submit.rawTxHex,
+        txId: submit.txId,
+        broadcasted: true,
+        contractUtxo: {
+            txid: request.summary.contractInput.txid,
+            vout: request.summary.contractInput.vout,
+            scriptPubKey: "",
+            asset: "",
+            sat: request.summary.contractInput.amountSat,
+            confirmed: true,
+        },
+        sponsorInput: request.summary.sponsorInput,
+    };
+}

package/dist/core/presets.d.ts

@@ -0,0 +1,16 @@
+import { PresetManifestEntry } from "./types";
+export declare const PRESET_MANIFEST: Record<string, PresetManifestEntry>;
+export declare function listPresets(): PresetManifestEntry[];
+export declare function getPresetOrThrow(preset: string): PresetManifestEntry;
+export declare function validatePresetParams(preset: PresetManifestEntry, params: Record<string, string | number>): Record<string, string | number>;
+export declare function describePreset(preset: PresetManifestEntry): Record<string, unknown>;
+export declare function validateWitnessConfig(preset: PresetManifestEntry, witness: {
+    values?: Record<string, {
+        type: string;
+        value: string;
+    }>;
+    signers?: Record<string, {
+        type: "schnorrPrivkeyHex";
+        privkeyHex: string;
+    }>;
+} | undefined): void;