@hardkas/artifacts 0.1.0

package/dist/index.js

@@ -0,0 +1,1434 @@
+// src/constants.ts
+var HARDKAS_VERSION = "0.2.0-alpha";
+var ARTIFACT_SCHEMAS = {
+  LOCALNET_STATE: "hardkas.localnetState.v1",
+  REAL_ACCOUNT_STORE: "hardkas.realAccountStore.v1",
+  TX_PLAN: "hardkas.txPlan",
+  SIGNED_TX: "hardkas.signedTx",
+  TX_RECEIPT: "hardkas.txReceipt",
+  TX_TRACE: "hardkas.txTrace",
+  SNAPSHOT: "hardkas.snapshot",
+  IGRA_TX_PLAN: "hardkas.igraTxPlan.v1",
+  IGRA_SIGNED_TX: "hardkas.igraSignedTx.v1",
+  IGRA_TX_RECEIPT: "hardkas.igraTxReceipt.v1"
+};
+
+// src/igra-artifacts.ts
+function isIgraTxPlanArtifact(value) {
+  return validateIgraTxPlanArtifact(value).ok;
+}
+function validateIgraTxPlanArtifact(value) {
+  const errors = [];
+  if (typeof value !== "object" || value === null) return { ok: false, errors: ["Artifact must be an object"] };
+  const v = value;
+  if (v.schema !== ARTIFACT_SCHEMAS.IGRA_TX_PLAN) errors.push(`Invalid schema: expected '${ARTIFACT_SCHEMAS.IGRA_TX_PLAN}'`);
+  validateCommon(v, errors);
+  if (v.status !== "built") errors.push("Invalid status: expected 'built'");
+  if (typeof v.planId !== "string" || !v.planId) errors.push("Missing planId");
+  if (typeof v.chainId !== "number" || v.chainId <= 0) errors.push("Invalid chainId");
+  if (!v.request || typeof v.request !== "object") {
+    errors.push("Missing or invalid request object");
+  } else {
+    const r = v.request;
+    if (r.from) assertEvmAddress(r.from, "request.from", errors);
+    if (v.txType === "contract-deploy") {
+      if (r.to !== void 0 && r.to !== null) {
+        errors.push("request.to must be empty for contract-deploy");
+      }
+    } else {
+      if (r.to) assertEvmAddress(r.to, "request.to", errors);
+    }
+    assertHexData(r.data, "request.data", errors);
+    assertDecimalBigIntString(r.valueWei, "request.valueWei", errors);
+    if (r.gasLimit) assertDecimalBigIntString(r.gasLimit, "request.gasLimit", errors);
+    if (r.gasPriceWei) assertDecimalBigIntString(r.gasPriceWei, "request.gasPriceWei", errors);
+    if (r.nonce) assertDecimalBigIntString(r.nonce, "request.nonce", errors);
+  }
+  if (v.estimatedGas) assertDecimalBigIntString(v.estimatedGas, "estimatedGas", errors);
+  if (v.estimatedFeeWei) assertDecimalBigIntString(v.estimatedFeeWei, "estimatedFeeWei", errors);
+  return { ok: errors.length === 0, errors };
+}
+function assertValidIgraTxPlanArtifact(value) {
+  const result = validateIgraTxPlanArtifact(value);
+  if (!result.ok) {
+    throw new Error(`Invalid Igra tx plan artifact:
+${result.errors.map((e) => `- ${e}`).join("\n")}`);
+  }
+}
+function validateIgraSignedTxArtifact(value) {
+  const errors = [];
+  if (typeof value !== "object" || value === null) return { ok: false, errors: ["Artifact must be an object"] };
+  const v = value;
+  if (v.schema !== ARTIFACT_SCHEMAS.IGRA_SIGNED_TX) errors.push(`Invalid schema: expected '${ARTIFACT_SCHEMAS.IGRA_SIGNED_TX}'`);
+  validateCommon(v, errors);
+  if (v.status !== "signed") errors.push("Invalid status: expected 'signed'");
+  if (typeof v.signedId !== "string" || !v.signedId) errors.push("Missing signedId");
+  if (typeof v.sourcePlanId !== "string" || !v.sourcePlanId) errors.push("Missing sourcePlanId");
+  assertHexData(v.rawTransaction, "rawTransaction", errors);
+  if (v.txHash) assertEvmTxHash(v.txHash, "txHash", errors);
+  return { ok: errors.length === 0, errors };
+}
+function assertValidIgraSignedTxArtifact(value) {
+  const result = validateIgraSignedTxArtifact(value);
+  if (!result.ok) {
+    throw new Error(`Invalid Igra signed tx artifact:
+${result.errors.map((e) => `- ${e}`).join("\n")}`);
+  }
+}
+function validateIgraTxReceiptArtifact(value) {
+  const errors = [];
+  if (typeof value !== "object" || value === null) return { ok: false, errors: ["Artifact must be an object"] };
+  const v = value;
+  if (v.schema !== ARTIFACT_SCHEMAS.IGRA_TX_RECEIPT) errors.push(`Invalid schema: expected '${ARTIFACT_SCHEMAS.IGRA_TX_RECEIPT}'`);
+  validateCommon(v, errors);
+  if (!["submitted", "confirmed", "failed"].includes(v.status)) errors.push("Invalid status");
+  assertEvmTxHash(v.txHash, "txHash", errors);
+  if (typeof v.rpcUrl !== "string" || !v.rpcUrl) errors.push("Missing rpcUrl");
+  if (v.blockNumber) assertDecimalBigIntString(v.blockNumber, "blockNumber", errors);
+  return { ok: errors.length === 0, errors };
+}
+function assertValidIgraTxReceiptArtifact(value) {
+  const result = validateIgraTxReceiptArtifact(value);
+  if (!result.ok) {
+    throw new Error(`Invalid Igra tx receipt artifact:
+${result.errors.map((e) => `- ${e}`).join("\n")}`);
+  }
+}
+function validateCommon(v, errors) {
+  if (!v.hardkasVersion) errors.push("Missing hardkasVersion");
+  if (typeof v.networkId !== "string" || !v.networkId) errors.push("Missing networkId");
+  if (v.mode !== "l2-rpc") errors.push("Invalid mode: expected 'l2-rpc'");
+  if (!v.createdAt) errors.push("Missing createdAt");
+  if (typeof v.l2Network !== "string" || !v.l2Network) errors.push("Missing l2Network");
+}
+function assertDecimalBigIntString(value, field, errors) {
+  if (typeof value !== "string" || !/^\d+$/.test(value)) {
+    errors.push(`Invalid ${field}: must be a decimal bigint string`);
+  }
+}
+function assertHexData(value, field, errors) {
+  if (typeof value !== "string" || !/^0x([a-fA-F0-9]{2})*$/.test(value)) {
+    errors.push(`Invalid ${field}: must be a 0x-prefixed hex string`);
+  }
+}
+function assertEvmAddress(value, field, errors) {
+  if (typeof value !== "string" || !/^0x[a-fA-F0-9]{40}$/.test(value)) {
+    errors.push(`Invalid ${field}: must be a 0x-prefixed 40-character EVM address`);
+  }
+}
+function assertEvmTxHash(value, field, errors) {
+  if (typeof value !== "string" || !/^0x[a-fA-F0-9]{64}$/.test(value)) {
+    errors.push(`Invalid ${field}: must be a 0x-prefixed 64-character EVM transaction hash`);
+  }
+}
+function createIgraPlanId() {
+  return `igra-plan-${Date.now()}-${Math.floor(Math.random() * 1e3)}`;
+}
+function createIgraSignedId() {
+  return `igra-signed-${Date.now()}-${Math.floor(Math.random() * 1e3)}`;
+}
+function createIgraDeployPlanId() {
+  return `igradeploy_${Date.now()}_${Math.floor(Math.random() * 1e3)}`;
+}
+
+// src/canonical.ts
+import { createHash } from "crypto";
+function canonicalStringify(obj) {
+  if (obj === null || typeof obj !== "object") {
+    if (typeof obj === "bigint") {
+      return obj.toString();
+    }
+    return JSON.stringify(obj);
+  }
+  if (Array.isArray(obj)) {
+    return "[" + obj.map((item) => canonicalStringify(item)).join(",") + "]";
+  }
+  const sortedKeys = Object.keys(obj).filter(
+    (key) => key !== "contentHash" && key !== "artifactId" && key !== "lineage" && obj[key] !== void 0
+  ).sort();
+  const result = sortedKeys.map((key) => {
+    const value = obj[key];
+    return JSON.stringify(key) + ":" + canonicalStringify(value);
+  }).join(",");
+  return "{" + result + "}";
+}
+function calculateContentHash(obj) {
+  const canonical = canonicalStringify(obj);
+  return createHash("sha256").update(canonical).digest("hex");
+}
+
+// src/schemas.ts
+import { z } from "zod";
+import { kaspaNetworkIdSchema, executionModeSchema } from "@hardkas/core";
+var ARTIFACT_VERSION = "1.0.0-alpha";
+var ArtifactLineageSchema = z.object({
+  artifactId: z.string(),
+  lineageId: z.string(),
+  parentArtifactId: z.string().optional(),
+  rootArtifactId: z.string(),
+  sequence: z.number().optional()
+});
+var BaseArtifactSchema = z.object({
+  schema: z.string(),
+  hardkasVersion: z.string(),
+  version: z.literal(ARTIFACT_VERSION),
+  networkId: kaspaNetworkIdSchema,
+  mode: executionModeSchema,
+  contentHash: z.string().optional(),
+  createdAt: z.string().datetime(),
+  lineage: ArtifactLineageSchema.optional()
+});
+var AccountRefSchema = z.object({
+  address: z.string(),
+  accountName: z.string().optional(),
+  input: z.string().optional()
+});
+var TxPlanSchema = BaseArtifactSchema.extend({
+  schema: z.literal("hardkas.txPlan"),
+  networkId: kaspaNetworkIdSchema,
+  mode: executionModeSchema,
+  planId: z.string(),
+  from: AccountRefSchema,
+  to: AccountRefSchema,
+  amountSompi: z.string(),
+  estimatedFeeSompi: z.string(),
+  estimatedMass: z.string(),
+  inputs: z.array(z.object({
+    outpoint: z.object({
+      transactionId: z.string(),
+      index: z.number()
+    }),
+    amountSompi: z.string()
+  })),
+  outputs: z.array(z.object({
+    address: z.string(),
+    amountSompi: z.string()
+  })),
+  change: z.object({
+    address: z.string(),
+    amountSompi: z.string()
+  }).optional(),
+  rpcUrl: z.string().optional()
+});
+var DagContextSchema = z.object({
+  mode: z.enum(["linear", "dag-light"]),
+  sink: z.string(),
+  selectedParent: z.string().optional(),
+  branchId: z.string().optional(),
+  acceptedTxIds: z.array(z.string()).optional(),
+  displacedTxIds: z.array(z.string()).optional(),
+  conflictSet: z.array(z.object({
+    outpoint: z.string(),
+    winnerTxId: z.string(),
+    loserTxIds: z.array(z.string())
+  })).optional(),
+  nonSelectedContext: z.boolean().optional()
+});
+var LocalnetUtxoSchemaV2 = z.object({
+  id: z.string(),
+  address: z.string(),
+  amountSompi: z.string(),
+  spent: z.boolean(),
+  createdAtDaaScore: z.string()
+});
+var SnapshotSchema = BaseArtifactSchema.extend({
+  schema: z.literal("hardkas.snapshot"),
+  name: z.string().optional(),
+  daaScore: z.string(),
+  accountsHash: z.string().optional(),
+  utxoSetHash: z.string().optional(),
+  stateHash: z.string().optional(),
+  accounts: z.array(z.object({
+    name: z.string(),
+    address: z.string()
+  })),
+  utxos: z.array(LocalnetUtxoSchemaV2)
+});
+var TxReceiptSchema = BaseArtifactSchema.extend({
+  schema: z.literal("hardkas.txReceipt"),
+  txId: z.string(),
+  status: z.enum(["pending", "submitted", "accepted", "confirmed", "failed"]),
+  mode: executionModeSchema,
+  networkId: kaspaNetworkIdSchema,
+  from: AccountRefSchema,
+  to: AccountRefSchema,
+  amountSompi: z.string(),
+  feeSompi: z.string(),
+  mass: z.string().optional(),
+  changeSompi: z.string().optional(),
+  spentUtxoIds: z.array(z.string()).optional(),
+  createdUtxoIds: z.array(z.string()).optional(),
+  daaScore: z.string().optional(),
+  preStateHash: z.string().optional(),
+  postStateHash: z.string().optional(),
+  submittedAt: z.string().optional(),
+  confirmedAt: z.string().optional(),
+  dagContext: DagContextSchema.optional(),
+  tracePath: z.string().optional(),
+  rpcUrl: z.string().optional(),
+  sourceSignedId: z.string().optional(),
+  metadata: z.any().optional()
+});
+var SignedTxSchema = BaseArtifactSchema.extend({
+  schema: z.literal("hardkas.signedTx"),
+  status: z.literal("signed"),
+  signedId: z.string(),
+  sourcePlanId: z.string(),
+  networkId: kaspaNetworkIdSchema,
+  mode: executionModeSchema,
+  from: AccountRefSchema,
+  to: AccountRefSchema,
+  amountSompi: z.string(),
+  signedTransaction: z.object({
+    format: z.string(),
+    payload: z.string()
+  }),
+  txId: z.string().optional(),
+  metadata: z.any().optional()
+});
+var TxTraceSchema = BaseArtifactSchema.extend({
+  schema: z.literal("hardkas.txTrace"),
+  txId: z.string(),
+  networkId: kaspaNetworkIdSchema,
+  mode: executionModeSchema,
+  steps: z.array(z.object({
+    phase: z.string(),
+    status: z.string(),
+    timestamp: z.string().datetime(),
+    details: z.any().optional()
+  })),
+  dagContext: DagContextSchema.optional()
+});
+
+// src/verify.ts
+import fs from "fs";
+
+// src/feeVerify.ts
+import {
+  estimateTransactionMass
+} from "@hardkas/tx-builder";
+function recomputeMass(artifact) {
+  if (artifact.schema === "hardkas.txPlan") {
+    const plan = artifact;
+    const result = estimateTransactionMass({
+      inputCount: (plan.inputs || []).length,
+      outputs: plan.outputs || [],
+      hasChange: !!plan.change,
+      payloadBytes: 0
+      // Default for now
+    });
+    return result.mass;
+  }
+  if (artifact.schema === "hardkas.txReceipt") {
+    const receipt = artifact;
+    return BigInt(receipt.mass || 0);
+  }
+  return 0n;
+}
+function verifyFeeSemantics(artifact) {
+  const issues = [];
+  let artifactMass = 0n;
+  let artifactFee = 0n;
+  let inputTotal = 0n;
+  let outputTotal = 0n;
+  let feeRate = 1n;
+  if (artifact.schema === "hardkas.txPlan") {
+    const plan = artifact;
+    artifactMass = BigInt(plan.estimatedMass || 0);
+    artifactFee = BigInt(plan.estimatedFeeSompi || 0);
+    inputTotal = (plan.inputs || []).reduce((sum, i) => sum + BigInt(i.amountSompi || 0), 0n);
+    outputTotal = (plan.outputs || []).reduce((sum, o) => sum + BigInt(o.amountSompi || 0), 0n);
+    if (plan.change) outputTotal += BigInt(plan.change.amountSompi || 0);
+  } else if (artifact.schema === "hardkas.txReceipt") {
+    const receipt = artifact;
+    artifactMass = BigInt(receipt.mass || 0);
+    artifactFee = BigInt(receipt.feeSompi);
+    outputTotal = BigInt(receipt.amountSompi);
+  }
+  const recomputedMass = recomputeMass(artifact);
+  if (recomputedMass !== artifactMass && artifactMass !== 0n) {
+    issues.push(`Mass mismatch: artifact reports ${artifactMass}, recomputed ${recomputedMass}`);
+  }
+  const impliedFeeRate = artifactMass > 0n ? artifactFee / artifactMass : 1n;
+  const recomputedFee = recomputedMass * impliedFeeRate;
+  if (recomputedFee !== artifactFee && artifactFee !== 0n) {
+    issues.push(`Fee mismatch: artifact reports ${artifactFee}, recomputed ${recomputedFee} (at rate ${impliedFeeRate})`);
+  }
+  if (inputTotal > 0n && inputTotal < outputTotal + artifactFee) {
+    issues.push(`Economic violation: Total inputs (${inputTotal}) less than outputs + fee (${outputTotal + artifactFee})`);
+  }
+  if (artifactFee < 0n) {
+    issues.push("Economic violation: Negative fee detected");
+  }
+  if (artifact.schema === "hardkas.txPlan") {
+    const plan = artifact;
+    (plan.outputs || []).forEach((o, i) => {
+      if (BigInt(o.amountSompi || 0) < 600n) {
+        issues.push(`Dust output detected at index ${i}: ${o.amountSompi} sompi`);
+      }
+    });
+  }
+  return {
+    ok: issues.length === 0,
+    actualMass: artifactMass,
+    expectedMass: recomputedMass,
+    actualFeeSompi: artifactFee,
+    expectedFeeSompi: recomputedFee,
+    feeRateSompiPerMass: impliedFeeRate,
+    deltaSompi: artifactFee - recomputedFee,
+    issues
+  };
+}
+
+// src/lineage.ts
+function verifyLineage(artifact, parent) {
+  const issues = [];
+  const addIssue = (code, message, severity = "error") => {
+    issues.push({ code, severity, message });
+  };
+  const lineage = artifact.lineage;
+  if (!lineage) {
+    addIssue("MISSING_LINEAGE", "Artifact has no lineage metadata", "warning");
+    return {
+      ok: issues.every((i) => i.severity !== "error"),
+      issues
+    };
+  }
+  const isHash = (s) => typeof s === "string" && /^[0-9a-f]{64}$/i.test(s);
+  if (!lineage.artifactId || !lineage.lineageId || !lineage.rootArtifactId) {
+    addIssue("INVALID_LINEAGE_STRUCTURE", "Lineage block is missing required fields (artifactId, lineageId, or rootArtifactId)");
+  } else {
+    if (!isHash(lineage.artifactId)) addIssue("INVALID_LINEAGE_FORMAT", "artifactId must be a 64-char hex string");
+    if (!isHash(lineage.lineageId)) addIssue("INVALID_LINEAGE_FORMAT", "lineageId must be a 64-char hex string");
+    if (!isHash(lineage.rootArtifactId)) addIssue("INVALID_LINEAGE_FORMAT", "rootArtifactId must be a 64-char hex string");
+    if (lineage.parentArtifactId && !isHash(lineage.parentArtifactId)) {
+      addIssue("INVALID_LINEAGE_FORMAT", "parentArtifactId must be a 64-char hex string");
+    }
+  }
+  if (artifact.contentHash && lineage.artifactId !== artifact.contentHash) {
+    addIssue("LINEAGE_IDENTITY_MISMATCH", `Lineage artifactId (${lineage.artifactId}) does not match contentHash (${artifact.contentHash})`);
+  }
+  if (parent) {
+    const parentLineage = parent.lineage;
+    if (!parentLineage) {
+      addIssue("PARENT_MISSING_LINEAGE", "Parent artifact has no lineage metadata");
+    } else {
+      if (lineage.lineageId !== parentLineage.lineageId) {
+        addIssue("LINEAGE_ID_MISMATCH", `Lineage ID mismatch: expected ${parentLineage.lineageId}, got ${lineage.lineageId}`);
+      }
+      if (lineage.rootArtifactId !== parentLineage.rootArtifactId) {
+        addIssue("ROOT_ID_MISMATCH", `Root Artifact ID mismatch: expected ${parentLineage.rootArtifactId}, got ${lineage.rootArtifactId}`);
+      }
+      if (lineage.parentArtifactId && lineage.parentArtifactId !== parentLineage.artifactId) {
+        addIssue("PARENT_ID_MISMATCH", `Parent Artifact ID mismatch: expected ${parentLineage.artifactId}, got ${lineage.parentArtifactId}`);
+      }
+      if (lineage.sequence !== void 0 && parentLineage.sequence !== void 0) {
+        if (lineage.sequence <= parentLineage.sequence) {
+          addIssue("INVALID_SEQUENCE", `Invalid sequence: current (${lineage.sequence}) must be greater than parent (${parentLineage.sequence})`);
+        }
+      }
+    }
+    if (artifact.networkId !== parent.networkId) {
+      addIssue("NETWORK_CONTAMINATION", `Network mismatch: parent is ${parent.networkId}, current is ${artifact.networkId}`);
+    }
+    if (artifact.mode !== parent.mode) {
+      addIssue("MODE_CONTAMINATION", `Mode mismatch: parent is ${parent.mode}, current is ${artifact.mode}`);
+    }
+  }
+  if (parent) {
+    const validTransitions = {
+      "hardkas.snapshot": ["hardkas.txPlan"],
+      "hardkas.txPlan": ["hardkas.signedTx"],
+      "hardkas.signedTx": ["hardkas.txReceipt"]
+    };
+    const allowed = validTransitions[parent.schema] || [];
+    if (!allowed.includes(artifact.schema)) {
+      addIssue("INVALID_TRANSITION", `Invalid lineage transition: ${parent.schema} -> ${artifact.schema}`);
+    }
+  }
+  return {
+    ok: issues.every((i) => i.severity !== "error"),
+    issues
+  };
+}
+
+// src/verify.ts
+var defaultClock = {
+  now: () => Date.now()
+};
+function sortUtxosByOutpoint(utxos) {
+  return [...utxos].sort((a, b) => {
+    const aId = a.id || (a.outpoint ? `${a.outpoint.transactionId}:${a.outpoint.index}` : "");
+    const bId = b.id || (b.outpoint ? `${b.outpoint.transactionId}:${b.outpoint.index}` : "");
+    return aId.localeCompare(bId);
+  });
+}
+async function verifyArtifactIntegrity(artifactOrPath) {
+  const result = {
+    ok: false,
+    errors: [],
+    issues: []
+  };
+  const addError = (code, message, path3) => {
+    result.errors.push(message);
+    result.issues.push({ code, severity: "error", message, path: path3 });
+  };
+  let artifact;
+  try {
+    if (typeof artifactOrPath === "string") {
+      if (!fs.existsSync(artifactOrPath)) {
+        addError("FILE_NOT_FOUND", `File not found: ${artifactOrPath}`);
+        return result;
+      }
+      const content = fs.readFileSync(artifactOrPath, "utf-8");
+      artifact = JSON.parse(content);
+    } else {
+      artifact = artifactOrPath;
+    }
+    const v = artifact;
+    result.artifactType = v.schema;
+    result.version = v.version;
+    result.expectedHash = v.contentHash;
+    if (!v.version || !v.schema) {
+      addError("MISSING_METADATA", "Missing version or schema (Artifact might be v1 or legacy)");
+      return result;
+    }
+    const [currentMajor] = ARTIFACT_VERSION.split(".");
+    const [artifactMajor] = v.version.split(".");
+    if (currentMajor !== artifactMajor) {
+      addError("INCOMPATIBLE_VERSION", `Incompatible version: current system is v${currentMajor}, artifact is v${artifactMajor}`);
+      return result;
+    }
+    const actualHash = calculateContentHash(v);
+    result.actualHash = actualHash;
+    if (!v.contentHash) {
+      addError("MISSING_HASH", "Missing contentHash field");
+    } else if (actualHash !== v.contentHash) {
+      addError("HASH_MISMATCH", `Hash mismatch: expected ${v.contentHash}, got ${actualHash}`);
+    }
+    let schema;
+    switch (v.schema) {
+      case "hardkas.snapshot":
+        schema = SnapshotSchema;
+        break;
+      case "hardkas.txPlan":
+        schema = TxPlanSchema;
+        break;
+      case "hardkas.txReceipt":
+        schema = TxReceiptSchema;
+        break;
+      case "hardkas.txTrace":
+        schema = TxTraceSchema;
+        break;
+      case "hardkas.signedTx":
+        schema = SignedTxSchema;
+        break;
+    }
+    if (schema) {
+      const validation = schema.safeParse(v);
+      if (!validation.success) {
+        validation.error.issues.forEach((e) => {
+          const pathStr = e.path.join(".");
+          addError("SCHEMA_VALIDATION_ERROR", `${pathStr}: ${e.message}`, pathStr);
+        });
+      }
+    } else {
+      addError("UNSUPPORTED_SCHEMA", `Unsupported or unknown artifact schema: ${v.schema}`);
+    }
+    result.ok = result.issues.every((i) => i.severity !== "error" && i.severity !== "critical");
+    return result;
+  } catch (e) {
+    addError("UNEXPECTED_ERROR", `Integrity verification error: ${e.message}`);
+    return result;
+  }
+}
+function verifyArtifactSemantics(artifact, context = {}) {
+  const result = {
+    ok: true,
+    errors: [],
+    issues: []
+  };
+  const clock = context.clock || defaultClock;
+  const strict = context.strict || false;
+  const addIssue = (issue) => {
+    if (issue.severity === "error" || issue.severity === "critical") result.ok = false;
+    result.issues.push(issue);
+    if (issue.severity === "error" || issue.severity === "critical") result.errors.push(issue.message);
+  };
+  const feeAudit = verifyFeeSemantics(artifact);
+  if (!feeAudit.ok) {
+    feeAudit.issues.forEach((msg) => {
+      addIssue({
+        code: "ECONOMIC_VIOLATION",
+        severity: strict ? "error" : "warning",
+        message: msg
+      });
+    });
+  }
+  const v = artifact;
+  if (v.createdAt && typeof v.createdAt === "string") {
+    const created = new Date(v.createdAt).getTime();
+    const now = clock.now();
+    const ageHours = (now - created) / (1e3 * 60 * 60);
+    if (ageHours > 24 * 30) {
+      addIssue({
+        code: "STALE_ARTIFACT",
+        severity: "error",
+        message: `Artifact is too old (${Math.round(ageHours / 24)} days). High risk of DAA divergence.`
+      });
+    } else if (ageHours > 24) {
+      addIssue({
+        code: "STALE_ARTIFACT",
+        severity: "warning",
+        message: `Artifact is over 24h old. May be stale.`
+      });
+    }
+  }
+  if (v.schema === "hardkas.signedTx" && v.mode === "simulated") {
+  }
+  const lineageAudit = verifyLineage(v, context.parent);
+  if (!lineageAudit.ok || strict && !v.lineage) {
+    if (!v.lineage && strict) {
+      addIssue({
+        code: "MISSING_LINEAGE",
+        severity: "error",
+        message: "Strict mode requires formal lineage metadata."
+      });
+    }
+    lineageAudit.issues.forEach((issue) => {
+      addIssue({
+        ...issue,
+        severity: strict ? "error" : "warning"
+      });
+    });
+  }
+  if (strict) {
+    if (!v.workflowId) addIssue({ code: "MISSING_WORKFLOW_ID", severity: "error", message: "Strict mode requires workflowId" });
+    if (!v.assumptionLevel) addIssue({ code: "MISSING_ASSUMPTION_LEVEL", severity: "error", message: "Strict mode requires assumptionLevel" });
+    if (!v.executionMode) addIssue({ code: "MISSING_EXECUTION_MODE", severity: "error", message: "Strict mode requires executionMode" });
+  } else {
+    if (!v.workflowId) addIssue({ code: "MISSING_WORKFLOW_ID", severity: "warning", message: "Missing workflowId" });
+    if (!v.assumptionLevel) addIssue({ code: "MISSING_ASSUMPTION_LEVEL", severity: "warning", message: "Missing assumptionLevel" });
+    if (!v.executionMode) addIssue({ code: "MISSING_EXECUTION_MODE", severity: "warning", message: "Missing executionMode" });
+  }
+  const networkId = context.networkId || v.networkId;
+  const networkIdStr = networkId;
+  if (networkId && (v.from || v.to)) {
+    const from = v.from;
+    const to = v.to;
+    const addr = from?.address || to?.address;
+    const expectedPrefix = networkIdStr === "mainnet" ? "kaspa:" : networkIdStr.startsWith("testnet") ? "kaspatest:" : "kaspasim:";
+    if (addr && typeof addr === "string" && !addr.startsWith(expectedPrefix)) {
+      addIssue({
+        code: "NETWORK_ADDRESS_MISMATCH",
+        severity: "error",
+        message: `Network/Address mismatch: network is ${networkId} but address is ${addr}`
+      });
+    }
+  }
+  const lineage = v.lineage;
+  if (lineage) {
+    const { artifactId, parentArtifactId, rootArtifactId } = lineage;
+    if (artifactId === parentArtifactId) {
+      addIssue({
+        code: "LINEAGE_INCONSISTENCY",
+        severity: "error",
+        message: "Artifact cannot be its own parent."
+      });
+    }
+    if (!parentArtifactId && artifactId !== rootArtifactId) {
+      addIssue({
+        code: "LINEAGE_INCONSISTENCY",
+        severity: "error",
+        message: "Root artifactId must match artifactId when no parent exists."
+      });
+    }
+  }
+  return result;
+}
+async function verifyArtifactReplay(artifact, context = {}) {
+  return {
+    ok: true,
+    issues: [],
+    errors: []
+  };
+}
+var verifyArtifact = verifyArtifactIntegrity;
+var verifyArtifactFile = verifyArtifactIntegrity;
+
+// src/invariants/definitions.ts
+var HashInvariant = class {
+  id = "INVAR_HASH_MATCH";
+  description = "Artifact content hash must match payload";
+  async check(context) {
+    const { artifact } = context;
+    if (!artifact || typeof artifact !== "object") return [];
+    const v = artifact;
+    const contentHash = v.contentHash;
+    if (typeof contentHash !== "string") return [];
+    const actualHash = calculateContentHash(v);
+    if (actualHash !== contentHash) {
+      return [{
+        code: this.id,
+        severity: "error",
+        message: `Hash mismatch: expected ${contentHash}, got ${actualHash}`,
+        metadata: { artifactId: typeof v.artifactId === "string" ? v.artifactId : void 0 }
+      }];
+    }
+    return [];
+  }
+};
+var SchemaInvariant = class {
+  id = "INVAR_SCHEMA_SUPPORT";
+  description = "Artifact schema and version must be supported";
+  async check(context) {
+    const { artifact } = context;
+    if (!artifact || typeof artifact !== "object") return [];
+    const v = artifact;
+    const schema = v.schema;
+    const version = v.version;
+    if (typeof schema !== "string" || typeof version !== "string") {
+      return [{
+        code: this.id,
+        severity: "error",
+        message: "Artifact missing schema or version metadata"
+      }];
+    }
+    const supportedSchemas = Object.values(ARTIFACT_SCHEMAS);
+    if (!supportedSchemas.includes(schema)) {
+      return [{
+        code: this.id,
+        severity: "error",
+        message: `Unsupported schema: ${schema}`
+      }];
+    }
+    return [];
+  }
+};
+var BasicCorrelationInvariant = class {
+  id = "INVAR_BASIC_CORRELATION";
+  description = "Events must have workflowId and correlationId";
+  async check(context) {
+    const { event } = context;
+    if (!event) return [];
+    const violations = [];
+    if (!event.workflowId) {
+      violations.push({
+        code: this.id,
+        severity: "error",
+        message: "Missing workflowId in event",
+        metadata: { eventId: event.eventId }
+      });
+    }
+    if (!event.correlationId) {
+      violations.push({
+        code: this.id,
+        severity: "warning",
+        message: "Missing correlationId in event",
+        metadata: { eventId: event.eventId }
+      });
+    }
+    return violations;
+  }
+};
+var BasicLineageInvariant = class {
+  id = "INVAR_BASIC_LINEAGE";
+  description = "Parent artifact should be resolvable if specified";
+  async check(context) {
+    const { artifact, artifactStore } = context;
+    if (!artifact || typeof artifact !== "object") return [];
+    const v = artifact;
+    const lineage = v.lineage;
+    const parentArtifactId = lineage?.parentArtifactId;
+    if (!lineage || typeof parentArtifactId !== "string" || !artifactStore) return [];
+    const parent = await artifactStore.getArtifact(parentArtifactId);
+    if (!parent) {
+      return [{
+        code: this.id,
+        severity: "warning",
+        message: `Parent artifact ${parentArtifactId} not found in store`,
+        metadata: { childId: typeof v.artifactId === "string" ? v.artifactId : void 0 }
+      }];
+    }
+    return [];
+  }
+};
+var LifecycleInvariant = class {
+  id = "INVAR_LIFECYCLE_ORDER";
+  description = "Workflow events must follow valid lifecycle ordering";
+  async check() {
+    return [];
+  }
+};
+var NetworkInvariant = class {
+  id = "INVAR_NETWORK_PREFIX";
+  description = "Network ID must match address prefixes";
+  async check() {
+    return [];
+  }
+};
+var ReplayInvariant = class {
+  id = "INVAR_REPLAY_CONSISTENCY";
+  description = "Replay execution must produce consistent results";
+  async check() {
+    return [];
+  }
+};
+
+// src/invariants/watcher.ts
+import { createEventEnvelope } from "@hardkas/core";
+var InvariantWatcher = class {
+  invariants;
+  eventBus;
+  artifactStore;
+  unsubscribe = null;
+  constructor(options) {
+    this.invariants = options.invariants;
+    this.eventBus = options.eventBus;
+    this.artifactStore = options.artifactStore;
+  }
+  /**
+   * Starts watching for events.
+   */
+  start() {
+    if (this.unsubscribe) return;
+    this.unsubscribe = this.eventBus.subscribe(async (event) => {
+      if (event.domain === "integrity") return;
+      const context = {
+        event,
+        artifactStore: this.artifactStore ?? void 0
+      };
+      for (const invariant of this.invariants) {
+        try {
+          const violations = await invariant.check(context);
+          for (const violation of violations) {
+            this.emitViolation(event, violation);
+          }
+        } catch (e) {
+          console.error(`Invariant ${invariant.id} failed with error:`, e);
+        }
+      }
+    });
+  }
+  /**
+   * Stops watching and clears subscriptions.
+   */
+  stop() {
+    if (this.unsubscribe) {
+      this.unsubscribe();
+      this.unsubscribe = null;
+    }
+  }
+  /**
+   * Alias for stop().
+   */
+  dispose() {
+    this.stop();
+  }
+  emitViolation(sourceEvent, violation) {
+    const integrityEvent = createEventEnvelope({
+      kind: "integrity.violation",
+      domain: "integrity",
+      workflowId: sourceEvent.workflowId,
+      correlationId: sourceEvent.correlationId,
+      networkId: sourceEvent.networkId,
+      payload: {
+        violationCode: violation.code,
+        severity: violation.severity,
+        message: violation.message,
+        metadata: violation.metadata,
+        sourceEventId: sourceEvent.eventId
+      }
+    });
+    this.eventBus.emit(integrityEvent);
+  }
+};
+
+// src/migration.ts
+function migrateToCanonical(v1Artifact) {
+  if (v1Artifact.version === ARTIFACT_VERSION) {
+    return v1Artifact;
+  }
+  const v2Artifact = { ...v1Artifact };
+  if (v1Artifact.schema) {
+    v2Artifact.schema = v1Artifact.schema.replace(".v1", "");
+  }
+  v2Artifact.version = ARTIFACT_VERSION;
+  if (v2Artifact.schema === "hardkas.txPlan" && v1Artifact.selectedUtxos) {
+    v2Artifact.inputs = v1Artifact.selectedUtxos;
+    delete v2Artifact.selectedUtxos;
+  }
+  if (v2Artifact.schema === "hardkas.snapshot" && v1Artifact.utxos) {
+    v2Artifact.utxos = sortUtxosByOutpoint(v1Artifact.utxos);
+  }
+  if (!v2Artifact.hardkasVersion) {
+    v2Artifact.hardkasVersion = HARDKAS_VERSION;
+  }
+  if (!v2Artifact.createdAt) {
+    v2Artifact.createdAt = (/* @__PURE__ */ new Date()).toISOString();
+  }
+  v2Artifact.contentHash = calculateContentHash(v2Artifact);
+  return v2Artifact;
+}
+
+// src/io.ts
+import fs2 from "fs/promises";
+import path from "path";
+var bigIntReplacer = (_key, value) => typeof value === "bigint" ? value.toString() : value;
+async function writeArtifact(filePath, artifact) {
+  try {
+    const dir = path.dirname(filePath);
+    await fs2.mkdir(dir, { recursive: true });
+    const content = typeof artifact === "string" ? artifact : JSON.stringify(artifact, bigIntReplacer, 2) + "\n";
+    await fs2.writeFile(filePath, content, "utf-8");
+  } catch (error) {
+    throw new Error(`Failed to write artifact at ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+function getDefaultReceiptPath(txId, cwd = process.cwd()) {
+  return path.join(cwd, "artifacts", "receipts", `${txId}.json`);
+}
+async function readArtifact(filePath) {
+  try {
+    const content = await fs2.readFile(filePath, "utf-8");
+    return JSON.parse(content);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      throw new Error(`Artifact file not found at ${filePath}`);
+    }
+    throw new Error(`Failed to read/parse artifact at ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+async function readTxPlanArtifact(filePath) {
+  const result = await verifyArtifact(filePath);
+  if (!result.ok) {
+    throw new Error(`Invalid TxPlan artifact: ${result.errors.join(", ")}`);
+  }
+  const data = await readArtifact(filePath);
+  return data;
+}
+async function readSignedTxArtifact(filePath) {
+  const result = await verifyArtifact(filePath);
+  if (!result.ok) {
+    throw new Error(`Invalid SignedTx artifact: ${result.errors.join(", ")}`);
+  }
+  const data = await readArtifact(filePath);
+  return data;
+}
+async function readTxReceiptArtifact(filePath) {
+  const result = await verifyArtifact(filePath);
+  if (!result.ok) {
+    throw new Error(`Invalid TxReceipt artifact: ${result.errors.join(", ")}`);
+  }
+  const data = await readArtifact(filePath);
+  return data;
+}
+
+// src/format.ts
+import { formatSompi } from "@hardkas/core";
+function formatTxPlanArtifact(artifact) {
+  const lines = [];
+  lines.push("HardKAS Transaction Plan Artifact (v2)");
+  lines.push("======================================");
+  lines.push(`Plan ID:      ${artifact.planId}`);
+  lines.push(`Version:      ${artifact.version}`);
+  lines.push(`Hash:         ${artifact.contentHash}`);
+  lines.push(`Created:      ${artifact.createdAt}`);
+  lines.push("");
+  lines.push(`Network:      ${artifact.networkId}`);
+  lines.push(`Mode:         ${artifact.mode}`);
+  lines.push("");
+  lines.push(`From:         ${artifact.from.accountName || artifact.from.address}`);
+  lines.push(`To:           ${artifact.to.address}`);
+  lines.push(`Amount:       ${formatSompi(BigInt(artifact.amountSompi))}`);
+  lines.push("");
+  lines.push(`Inputs:       ${artifact.inputs.length}`);
+  lines.push(`Outputs:      ${artifact.outputs.length}`);
+  lines.push(`Fee:          ${formatSompi(BigInt(artifact.estimatedFeeSompi))}`);
+  lines.push(`Mass:         ${artifact.estimatedMass}`);
+  return lines.join("\n");
+}
+function formatTxReceiptArtifact(artifact) {
+  const lines = [];
+  lines.push("HardKAS Transaction Receipt Artifact (v2)");
+  lines.push("=========================================");
+  lines.push(`Tx ID:        ${artifact.txId}`);
+  lines.push(`Status:       ${artifact.status}`);
+  lines.push(`Hash:         ${artifact.contentHash}`);
+  lines.push("");
+  lines.push(`From:         ${artifact.from.address}`);
+  lines.push(`To:           ${artifact.to.address}`);
+  lines.push(`Amount:       ${formatSompi(BigInt(artifact.amountSompi))}`);
+  lines.push(`Fee:          ${formatSompi(BigInt(artifact.feeSompi))}`);
+  return lines.join("\n");
+}
+function formatSignedTxArtifact(artifact) {
+  const lines = [];
+  lines.push("HardKAS Signed Transaction Artifact (v2)");
+  lines.push("=========================================");
+  lines.push(`Signed ID:    ${artifact.signedId}`);
+  lines.push(`Plan ID:      ${artifact.sourcePlanId}`);
+  lines.push(`Hash:         ${artifact.contentHash}`);
+  lines.push("");
+  lines.push(`Network:      ${artifact.networkId}`);
+  lines.push(`Mode:         ${artifact.mode}`);
+  lines.push("");
+  lines.push(`From:         ${artifact.from.address}`);
+  lines.push(`To:           ${artifact.to.address}`);
+  lines.push(`Amount:       ${formatSompi(BigInt(artifact.amountSompi))}`);
+  lines.push("");
+  lines.push(`Format:       ${artifact.signedTransaction.format}`);
+  lines.push(`Tx ID:        ${artifact.txId || "unknown (pending broadcast)"}`);
+  return lines.join("\n");
+}
+
+// src/conversions.ts
+function utxoToArtifact(utxo) {
+  const artifact = {
+    outpoint: {
+      transactionId: utxo.outpoint.transactionId,
+      index: utxo.outpoint.index
+    },
+    address: utxo.address,
+    amountSompi: utxo.amountSompi.toString(),
+    scriptPublicKey: utxo.scriptPublicKey
+  };
+  if (utxo.blockDaaScore !== void 0) {
+    artifact.blockDaaScore = utxo.blockDaaScore.toString();
+  }
+  if (utxo.isCoinbase !== void 0) {
+    artifact.isCoinbase = utxo.isCoinbase;
+  }
+  return artifact;
+}
+function utxoFromArtifact(artifact) {
+  const utxo = {
+    outpoint: {
+      transactionId: artifact.outpoint.transactionId,
+      index: artifact.outpoint.index
+    },
+    address: artifact.address,
+    amountSompi: safeParseBigInt(artifact.amountSompi, "UtxoArtifact.amountSompi"),
+    scriptPublicKey: artifact.scriptPublicKey
+  };
+  if (artifact.blockDaaScore !== void 0) {
+    utxo.blockDaaScore = safeParseBigInt(artifact.blockDaaScore, "UtxoArtifact.blockDaaScore");
+  }
+  if (artifact.isCoinbase !== void 0) {
+    utxo.isCoinbase = artifact.isCoinbase;
+  }
+  return utxo;
+}
+function txOutputToArtifact(output) {
+  return {
+    address: output.address,
+    amountSompi: output.amountSompi.toString()
+  };
+}
+function txOutputFromArtifact(artifact) {
+  return {
+    address: artifact.address,
+    amountSompi: safeParseBigInt(artifact.amountSompi, "TxOutputArtifact.amountSompi")
+  };
+}
+function safeParseBigInt(val, context) {
+  try {
+    return BigInt(val);
+  } catch (e) {
+    throw new Error(`Invalid BigInt string in ${context}: '${val}'`);
+  }
+}
+
+// src/tx-plan.ts
+function createTxPlanArtifact(options) {
+  const artifact = {
+    schema: "hardkas.txPlan",
+    hardkasVersion: HARDKAS_VERSION,
+    version: ARTIFACT_VERSION,
+    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    networkId: options.networkId,
+    mode: options.mode,
+    planId: `plan-${Date.now()}-${Math.random().toString(36).slice(2, 7)}`,
+    from: {
+      address: options.from.address,
+      accountName: options.from.accountName,
+      input: options.from.input
+    },
+    to: {
+      address: options.to.address,
+      input: options.to.input
+    },
+    amountSompi: options.amountSompi.toString(),
+    estimatedFeeSompi: options.plan.estimatedFeeSompi.toString(),
+    estimatedMass: options.plan.estimatedMass.toString(),
+    inputs: options.plan.inputs.map((i) => ({
+      outpoint: {
+        transactionId: i.outpoint.transactionId,
+        index: i.outpoint.index
+      },
+      amountSompi: i.amountSompi.toString()
+    })),
+    outputs: options.plan.outputs.map((o) => ({
+      address: o.address,
+      amountSompi: o.amountSompi.toString()
+    })),
+    rpcUrl: options.rpcUrl
+  };
+  if (options.plan.change) {
+    artifact.change = {
+      address: options.plan.change.address,
+      amountSompi: options.plan.change.amountSompi.toString()
+    };
+  }
+  artifact.contentHash = calculateContentHash(artifact);
+  return artifact;
+}
+
+// src/signed-tx.ts
+function createSimulatedSignedTxArtifact(plan, payload) {
+  const artifact = {
+    schema: "hardkas.signedTx",
+    hardkasVersion: HARDKAS_VERSION,
+    version: ARTIFACT_VERSION,
+    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    status: "signed",
+    signedId: `signed-${Date.now()}`,
+    sourcePlanId: plan.planId,
+    networkId: plan.networkId,
+    mode: plan.mode,
+    from: { address: plan.from.address },
+    to: { address: plan.to.address },
+    amountSompi: plan.amountSompi,
+    txId: `simulated-${plan.planId}-${Date.now()}`,
+    signedTransaction: {
+      format: "simulated",
+      payload
+    }
+  };
+  artifact.contentHash = calculateContentHash(artifact);
+  return artifact;
+}
+function createSimulatedTxReceipt(plan, txId, extra) {
+  const artifact = {
+    schema: "hardkas.txReceipt",
+    hardkasVersion: HARDKAS_VERSION,
+    version: ARTIFACT_VERSION,
+    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    txId,
+    status: "accepted",
+    mode: "simulated",
+    networkId: plan.networkId,
+    from: { address: plan.from.address },
+    to: { address: plan.to.address },
+    amountSompi: plan.amountSompi,
+    feeSompi: plan.estimatedFeeSompi,
+    changeSompi: plan.change?.amountSompi,
+    spentUtxoIds: extra?.spentUtxoIds,
+    createdUtxoIds: extra?.createdUtxoIds,
+    daaScore: extra?.daaScore
+  };
+  artifact.contentHash = calculateContentHash(artifact);
+  return artifact;
+}
+function getBroadcastableSignedTransaction(artifact) {
+  if (!artifact.signedTransaction?.payload) {
+    throw new Error("Signed artifact is missing the raw transaction payload.");
+  }
+  return {
+    mode: artifact.mode || "rpc",
+    rawTransaction: artifact.signedTransaction.payload
+  };
+}
+
+// src/validate.ts
+function validateTxPlanArtifact(value) {
+  const errors = [];
+  if (typeof value !== "object" || value === null) return { ok: false, errors: ["Artifact must be an object"] };
+  const v = value;
+  if (v.schema !== ARTIFACT_SCHEMAS.TX_PLAN) errors.push(`Invalid schema: expected '${ARTIFACT_SCHEMAS.TX_PLAN}'`);
+  validateCommon2(v, errors);
+  if (typeof v.planId !== "string" || !v.planId) errors.push("Missing planId");
+  if (!v.from || typeof v.from.address !== "string") errors.push("Missing or invalid 'from' address");
+  if (!v.to || typeof v.to.address !== "string") errors.push("Missing or invalid 'to' address");
+  assertDecimalBigIntString2(v.amountSompi, "amountSompi", errors);
+  if (!Array.isArray(v.inputs)) errors.push("Missing or invalid 'inputs' array");
+  if (!Array.isArray(v.outputs)) errors.push("Missing or invalid 'outputs' array");
+  return { ok: errors.length === 0, errors };
+}
+function assertValidTxPlanArtifact(value) {
+  const result = validateTxPlanArtifact(value);
+  if (!result.ok) throw new Error(`Invalid tx plan artifact:
+${result.errors.map((e) => `- ${e}`).join("\n")}`);
+}
+function validateSignedTxArtifact(value) {
+  const errors = [];
+  if (typeof value !== "object" || value === null) return { ok: false, errors: ["Artifact must be an object"] };
+  const v = value;
+  if (v.schema !== ARTIFACT_SCHEMAS.SIGNED_TX) errors.push(`Invalid schema: expected '${ARTIFACT_SCHEMAS.SIGNED_TX}'`);
+  validateCommon2(v, errors);
+  if (v.status !== "signed") errors.push("Invalid status: expected 'signed'");
+  if (typeof v.signedId !== "string" || !v.signedId) errors.push("Missing signedId");
+  if (typeof v.sourcePlanId !== "string" || !v.sourcePlanId) errors.push("Missing sourcePlanId");
+  if (!v.signedTransaction) {
+    errors.push("Missing signedTransaction object");
+  } else {
+    if (!["kaspa-sdk", "hex", "simulated", "unknown"].includes(v.signedTransaction.format)) {
+      errors.push("Invalid signedTransaction.format");
+    }
+  }
+  return { ok: errors.length === 0, errors };
+}
+function assertValidSignedTxArtifact(value) {
+  const result = validateSignedTxArtifact(value);
+  if (!result.ok) throw new Error(`Invalid signed tx artifact:
+${result.errors.map((e) => `- ${e}`).join("\n")}`);
+}
+function validateTxReceiptArtifact(value) {
+  const errors = [];
+  if (typeof value !== "object" || value === null) return { ok: false, errors: ["Artifact must be an object"] };
+  const v = value;
+  if (v.schema !== ARTIFACT_SCHEMAS.TX_RECEIPT) errors.push(`Invalid schema: expected '${ARTIFACT_SCHEMAS.TX_RECEIPT}'`);
+  validateCommon2(v, errors);
+  if (!["submitted", "confirmed", "failed"].includes(v.status)) errors.push("Invalid status");
+  if (typeof v.txId !== "string" || !v.txId) errors.push("Missing txId");
+  assertDecimalBigIntString2(v.amountSompi, "amountSompi", errors);
+  assertDecimalBigIntString2(v.feeSompi, "feeSompi", errors);
+  return { ok: errors.length === 0, errors };
+}
+function assertValidTxReceiptArtifact(value) {
+  const result = validateTxReceiptArtifact(value);
+  if (!result.ok) throw new Error(`Invalid tx receipt artifact:
+${result.errors.map((e) => `- ${e}`).join("\n")}`);
+}
+function validateArtifact(data) {
+  if (!data || typeof data !== "object") return { ok: false, errors: ["Artifact must be an object"] };
+  const v = data;
+  const schema = v.schema;
+  switch (schema) {
+    case ARTIFACT_SCHEMAS.TX_PLAN:
+      return validateTxPlanArtifact(data);
+    case ARTIFACT_SCHEMAS.SIGNED_TX:
+      return validateSignedTxArtifact(data);
+    case ARTIFACT_SCHEMAS.TX_RECEIPT:
+      return validateTxReceiptArtifact(data);
+    case ARTIFACT_SCHEMAS.IGRA_TX_PLAN:
+      return validateIgraTxPlanArtifact(data);
+    case ARTIFACT_SCHEMAS.IGRA_SIGNED_TX:
+      return validateIgraSignedTxArtifact(data);
+    case ARTIFACT_SCHEMAS.IGRA_TX_RECEIPT:
+      return validateIgraTxReceiptArtifact(data);
+    default:
+      return { ok: false, errors: [`Unknown or unsupported artifact schema: ${schema}`] };
+  }
+}
+function validateCommon2(v, errors) {
+  if (!v.hardkasVersion) errors.push("Missing hardkasVersion");
+  if (typeof v.networkId !== "string" || !v.networkId) errors.push("Missing networkId");
+  if (!["simulated", "node", "rpc", "l2-rpc", "real"].includes(v.mode)) errors.push("Invalid mode");
+  if (!v.createdAt) errors.push("Missing createdAt");
+}
+function assertDecimalBigIntString2(value, field, errors) {
+  if (typeof value !== "string" || !/^\d+$/.test(value)) {
+    errors.push(`Invalid ${field}: must be a decimal bigint string`);
+  }
+}
+
+// src/explain.ts
+async function explainArtifact(artifact) {
+  const schema = artifact.schema || "unknown";
+  const type = schema.split(".")[1] || "unknown";
+  const integrity = await verifyArtifactIntegrity(artifact);
+  const semantic = verifyArtifactSemantics(artifact, { strict: true });
+  const lineage = verifyLineage(artifact);
+  const status = integrity.ok && semantic.ok && lineage.ok ? "valid" : "corrupted";
+  const explanation = {
+    summary: {
+      type: type.toUpperCase(),
+      version: artifact.version || "0.0.0",
+      network: artifact.networkId || "unknown",
+      mode: artifact.mode || "simulated",
+      createdAt: artifact.createdAt || "unknown",
+      status
+    },
+    identity: {
+      artifactId: artifact.lineage?.artifactId || "orphan",
+      contentHash: artifact.contentHash || "missing",
+      lineageId: artifact.lineage?.lineageId,
+      rootArtifactId: artifact.lineage?.rootArtifactId,
+      parentArtifactId: artifact.lineage?.parentArtifactId
+    },
+    security: {
+      strictOk: status === "valid",
+      issues: [
+        ...integrity.issues.map((i) => ({ ...i, severity: i.severity })),
+        ...semantic.issues.map((i) => ({ ...i, severity: i.severity })),
+        ...lineage.issues.map((i) => ({ ...i, severity: i.severity }))
+      ]
+    },
+    metadata: artifact.metadata || {}
+  };
+  if (type === "txPlan" || type === "signedTx" || type === "txReceipt") {
+    const feeAudit = verifyFeeSemantics(artifact);
+    let inputTotal = 0n;
+    let outputTotal = 0n;
+    let changeAmount = 0n;
+    if (type === "txPlan") {
+      const plan = artifact;
+      inputTotal = (plan.inputs || []).reduce((sum, i) => sum + BigInt(i.amountSompi || 0), 0n);
+      outputTotal = (plan.outputs || []).reduce((sum, o) => sum + BigInt(o.amountSompi || 0), 0n);
+      changeAmount = plan.change ? BigInt(plan.change.amountSompi || 0) : 0n;
+    }
+    explanation.economics = {
+      ok: feeAudit.ok,
+      mass: {
+        reported: feeAudit.actualMass,
+        recomputed: feeAudit.expectedMass,
+        delta: feeAudit.expectedMass - feeAudit.actualMass
+      },
+      fee: {
+        reported: feeAudit.actualFeeSompi,
+        recomputed: feeAudit.expectedFeeSompi,
+        delta: feeAudit.deltaSompi,
+        rate: feeAudit.feeRateSompiPerMass
+      },
+      balance: {
+        inputs: inputTotal,
+        outputs: outputTotal,
+        change: changeAmount,
+        impliedFee: inputTotal - outputTotal - changeAmount
+      }
+    };
+  }
+  return explanation;
+}
+
+// src/igra-io.ts
+import fs3 from "fs/promises";
+import path2 from "path";
+function getDefaultL2ReceiptsDir(cwd = process.cwd()) {
+  return path2.join(cwd, ".hardkas", "l2-receipts");
+}
+function getL2ReceiptPath(txHash, options) {
+  validateTxHash(txHash);
+  const dir = getDefaultL2ReceiptsDir(options?.cwd);
+  return path2.join(dir, `${txHash}.igra.receipt.json`);
+}
+async function saveIgraTxReceiptArtifact(receipt, options) {
+  assertValidIgraTxReceiptArtifact(receipt);
+  const filePath = getL2ReceiptPath(receipt.txHash, options);
+  await writeArtifact(filePath, receipt);
+  return filePath;
+}
+async function loadIgraTxReceiptArtifact(txHash, options) {
+  const filePath = getL2ReceiptPath(txHash, options);
+  const data = await readArtifact(filePath);
+  assertValidIgraTxReceiptArtifact(data);
+  return data;
+}
+async function listIgraTxReceiptArtifacts(options) {
+  const dir = getDefaultL2ReceiptsDir(options?.cwd);
+  try {
+    const files = await fs3.readdir(dir);
+    const receiptFiles = files.filter((f) => f.endsWith(".igra.receipt.json"));
+    const receipts = [];
+    for (const file of receiptFiles) {
+      try {
+        const data = await readArtifact(path2.join(dir, file));
+        if (data && typeof data === "object" && data.schema === "hardkas.igraTxReceipt.v1") {
+          receipts.push(data);
+        }
+      } catch (e) {
+      }
+    }
+    return receipts.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+  } catch (e) {
+    if (e.code === "ENOENT") return [];
+    throw e;
+  }
+}
+function validateTxHash(txHash) {
+  if (!/^0x[a-fA-F0-9]{64}$/.test(txHash)) {
+    throw new Error(`Invalid EVM txHash: must be a 0x-prefixed 64-character hex string. Got: ${txHash}`);
+  }
+}
+export {
+  ARTIFACT_SCHEMAS,
+  ARTIFACT_VERSION,
+  AccountRefSchema,
+  ArtifactLineageSchema,
+  BaseArtifactSchema,
+  BasicCorrelationInvariant,
+  BasicLineageInvariant,
+  DagContextSchema,
+  HARDKAS_VERSION,
+  HashInvariant,
+  InvariantWatcher,
+  LifecycleInvariant,
+  LocalnetUtxoSchemaV2,
+  NetworkInvariant,
+  ReplayInvariant,
+  SchemaInvariant,
+  SignedTxSchema,
+  SnapshotSchema,
+  TxPlanSchema,
+  TxReceiptSchema,
+  TxTraceSchema,
+  assertDecimalBigIntString,
+  assertEvmAddress,
+  assertEvmTxHash,
+  assertHexData,
+  assertValidIgraSignedTxArtifact,
+  assertValidIgraTxPlanArtifact,
+  assertValidIgraTxReceiptArtifact,
+  assertValidSignedTxArtifact,
+  assertValidTxPlanArtifact,
+  assertValidTxReceiptArtifact,
+  bigIntReplacer,
+  calculateContentHash,
+  canonicalStringify,
+  createIgraDeployPlanId,
+  createIgraPlanId,
+  createIgraSignedId,
+  createSimulatedSignedTxArtifact,
+  createSimulatedTxReceipt,
+  createTxPlanArtifact,
+  defaultClock,
+  explainArtifact,
+  formatSignedTxArtifact,
+  formatTxPlanArtifact,
+  formatTxReceiptArtifact,
+  getBroadcastableSignedTransaction,
+  getDefaultL2ReceiptsDir,
+  getDefaultReceiptPath,
+  getL2ReceiptPath,
+  isIgraTxPlanArtifact,
+  listIgraTxReceiptArtifacts,
+  loadIgraTxReceiptArtifact,
+  migrateToCanonical,
+  readArtifact,
+  readSignedTxArtifact,
+  readTxPlanArtifact,
+  readTxReceiptArtifact,
+  recomputeMass,
+  saveIgraTxReceiptArtifact,
+  sortUtxosByOutpoint,
+  txOutputFromArtifact,
+  txOutputToArtifact,
+  utxoFromArtifact,
+  utxoToArtifact,
+  validateArtifact,
+  validateIgraSignedTxArtifact,
+  validateIgraTxPlanArtifact,
+  validateIgraTxReceiptArtifact,
+  validateSignedTxArtifact,
+  validateTxPlanArtifact,
+  validateTxReceiptArtifact,
+  verifyArtifact,
+  verifyArtifactFile,
+  verifyArtifactIntegrity,
+  verifyArtifactReplay,
+  verifyArtifactSemantics,
+  verifyFeeSemantics,
+  verifyLineage,
+  writeArtifact
+};