@hazbase/simplicity 0.0.3 → 0.0.4

package/README.md

@@ -134,6 +134,82 @@ simplicity-cli definition verify \
 
 For a bond-oriented walkthrough, see [docs/definitions/README.md](./docs/definitions/README.md).
 
+## Trusted Issuance State JSON
+
+The same hash-anchor model now also applies to issuance state documents such as a bond issuance record.
+
+This is useful when you want to say not only:
+
+- "these are the bond terms,"
+
+but also:
+
+- "this bond was issued in this amount, with this outstanding principal, under this controller."
+
+The SDK now supports:
+
+- loading and hashing a state JSON with `sdk.loadStateDocument(...)`,
+- storing its hash in the artifact,
+- committing `STATE_HASH` into custom `.simf` contract logic,
+- verifying later that the issuance state JSON still matches the compiled contract.
+
+For Bond issuance, the recommended shape is:
+
+```json
+{
+  "issuanceId": "BOND-2026-001-ISSUE-1",
+  "bondId": "BOND-2026-001",
+  "issuerEntityId": "hazbase-treasury",
+  "issuedPrincipal": 1000000,
+  "outstandingPrincipal": 1000000,
+  "redeemedPrincipal": 0,
+  "currencyAssetId": "bitcoin",
+  "controllerXonly": "<xonly>",
+  "issuedAt": "2026-03-10T00:00:00Z",
+  "status": "ISSUED"
+}
+```
+
+Minimal TypeScript flow:
+
+```ts
+const compiled = await sdk.bonds.defineBond({
+  definitionPath: "./docs/definitions/bond-definition.json",
+  issuancePath: "./docs/definitions/bond-issuance-state.json",
+  simfPath: "./docs/definitions/bond-issuance-anchor.simf",
+  artifactPath: "./bond-issuance.artifact.json",
+});
+
+const verification = await sdk.bonds.verifyBond({
+  artifactPath: "./bond-issuance.artifact.json",
+  definitionPath: "./docs/definitions/bond-definition.json",
+  issuancePath: "./docs/definitions/bond-issuance-state.json",
+});
+
+console.log(verification.crossChecks.principalInvariantValid);
+console.log(verification.issuance.trust.effectiveMode);
+```
+
+CLI equivalents:
+
+```bash
+simplicity-cli state show \
+  --type bond-issuance \
+  --id BOND-2026-001-ISSUE-1 \
+  --json-path ./docs/definitions/bond-issuance-state.json
+
+simplicity-cli state verify \
+  --artifact ./bond-issuance.artifact.json \
+  --type bond-issuance \
+  --id BOND-2026-001-ISSUE-1 \
+  --json-path ./docs/definitions/bond-issuance-state.json
+
+simplicity-cli bond verify \
+  --artifact ./bond-issuance.artifact.json \
+  --definition-json ./docs/definitions/bond-definition.json \
+  --issuance-json ./docs/definitions/bond-issuance-state.json
+```
+
 ## Install
 
 You need three things:
@@ -811,6 +887,9 @@ These examples are included to help you jump to the right workflow quickly.
 - [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.
+- [define-bond-issuance.ts](./examples/define-bond-issuance.ts): compile a bond example with both trusted definition and issuance state anchors.
+- [show-bond-issuance.ts](./examples/show-bond-issuance.ts): load a bond artifact together with its verified issuance state.
+- [verify-bond-issuance.ts](./examples/verify-bond-issuance.ts): run combined Bond definition/state verification and invariant checks.
 
 In addition to the in-repo examples, the package has also been validated from a blank external consumer project with:
 - `npm install @hazbase/simplicity`
@@ -843,6 +922,16 @@ When you compile with `definition: { ... }`, the artifact also carries:
 
 That is what allows the SDK and CLI to verify that an off-chain JSON definition still matches the contract you compiled.
 
+When you also compile with `state: { ... }`, the artifact can additionally carry:
+- `stateType`
+- `stateId`
+- `schemaVersion`
+- `hash`
+- `trustMode`
+- `anchorMode`
+
+That is what allows the SDK and CLI to verify that an off-chain issuance state document 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

@@ -8,6 +8,7 @@ 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 state_1 = require("./core/state");
 const presets_1 = require("./core/presets");
 const errors_1 = require("./core/errors");
 const SimplicityClient_1 = require("./client/SimplicityClient");
@@ -85,6 +86,25 @@ function parseDefinitionInput() {
         anchorMode,
     };
 }
+function parseStateInput() {
+    const type = getArg("state-type");
+    const id = getArg("state-id");
+    const jsonPath = getArg("state-json");
+    const valueJson = getArg("state-value");
+    const schemaVersion = getArg("state-schema-version");
+    const anchorMode = getArg("state-anchor-mode");
+    if (!type && !id && !jsonPath && !valueJson && !schemaVersion && !anchorMode) {
+        return undefined;
+    }
+    return {
+        type: type ?? "",
+        id: id ?? "",
+        schemaVersion: schemaVersion ?? undefined,
+        jsonPath,
+        value: valueJson ? JSON.parse(valueJson) : undefined,
+        anchorMode,
+    };
+}
 function resolveConfig() {
     return {
         network: getArg("network", "liquidtestnet"),
@@ -389,6 +409,18 @@ function formatArtifactHelp(artifact, preset, utxos) {
             `  source verified: ${artifact.definition.onChainAnchor?.sourceVerified === true ? "yes" : "no"}`,
         ].join("\n")
         : "  (none)";
+    const state = artifact.state
+        ? [
+            `  type: ${artifact.state.stateType}`,
+            `  id: ${artifact.state.stateId}`,
+            `  schema version: ${artifact.state.schemaVersion}`,
+            `  hash: ${artifact.state.hash}`,
+            `  trust mode: ${artifact.state.trustMode}`,
+            `  anchor mode: ${artifact.state.anchorMode}`,
+            `  on-chain helper: ${artifact.state.onChainAnchor?.helper ?? "(none)"}`,
+            `  source verified: ${artifact.state.onChainAnchor?.sourceVerified === true ? "yes" : "no"}`,
+        ].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...`;
@@ -410,6 +442,9 @@ function formatArtifactHelp(artifact, preset, utxos) {
         "Definition Anchor:",
         definition,
         "",
+        "State Anchor:",
+        state,
+        "",
         "Suggested Commands:",
         `  ${inspectCommand}`,
         `  ${executeCommand}`,
@@ -451,7 +486,7 @@ 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|definition|gasless> ...");
+        throw new Error("Usage: simplicity-cli <compile|presets|preset|contract|artifact|definition|state|bond|gasless> ...");
     }
     if (command === "compile") {
         const result = await sdk.compileFromFile({
@@ -459,6 +494,7 @@ async function main() {
             templateVars: parseAssignments(getMultiArgs("template-var")),
             artifactPath: getArg("artifact"),
             definition: parseDefinitionInput(),
+            state: parseStateInput(),
         });
         printJson({ artifact: result.artifact, deployment: result.deployment() });
         return;
@@ -497,6 +533,40 @@ async function main() {
         });
         return;
     }
+    if (command === "state" && subcommand === "show") {
+        const state = await (0, state_1.loadStateInput)({
+            type: requireArg("type"),
+            id: requireArg("id"),
+            jsonPath: getArg("json-path"),
+            value: getArg("value") ? JSON.parse(getArg("value")) : undefined,
+            schemaVersion: getArg("schema-version"),
+        });
+        printJson({
+            ...state,
+            anchorRecommendation: "Use --state-anchor-mode on-chain-constant-committed with a blessed custom .simf helper for on-chain enforcement",
+        });
+        return;
+    }
+    if (command === "state" && subcommand === "verify") {
+        const verification = await sdk.verifyStateAgainstArtifact({
+            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,
+            state: verification.state,
+            artifactState: verification.artifactState ?? null,
+            trust: verification.trust,
+        });
+        return;
+    }
     if (command === "presets" && subcommand === "list") {
         printJson((0, presets_1.listPresets)().map((preset) => (0, presets_1.describePreset)(preset)));
         return;
@@ -543,6 +613,7 @@ async function main() {
             params,
             artifactPath: getArg("artifact"),
             definition: parseDefinitionInput(),
+            state: parseStateInput(),
         });
         printJson({ artifact: result.artifact, deployment: result.deployment() });
         return;
@@ -572,6 +643,25 @@ async function main() {
         });
         return;
     }
+    if (command === "bond" && subcommand === "define") {
+        const result = await sdk.bonds.defineBond({
+            definitionPath: getArg("definition-json"),
+            issuancePath: getArg("issuance-json"),
+            simfPath: getArg("simf"),
+            artifactPath: getArg("artifact"),
+        });
+        printJson({ artifact: result.artifact, deployment: result.deployment() });
+        return;
+    }
+    if (command === "bond" && subcommand === "verify") {
+        const result = await sdk.bonds.verifyBond({
+            artifactPath: requireArg("artifact"),
+            definitionPath: getArg("definition-json"),
+            issuancePath: getArg("issuance-json"),
+        });
+        printJson(result);
+        return;
+    }
     if (command === "contract" && subcommand === "wait-funding") {
         const compiled = await sdk.loadArtifact(requireArg("artifact"));
         const utxos = await compiled.at().waitForFunding({

package/dist/client/ContractFactory.d.ts

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

package/dist/client/ContractFactory.js

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

package/dist/client/DeployedContract.d.ts

@@ -1,5 +1,6 @@
 import { verifyDefinitionAgainstArtifact } from "../core/definition";
-import { ArtifactDefinitionMetadata, ContractUtxo, ExecuteCallInput, ExecuteResult, GaslessExecuteInput, GaslessExecuteResult, InspectCallInput, InspectResult, SimplicityArtifact, SimplicityClientConfig, WaitForFundingInput } from "../core/types";
+import { verifyStateAgainstArtifact } from "../core/state";
+import { ArtifactDefinitionMetadata, ArtifactStateMetadata, ContractUtxo, ExecuteCallInput, ExecuteResult, GaslessExecuteInput, GaslessExecuteResult, InspectCallInput, InspectResult, SimplicityArtifact, SimplicityClientConfig, WaitForFundingInput } from "../core/types";
 export declare class DeployedContract {
     private readonly config;
     readonly artifact: SimplicityArtifact;
@@ -23,4 +24,17 @@ export declare class DeployedContract {
         reason?: string;
         trust: Awaited<ReturnType<typeof verifyDefinitionAgainstArtifact>>["trust"];
     }>;
+    getTrustedState(input: {
+        jsonPath?: string;
+        value?: unknown;
+        type?: string;
+        id?: string;
+        schemaVersion?: string;
+    }): Promise<{
+        verified: boolean;
+        state: Awaited<ReturnType<typeof verifyStateAgainstArtifact>>["state"];
+        artifactState: ArtifactStateMetadata | null;
+        reason?: string;
+        trust: Awaited<ReturnType<typeof verifyStateAgainstArtifact>>["trust"];
+    }>;
 }

package/dist/client/DeployedContract.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.DeployedContract = void 0;
 const executor_1 = require("../core/executor");
 const definition_1 = require("../core/definition");
+const state_1 = require("../core/state");
 const executor_2 = require("../core/executor");
 class DeployedContract {
     config;
@@ -61,5 +62,26 @@ class DeployedContract {
             trust: verification.trust,
         };
     }
+    async getTrustedState(input) {
+        const verification = await (0, state_1.verifyStateAgainstArtifact)({
+            artifact: this.artifact,
+            state: {
+                type: input.type ?? this.artifact.state?.stateType ?? "",
+                id: input.id ?? this.artifact.state?.stateId ?? "",
+                schemaVersion: input.schemaVersion,
+                jsonPath: input.jsonPath,
+                value: input.value,
+            },
+            expectedType: this.artifact.state?.stateType,
+            expectedId: this.artifact.state?.stateId,
+        });
+        return {
+            verified: verification.ok,
+            state: verification.state,
+            artifactState: verification.artifactState ?? null,
+            reason: verification.reason,
+            trust: verification.trust,
+        };
+    }
 }
 exports.DeployedContract = DeployedContract;

package/dist/client/SimplicityClient.d.ts

@@ -1,21 +1,48 @@
 import { ElementsRpcClient } from "../core/rpc";
-import { DefinitionInput, DefinitionVerificationResult, CompileFromFileInput, CompileFromPresetInput, DefinitionDescriptor, SimplicityArtifact, SimplicityClientConfig } from "../core/types";
+import { BondDefinition, BondIssuanceState, DefinitionInput, DefinitionVerificationResult, CompileFromFileInput, CompileFromPresetInput, DefinitionDescriptor, StateDocumentDescriptor, StateDocumentInput, StateVerificationResult, SimplicityArtifact, SimplicityClientConfig } from "../core/types";
 import { RelayerClient } from "../gasless/RelayerClient";
 import { GaslessTransferInput, GaslessTransferResult, RelayerClientConfig } from "../gasless/types";
 import { CompiledContract } from "./ContractFactory";
 import { DeployedContract } from "./DeployedContract";
+import { loadBond, verifyBond } from "../domain/bond";
 export declare class SimplicityClient {
     readonly config: SimplicityClientConfig;
     readonly rpc: ElementsRpcClient;
     readonly payments: {
         gaslessTransfer: (input: GaslessTransferInput) => Promise<GaslessTransferResult>;
     };
+    readonly bonds: {
+        defineBond: (input: {
+            definitionPath?: string;
+            definitionValue?: BondDefinition;
+            issuancePath?: string;
+            issuanceValue?: BondIssuanceState;
+            simfPath?: string;
+            artifactPath?: string;
+        }) => Promise<CompiledContract>;
+        verifyBond: (input: {
+            artifactPath?: string;
+            artifact?: SimplicityArtifact;
+            definitionPath?: string;
+            definitionValue?: BondDefinition;
+            issuancePath?: string;
+            issuanceValue?: BondIssuanceState;
+        }) => ReturnType<typeof verifyBond>;
+        loadBond: (input: {
+            artifactPath: string;
+            definitionPath?: string;
+            definitionValue?: BondDefinition;
+            issuancePath?: string;
+            issuanceValue?: BondIssuanceState;
+        }) => ReturnType<typeof loadBond>;
+    };
     constructor(config: SimplicityClientConfig);
     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>;
+    loadStateDocument(input: StateDocumentInput): Promise<StateDocumentDescriptor>;
     verifyDefinitionAgainstArtifact(input: {
         artifactPath?: string;
         artifact?: SimplicityArtifact;
@@ -27,6 +54,17 @@ export declare class SimplicityClient {
         id?: string;
         schemaVersion?: string;
     }): Promise<DefinitionVerificationResult>;
+    verifyStateAgainstArtifact(input: {
+        artifactPath?: string;
+        artifact?: SimplicityArtifact;
+        jsonPath?: string;
+        value?: unknown;
+        expectedType?: string;
+        expectedId?: string;
+        type?: string;
+        id?: string;
+        schemaVersion?: string;
+    }): Promise<StateVerificationResult>;
     fromArtifact(artifact: SimplicityArtifact): DeployedContract;
     relayer(config: RelayerClientConfig): RelayerClient;
     private gaslessTransfer;

package/dist/client/SimplicityClient.js

@@ -5,21 +5,29 @@ exports.createSimplicityClient = createSimplicityClient;
 const artifact_1 = require("../core/artifact");
 const compiler_1 = require("../core/compiler");
 const definition_1 = require("../core/definition");
+const state_1 = require("../core/state");
 const errors_1 = require("../core/errors");
 const rpc_1 = require("../core/rpc");
 const RelayerClient_1 = require("../gasless/RelayerClient");
 const ContractFactory_1 = require("./ContractFactory");
 const DeployedContract_1 = require("./DeployedContract");
+const bond_1 = require("../domain/bond");
 class SimplicityClient {
     config;
     rpc;
     payments;
+    bonds;
     constructor(config) {
         this.config = config;
         this.rpc = new rpc_1.ElementsRpcClient(config.rpc);
         this.payments = {
             gaslessTransfer: async (input) => this.gaslessTransfer(input),
         };
+        this.bonds = {
+            defineBond: async (input) => (0, bond_1.defineBond)(this, input),
+            verifyBond: async (input) => (0, bond_1.verifyBond)(this, input),
+            loadBond: async (input) => (0, bond_1.loadBond)(this, input),
+        };
     }
     async compileFromFile(input) {
         const artifact = await (0, compiler_1.compileFromFile)(this.config, input);
@@ -39,6 +47,9 @@ class SimplicityClient {
     async loadDefinition(input) {
         return (0, definition_1.loadDefinitionInput)(input);
     }
+    async loadStateDocument(input) {
+        return (0, state_1.loadStateInput)(input);
+    }
     async verifyDefinitionAgainstArtifact(input) {
         const artifact = input.artifact ?? (input.artifactPath ? await (0, artifact_1.loadArtifact)(input.artifactPath, this.config.network) : undefined);
         if (!artifact) {
@@ -57,6 +68,24 @@ class SimplicityClient {
             expectedId: input.expectedId,
         });
     }
+    async verifyStateAgainstArtifact(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, state_1.verifyStateAgainstArtifact)({
+            artifact,
+            state: {
+                type: input.type ?? input.expectedType ?? artifact.state?.stateType ?? "",
+                id: input.id ?? input.expectedId ?? artifact.state?.stateId ?? "",
+                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

@@ -26,6 +26,12 @@ function normalizeArtifact(artifact, networkDefault = "liquidtestnet") {
                     anchorMode: current.definition.anchorMode ?? "artifact-hash-anchor",
                 }
                 : undefined,
+            state: current.state
+                ? {
+                    ...current.state,
+                    anchorMode: current.state.anchorMode ?? "artifact-hash-anchor",
+                }
+                : undefined,
         };
     }
     if (!isArtifactV5(artifact)) {
@@ -65,6 +71,7 @@ function normalizeArtifact(artifact, networkDefault = "liquidtestnet") {
             notes: null,
         },
         definition: undefined,
+        state: undefined,
         legacy: {
             simfTemplatePath: artifact.simfTemplatePath,
             params: artifact.params,
@@ -101,6 +108,7 @@ async function loadArtifact(artifactPath, networkDefault = "liquidtestnet") {
             }
             : undefined,
         definition: normalized.definition,
+        state: normalized.state,
     };
 }
 async function saveArtifact(artifactPath, artifact) {

package/dist/core/compiler.js

@@ -12,6 +12,7 @@ const artifact_1 = require("./artifact");
 const definition_1 = require("./definition");
 const errors_1 = require("./errors");
 const presets_1 = require("./presets");
+const state_1 = require("./state");
 const templating_1 = require("./templating");
 const toolchain_1 = require("./toolchain");
 function parseSimcProgram(output) {
@@ -74,6 +75,12 @@ async function buildArtifact(input) {
                 onChainAnchor: input.definition.onChainAnchor,
             })
             : undefined,
+        state: input.state
+            ? (0, state_1.buildArtifactStateMetadata)(input.state, {
+                anchorMode: input.state.anchorMode,
+                onChainAnchor: input.state.onChainAnchor,
+            })
+            : undefined,
         legacy: {
             simfTemplatePath: input.sourceSimfPath,
             params: {
@@ -85,14 +92,22 @@ async function buildArtifact(input) {
 }
 async function compileFromFile(config, input) {
     const definition = input.definition ? await (0, definition_1.loadDefinitionInput)(input.definition) : undefined;
+    const state = input.state ? await (0, state_1.loadStateInput)(input.state) : undefined;
     if (definition && input.templateVars?.DEFINITION_HASH !== undefined) {
         throw new errors_1.ValidationError("DEFINITION_HASH must not be provided explicitly when definition metadata is supplied", { code: "DEFINITION_HASH_OVERRIDE_FORBIDDEN" });
     }
     if (definition && input.templateVars?.DEFINITION_ID !== undefined) {
         throw new errors_1.ValidationError("DEFINITION_ID must not be provided explicitly when definition metadata is supplied", { code: "DEFINITION_ID_OVERRIDE_FORBIDDEN" });
     }
+    if (state && input.templateVars?.STATE_HASH !== undefined) {
+        throw new errors_1.ValidationError("STATE_HASH must not be provided explicitly when state metadata is supplied", { code: "STATE_HASH_OVERRIDE_FORBIDDEN" });
+    }
+    if (state && input.templateVars?.STATE_ID !== undefined) {
+        throw new errors_1.ValidationError("STATE_ID must not be provided explicitly when state metadata is supplied", { code: "STATE_ID_OVERRIDE_FORBIDDEN" });
+    }
     const rawSource = await (0, promises_1.readFile)(input.simfPath, "utf8");
     let onChainAnchor;
+    let onChainStateAnchor;
     if (input.definition?.anchorMode === "on-chain-constant-committed") {
         const detection = (0, definition_1.detectOnChainDefinitionAnchor)(rawSource);
         if (!rawSource.includes("{{DEFINITION_HASH}}")) {
@@ -110,10 +125,27 @@ async function compileFromFile(config, input) {
             sourceVerified: true,
         };
     }
+    if (input.state?.anchorMode === "on-chain-constant-committed") {
+        const detection = (0, state_1.detectOnChainStateAnchor)(rawSource);
+        if (!rawSource.includes("{{STATE_HASH}}")) {
+            throw new errors_1.ValidationError("Requested on-chain constant-committed state anchor, but the .simf source does not contain {{STATE_HASH}}", { code: "STATE_HASH_PLACEHOLDER_MISSING" });
+        }
+        if (!detection.sourceVerified || !detection.helper) {
+            const code = detection.reason?.includes("called")
+                ? "STATE_ONCHAIN_HELPER_NOT_CALLED"
+                : "STATE_ONCHAIN_HELPER_MISSING";
+            throw new errors_1.ValidationError(`Requested on-chain constant-committed state anchor, but the .simf source does not contain the required state helper pattern: ${detection.reason ?? "unknown reason"}`, { code });
+        }
+        onChainStateAnchor = {
+            helper: detection.helper,
+            templateVar: "STATE_HASH",
+            sourceVerified: true,
+        };
+    }
     const templateVars = {
         ...(input.templateVars ?? {}),
-        ...(definition && input.templateVars?.DEFINITION_HASH === undefined ? { DEFINITION_HASH: definition.hash } : {}),
-        ...(definition && input.templateVars?.DEFINITION_ID === undefined ? { DEFINITION_ID: definition.definitionId } : {}),
+        ...(definition ? { DEFINITION_HASH: definition.hash, DEFINITION_ID: definition.definitionId } : {}),
+        ...(state ? { STATE_HASH: state.hash, STATE_ID: state.stateId } : {}),
     };
     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-"));
@@ -123,7 +155,7 @@ async function compileFromFile(config, input) {
         config,
         renderedSimfPath: renderedPath,
         sourceMode: "file",
-        sourceSimfPath: input.simfPath,
+        sourceSimfPath: node_path_1.default.resolve(input.simfPath),
         templateVars,
         definition: definition
             ? {
@@ -132,6 +164,13 @@ async function compileFromFile(config, input) {
                 onChainAnchor,
             }
             : undefined,
+        state: state
+            ? {
+                ...state,
+                anchorMode: input.state?.anchorMode ?? "artifact-hash-anchor",
+                onChainAnchor: onChainStateAnchor,
+            }
+            : undefined,
     });
     if (input.artifactPath) {
         await (0, artifact_1.saveArtifact)(input.artifactPath, artifact);
@@ -143,17 +182,27 @@ async function compileFromPreset(config, input) {
     if (input.definition?.anchorMode === "on-chain-constant-committed") {
         throw new errors_1.UnsupportedFeatureError(`Preset '${preset.id}' does not yet support on-chain constant-committed definition anchors`, { code: "DEFINITION_ANCHOR_MODE_UNSUPPORTED_FOR_PRESET", preset: preset.id });
     }
+    if (input.state?.anchorMode === "on-chain-constant-committed") {
+        throw new errors_1.UnsupportedFeatureError(`Preset '${preset.id}' does not yet support on-chain constant-committed state anchors`, { code: "STATE_ANCHOR_MODE_UNSUPPORTED_FOR_PRESET", preset: preset.id });
+    }
     const definition = input.definition ? await (0, definition_1.loadDefinitionInput)(input.definition) : undefined;
+    const state = input.state ? await (0, state_1.loadStateInput)(input.state) : undefined;
     if (definition && input.params.DEFINITION_HASH !== undefined) {
         throw new errors_1.ValidationError("DEFINITION_HASH must not be provided explicitly when definition metadata is supplied", { code: "DEFINITION_HASH_OVERRIDE_FORBIDDEN" });
     }
     if (definition && input.params.DEFINITION_ID !== undefined) {
         throw new errors_1.ValidationError("DEFINITION_ID must not be provided explicitly when definition metadata is supplied", { code: "DEFINITION_ID_OVERRIDE_FORBIDDEN" });
     }
+    if (state && input.params.STATE_HASH !== undefined) {
+        throw new errors_1.ValidationError("STATE_HASH must not be provided explicitly when state metadata is supplied", { code: "STATE_HASH_OVERRIDE_FORBIDDEN" });
+    }
+    if (state && input.params.STATE_ID !== undefined) {
+        throw new errors_1.ValidationError("STATE_ID must not be provided explicitly when state metadata is supplied", { code: "STATE_ID_OVERRIDE_FORBIDDEN" });
+    }
     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 } : {}),
+        ...(definition ? { DEFINITION_HASH: definition.hash, DEFINITION_ID: definition.definitionId } : {}),
+        ...(state ? { STATE_HASH: state.hash, STATE_ID: state.stateId } : {}),
     };
     const rawSource = await (0, promises_1.readFile)(preset.simfTemplatePath, "utf8");
     const rendered = (0, templating_1.renderTemplate)(rawSource, params);
@@ -173,6 +222,12 @@ async function compileFromPreset(config, input) {
                 anchorMode: input.definition?.anchorMode ?? "artifact-hash-anchor",
             }
             : undefined,
+        state: state
+            ? {
+                ...state,
+                anchorMode: input.state?.anchorMode ?? "artifact-hash-anchor",
+            }
+            : undefined,
     });
     if (input.artifactPath) {
         await (0, artifact_1.saveArtifact)(input.artifactPath, artifact);