@hazbase/simplicity 0.0.3 → 0.0.5

package/dist/client/SimplicityClient.d.ts

@@ -1,21 +1,313 @@
 import { ElementsRpcClient } from "../core/rpc";
-import { DefinitionInput, DefinitionVerificationResult, CompileFromFileInput, CompileFromPresetInput, DefinitionDescriptor, SimplicityArtifact, SimplicityClientConfig } from "../core/types";
+import { BondDefinition, BondIssuanceState, BondSettlementDescriptor, 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 { buildBondPayload, buildBondRedemption, buildBondTransitionPayload, buildBondRolloverPlan, buildBondMachineRolloverPlan, buildBondMachineSettlementPlan, buildBondSettlementDescriptor, buildBondSettlementPayload, compileBondRedemptionMachine, compileBondTransition, executeBondStateRollover, executeBondMachineRollover, executeBondMachineSettlement, inspectBondStateRollover, inspectBondMachineRollover, inspectBondMachineSettlement, loadBond, redeemBond, verifyBond, verifyBondSettlementDescriptor, verifyBondRedemptionMachineArtifact, verifyBondTransition } 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>;
+        redeemBond: (input: {
+            definitionPath?: string;
+            definitionValue?: BondDefinition;
+            previousIssuancePath?: string;
+            previousIssuanceValue?: BondIssuanceState;
+            amount: number;
+            redeemedAt: string;
+            simfPath?: string;
+            artifactPath?: string;
+        }) => ReturnType<typeof redeemBond>;
+        verifyBondTransition: (input: {
+            previousIssuancePath?: string;
+            previousIssuanceValue?: BondIssuanceState;
+            nextIssuancePath?: string;
+            nextIssuanceValue?: BondIssuanceState;
+        }) => ReturnType<typeof verifyBondTransition>;
+        buildBondRedemption: (input: {
+            definitionPath?: string;
+            definitionValue?: BondDefinition;
+            previousIssuancePath?: string;
+            previousIssuanceValue?: BondIssuanceState;
+            amount: number;
+            redeemedAt: string;
+        }) => ReturnType<typeof buildBondRedemption>;
+        buildBondPayload: (input: {
+            artifactPath?: string;
+            artifact?: SimplicityArtifact;
+            definitionPath?: string;
+            definitionValue?: BondDefinition;
+            issuancePath?: string;
+            issuanceValue?: BondIssuanceState;
+        }) => ReturnType<typeof buildBondPayload>;
+        buildBondTransitionPayload: (input: {
+            definitionPath?: string;
+            definitionValue?: BondDefinition;
+            previousIssuancePath?: string;
+            previousIssuanceValue?: BondIssuanceState;
+            nextIssuancePath?: string;
+            nextIssuanceValue?: BondIssuanceState;
+        }) => ReturnType<typeof buildBondTransitionPayload>;
+        buildBondSettlementDescriptor: (input: {
+            definitionPath?: string;
+            definitionValue?: BondDefinition;
+            previousIssuancePath?: string;
+            previousIssuanceValue?: BondIssuanceState;
+            nextIssuancePath?: string;
+            nextIssuanceValue?: BondIssuanceState;
+            nextStateSimfPath?: string;
+            nextAmountSat: number;
+            maxFeeSat?: number;
+        }) => ReturnType<typeof buildBondSettlementDescriptor>;
+        verifyBondSettlementDescriptor: (input: {
+            descriptorPath?: string;
+            descriptorValue?: BondSettlementDescriptor;
+            definitionPath?: string;
+            definitionValue?: BondDefinition;
+            previousIssuancePath?: string;
+            previousIssuanceValue?: BondIssuanceState;
+            nextIssuancePath?: string;
+            nextIssuanceValue?: BondIssuanceState;
+            nextStateSimfPath?: string;
+            nextAmountSat?: number;
+            maxFeeSat?: number;
+        }) => ReturnType<typeof verifyBondSettlementDescriptor>;
+        buildBondSettlementPayload: (input: {
+            definitionPath?: string;
+            definitionValue?: BondDefinition;
+            previousIssuancePath?: string;
+            previousIssuanceValue?: BondIssuanceState;
+            nextIssuancePath?: string;
+            nextIssuanceValue?: BondIssuanceState;
+            nextStateSimfPath?: string;
+            nextAmountSat: number;
+            maxFeeSat?: number;
+        }) => ReturnType<typeof buildBondSettlementPayload>;
+        buildBondRolloverPlan: (input: {
+            currentArtifactPath?: string;
+            currentArtifact?: SimplicityArtifact;
+            definitionPath?: string;
+            definitionValue?: BondDefinition;
+            previousIssuancePath?: string;
+            previousIssuanceValue?: BondIssuanceState;
+            nextIssuancePath?: string;
+            nextIssuanceValue?: BondIssuanceState;
+            nextSimfPath?: string;
+            nextArtifactPath?: string;
+        }) => ReturnType<typeof buildBondRolloverPlan>;
+        buildBondMachineRolloverPlan: (input: {
+            currentArtifactPath?: string;
+            currentArtifact?: SimplicityArtifact;
+            definitionPath?: string;
+            definitionValue?: BondDefinition;
+            previousIssuancePath?: string;
+            previousIssuanceValue?: BondIssuanceState;
+            nextIssuancePath?: string;
+            nextIssuanceValue?: BondIssuanceState;
+            nextStateSimfPath?: string;
+            machineSimfPath?: string;
+            machineArtifactPath?: string;
+        }) => ReturnType<typeof buildBondMachineRolloverPlan>;
+        buildBondMachineSettlementPlan: (input: {
+            currentMachineArtifactPath?: string;
+            currentMachineArtifact?: SimplicityArtifact;
+            definitionPath?: string;
+            definitionValue?: BondDefinition;
+            previousIssuancePath?: string;
+            previousIssuanceValue?: BondIssuanceState;
+            nextIssuancePath?: string;
+            nextIssuanceValue?: BondIssuanceState;
+            nextSimfPath?: string;
+            nextArtifactPath?: string;
+        }) => ReturnType<typeof buildBondMachineSettlementPlan>;
+        compileBondTransition: (input: {
+            definitionPath?: string;
+            definitionValue?: BondDefinition;
+            previousIssuancePath?: string;
+            previousIssuanceValue?: BondIssuanceState;
+            nextIssuancePath?: string;
+            nextIssuanceValue?: BondIssuanceState;
+            simfPath?: string;
+            artifactPath?: string;
+        }) => ReturnType<typeof compileBondTransition>;
+        compileBondRedemptionMachine: (input: {
+            definitionPath?: string;
+            definitionValue?: BondDefinition;
+            previousIssuancePath?: string;
+            previousIssuanceValue?: BondIssuanceState;
+            nextIssuancePath?: string;
+            nextIssuanceValue?: BondIssuanceState;
+            nextStateSimfPath?: string;
+            nextAmountSat?: number;
+            maxFeeSat?: number;
+            simfPath?: string;
+            artifactPath?: string;
+        }) => ReturnType<typeof compileBondRedemptionMachine>;
+        verifyBondRedemptionMachineArtifact: (input: {
+            artifactPath?: string;
+            artifact?: SimplicityArtifact;
+            definitionPath?: string;
+            definitionValue?: BondDefinition;
+            previousIssuancePath?: string;
+            previousIssuanceValue?: BondIssuanceState;
+            nextIssuancePath?: string;
+            nextIssuanceValue?: BondIssuanceState;
+            nextStateSimfPath?: string;
+            nextAmountSat?: number;
+            maxFeeSat?: number;
+        }) => ReturnType<typeof verifyBondRedemptionMachineArtifact>;
+        inspectBondStateRollover: (input: {
+            currentArtifactPath?: string;
+            currentArtifact?: SimplicityArtifact;
+            definitionPath?: string;
+            definitionValue?: BondDefinition;
+            previousIssuancePath?: string;
+            previousIssuanceValue?: BondIssuanceState;
+            nextIssuancePath?: string;
+            nextIssuanceValue?: BondIssuanceState;
+            nextSimfPath?: string;
+            nextArtifactPath?: string;
+            wallet: string;
+            signer: {
+                type: "schnorrPrivkeyHex";
+                privkeyHex: string;
+            };
+            feeSat?: number;
+            utxoPolicy?: "smallest_over" | "largest" | "newest";
+        }) => ReturnType<typeof inspectBondStateRollover>;
+        inspectBondMachineRollover: (input: {
+            currentArtifactPath?: string;
+            currentArtifact?: SimplicityArtifact;
+            definitionPath?: string;
+            definitionValue?: BondDefinition;
+            previousIssuancePath?: string;
+            previousIssuanceValue?: BondIssuanceState;
+            nextIssuancePath?: string;
+            nextIssuanceValue?: BondIssuanceState;
+            machineSimfPath?: string;
+            machineArtifactPath?: string;
+            wallet: string;
+            signer: {
+                type: "schnorrPrivkeyHex";
+                privkeyHex: string;
+            };
+            feeSat?: number;
+            utxoPolicy?: "smallest_over" | "largest" | "newest";
+        }) => ReturnType<typeof inspectBondMachineRollover>;
+        inspectBondMachineSettlement: (input: {
+            currentMachineArtifactPath?: string;
+            currentMachineArtifact?: SimplicityArtifact;
+            definitionPath?: string;
+            definitionValue?: BondDefinition;
+            previousIssuancePath?: string;
+            previousIssuanceValue?: BondIssuanceState;
+            nextIssuancePath?: string;
+            nextIssuanceValue?: BondIssuanceState;
+            nextSimfPath?: string;
+            nextArtifactPath?: string;
+            wallet: string;
+            signer: {
+                type: "schnorrPrivkeyHex";
+                privkeyHex: string;
+            };
+            feeSat?: number;
+            utxoPolicy?: "smallest_over" | "largest" | "newest";
+        }) => ReturnType<typeof inspectBondMachineSettlement>;
+        executeBondStateRollover: (input: {
+            currentArtifactPath?: string;
+            currentArtifact?: SimplicityArtifact;
+            definitionPath?: string;
+            definitionValue?: BondDefinition;
+            previousIssuancePath?: string;
+            previousIssuanceValue?: BondIssuanceState;
+            nextIssuancePath?: string;
+            nextIssuanceValue?: BondIssuanceState;
+            nextSimfPath?: string;
+            nextArtifactPath?: string;
+            wallet: string;
+            signer: {
+                type: "schnorrPrivkeyHex";
+                privkeyHex: string;
+            };
+            feeSat?: number;
+            utxoPolicy?: "smallest_over" | "largest" | "newest";
+            broadcast?: boolean;
+        }) => ReturnType<typeof executeBondStateRollover>;
+        executeBondMachineRollover: (input: {
+            currentArtifactPath?: string;
+            currentArtifact?: SimplicityArtifact;
+            definitionPath?: string;
+            definitionValue?: BondDefinition;
+            previousIssuancePath?: string;
+            previousIssuanceValue?: BondIssuanceState;
+            nextIssuancePath?: string;
+            nextIssuanceValue?: BondIssuanceState;
+            machineSimfPath?: string;
+            machineArtifactPath?: string;
+            wallet: string;
+            signer: {
+                type: "schnorrPrivkeyHex";
+                privkeyHex: string;
+            };
+            feeSat?: number;
+            utxoPolicy?: "smallest_over" | "largest" | "newest";
+            broadcast?: boolean;
+        }) => ReturnType<typeof executeBondMachineRollover>;
+        executeBondMachineSettlement: (input: {
+            currentMachineArtifactPath?: string;
+            currentMachineArtifact?: SimplicityArtifact;
+            definitionPath?: string;
+            definitionValue?: BondDefinition;
+            previousIssuancePath?: string;
+            previousIssuanceValue?: BondIssuanceState;
+            nextIssuancePath?: string;
+            nextIssuanceValue?: BondIssuanceState;
+            nextSimfPath?: string;
+            nextArtifactPath?: string;
+            wallet: string;
+            signer: {
+                type: "schnorrPrivkeyHex";
+                privkeyHex: string;
+            };
+            feeSat?: number;
+            utxoPolicy?: "smallest_over" | "largest" | "newest";
+            broadcast?: boolean;
+        }) => ReturnType<typeof executeBondMachineSettlement>;
+        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 +319,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,49 @@ 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),
+            redeemBond: async (input) => (0, bond_1.redeemBond)(this, input),
+            verifyBondTransition: async (input) => (0, bond_1.verifyBondTransition)(this, input),
+            buildBondRedemption: async (input) => (0, bond_1.buildBondRedemption)(this, input),
+            buildBondPayload: async (input) => (0, bond_1.buildBondPayload)(this, input),
+            buildBondTransitionPayload: async (input) => (0, bond_1.buildBondTransitionPayload)(this, input),
+            buildBondSettlementDescriptor: async (input) => (0, bond_1.buildBondSettlementDescriptor)(this, input),
+            verifyBondSettlementDescriptor: async (input) => (0, bond_1.verifyBondSettlementDescriptor)(this, input),
+            buildBondSettlementPayload: async (input) => (0, bond_1.buildBondSettlementPayload)(this, input),
+            buildBondRolloverPlan: async (input) => (0, bond_1.buildBondRolloverPlan)(this, input),
+            buildBondMachineRolloverPlan: async (input) => (0, bond_1.buildBondMachineRolloverPlan)(this, input),
+            buildBondMachineSettlementPlan: async (input) => (0, bond_1.buildBondMachineSettlementPlan)(this, input),
+            compileBondTransition: async (input) => (0, bond_1.compileBondTransition)(this, input),
+            compileBondRedemptionMachine: async (input) => (0, bond_1.compileBondRedemptionMachine)(this, input),
+            verifyBondRedemptionMachineArtifact: async (input) => (0, bond_1.verifyBondRedemptionMachineArtifact)(this, input),
+            inspectBondStateRollover: async (input) => (0, bond_1.inspectBondStateRollover)(this, input),
+            inspectBondMachineRollover: async (input) => (0, bond_1.inspectBondMachineRollover)(this, input),
+            inspectBondMachineSettlement: async (input) => (0, bond_1.inspectBondMachineSettlement)(this, input),
+            executeBondStateRollover: async (input) => (0, bond_1.executeBondStateRollover)(this, input),
+            executeBondMachineRollover: async (input) => (0, bond_1.executeBondMachineRollover)(this, input),
+            executeBondMachineSettlement: async (input) => (0, bond_1.executeBondMachineSettlement)(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 +67,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 +88,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);

package/dist/core/executor.js

@@ -213,6 +213,13 @@ function buildPsetSummary(decoded, meta) {
             trustMode: meta.definitionTrustMode ?? null,
             anchorMode: meta.definitionAnchorMode ?? null,
         },
+        state: {
+            type: meta.stateType ?? null,
+            id: meta.stateId ?? null,
+            hash: meta.stateHash ?? null,
+            trustMode: meta.stateTrustMode ?? null,
+            anchorMode: meta.stateAnchorMode ?? null,
+        },
         contract: {
             address: meta.contractAddress,
             cmr: meta.cmr,
@@ -304,6 +311,11 @@ async function buildExecutionState(config, artifact, input) {
         definitionHash: artifact.definition?.hash,
         definitionTrustMode: artifact.definition?.trustMode,
         definitionAnchorMode: artifact.definition?.anchorMode,
+        stateType: artifact.state?.stateType,
+        stateId: artifact.state?.stateId,
+        stateHash: artifact.state?.hash,
+        stateTrustMode: artifact.state?.trustMode,
+        stateAnchorMode: artifact.state?.anchorMode,
         expectedLiquidReceiver: input.expectedLiquidReceiver ?? recipientAddress,
         contractAddress: artifact.compiled.contractAddress,
         cmr: artifact.compiled.cmr,
@@ -460,6 +472,11 @@ async function executeGaslessContractCall(config, artifact, input) {
         definitionHash: artifact.definition?.hash,
         definitionTrustMode: artifact.definition?.trustMode,
         definitionAnchorMode: artifact.definition?.anchorMode,
+        stateType: artifact.state?.stateType,
+        stateId: artifact.state?.stateId,
+        stateHash: artifact.state?.hash,
+        stateTrustMode: artifact.state?.trustMode,
+        stateAnchorMode: artifact.state?.anchorMode,
         contractAddress: artifact.compiled.contractAddress,
         cmr: artifact.compiled.cmr,
         internalKey: artifact.compiled.internalKey,
@@ -653,6 +670,13 @@ async function executeRelayedGaslessContractCall(config, artifact, input, relaye
                 trustMode: artifact.definition?.trustMode ?? null,
                 anchorMode: artifact.definition?.anchorMode ?? null,
             },
+            state: {
+                type: artifact.state?.stateType ?? null,
+                id: artifact.state?.stateId ?? null,
+                hash: artifact.state?.hash ?? null,
+                trustMode: artifact.state?.trustMode ?? null,
+                anchorMode: artifact.state?.anchorMode ?? null,
+            },
             contract: {
                 address: request.detailedSummary.contract.contractAddress,
                 cmr: request.detailedSummary.contract.cmr,

package/dist/core/state.d.ts

@@ -0,0 +1,18 @@
+import { ArtifactStateMetadata, DefinitionAnchorMode, SimplicityArtifact, StateDocumentDescriptor, StateDocumentInput, StateVerificationResult } from "./types";
+export declare function loadStateInput(input: StateDocumentInput): Promise<StateDocumentDescriptor>;
+export declare function detectOnChainStateAnchor(simfSource: string): {
+    sourceVerified: boolean;
+    helper?: "nonzero-eq_256";
+    reason?: string;
+};
+export declare function buildArtifactStateMetadata(state: StateDocumentDescriptor, options?: {
+    anchorMode?: DefinitionAnchorMode;
+    onChainAnchor?: ArtifactStateMetadata["onChainAnchor"];
+}): ArtifactStateMetadata;
+export declare function verifyStateDescriptorAgainstArtifact(state: StateDocumentDescriptor, artifactState?: ArtifactStateMetadata, expectedType?: string, expectedId?: string): StateVerificationResult;
+export declare function verifyStateAgainstArtifact(input: {
+    artifact: SimplicityArtifact;
+    state: StateDocumentInput;
+    expectedType?: string;
+    expectedId?: string;
+}): Promise<StateVerificationResult>;