@hazbase/simplicity 0.0.1 → 0.0.2

package/README.md

@@ -7,6 +7,22 @@ This SDK is designed to help Node developers get productive quickly, but it is s
 - This SDK currently optimizes for explicit / unblinded success paths first.
 - Gasless support exists, but it comes in multiple modes with different tradeoffs.
 
+Consumer validation note:
+- The published npm package has been validated from a fresh external Node.js project using `npm install @hazbase/simplicity`.
+- Verified flows include preset-based contract execution, custom `.simf` execution, and relayer-backed gasless execution on `liquidtestnet`.
+
+## Validated Scenarios
+
+The published package has been exercised from a blank external consumer project. For the full reproducible fixture, see [docs/consumer-validation/README.md](./docs/consumer-validation/README.md).
+
+| Scenario | Status | Notes |
+| --- | --- | --- |
+| Fresh install + JS import | Success | `npm install @hazbase/simplicity` and `import { createSimplicityClient } from "@hazbase/simplicity"` both worked |
+| CLI smoke | Success | `npx simplicity-cli presets list` worked from the external project |
+| Preset flow (`p2pkLockHeight`) | Success | compile -> fund -> inspect -> execute(`broadcast=true`) |
+| Custom `.simf` flow | Success | `compileFromFile(...)` -> fund -> inspect -> execute(`broadcast=true`) |
+| Relayer-backed gasless flow | Success | `executeGasless(...)` succeeded from the external project |
+
 ## Who This Is For
 
 This README is for you if:
@@ -45,6 +61,68 @@ With the current SDK you can build and test flows such as:
 
 You can also design more advanced systems such as ERC20-like token behavior, but the model is different from Ethereum. On Liquid/Simplicity, you usually represent state transitions as UTXO transitions instead of account storage updates. So the SDK can support that kind of application, but it does not mean you port Solidity account logic 1:1.
 
+## Trusted Definition JSON
+
+When your contract depends on off-chain business metadata such as a bond definition, coupon schedule, note terms, or asset terms, you usually do not want to trust a plain JSON file by itself. This SDK now supports a **hash-anchor** model for definition JSON.
+
+What that means:
+- the SDK canonicalizes the JSON using stable key ordering,
+- computes `sha256(canonicalJson)`,
+- stores that hash in the artifact as a definition anchor,
+- injects `DEFINITION_HASH` and `DEFINITION_ID` into compile-time template vars when a definition is provided,
+- lets you verify later that the JSON you are reading still matches the contract/artifact it was compiled against.
+
+Minimal TypeScript flow:
+
+```ts
+const definition = await sdk.loadDefinition({
+  type: "bond",
+  id: "BOND-2026-001",
+  jsonPath: "./docs/definitions/bond-definition.json",
+});
+
+const compiled = await sdk.compileFromFile({
+  simfPath: "./docs/definitions/bond-anchor.simf",
+  templateVars: {
+    MIN_HEIGHT: 2344430,
+    SIGNER_XONLY: "79be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798",
+  },
+  definition: {
+    type: definition.definitionType,
+    id: definition.definitionId,
+    schemaVersion: definition.schemaVersion,
+    jsonPath: definition.sourcePath,
+  },
+  artifactPath: "./bond.artifact.json",
+});
+
+const verification = await sdk.verifyDefinitionAgainstArtifact({
+  artifactPath: "./bond.artifact.json",
+  jsonPath: "./docs/definitions/bond-definition.json",
+  type: "bond",
+  id: "BOND-2026-001",
+});
+
+console.log(verification.ok);
+```
+
+CLI equivalents:
+
+```bash
+simplicity-cli definition show \
+  --type bond \
+  --id BOND-2026-001 \
+  --json-path ./docs/definitions/bond-definition.json
+
+simplicity-cli definition verify \
+  --artifact ./bond.artifact.json \
+  --type bond \
+  --id BOND-2026-001 \
+  --json-path ./docs/definitions/bond-definition.json
+```
+
+For a bond-oriented walkthrough, see [docs/definitions/README.md](./docs/definitions/README.md).
+
 ## Install
 
 You need three things:
@@ -467,6 +545,12 @@ Use custom `.simf` when:
 - you need your own parameterization,
 - you want to build app-specific wrappers on top of the generic SDK.
 
+A real external-consumer validation of this path has been completed with:
+- a fresh project created outside this repo,
+- a local `contract.simf` file owned by that project,
+- `compileFromFile(...)`,
+- funding + inspect + `broadcast: true` execution.
+
 Recommended path:
 - learn the lifecycle with a preset first,
 - then move to `compileFromFile(...)` once the model is clear.
@@ -714,6 +798,15 @@ These examples are included to help you jump to the right workflow quickly.
 - [execute-htlc.ts](./examples/execute-htlc.ts): HTLC preset with custom witness values.
 - [execute-transfer-with-timeout-cooperative.ts](./examples/execute-transfer-with-timeout-cooperative.ts): cooperative multi-witness timeout flow.
 - [gasless-transfer.ts](./examples/gasless-transfer.ts): standard relayer-backed gasless L-BTC transfer.
+- [define-bond.ts](./examples/define-bond.ts): compile a bond example with a trusted definition hash anchor.
+- [show-bond-definition.ts](./examples/show-bond-definition.ts): verify and retrieve a trusted bond definition from JSON + artifact.
+
+In addition to the in-repo examples, the package has also been validated from a blank external consumer project with:
+- `npm install @hazbase/simplicity`
+- JS/TS import of `createSimplicityClient`
+- preset compile -> fund -> inspect -> execute
+- custom `.simf` compile -> fund -> inspect -> execute
+- relayer-backed gasless execution
 
 ## FAQ / Practical Notes
 
@@ -729,6 +822,15 @@ It means: compile the contract, derive its address, then fund that address with
 
 An artifact is the contract's compile output plus the metadata needed to reload, inspect, and execute it later. Think of it as the bridge between compilation time and on-chain execution time.
 
+When you compile with `definition: { ... }`, the artifact also carries:
+- `definitionType`
+- `definitionId`
+- `schemaVersion`
+- `hash`
+- `trustMode`
+
+That is what allows the SDK and CLI to verify that an off-chain JSON definition still matches the contract you compiled.
+
 ### When should I use a preset instead of a custom `.simf` file?
 
 Use a preset first when you are learning the lifecycle or your use case already matches a built-in contract. Move to custom `.simf` when your business rules are app-specific.

package/dist/cli.js

@@ -7,6 +7,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const promises_1 = require("node:fs/promises");
 const node_path_1 = __importDefault(require("node:path"));
 const artifact_1 = require("./core/artifact");
+const definition_1 = require("./core/definition");
 const presets_1 = require("./core/presets");
 const errors_1 = require("./core/errors");
 const SimplicityClient_1 = require("./client/SimplicityClient");
@@ -65,6 +66,23 @@ function parseWitnessSigners(values) {
         return [name, { type: "schnorrPrivkeyHex", privkeyHex }];
     }));
 }
+function parseDefinitionInput() {
+    const type = getArg("definition-type");
+    const id = getArg("definition-id");
+    const jsonPath = getArg("definition-json");
+    const valueJson = getArg("definition-value");
+    const schemaVersion = getArg("definition-schema-version");
+    if (!type && !id && !jsonPath && !valueJson && !schemaVersion) {
+        return undefined;
+    }
+    return {
+        type: type ?? "",
+        id: id ?? "",
+        schemaVersion: schemaVersion ?? undefined,
+        jsonPath,
+        value: valueJson ? JSON.parse(valueJson) : undefined,
+    };
+}
 function resolveConfig() {
     return {
         network: getArg("network", "liquidtestnet"),
@@ -357,6 +375,15 @@ function formatArtifactHelp(artifact, preset, utxos) {
         `  status: ${status}`,
         `  ready: ${ready ? "yes" : "no"}`,
     ].join("\n");
+    const definition = artifact.definition
+        ? [
+            `  type: ${artifact.definition.definitionType}`,
+            `  id: ${artifact.definition.definitionId}`,
+            `  schema version: ${artifact.definition.schemaVersion}`,
+            `  hash: ${artifact.definition.hash}`,
+            `  trust mode: ${artifact.definition.trustMode}`,
+        ].join("\n")
+        : "  (none)";
     const compileSource = artifact.source.simfPath ?? artifact.legacy?.simfTemplatePath ?? "(unknown)";
     const templateVars = artifact.source.templateVars ?? {};
     const inspectCommand = `simplicity-cli contract inspect --artifact ./artifact.json --wallet simplicity-test --privkey <privkey-hex> --to-address tex1...`;
@@ -375,6 +402,9 @@ function formatArtifactHelp(artifact, preset, utxos) {
         "Template Vars:",
         indent(JSON.stringify(templateVars, null, 2)),
         "",
+        "Definition Anchor:",
+        definition,
+        "",
         "Suggested Commands:",
         `  ${inspectCommand}`,
         `  ${executeCommand}`,
@@ -416,17 +446,48 @@ async function main() {
     const subcommand = process.argv[3];
     const sdk = (0, SimplicityClient_1.createSimplicityClient)(resolveConfig());
     if (!command) {
-        throw new Error("Usage: simplicity-cli <compile|presets|preset|contract|artifact|gasless> ...");
+        throw new Error("Usage: simplicity-cli <compile|presets|preset|contract|artifact|definition|gasless> ...");
     }
     if (command === "compile") {
         const result = await sdk.compileFromFile({
             simfPath: requireArg("simf"),
             templateVars: parseAssignments(getMultiArgs("template-var")),
             artifactPath: getArg("artifact"),
+            definition: parseDefinitionInput(),
         });
         printJson({ artifact: result.artifact, deployment: result.deployment() });
         return;
     }
+    if (command === "definition" && subcommand === "show") {
+        const definition = await (0, definition_1.loadDefinitionInput)({
+            type: requireArg("type"),
+            id: requireArg("id"),
+            jsonPath: getArg("json-path"),
+            value: getArg("value") ? JSON.parse(getArg("value")) : undefined,
+            schemaVersion: getArg("schema-version"),
+        });
+        printJson(definition);
+        return;
+    }
+    if (command === "definition" && subcommand === "verify") {
+        const verification = await sdk.verifyDefinitionAgainstArtifact({
+            artifactPath: requireArg("artifact"),
+            type: getArg("type"),
+            id: getArg("id"),
+            expectedType: getArg("expected-type"),
+            expectedId: getArg("expected-id"),
+            jsonPath: getArg("json-path"),
+            value: getArg("value") ? JSON.parse(getArg("value")) : undefined,
+            schemaVersion: getArg("schema-version"),
+        });
+        printJson({
+            verified: verification.ok,
+            reason: verification.reason,
+            definition: verification.definition,
+            artifactDefinition: verification.artifactDefinition ?? null,
+        });
+        return;
+    }
     if (command === "presets" && subcommand === "list") {
         printJson((0, presets_1.listPresets)().map((preset) => (0, presets_1.describePreset)(preset)));
         return;
@@ -472,6 +533,7 @@ async function main() {
             preset: requireArg("preset"),
             params,
             artifactPath: getArg("artifact"),
+            definition: parseDefinitionInput(),
         });
         printJson({ artifact: result.artifact, deployment: result.deployment() });
         return;

package/dist/client/ContractFactory.d.ts

@@ -1,4 +1,4 @@
-import { DeploymentInfo, SimplicityArtifact, SimplicityClientConfig } from "../core/types";
+import { ArtifactDefinitionMetadata, DeploymentInfo, SimplicityArtifact, SimplicityClientConfig } from "../core/types";
 import { DeployedContract } from "./DeployedContract";
 export declare class CompiledContract {
     private readonly config;
@@ -7,6 +7,7 @@ export declare class CompiledContract {
     get contractAddress(): string;
     get cmr(): string;
     get program(): string;
+    definition(): ArtifactDefinitionMetadata | null;
     deployment(): DeploymentInfo;
     saveArtifact(path: string): Promise<void>;
     at(addressOverride?: string): DeployedContract;

package/dist/client/ContractFactory.js

@@ -19,6 +19,9 @@ class CompiledContract {
     get program() {
         return this.artifact.compiled.program;
     }
+    definition() {
+        return this.artifact.definition ?? null;
+    }
     deployment() {
         return {
             contractAddress: this.artifact.compiled.contractAddress,

package/dist/client/DeployedContract.d.ts

@@ -1,4 +1,5 @@
-import { ContractUtxo, ExecuteCallInput, ExecuteResult, GaslessExecuteInput, GaslessExecuteResult, InspectCallInput, InspectResult, SimplicityArtifact, SimplicityClientConfig, WaitForFundingInput } from "../core/types";
+import { verifyDefinitionAgainstArtifact } from "../core/definition";
+import { ArtifactDefinitionMetadata, ContractUtxo, ExecuteCallInput, ExecuteResult, GaslessExecuteInput, GaslessExecuteResult, InspectCallInput, InspectResult, SimplicityArtifact, SimplicityClientConfig, WaitForFundingInput } from "../core/types";
 export declare class DeployedContract {
     private readonly config;
     readonly artifact: SimplicityArtifact;
@@ -9,4 +10,16 @@ export declare class DeployedContract {
     inspectCall(input: InspectCallInput): Promise<InspectResult>;
     execute(input: ExecuteCallInput): Promise<ExecuteResult>;
     executeGasless(input: GaslessExecuteInput): Promise<GaslessExecuteResult>;
+    getTrustedDefinition(input: {
+        jsonPath?: string;
+        value?: unknown;
+        type?: string;
+        id?: string;
+        schemaVersion?: string;
+    }): Promise<{
+        verified: boolean;
+        definition: Awaited<ReturnType<typeof verifyDefinitionAgainstArtifact>>["definition"];
+        artifactDefinition: ArtifactDefinitionMetadata | null;
+        reason?: string;
+    }>;
 }

package/dist/client/DeployedContract.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DeployedContract = void 0;
 const executor_1 = require("../core/executor");
+const definition_1 = require("../core/definition");
 const executor_2 = require("../core/executor");
 class DeployedContract {
     config;
@@ -39,5 +40,25 @@ class DeployedContract {
     async executeGasless(input) {
         return (0, executor_2.executeGaslessContractCall)(this.config, this.artifact, input);
     }
+    async getTrustedDefinition(input) {
+        const verification = await (0, definition_1.verifyDefinitionAgainstArtifact)({
+            artifact: this.artifact,
+            definition: {
+                type: input.type ?? this.artifact.definition?.definitionType ?? "",
+                id: input.id ?? this.artifact.definition?.definitionId ?? "",
+                schemaVersion: input.schemaVersion,
+                jsonPath: input.jsonPath,
+                value: input.value,
+            },
+            expectedType: this.artifact.definition?.definitionType,
+            expectedId: this.artifact.definition?.definitionId,
+        });
+        return {
+            verified: verification.ok,
+            definition: verification.definition,
+            artifactDefinition: verification.artifactDefinition ?? null,
+            reason: verification.reason,
+        };
+    }
 }
 exports.DeployedContract = DeployedContract;

package/dist/client/SimplicityClient.d.ts

@@ -1,5 +1,5 @@
 import { ElementsRpcClient } from "../core/rpc";
-import { CompileFromFileInput, CompileFromPresetInput, SimplicityArtifact, SimplicityClientConfig } from "../core/types";
+import { DefinitionInput, DefinitionVerificationResult, CompileFromFileInput, CompileFromPresetInput, DefinitionDescriptor, SimplicityArtifact, SimplicityClientConfig } from "../core/types";
 import { RelayerClient } from "../gasless/RelayerClient";
 import { GaslessTransferInput, GaslessTransferResult, RelayerClientConfig } from "../gasless/types";
 import { CompiledContract } from "./ContractFactory";
@@ -14,6 +14,19 @@ export declare class SimplicityClient {
     compileFromFile(input: CompileFromFileInput): Promise<CompiledContract>;
     compileFromPreset(input: CompileFromPresetInput): Promise<CompiledContract>;
     loadArtifact(path: string): Promise<CompiledContract>;
+    define(input: DefinitionInput): Promise<DefinitionDescriptor>;
+    loadDefinition(input: DefinitionInput): Promise<DefinitionDescriptor>;
+    verifyDefinitionAgainstArtifact(input: {
+        artifactPath?: string;
+        artifact?: SimplicityArtifact;
+        jsonPath?: string;
+        value?: unknown;
+        expectedType?: string;
+        expectedId?: string;
+        type?: string;
+        id?: string;
+        schemaVersion?: string;
+    }): Promise<DefinitionVerificationResult>;
     fromArtifact(artifact: SimplicityArtifact): DeployedContract;
     relayer(config: RelayerClientConfig): RelayerClient;
     private gaslessTransfer;

package/dist/client/SimplicityClient.js

@@ -4,6 +4,8 @@ exports.SimplicityClient = void 0;
 exports.createSimplicityClient = createSimplicityClient;
 const artifact_1 = require("../core/artifact");
 const compiler_1 = require("../core/compiler");
+const definition_1 = require("../core/definition");
+const errors_1 = require("../core/errors");
 const rpc_1 = require("../core/rpc");
 const RelayerClient_1 = require("../gasless/RelayerClient");
 const ContractFactory_1 = require("./ContractFactory");
@@ -31,6 +33,30 @@ class SimplicityClient {
         const artifact = await (0, artifact_1.loadArtifact)(path, this.config.network);
         return new ContractFactory_1.CompiledContract(this.config, artifact);
     }
+    async define(input) {
+        return (0, definition_1.loadDefinitionInput)(input);
+    }
+    async loadDefinition(input) {
+        return (0, definition_1.loadDefinitionInput)(input);
+    }
+    async verifyDefinitionAgainstArtifact(input) {
+        const artifact = input.artifact ?? (input.artifactPath ? await (0, artifact_1.loadArtifact)(input.artifactPath, this.config.network) : undefined);
+        if (!artifact) {
+            throw new errors_1.ValidationError("artifactPath or artifact is required");
+        }
+        return (0, definition_1.verifyDefinitionAgainstArtifact)({
+            artifact,
+            definition: {
+                type: input.type ?? input.expectedType ?? artifact.definition?.definitionType ?? "",
+                id: input.id ?? input.expectedId ?? artifact.definition?.definitionId ?? "",
+                schemaVersion: input.schemaVersion,
+                jsonPath: input.jsonPath,
+                value: input.value,
+            },
+            expectedType: input.expectedType,
+            expectedId: input.expectedId,
+        });
+    }
     fromArtifact(artifact) {
         return new DeployedContract_1.DeployedContract(this.config, artifact);
     }

package/dist/core/artifact.js

@@ -55,6 +55,7 @@ function normalizeArtifact(artifact, networkDefault = "liquidtestnet") {
             sdkVersion: exports.SDK_PACKAGE_VERSION,
             notes: null,
         },
+        definition: undefined,
         legacy: {
             simfTemplatePath: artifact.simfTemplatePath,
             params: artifact.params,
@@ -90,6 +91,7 @@ async function loadArtifact(artifactPath, networkDefault = "liquidtestnet") {
                 simfTemplatePath: legacySimfTemplatePath,
             }
             : undefined,
+        definition: normalized.definition,
     };
 }
 async function saveArtifact(artifactPath, artifact) {

package/dist/core/compiler.js

@@ -9,6 +9,7 @@ const promises_1 = require("node:fs/promises");
 const node_os_1 = require("node:os");
 const node_path_1 = __importDefault(require("node:path"));
 const artifact_1 = require("./artifact");
+const definition_1 = require("./definition");
 const errors_1 = require("./errors");
 const presets_1 = require("./presets");
 const templating_1 = require("./templating");
@@ -67,6 +68,7 @@ async function buildArtifact(input) {
             sdkVersion: artifact_1.SDK_PACKAGE_VERSION,
             notes: null,
         },
+        definition: input.definition ? (0, definition_1.buildArtifactDefinitionMetadata)(input.definition) : undefined,
         legacy: {
             simfTemplatePath: input.sourceSimfPath,
             params: {
@@ -77,8 +79,14 @@ async function buildArtifact(input) {
     }, input.config.network);
 }
 async function compileFromFile(config, input) {
+    const definition = input.definition ? await (0, definition_1.loadDefinitionInput)(input.definition) : undefined;
     const rawSource = await (0, promises_1.readFile)(input.simfPath, "utf8");
-    const rendered = (0, templating_1.renderTemplate)(rawSource, input.templateVars ?? {});
+    const templateVars = {
+        ...(input.templateVars ?? {}),
+        ...(definition && input.templateVars?.DEFINITION_HASH === undefined ? { DEFINITION_HASH: definition.hash } : {}),
+        ...(definition && input.templateVars?.DEFINITION_ID === undefined ? { DEFINITION_ID: definition.definitionId } : {}),
+    };
+    const rendered = (0, templating_1.renderTemplate)(rawSource, templateVars);
     const workDir = await (0, promises_1.mkdtemp)(node_path_1.default.join((0, node_os_1.tmpdir)(), "simplicity-sdk-compile-"));
     const renderedPath = node_path_1.default.join(workDir, node_path_1.default.basename(input.simfPath));
     await (0, promises_1.writeFile)(renderedPath, rendered, "utf8");
@@ -87,7 +95,8 @@ async function compileFromFile(config, input) {
         renderedSimfPath: renderedPath,
         sourceMode: "file",
         sourceSimfPath: input.simfPath,
-        templateVars: input.templateVars,
+        templateVars,
+        definition,
     });
     if (input.artifactPath) {
         await (0, artifact_1.saveArtifact)(input.artifactPath, artifact);
@@ -96,7 +105,12 @@ async function compileFromFile(config, input) {
 }
 async function compileFromPreset(config, input) {
     const preset = (0, presets_1.getPresetOrThrow)(input.preset);
-    const params = (0, presets_1.validatePresetParams)(preset, input.params);
+    const definition = input.definition ? await (0, definition_1.loadDefinitionInput)(input.definition) : undefined;
+    const params = {
+        ...(0, presets_1.validatePresetParams)(preset, input.params),
+        ...(definition && input.params.DEFINITION_HASH === undefined ? { DEFINITION_HASH: definition.hash } : {}),
+        ...(definition && input.params.DEFINITION_ID === undefined ? { DEFINITION_ID: definition.definitionId } : {}),
+    };
     const rawSource = await (0, promises_1.readFile)(preset.simfTemplatePath, "utf8");
     const rendered = (0, templating_1.renderTemplate)(rawSource, params);
     const workDir = await (0, promises_1.mkdtemp)(node_path_1.default.join((0, node_os_1.tmpdir)(), "simplicity-sdk-preset-"));
@@ -109,6 +123,7 @@ async function compileFromPreset(config, input) {
         sourceSimfPath: preset.simfTemplatePath,
         preset: preset.id,
         templateVars: params,
+        definition,
     });
     if (input.artifactPath) {
         await (0, artifact_1.saveArtifact)(input.artifactPath, artifact);

package/dist/core/definition.d.ts

@@ -0,0 +1,10 @@
+import { ArtifactDefinitionMetadata, DefinitionDescriptor, DefinitionInput, DefinitionVerificationResult, SimplicityArtifact } from "./types";
+export declare function loadDefinitionInput(input: DefinitionInput): Promise<DefinitionDescriptor>;
+export declare function buildArtifactDefinitionMetadata(definition: DefinitionDescriptor): ArtifactDefinitionMetadata;
+export declare function verifyDefinitionDescriptorAgainstArtifact(definition: DefinitionDescriptor, artifactDefinition?: ArtifactDefinitionMetadata, expectedType?: string, expectedId?: string): DefinitionVerificationResult;
+export declare function verifyDefinitionAgainstArtifact(input: {
+    artifact: SimplicityArtifact;
+    definition: DefinitionInput;
+    expectedType?: string;
+    expectedId?: string;
+}): Promise<DefinitionVerificationResult>;

package/dist/core/definition.js

@@ -0,0 +1,150 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadDefinitionInput = loadDefinitionInput;
+exports.buildArtifactDefinitionMetadata = buildArtifactDefinitionMetadata;
+exports.verifyDefinitionDescriptorAgainstArtifact = verifyDefinitionDescriptorAgainstArtifact;
+exports.verifyDefinitionAgainstArtifact = verifyDefinitionAgainstArtifact;
+const promises_1 = require("node:fs/promises");
+const node_path_1 = __importDefault(require("node:path"));
+const errors_1 = require("./errors");
+const summary_1 = require("./summary");
+const DEFAULT_SCHEMA_VERSION = "1";
+function assertNonEmpty(value, fieldName) {
+    if (!value || value.trim().length === 0) {
+        throw new errors_1.DefinitionError(`${fieldName} must not be empty`);
+    }
+    return value;
+}
+function ensureSerializable(value, seen = new WeakSet()) {
+    if (value === undefined) {
+        throw new errors_1.DefinitionError("Definition JSON must not contain undefined values");
+    }
+    if (value === null)
+        return;
+    if (typeof value === "bigint") {
+        throw new errors_1.DefinitionError("Definition JSON must not contain bigint values");
+    }
+    if (value instanceof Date) {
+        throw new errors_1.DefinitionError("Definition JSON must not contain Date objects; normalize them first");
+    }
+    if (Array.isArray(value)) {
+        for (const entry of value)
+            ensureSerializable(entry, seen);
+        return;
+    }
+    if (typeof value === "object") {
+        const objectValue = value;
+        if (seen.has(objectValue)) {
+            throw new errors_1.DefinitionError("Definition JSON must not contain circular references");
+        }
+        seen.add(objectValue);
+        for (const entry of Object.values(objectValue))
+            ensureSerializable(entry, seen);
+    }
+}
+async function resolveDefinitionValue(input) {
+    if ((input.jsonPath ? 1 : 0) + (input.value !== undefined ? 1 : 0) !== 1) {
+        throw new errors_1.DefinitionError("Exactly one of jsonPath or value must be provided");
+    }
+    if (input.jsonPath) {
+        const sourcePath = node_path_1.default.resolve(input.jsonPath);
+        const raw = await (0, promises_1.readFile)(sourcePath, "utf8");
+        try {
+            return { value: JSON.parse(raw), sourcePath };
+        }
+        catch (error) {
+            throw new errors_1.DefinitionError(`Failed to parse definition JSON at ${sourcePath}`, error);
+        }
+    }
+    return { value: input.value };
+}
+async function loadDefinitionInput(input) {
+    const definitionType = assertNonEmpty(input.type, "definition.type");
+    const definitionId = assertNonEmpty(input.id, "definition.id");
+    const schemaVersion = assertNonEmpty(input.schemaVersion ?? DEFAULT_SCHEMA_VERSION, "definition.schemaVersion");
+    const { value, sourcePath } = await resolveDefinitionValue(input);
+    ensureSerializable(value);
+    const canonicalJson = (0, summary_1.stableStringify)(value);
+    return {
+        definitionType,
+        definitionId,
+        schemaVersion,
+        canonicalJson,
+        hash: (0, summary_1.sha256HexUtf8)(canonicalJson),
+        sourcePath,
+    };
+}
+function buildArtifactDefinitionMetadata(definition) {
+    return {
+        definitionType: definition.definitionType,
+        definitionId: definition.definitionId,
+        schemaVersion: definition.schemaVersion,
+        hash: definition.hash,
+        trustMode: "hash-anchor",
+    };
+}
+function verifyDefinitionDescriptorAgainstArtifact(definition, artifactDefinition, expectedType, expectedId) {
+    if (expectedType && expectedType !== definition.definitionType) {
+        return {
+            ok: false,
+            reason: `Definition type mismatch: expected=${expectedType} actual=${definition.definitionType}`,
+            definition,
+            artifactDefinition,
+        };
+    }
+    if (expectedId && expectedId !== definition.definitionId) {
+        return {
+            ok: false,
+            reason: `Definition id mismatch: expected=${expectedId} actual=${definition.definitionId}`,
+            definition,
+            artifactDefinition,
+        };
+    }
+    if (!artifactDefinition) {
+        return {
+            ok: false,
+            reason: "Artifact does not contain definition metadata",
+            definition,
+        };
+    }
+    if (artifactDefinition.definitionType !== definition.definitionType) {
+        return {
+            ok: false,
+            reason: `Definition type mismatch: artifact=${artifactDefinition.definitionType} actual=${definition.definitionType}`,
+            definition,
+            artifactDefinition,
+        };
+    }
+    if (artifactDefinition.definitionId !== definition.definitionId) {
+        return {
+            ok: false,
+            reason: `Definition id mismatch: artifact=${artifactDefinition.definitionId} actual=${definition.definitionId}`,
+            definition,
+            artifactDefinition,
+        };
+    }
+    if (artifactDefinition.schemaVersion !== definition.schemaVersion) {
+        return {
+            ok: false,
+            reason: `Definition schemaVersion mismatch: artifact=${artifactDefinition.schemaVersion} actual=${definition.schemaVersion}`,
+            definition,
+            artifactDefinition,
+        };
+    }
+    if (artifactDefinition.hash !== definition.hash) {
+        return {
+            ok: false,
+            reason: `Definition hash mismatch: artifact=${artifactDefinition.hash} actual=${definition.hash}`,
+            definition,
+            artifactDefinition,
+        };
+    }
+    return { ok: true, definition, artifactDefinition };
+}
+async function verifyDefinitionAgainstArtifact(input) {
+    const definition = await loadDefinitionInput(input.definition);
+    return verifyDefinitionDescriptorAgainstArtifact(definition, input.artifact.definition, input.expectedType, input.expectedId);
+}

package/dist/core/errors.d.ts

@@ -31,3 +31,9 @@ export declare class ValidationError extends SimplicitySdkError {
 export declare class PresetExecutionError extends SimplicitySdkError {
     constructor(message: string, details?: unknown);
 }
+export declare class DefinitionError extends SimplicitySdkError {
+    constructor(message: string, details?: unknown);
+}
+export declare class DefinitionVerificationError extends SimplicitySdkError {
+    constructor(message: string, details?: unknown);
+}

package/dist/core/errors.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PresetExecutionError = exports.ValidationError = exports.UnsupportedFeatureError = exports.RelayerError = exports.UtxoNotFoundError = exports.ExecutionError = exports.ArtifactError = exports.CompilerError = exports.ToolchainError = exports.SimplicitySdkError = void 0;
+exports.DefinitionVerificationError = exports.DefinitionError = exports.PresetExecutionError = exports.ValidationError = exports.UnsupportedFeatureError = exports.RelayerError = exports.UtxoNotFoundError = exports.ExecutionError = exports.ArtifactError = exports.CompilerError = exports.ToolchainError = exports.SimplicitySdkError = void 0;
 class SimplicitySdkError extends Error {
     code;
     details;
@@ -68,3 +68,15 @@ class PresetExecutionError extends SimplicitySdkError {
     }
 }
 exports.PresetExecutionError = PresetExecutionError;
+class DefinitionError extends SimplicitySdkError {
+    constructor(message, details) {
+        super("DEFINITION_ERROR", message, details);
+    }
+}
+exports.DefinitionError = DefinitionError;
+class DefinitionVerificationError extends SimplicitySdkError {
+    constructor(message, details) {
+        super("DEFINITION_VERIFICATION_ERROR", message, details);
+    }
+}
+exports.DefinitionVerificationError = DefinitionVerificationError;

package/dist/core/executor.js

@@ -202,8 +202,16 @@ function buildPsetSummary(decoded, meta) {
     return {
         network: meta.network,
         purpose: meta.purpose,
-        bondDefinitionId: meta.bondDefinitionId ?? null,
+        bondDefinitionId: meta.definitionType === "bond"
+            ? (meta.definitionId ?? meta.bondDefinitionId ?? null)
+            : (meta.bondDefinitionId ?? null),
         periodId: meta.periodId ?? null,
+        definition: {
+            type: meta.definitionType ?? null,
+            id: meta.definitionId ?? null,
+            hash: meta.definitionHash ?? null,
+            trustMode: meta.definitionTrustMode ?? null,
+        },
         contract: {
             address: meta.contractAddress,
             cmr: meta.cmr,
@@ -290,6 +298,10 @@ async function buildExecutionState(config, artifact, input) {
         purpose: input.purpose ?? "sdk_execute",
         bondDefinitionId: input.bondDefinitionId,
         periodId: input.periodId,
+        definitionType: artifact.definition?.definitionType,
+        definitionId: artifact.definition?.definitionId,
+        definitionHash: artifact.definition?.hash,
+        definitionTrustMode: artifact.definition?.trustMode,
         expectedLiquidReceiver: input.expectedLiquidReceiver ?? recipientAddress,
         contractAddress: artifact.compiled.contractAddress,
         cmr: artifact.compiled.cmr,
@@ -440,6 +452,11 @@ async function executeGaslessContractCall(config, artifact, input) {
     const summary = buildPsetSummary(decoded, {
         network: artifact.network,
         purpose: "sdk_gasless_execute",
+        bondDefinitionId: null,
+        definitionType: artifact.definition?.definitionType,
+        definitionId: artifact.definition?.definitionId,
+        definitionHash: artifact.definition?.hash,
+        definitionTrustMode: artifact.definition?.trustMode,
         contractAddress: artifact.compiled.contractAddress,
         cmr: artifact.compiled.cmr,
         internalKey: artifact.compiled.internalKey,
@@ -624,8 +641,14 @@ async function executeRelayedGaslessContractCall(config, artifact, input, relaye
         summary: {
             network: artifact.network,
             purpose: "sdk_gasless_execute_relayer",
-            bondDefinitionId: null,
+            bondDefinitionId: artifact.definition?.definitionType === "bond" ? artifact.definition.definitionId : null,
             periodId: null,
+            definition: {
+                type: artifact.definition?.definitionType ?? null,
+                id: artifact.definition?.definitionId ?? null,
+                hash: artifact.definition?.hash ?? null,
+                trustMode: artifact.definition?.trustMode ?? null,
+            },
             contract: {
                 address: request.detailedSummary.contract.contractAddress,
                 cmr: request.detailedSummary.contract.cmr,

package/dist/core/types.d.ts

@@ -1,5 +1,6 @@
 export type NetworkName = "liquidtestnet" | "liquidv1" | "regtest";
 export type UtxoPolicy = "smallest_over" | "largest" | "newest";
+export type DefinitionTrustMode = "hash-anchor";
 export interface RpcConfig {
     url: string;
     username: string;
@@ -68,6 +69,7 @@ export interface SimplicityArtifact {
         sdkVersion: string;
         notes: string | null;
     };
+    definition?: ArtifactDefinitionMetadata;
     legacy?: {
         simfTemplatePath?: string;
         params?: {
@@ -81,11 +83,35 @@ export interface CompileFromFileInput {
     simfPath: string;
     templateVars?: Record<string, string | number>;
     artifactPath?: string;
+    definition?: DefinitionInput;
 }
 export interface CompileFromPresetInput {
     preset: string;
     params: Record<string, string | number>;
     artifactPath?: string;
+    definition?: DefinitionInput;
+}
+export interface DefinitionInput {
+    type: string;
+    id: string;
+    schemaVersion?: string;
+    jsonPath?: string;
+    value?: unknown;
+}
+export interface DefinitionDescriptor {
+    definitionType: string;
+    definitionId: string;
+    schemaVersion: string;
+    canonicalJson: string;
+    hash: string;
+    sourcePath?: string;
+}
+export interface ArtifactDefinitionMetadata {
+    definitionType: string;
+    definitionId: string;
+    schemaVersion: string;
+    hash: string;
+    trustMode: DefinitionTrustMode;
 }
 export interface DeploymentInfo {
     contractAddress: string;
@@ -151,6 +177,12 @@ export interface PsetSummary {
     purpose?: string;
     bondDefinitionId?: string | null;
     periodId?: string | null;
+    definition?: {
+        type: string | null;
+        id: string | null;
+        hash: string | null;
+        trustMode: DefinitionTrustMode | null;
+    };
     contract: {
         address: string;
         cmr: string;
@@ -218,6 +250,12 @@ export interface GaslessExecuteResult {
         amountSat: number;
     };
 }
+export interface DefinitionVerificationResult {
+    ok: boolean;
+    reason?: string;
+    definition: DefinitionDescriptor;
+    artifactDefinition?: ArtifactDefinitionMetadata;
+}
 export interface WaitForFundingInput {
     minAmountSat?: number;
     pollIntervalMs?: number;

package/dist/index.d.ts

@@ -6,3 +6,4 @@ export * from "./core/types";
 export * from "./core/errors";
 export { listPresets, getPresetOrThrow } from "./core/presets";
 export { loadArtifact, saveArtifact, normalizeArtifact } from "./core/artifact";
+export { loadDefinitionInput, buildArtifactDefinitionMetadata, verifyDefinitionAgainstArtifact, verifyDefinitionDescriptorAgainstArtifact, } from "./core/definition";

package/dist/index.js

@@ -14,7 +14,7 @@ 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;
+exports.verifyDefinitionDescriptorAgainstArtifact = exports.verifyDefinitionAgainstArtifact = exports.buildArtifactDefinitionMetadata = exports.loadDefinitionInput = 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; } });
@@ -33,3 +33,8 @@ 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; } });
+var definition_1 = require("./core/definition");
+Object.defineProperty(exports, "loadDefinitionInput", { enumerable: true, get: function () { return definition_1.loadDefinitionInput; } });
+Object.defineProperty(exports, "buildArtifactDefinitionMetadata", { enumerable: true, get: function () { return definition_1.buildArtifactDefinitionMetadata; } });
+Object.defineProperty(exports, "verifyDefinitionAgainstArtifact", { enumerable: true, get: function () { return definition_1.verifyDefinitionAgainstArtifact; } });
+Object.defineProperty(exports, "verifyDefinitionDescriptorAgainstArtifact", { enumerable: true, get: function () { return definition_1.verifyDefinitionDescriptorAgainstArtifact; } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hazbase/simplicity",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "An SDK for Simplicity on Liquid",
   "author": "IndieSquare Inc <info@hazbase.com>",
   "keywords": [
@@ -36,7 +36,8 @@
     "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"
+    "e2e:simplicity-relayer": "npm run build && node scripts/e2e-simplicity-relayer.mjs",
+    "prepublishOnly": "npm run build"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",