@hazbase/simplicity 0.0.1

package/dist/core/types.d.ts

@@ -0,0 +1,258 @@
+export type NetworkName = "liquidtestnet" | "liquidv1" | "regtest";
+export type UtxoPolicy = "smallest_over" | "largest" | "newest";
+export interface RpcConfig {
+    url: string;
+    username: string;
+    password: string;
+    wallet?: string;
+}
+export interface ToolchainConfig {
+    simcPath: string;
+    halSimplicityPath: string;
+    elementsCliPath?: string;
+}
+export interface SimplicityClientConfig {
+    network: NetworkName;
+    rpc: RpcConfig;
+    toolchain: ToolchainConfig;
+    defaults?: {
+        feeSat?: number;
+        utxoPolicy?: UtxoPolicy;
+    };
+    relayer?: {
+        baseUrl: string;
+        apiKey?: string;
+    };
+}
+export interface ArtifactV5 {
+    version: 5;
+    createdAt: string;
+    simfTemplatePath?: string;
+    params?: {
+        minHeight?: number;
+        signerXonly?: string;
+    };
+    compiled?: {
+        program?: string;
+        cmr?: string;
+        internalKey?: string;
+        contractAddress?: string;
+    };
+    toolchain?: {
+        simcPath?: string;
+        halSimplicity?: string;
+    };
+}
+export interface SimplicityArtifact {
+    version: 6;
+    kind: "simplicity-artifact";
+    createdAt: string;
+    network: NetworkName;
+    source: {
+        mode: "file" | "preset";
+        simfPath?: string;
+        preset?: string;
+        templateVars?: Record<string, string | number>;
+    };
+    compiled: {
+        program: string;
+        cmr: string;
+        internalKey: string;
+        contractAddress: string;
+    };
+    toolchain: {
+        simcPath: string;
+        halSimplicity: string;
+    };
+    metadata: {
+        sdkVersion: string;
+        notes: string | null;
+    };
+    legacy?: {
+        simfTemplatePath?: string;
+        params?: {
+            minHeight?: number;
+            signerXonly?: string;
+        };
+    };
+}
+export type AnyArtifact = ArtifactV5 | SimplicityArtifact;
+export interface CompileFromFileInput {
+    simfPath: string;
+    templateVars?: Record<string, string | number>;
+    artifactPath?: string;
+}
+export interface CompileFromPresetInput {
+    preset: string;
+    params: Record<string, string | number>;
+    artifactPath?: string;
+}
+export interface DeploymentInfo {
+    contractAddress: string;
+    internalKey: string;
+    cmr: string;
+    network: NetworkName;
+    instructions: string[];
+}
+export interface ContractUtxo {
+    txid: string;
+    vout: number;
+    scriptPubKey: string;
+    asset: string;
+    sat: number;
+    height?: number;
+    confirmed: boolean;
+}
+export interface SignerConfig {
+    type: "schnorrPrivkeyHex";
+    privkeyHex: string;
+}
+export interface WitnessValueInput {
+    type: string;
+    value: string;
+}
+export interface WitnessConfig {
+    source?: string;
+    values?: Record<string, WitnessValueInput>;
+    signers?: Record<string, SignerConfig>;
+}
+export interface CallBaseInput {
+    wallet: string;
+    toAddress: string;
+    sendAmount?: number;
+    feeSat?: number;
+    utxoPolicy?: UtxoPolicy;
+    signer?: SignerConfig;
+    expectedLiquidReceiver?: string;
+    purpose?: string;
+    periodId?: string;
+    bondDefinitionId?: string;
+    sequence?: number;
+    witness?: WitnessConfig;
+}
+export interface InspectCallInput extends CallBaseInput {
+    signer: SignerConfig;
+}
+export interface ExecuteCallInput extends CallBaseInput {
+    signer: SignerConfig;
+    broadcast?: boolean;
+    verbose?: boolean;
+}
+export interface SummaryOutput {
+    n: number;
+    value: number | null;
+    asset: string | null;
+    address: string | null;
+    scriptPubKeyHex: string | null;
+    isFee: boolean;
+}
+export interface PsetSummary {
+    network: string;
+    purpose?: string;
+    bondDefinitionId?: string | null;
+    periodId?: string | null;
+    contract: {
+        address: string;
+        cmr: string;
+        internalKey: string;
+        program: string;
+        minHeight?: number;
+    };
+    expectedLiquidReceiver?: string | null;
+    inputs: Array<{
+        txid: string | null;
+        vout: number | null;
+        sequence: number | null;
+    }>;
+    outputs: SummaryOutput[];
+    fee: unknown;
+}
+export interface InspectResult {
+    mode: "inspect";
+    summary: PsetSummary;
+    summaryHash: string;
+    summaryCanonicalJson: string;
+    psetBase64: string;
+    contractUtxo: ContractUtxo;
+    warnings: string[];
+}
+export interface ExecuteResult {
+    mode: "execute";
+    summary: PsetSummary;
+    summaryHash: string;
+    summaryCanonicalJson: string;
+    psetBase64: string;
+    rawTxHex: string;
+    txId?: string;
+    broadcasted: boolean;
+    contractUtxo: ContractUtxo;
+}
+export interface GaslessExecuteInput {
+    relayer?: import("../gasless/RelayerClient").RelayerClient;
+    fromLabel?: string;
+    wallet?: string;
+    sponsorWallet?: string;
+    toAddress: string;
+    signer: SignerConfig;
+    witness?: WitnessConfig;
+    sendAmount?: number;
+    feeSat?: number;
+    contractChangeAddress?: string;
+    sponsorChangeAddress?: string;
+    utxoPolicy?: UtxoPolicy;
+    broadcast?: boolean;
+}
+export interface GaslessExecuteResult {
+    mode: "gasless-execute";
+    summary: PsetSummary;
+    summaryHash: string;
+    summaryCanonicalJson: string;
+    psetBase64: string;
+    rawTxHex: string;
+    txId?: string;
+    broadcasted: boolean;
+    contractUtxo: ContractUtxo;
+    sponsorInput: {
+        txid: string;
+        vout: number;
+        amountSat: number;
+    };
+}
+export interface WaitForFundingInput {
+    minAmountSat?: number;
+    pollIntervalMs?: number;
+    timeoutMs?: number;
+    utxoPolicy?: UtxoPolicy;
+}
+export interface PresetManifestEntry {
+    id: string;
+    title: string;
+    description: string;
+    simfTemplatePath: string;
+    parameterSchema: Record<string, "string" | "number">;
+    witnessSchema?: Record<string, {
+        type: string;
+        signerAlias?: string;
+        description?: string;
+    }>;
+    exampleWitness?: {
+        signers?: Record<string, {
+            type: "schnorrPrivkeyHex";
+            privkeyHex: string;
+        }>;
+        values?: Record<string, {
+            type: string;
+            value: string;
+        }>;
+    };
+    executionProfile: {
+        witnessMode: "inlineSignature";
+        supportsGasless: boolean;
+        supportsDirectExecute: boolean;
+        supportsRelayerExecute: boolean;
+        requiredWitnessFields: string[];
+        defaultFeeSat: number;
+        recommendedUtxoPolicy: UtxoPolicy;
+    };
+    exampleParams: Record<string, string | number>;
+}

package/dist/core/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/gasless/RelayerClient.d.ts

@@ -0,0 +1,13 @@
+import { PsetStatusResult, RelayerClientConfig, RequestPsetInput, RequestPsetResult, RequestSimplicityExecutionInput, RequestSimplicityExecutionResult, SimplicityStatusResult, SubmitSignedPsetInput, SubmitSignedPsetResult, SubmitSimplicityExecutionInput, SubmitSimplicityExecutionResult } from "./types";
+export declare class RelayerClient {
+    private readonly config;
+    constructor(config: RelayerClientConfig);
+    private headers;
+    private parseResponse;
+    requestPset(input: RequestPsetInput): Promise<RequestPsetResult>;
+    submitSignedPset(input: SubmitSignedPsetInput): Promise<SubmitSignedPsetResult>;
+    getPsetStatus(psetId: string): Promise<PsetStatusResult>;
+    requestSimplicityExecution(input: RequestSimplicityExecutionInput): Promise<RequestSimplicityExecutionResult>;
+    submitSimplicityExecution(input: SubmitSimplicityExecutionInput): Promise<SubmitSimplicityExecutionResult>;
+    getSimplicityStatus(requestId: string): Promise<SimplicityStatusResult>;
+}

package/dist/gasless/RelayerClient.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RelayerClient = void 0;
+const errors_1 = require("../core/errors");
+class RelayerClient {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    headers() {
+        return {
+            "content-type": "application/json",
+            "x-api-key": this.config.apiKey,
+        };
+    }
+    async parseResponse(response) {
+        let payload = null;
+        try {
+            payload = await response.json();
+        }
+        catch {
+            payload = null;
+        }
+        if (!response.ok) {
+            throw new errors_1.RelayerError(payload?.error?.message ?? `Relayer request failed with status ${response.status}`, payload, response.status);
+        }
+        return payload;
+    }
+    async requestPset(input) {
+        const response = await fetch(`${this.config.baseUrl}/pset/request`, {
+            method: "POST",
+            headers: this.headers(),
+            body: JSON.stringify(input),
+        });
+        return this.parseResponse(response);
+    }
+    async submitSignedPset(input) {
+        const response = await fetch(`${this.config.baseUrl}/pset/submit`, {
+            method: "POST",
+            headers: this.headers(),
+            body: JSON.stringify(input),
+        });
+        return this.parseResponse(response);
+    }
+    async getPsetStatus(psetId) {
+        const response = await fetch(`${this.config.baseUrl}/pset/${psetId}`, {
+            method: "GET",
+            headers: this.headers(),
+        });
+        return this.parseResponse(response);
+    }
+    async requestSimplicityExecution(input) {
+        const response = await fetch(`${this.config.baseUrl}/simplicity/request`, {
+            method: "POST",
+            headers: this.headers(),
+            body: JSON.stringify(input),
+        });
+        return this.parseResponse(response);
+    }
+    async submitSimplicityExecution(input) {
+        const response = await fetch(`${this.config.baseUrl}/simplicity/submit`, {
+            method: "POST",
+            headers: this.headers(),
+            body: JSON.stringify(input),
+        });
+        return this.parseResponse(response);
+    }
+    async getSimplicityStatus(requestId) {
+        const response = await fetch(`${this.config.baseUrl}/simplicity/${requestId}`, {
+            method: "GET",
+            headers: this.headers(),
+        });
+        return this.parseResponse(response);
+    }
+}
+exports.RelayerClient = RelayerClient;

package/dist/gasless/types.d.ts

@@ -0,0 +1,144 @@
+export interface RelayerClientConfig {
+    baseUrl: string;
+    apiKey: string;
+}
+export interface RequestPsetInput {
+    amount: number;
+    toAddress: string;
+    fromLabel: string;
+}
+export interface RequestPsetResult {
+    psetId: string;
+    psetBase64: string;
+    summary: {
+        assetId: string;
+        amountSat: number;
+        toAddress: string;
+        userInput: {
+            txid: string;
+            vout: number;
+            amountSat: number;
+        };
+        userChangeSat: number;
+        maxFeeSat: number;
+        expiresAt: string;
+        summaryHash: string;
+    };
+}
+export interface SubmitSignedPsetInput {
+    psetId: string;
+    signedPsetBase64: string;
+}
+export interface SubmitSignedPsetResult {
+    txId: string;
+    status: "BROADCASTED";
+    summaryHash: string;
+    broadcastAt: string;
+}
+export interface PsetStatusResult {
+    psetId: string;
+    status: string;
+    summaryHash: string;
+    expiresAt: string;
+    txId: string | null;
+}
+export interface GaslessTransferInput {
+    relayer?: import("./RelayerClient").RelayerClient;
+    amount: number;
+    toAddress: string;
+    fromLabel: string;
+    userWallet: string;
+}
+export interface GaslessTransferResult {
+    request: RequestPsetResult;
+    signedPsetBase64: string;
+    submit: SubmitSignedPsetResult;
+}
+export interface RequestSimplicityExecutionInput {
+    fromLabel: string;
+    artifact: {
+        compiled: {
+            program: string;
+            cmr: string;
+            internalKey: string;
+            contractAddress: string;
+        };
+        source: {
+            simfPath?: string;
+            templateVars?: Record<string, string | number>;
+        };
+        legacy?: {
+            params?: {
+                minHeight?: number;
+            };
+        };
+        network?: string;
+    };
+    toAddress: string;
+    sendAmount?: number;
+    feeSat?: number;
+}
+export interface RequestSimplicityExecutionResult {
+    requestId: string;
+    psetBase64: string;
+    summaryCanonicalJson: string;
+    detailedSummary: {
+        contract: {
+            program: string;
+            cmr: string;
+            internalKey: string;
+            contractAddress: string;
+        };
+        expectedReceiver: string;
+        inputs: Array<{
+            txid: string | null;
+            vout: number | null;
+            sequence: number | null;
+        }>;
+        outputs: Array<{
+            n: number;
+            amount: number | null;
+            asset: string | null;
+            scriptPubKeyHex: string | null;
+            address: string | null;
+            isFee: boolean;
+        }>;
+        fee: Record<string, number> | null;
+        locktime: number;
+    };
+    summary: {
+        toAddress: string;
+        sendAmountSat: number;
+        feeSat: number;
+        summaryHash: string;
+        expiresAt: string;
+        contractInput: {
+            txid: string;
+            vout: number;
+            amountSat: number;
+        };
+        sponsorInput: {
+            txid: string;
+            vout: number;
+            amountSat: number;
+        };
+    };
+}
+export interface SubmitSimplicityExecutionInput {
+    requestId: string;
+    signedPsetBase64: string;
+}
+export interface SubmitSimplicityExecutionResult {
+    txId: string;
+    status: "BROADCASTED";
+    summaryHash: string;
+    broadcastAt: string;
+    rawTxHex: string;
+}
+export interface SimplicityStatusResult {
+    requestId: string;
+    status: string;
+    summaryHash: string;
+    expiresAt: string;
+    txId: string | null;
+}

package/dist/gasless/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { createSimplicityClient, SimplicityClient } from "./client/SimplicityClient";
+export { CompiledContract } from "./client/ContractFactory";
+export { DeployedContract } from "./client/DeployedContract";
+export { RelayerClient } from "./gasless/RelayerClient";
+export * from "./core/types";
+export * from "./core/errors";
+export { listPresets, getPresetOrThrow } from "./core/presets";
+export { loadArtifact, saveArtifact, normalizeArtifact } from "./core/artifact";

package/dist/index.js

@@ -0,0 +1,35 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeArtifact = exports.saveArtifact = exports.loadArtifact = exports.getPresetOrThrow = exports.listPresets = exports.RelayerClient = exports.DeployedContract = exports.CompiledContract = exports.SimplicityClient = exports.createSimplicityClient = void 0;
+var SimplicityClient_1 = require("./client/SimplicityClient");
+Object.defineProperty(exports, "createSimplicityClient", { enumerable: true, get: function () { return SimplicityClient_1.createSimplicityClient; } });
+Object.defineProperty(exports, "SimplicityClient", { enumerable: true, get: function () { return SimplicityClient_1.SimplicityClient; } });
+var ContractFactory_1 = require("./client/ContractFactory");
+Object.defineProperty(exports, "CompiledContract", { enumerable: true, get: function () { return ContractFactory_1.CompiledContract; } });
+var DeployedContract_1 = require("./client/DeployedContract");
+Object.defineProperty(exports, "DeployedContract", { enumerable: true, get: function () { return DeployedContract_1.DeployedContract; } });
+var RelayerClient_1 = require("./gasless/RelayerClient");
+Object.defineProperty(exports, "RelayerClient", { enumerable: true, get: function () { return RelayerClient_1.RelayerClient; } });
+__exportStar(require("./core/types"), exports);
+__exportStar(require("./core/errors"), exports);
+var presets_1 = require("./core/presets");
+Object.defineProperty(exports, "listPresets", { enumerable: true, get: function () { return presets_1.listPresets; } });
+Object.defineProperty(exports, "getPresetOrThrow", { enumerable: true, get: function () { return presets_1.getPresetOrThrow; } });
+var artifact_1 = require("./core/artifact");
+Object.defineProperty(exports, "loadArtifact", { enumerable: true, get: function () { return artifact_1.loadArtifact; } });
+Object.defineProperty(exports, "saveArtifact", { enumerable: true, get: function () { return artifact_1.saveArtifact; } });
+Object.defineProperty(exports, "normalizeArtifact", { enumerable: true, get: function () { return artifact_1.normalizeArtifact; } });

package/dist/presets/htlc.simf.tmpl

@@ -0,0 +1,35 @@
+fn sha2(string: u256) -> u256 {
+    let hasher: Ctx8 = jet::sha_256_ctx_8_init();
+    let hasher: Ctx8 = jet::sha_256_ctx_8_add_32(hasher, string);
+    jet::sha_256_ctx_8_finalize(hasher)
+}
+
+fn checksig(pk: Pubkey, sig: Signature) {
+    let msg: u256 = jet::sig_all_hash();
+    jet::bip_0340_verify((pk, msg), sig);
+}
+
+fn complete_spend(preimage: u256, recipient_sig: Signature) {
+    let hash: u256 = sha2(preimage);
+    let expected_hash: u256 = 0x{{EXPECTED_HASH}};
+    assert!(jet::eq_256(hash, expected_hash));
+    let recipient_pk: Pubkey = 0x{{RECIPIENT_XONLY}};
+    checksig(recipient_pk, recipient_sig);
+}
+
+fn cancel_spend(sender_sig: Signature) {
+    let timeout: Height = {{TIMEOUT_HEIGHT}};
+    jet::check_lock_height(timeout);
+    let sender_pk: Pubkey = 0x{{SENDER_XONLY}};
+    checksig(sender_pk, sender_sig)
+}
+
+fn main() {
+    match witness::COMPLETE_OR_CANCEL {
+        Left(preimage_sig: (u256, Signature)) => {
+            let (preimage, recipient_sig): (u256, Signature) = preimage_sig;
+            complete_spend(preimage, recipient_sig);
+        },
+        Right(sender_sig: Signature) => cancel_spend(sender_sig),
+    }
+}

package/dist/presets/manifest.d.ts

@@ -0,0 +1 @@
+export { PRESET_MANIFEST } from "../core/presets";

package/dist/presets/manifest.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PRESET_MANIFEST = void 0;
+var presets_1 = require("../core/presets");
+Object.defineProperty(exports, "PRESET_MANIFEST", { enumerable: true, get: function () { return presets_1.PRESET_MANIFEST; } });

package/dist/presets/p2pk.simf.tmpl

@@ -0,0 +1,4 @@
+fn main() {
+    let signer: Pubkey = 0x{{SIGNER_XONLY}};
+    jet::bip_0340_verify((signer, jet::sig_all_hash()), witness::SIGNER_SIGNATURE)
+}

package/dist/presets/p2pkLockHeight.simf.tmpl

@@ -0,0 +1,5 @@
+fn main() {
+    jet::check_lock_height({{MIN_HEIGHT}});
+    let signer: Pubkey = 0x{{SIGNER_XONLY}};
+    jet::bip_0340_verify((signer, jet::sig_all_hash()), witness::SIGNER_SIGNATURE)
+}

package/dist/presets/transferWithTimeout.simf.tmpl

@@ -0,0 +1,26 @@
+fn checksig(pk: Pubkey, sig: Signature) {
+    let msg: u256 = jet::sig_all_hash();
+    jet::bip_0340_verify((pk, msg), sig);
+}
+
+fn transfer_spend(sender_sig: Signature, recipient_sig: Signature) {
+    let sender_pk: Pubkey = 0x{{SENDER_XONLY}};
+    checksig(sender_pk, sender_sig);
+    let recipient_pk: Pubkey = 0x{{RECIPIENT_XONLY}};
+    checksig(recipient_pk, recipient_sig);
+}
+
+fn timeout_spend(sender_sig: Signature) {
+     let sender_pk: Pubkey = 0x{{SENDER_XONLY}};
+     checksig(sender_pk, sender_sig);
+     let timeout: Height = {{TIMEOUT_HEIGHT}};
+     jet::check_lock_height(timeout);
+}
+
+fn main() {
+    let sender_sig: Signature = witness::SENDER_SIG;
+    match witness::TRANSFER_OR_TIMEOUT {
+        Some(recipient_sig: Signature) => transfer_spend(sender_sig, recipient_sig),
+        None => timeout_spend(sender_sig),
+    }
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@hazbase/simplicity",
+  "version": "0.0.1",
+  "description": "An SDK for Simplicity on Liquid",
+  "author": "IndieSquare Inc <info@hazbase.com>",
+  "keywords": [
+    "hazBase",
+    "backend",
+    "simplicity",
+    "liquid",
+    "bitcoin",
+    "sidechain",
+    "smart-contracts",
+    "sdk"
+  ],
+  "homepage": "https://lp.hazbase.com/",
+  "repository": "hazbase/simplicity",
+  "license": "Apache-2.0",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "dist",
+    "!dist/test",
+    "README.md"
+  ],
+  "bin": {
+    "simplicity-cli": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc && node scripts/copy-presets.mjs",
+    "start": "node dist/cli.js",
+    "test": "npm run build && node --test dist/test",
+    "e2e:simplicity-relayer": "npm run build && node scripts/e2e-simplicity-relayer.mjs"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.5.0"
+  }
+}