@hazbase/simplicity 0.0.2 → 0.0.4

package/dist/core/state.js

@@ -0,0 +1,278 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadStateInput = loadStateInput;
+exports.detectOnChainStateAnchor = detectOnChainStateAnchor;
+exports.buildArtifactStateMetadata = buildArtifactStateMetadata;
+exports.verifyStateDescriptorAgainstArtifact = verifyStateDescriptorAgainstArtifact;
+exports.verifyStateAgainstArtifact = verifyStateAgainstArtifact;
+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";
+const DEFAULT_ANCHOR_MODE = "artifact-hash-anchor";
+const ZERO_HASH_256 = "0x0000000000000000000000000000000000000000000000000000000000000000";
+function stripComments(source) {
+    return source
+        .replace(/\/\*[\s\S]*?\*\//g, "")
+        .replace(/(^|[^:])\/\/.*$/gm, "$1");
+}
+function extractFunctionBody(source, functionName) {
+    const marker = `fn ${functionName}()`;
+    const start = source.indexOf(marker);
+    if (start === -1)
+        return null;
+    const braceStart = source.indexOf("{", start);
+    if (braceStart === -1)
+        return null;
+    let depth = 0;
+    for (let i = braceStart; i < source.length; i += 1) {
+        const char = source[i];
+        if (char === "{")
+            depth += 1;
+        if (char === "}") {
+            depth -= 1;
+            if (depth === 0) {
+                return source.slice(braceStart + 1, i);
+            }
+        }
+    }
+    return null;
+}
+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("State JSON must not contain undefined values");
+    }
+    if (value === null)
+        return;
+    if (typeof value === "bigint") {
+        throw new errors_1.DefinitionError("State JSON must not contain bigint values");
+    }
+    if (value instanceof Date) {
+        throw new errors_1.DefinitionError("State 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("State JSON must not contain circular references");
+        }
+        seen.add(objectValue);
+        for (const entry of Object.values(objectValue))
+            ensureSerializable(entry, seen);
+    }
+}
+async function resolveStateValue(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 state JSON at ${sourcePath}`, error);
+        }
+    }
+    return { value: input.value };
+}
+async function loadStateInput(input) {
+    const stateType = assertNonEmpty(input.type, "state.type");
+    const stateId = assertNonEmpty(input.id, "state.id");
+    const schemaVersion = assertNonEmpty(input.schemaVersion ?? DEFAULT_SCHEMA_VERSION, "state.schemaVersion");
+    const { value, sourcePath } = await resolveStateValue(input);
+    ensureSerializable(value);
+    const canonicalJson = (0, summary_1.stableStringify)(value);
+    return {
+        stateType,
+        stateId,
+        schemaVersion,
+        canonicalJson,
+        hash: (0, summary_1.sha256HexUtf8)(canonicalJson),
+        sourcePath,
+    };
+}
+function detectOnChainStateAnchor(simfSource) {
+    const source = stripComments(simfSource.replace(/\r\n/g, "\n"));
+    if (!source.includes("{{STATE_HASH}}")) {
+        return { sourceVerified: false, reason: "STATE_HASH placeholder is missing" };
+    }
+    const helperBody = extractFunctionBody(source, "require_state_anchor");
+    if (!helperBody) {
+        return { sourceVerified: false, reason: "Required state anchor helper function is missing" };
+    }
+    if (!helperBody.includes("let anchored_state_hash: u256 = 0x{{STATE_HASH}};")) {
+        return { sourceVerified: false, reason: "Required anchored_state_hash assignment is missing" };
+    }
+    if (!helperBody.includes(`let zero_hash: u256 = ${ZERO_HASH_256};`)) {
+        return { sourceVerified: false, reason: "Required zero_hash assignment is missing" };
+    }
+    if (!helperBody.includes("assert!(not(jet::eq_256(anchored_state_hash, zero_hash)));")) {
+        return { sourceVerified: false, reason: "Required eq_256 assertion is missing" };
+    }
+    const mainBody = extractFunctionBody(source, "main");
+    if (!mainBody) {
+        return { sourceVerified: false, reason: "main function is missing" };
+    }
+    if (!mainBody.includes("require_state_anchor();")) {
+        return { sourceVerified: false, reason: "require_state_anchor() is not called from main" };
+    }
+    return { sourceVerified: true, helper: "nonzero-eq_256" };
+}
+function buildArtifactStateMetadata(state, options) {
+    return {
+        stateType: state.stateType,
+        stateId: state.stateId,
+        schemaVersion: state.schemaVersion,
+        hash: state.hash,
+        trustMode: "hash-anchor",
+        anchorMode: options?.anchorMode ?? DEFAULT_ANCHOR_MODE,
+        onChainAnchor: options?.onChainAnchor,
+    };
+}
+function verifyStateDescriptorAgainstArtifact(state, artifactState, expectedType, expectedId) {
+    const noStateTrust = {
+        artifactMatch: false,
+        onChainAnchorPresent: false,
+        onChainAnchorVerified: false,
+        effectiveMode: "none",
+    };
+    if (expectedType && expectedType !== state.stateType) {
+        return {
+            ok: false,
+            reason: `State type mismatch: expected=${expectedType} actual=${state.stateType}`,
+            state,
+            artifactState,
+            trust: noStateTrust,
+        };
+    }
+    if (expectedId && expectedId !== state.stateId) {
+        return {
+            ok: false,
+            reason: `State id mismatch: expected=${expectedId} actual=${state.stateId}`,
+            state,
+            artifactState,
+            trust: noStateTrust,
+        };
+    }
+    if (!artifactState) {
+        return {
+            ok: false,
+            reason: "Artifact does not contain state metadata",
+            state,
+            trust: noStateTrust,
+        };
+    }
+    const trust = {
+        artifactMatch: false,
+        onChainAnchorPresent: artifactState.anchorMode === "on-chain-constant-committed",
+        onChainAnchorVerified: false,
+        effectiveMode: artifactState.anchorMode,
+    };
+    if (artifactState.stateType !== state.stateType) {
+        return {
+            ok: false,
+            reason: `State type mismatch: artifact=${artifactState.stateType} actual=${state.stateType}`,
+            state,
+            artifactState,
+            trust,
+        };
+    }
+    if (artifactState.stateId !== state.stateId) {
+        return {
+            ok: false,
+            reason: `State id mismatch: artifact=${artifactState.stateId} actual=${state.stateId}`,
+            state,
+            artifactState,
+            trust,
+        };
+    }
+    if (artifactState.schemaVersion !== state.schemaVersion) {
+        return {
+            ok: false,
+            reason: `State schemaVersion mismatch: artifact=${artifactState.schemaVersion} actual=${state.schemaVersion}`,
+            state,
+            artifactState,
+            trust,
+        };
+    }
+    if (artifactState.hash !== state.hash) {
+        return {
+            ok: false,
+            reason: `State hash mismatch: artifact=${artifactState.hash} actual=${state.hash}`,
+            state,
+            artifactState,
+            trust,
+        };
+    }
+    return {
+        ok: true,
+        state,
+        artifactState,
+        trust: {
+            ...trust,
+            artifactMatch: true,
+        },
+    };
+}
+async function resolveStateTrust(artifact, baseTrust) {
+    if (!artifact.state) {
+        return {
+            artifactMatch: false,
+            onChainAnchorPresent: false,
+            onChainAnchorVerified: false,
+            effectiveMode: "none",
+        };
+    }
+    if (artifact.state.anchorMode !== "on-chain-constant-committed") {
+        return baseTrust;
+    }
+    const sourcePath = artifact.source.mode === "file" ? artifact.source.simfPath : undefined;
+    if (!sourcePath) {
+        return {
+            ...baseTrust,
+            onChainAnchorPresent: true,
+            onChainAnchorVerified: false,
+        };
+    }
+    try {
+        const source = await (0, promises_1.readFile)(sourcePath, "utf8");
+        const detection = detectOnChainStateAnchor(source);
+        return {
+            ...baseTrust,
+            onChainAnchorPresent: true,
+            onChainAnchorVerified: detection.sourceVerified,
+        };
+    }
+    catch {
+        return {
+            ...baseTrust,
+            onChainAnchorPresent: true,
+            onChainAnchorVerified: false,
+        };
+    }
+}
+async function verifyStateAgainstArtifact(input) {
+    const state = await loadStateInput(input.state);
+    const base = verifyStateDescriptorAgainstArtifact(state, input.artifact.state, input.expectedType, input.expectedId);
+    const trust = await resolveStateTrust(input.artifact, base.trust);
+    return {
+        ...base,
+        trust,
+    };
+}

package/dist/core/types.d.ts

@@ -1,6 +1,7 @@
 export type NetworkName = "liquidtestnet" | "liquidv1" | "regtest";
 export type UtxoPolicy = "smallest_over" | "largest" | "newest";
 export type DefinitionTrustMode = "hash-anchor";
+export type DefinitionAnchorMode = "artifact-hash-anchor" | "on-chain-constant-committed";
 export interface RpcConfig {
     url: string;
     username: string;
@@ -70,6 +71,7 @@ export interface SimplicityArtifact {
         notes: string | null;
     };
     definition?: ArtifactDefinitionMetadata;
+    state?: ArtifactStateMetadata;
     legacy?: {
         simfTemplatePath?: string;
         params?: {
@@ -84,12 +86,14 @@ export interface CompileFromFileInput {
     templateVars?: Record<string, string | number>;
     artifactPath?: string;
     definition?: DefinitionInput;
+    state?: StateDocumentInput;
 }
 export interface CompileFromPresetInput {
     preset: string;
     params: Record<string, string | number>;
     artifactPath?: string;
     definition?: DefinitionInput;
+    state?: StateDocumentInput;
 }
 export interface DefinitionInput {
     type: string;
@@ -97,6 +101,7 @@ export interface DefinitionInput {
     schemaVersion?: string;
     jsonPath?: string;
     value?: unknown;
+    anchorMode?: DefinitionAnchorMode;
 }
 export interface DefinitionDescriptor {
     definitionType: string;
@@ -106,12 +111,47 @@ export interface DefinitionDescriptor {
     hash: string;
     sourcePath?: string;
 }
+export interface StateDocumentInput {
+    type: string;
+    id: string;
+    schemaVersion?: string;
+    jsonPath?: string;
+    value?: unknown;
+    anchorMode?: DefinitionAnchorMode;
+}
+export interface StateDocumentDescriptor {
+    stateType: string;
+    stateId: string;
+    schemaVersion: string;
+    canonicalJson: string;
+    hash: string;
+    sourcePath?: string;
+}
 export interface ArtifactDefinitionMetadata {
     definitionType: string;
     definitionId: string;
     schemaVersion: string;
     hash: string;
     trustMode: DefinitionTrustMode;
+    anchorMode: DefinitionAnchorMode;
+    onChainAnchor?: {
+        helper: "nonzero-eq_256";
+        templateVar: "DEFINITION_HASH";
+        sourceVerified: boolean;
+    };
+}
+export interface ArtifactStateMetadata {
+    stateType: string;
+    stateId: string;
+    schemaVersion: string;
+    hash: string;
+    trustMode: DefinitionTrustMode;
+    anchorMode: DefinitionAnchorMode;
+    onChainAnchor?: {
+        helper: "nonzero-eq_256";
+        templateVar: "STATE_HASH";
+        sourceVerified: boolean;
+    };
 }
 export interface DeploymentInfo {
     contractAddress: string;
@@ -182,6 +222,14 @@ export interface PsetSummary {
         id: string | null;
         hash: string | null;
         trustMode: DefinitionTrustMode | null;
+        anchorMode: DefinitionAnchorMode | null;
+    };
+    state?: {
+        type: string | null;
+        id: string | null;
+        hash: string | null;
+        trustMode: DefinitionTrustMode | null;
+        anchorMode: DefinitionAnchorMode | null;
     };
     contract: {
         address: string;
@@ -255,6 +303,46 @@ export interface DefinitionVerificationResult {
     reason?: string;
     definition: DefinitionDescriptor;
     artifactDefinition?: ArtifactDefinitionMetadata;
+    trust: {
+        artifactMatch: boolean;
+        onChainAnchorPresent: boolean;
+        onChainAnchorVerified: boolean;
+        effectiveMode: "none" | DefinitionAnchorMode;
+    };
+}
+export interface StateVerificationResult {
+    ok: boolean;
+    reason?: string;
+    state: StateDocumentDescriptor;
+    artifactState?: ArtifactStateMetadata;
+    trust: {
+        artifactMatch: boolean;
+        onChainAnchorPresent: boolean;
+        onChainAnchorVerified: boolean;
+        effectiveMode: "none" | DefinitionAnchorMode;
+    };
+}
+export interface BondDefinition {
+    bondId: string;
+    issuer: string;
+    faceValue: number;
+    couponBps: number;
+    issueDate: string;
+    maturityDate: number;
+    currencyAssetId: string;
+    controllerXonly: string;
+}
+export interface BondIssuanceState {
+    issuanceId: string;
+    bondId: string;
+    issuerEntityId: string;
+    issuedPrincipal: number;
+    outstandingPrincipal: number;
+    redeemedPrincipal: number;
+    currencyAssetId: string;
+    controllerXonly: string;
+    issuedAt: string;
+    status: "ISSUED" | "REDEEMED";
 }
 export interface WaitForFundingInput {
     minAmountSat?: number;

package/dist/domain/bond.d.ts

@@ -0,0 +1,59 @@
+import type { SimplicityClient } from "../client/SimplicityClient";
+import { BondDefinition, BondIssuanceState, SimplicityArtifact } from "../core/types";
+export declare function defineBond(sdk: SimplicityClient, input: {
+    definitionPath?: string;
+    definitionValue?: BondDefinition;
+    issuancePath?: string;
+    issuanceValue?: BondIssuanceState;
+    simfPath?: string;
+    artifactPath?: string;
+}): Promise<import("..").CompiledContract>;
+export declare function verifyBond(sdk: SimplicityClient, input: {
+    artifactPath?: string;
+    artifact?: SimplicityArtifact;
+    definitionPath?: string;
+    definitionValue?: BondDefinition;
+    issuancePath?: string;
+    issuanceValue?: BondIssuanceState;
+}): Promise<{
+    artifact: SimplicityArtifact;
+    definition: import("../core/types").DefinitionVerificationResult;
+    issuance: import("../core/types").StateVerificationResult;
+    crossChecks: {
+        bondIdMatch: boolean;
+        currencyMatch: boolean;
+        controllerMatch: boolean;
+        principalInvariantValid: boolean;
+    };
+}>;
+export declare function loadBond(sdk: SimplicityClient, input: {
+    artifactPath: string;
+    definitionPath?: string;
+    definitionValue?: BondDefinition;
+    issuancePath?: string;
+    issuanceValue?: BondIssuanceState;
+}): Promise<{
+    artifact: SimplicityArtifact;
+    definition: import("../core/types").DefinitionVerificationResult;
+    issuance: import("../core/types").StateVerificationResult;
+    crossChecks: {
+        bondIdMatch: boolean;
+        currencyMatch: boolean;
+        controllerMatch: boolean;
+        principalInvariantValid: boolean;
+    };
+    trust: {
+        definitionTrust: {
+            artifactMatch: boolean;
+            onChainAnchorPresent: boolean;
+            onChainAnchorVerified: boolean;
+            effectiveMode: "none" | import("../core/types").DefinitionAnchorMode;
+        };
+        issuanceTrust: {
+            artifactMatch: boolean;
+            onChainAnchorPresent: boolean;
+            onChainAnchorVerified: boolean;
+            effectiveMode: "none" | import("../core/types").DefinitionAnchorMode;
+        };
+    };
+}>;

package/dist/domain/bond.js

@@ -0,0 +1,128 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineBond = defineBond;
+exports.verifyBond = verifyBond;
+exports.loadBond = loadBond;
+const node_path_1 = __importDefault(require("node:path"));
+const bondValidation_1 = require("./bondValidation");
+function resolveValueOrPath(options) {
+    if (options.pathValue)
+        return { jsonPath: options.pathValue };
+    if (options.objectValue !== undefined)
+        return { value: options.objectValue };
+    return {};
+}
+async function defineBond(sdk, input) {
+    const definitionSource = resolveValueOrPath({
+        pathValue: input.definitionPath,
+        objectValue: input.definitionValue,
+    });
+    const issuanceSource = resolveValueOrPath({
+        pathValue: input.issuancePath,
+        objectValue: input.issuanceValue,
+    });
+    const initialDefinitionDescriptor = await sdk.loadDefinition({
+        type: "bond",
+        id: input.definitionValue?.bondId ?? "BOND-2026-001",
+        ...definitionSource,
+    });
+    const definition = (0, bondValidation_1.validateBondDefinition)(JSON.parse(initialDefinitionDescriptor.canonicalJson));
+    const definitionDescriptor = await sdk.loadDefinition({
+        type: "bond",
+        id: definition.bondId,
+        ...(definitionSource.jsonPath ? { jsonPath: definitionSource.jsonPath } : { value: definition }),
+    });
+    const initialStateDescriptor = await sdk.loadStateDocument({
+        type: "bond-issuance",
+        id: input.issuanceValue?.issuanceId ?? "BOND-2026-001-ISSUE-1",
+        ...issuanceSource,
+    });
+    const issuance = (0, bondValidation_1.validateBondIssuanceState)(JSON.parse(initialStateDescriptor.canonicalJson));
+    const stateDescriptor = await sdk.loadStateDocument({
+        type: "bond-issuance",
+        id: issuance.issuanceId,
+        ...(issuanceSource.jsonPath ? { jsonPath: issuanceSource.jsonPath } : { value: issuance }),
+    });
+    (0, bondValidation_1.validateBondCrossChecks)(definition, issuance);
+    const simfPath = input.simfPath ?? node_path_1.default.resolve(process.cwd(), "docs/definitions/bond-issuance-anchor.simf");
+    return sdk.compileFromFile({
+        simfPath,
+        templateVars: {
+            MIN_HEIGHT: definition.maturityDate,
+            SIGNER_XONLY: definition.controllerXonly,
+        },
+        definition: {
+            type: definitionDescriptor.definitionType,
+            id: definitionDescriptor.definitionId,
+            schemaVersion: definitionDescriptor.schemaVersion,
+            ...(definitionDescriptor.sourcePath ? { jsonPath: definitionDescriptor.sourcePath } : { value: definition }),
+            anchorMode: "on-chain-constant-committed",
+        },
+        state: {
+            type: stateDescriptor.stateType,
+            id: stateDescriptor.stateId,
+            schemaVersion: stateDescriptor.schemaVersion,
+            ...(stateDescriptor.sourcePath ? { jsonPath: stateDescriptor.sourcePath } : { value: issuance }),
+            anchorMode: "on-chain-constant-committed",
+        },
+        artifactPath: input.artifactPath,
+    });
+}
+async function verifyBond(sdk, input) {
+    const artifact = input.artifact ?? (input.artifactPath ? (await sdk.loadArtifact(input.artifactPath)).artifact : undefined);
+    if (!artifact) {
+        throw new Error("artifactPath or artifact is required");
+    }
+    const definitionSource = resolveValueOrPath({
+        pathValue: input.definitionPath,
+        objectValue: input.definitionValue,
+    });
+    const issuanceSource = resolveValueOrPath({
+        pathValue: input.issuancePath,
+        objectValue: input.issuanceValue,
+    });
+    const definition = await sdk.verifyDefinitionAgainstArtifact({
+        artifact,
+        type: "bond",
+        id: artifact.definition?.definitionId,
+        ...definitionSource,
+    });
+    const issuance = await sdk.verifyStateAgainstArtifact({
+        artifact,
+        type: "bond-issuance",
+        id: artifact.state?.stateId,
+        ...issuanceSource,
+    });
+    const definitionValue = (0, bondValidation_1.validateBondDefinition)(JSON.parse(definition.definition.canonicalJson));
+    const issuanceValue = (0, bondValidation_1.validateBondIssuanceState)(JSON.parse(issuance.state.canonicalJson));
+    const crossChecks = (0, bondValidation_1.validateBondCrossChecks)(definitionValue, issuanceValue);
+    return {
+        artifact,
+        definition,
+        issuance,
+        crossChecks,
+    };
+}
+async function loadBond(sdk, input) {
+    const compiled = await sdk.loadArtifact(input.artifactPath);
+    const verification = await verifyBond(sdk, {
+        artifact: compiled.artifact,
+        definitionPath: input.definitionPath,
+        definitionValue: input.definitionValue,
+        issuancePath: input.issuancePath,
+        issuanceValue: input.issuanceValue,
+    });
+    return {
+        artifact: compiled.artifact,
+        definition: verification.definition,
+        issuance: verification.issuance,
+        crossChecks: verification.crossChecks,
+        trust: {
+            definitionTrust: verification.definition.trust,
+            issuanceTrust: verification.issuance.trust,
+        },
+    };
+}

package/dist/domain/bondValidation.d.ts

@@ -0,0 +1,9 @@
+import { BondDefinition, BondIssuanceState } from "../core/types";
+export declare function validateBondDefinition(value: unknown): BondDefinition;
+export declare function validateBondIssuanceState(value: unknown): BondIssuanceState;
+export declare function validateBondCrossChecks(definition: BondDefinition, issuance: BondIssuanceState): {
+    bondIdMatch: boolean;
+    currencyMatch: boolean;
+    controllerMatch: boolean;
+    principalInvariantValid: boolean;
+};