@hardkas/accounts 0.8.16-alpha → 0.8.19-alpha

package/dist/index.js

@@ -113,9 +113,33 @@ function validateAddressPrefix(address) {
   const validPrefixes = ["kaspa:", "kaspatest:", "kaspasim:"];
   const hasValidPrefix = validPrefixes.some((prefix) => address.startsWith(prefix));
   if (!hasValidPrefix) {
-    throw new Error(
-      `Invalid address '${address}'. Must start with one of: ${validPrefixes.join(", ")}`
-    );
+    const err = new Error(`HARDKAS_INVALID_ADDRESS: Invalid address '${address}'. Must start with one of: ${validPrefixes.join(", ")}`);
+    err.code = "HARDKAS_INVALID_ADDRESS";
+    throw err;
+  }
+}
+function validateAddressNetwork(address, networkId, allowMainnet) {
+  if (address.startsWith("kaspa:sim_")) {
+    return;
+  }
+  validateAddressPrefix(address);
+  let expectedPrefix;
+  if (networkId === "mainnet") {
+    expectedPrefix = "kaspa:";
+  } else if (networkId === "testnet-10" || networkId === "testnet-11") {
+    expectedPrefix = "kaspatest:";
+  } else if (networkId === "simnet" || networkId === "devnet" || networkId === "simulated") {
+    expectedPrefix = "kaspasim:";
+  } else {
+    return;
+  }
+  if (expectedPrefix !== "kaspa:" && address.startsWith("kaspa:") && allowMainnet) {
+    return;
+  }
+  if (!address.startsWith(expectedPrefix)) {
+    const err = new Error(`NETWORK_ADDRESS_MISMATCH: Address '${address}' does not match the expected prefix '${expectedPrefix}' for network '${networkId}'.`);
+    err.code = "NETWORK_ADDRESS_MISMATCH";
+    throw err;
   }
 }
 function importRealDevAccount(store, account) {
@@ -194,7 +218,8 @@ function resolveHardkasAccount(options) {
         return {
           name: alias,
           kind: "kaspa-private-key",
-          address: keystore.metadata?.address
+          address: keystore.metadata?.address,
+          keystorePath: devAccountPath
         };
       }
     } catch (e) {
@@ -259,7 +284,8 @@ function listHardkasAccounts(config) {
             accounts.set(name, {
               name,
               kind: "kaspa-private-key",
-              address: keystore.payload?.address || keystore.metadata?.address
+              address: keystore.payload?.address || keystore.metadata?.address,
+              keystorePath: path2.join(devAccountsDir, file)
             });
           }
         } catch (e) {
@@ -293,8 +319,9 @@ function listHardkasAccounts(config) {
             accounts.set(name, {
               name,
               kind: "kaspa-private-key",
-              address: keystore.payload?.address || keystore.metadata?.address
+              address: keystore.payload?.address || keystore.metadata?.address,
               // Payloads are encrypted, but address might be in metadata
+              keystorePath: path2.join(keystoreDir, file)
             });
           }
         } catch (e) {
@@ -478,319 +505,332 @@ async function getKaspaSigningBackendStatus() {
 
 // src/kaspa-wasm-signer.ts
 import { calculateContentHash } from "@hardkas/artifacts";
-function toHex(arr) {
-  return Buffer.from(arr).toString("hex");
-}
-function parseWasmTxToRpc(wasmTxStr) {
-  let parsed = JSON.parse(wasmTxStr);
-  if (typeof parsed === "string") {
-    parsed = JSON.parse(parsed);
-  }
-  const txInner = parsed.tx ? parsed.tx.inner : parsed.inner;
-  if (!txInner) throw new Error("Could not find inner tx data");
-  return {
-    version: txInner.version || 0,
-    inputs: (txInner.inputs || []).map((i) => ({
-      previousOutpoint: {
-        transactionId: i.inner.previousOutpoint.inner.transactionId,
-        index: i.inner.previousOutpoint.inner.index
+
+// src/keystore.ts
+import fs3 from "fs";
+import path3 from "path";
+import crypto from "crypto";
+import { argon2id } from "hash-wasm";
+import { writeFileAtomic } from "@hardkas/core";
+var KeystoreManager = class {
+  /**
+   * Keystore container format version. Separate from ARTIFACT_VERSION.
+   * This versions the encrypted keystore envelope, not HardKAS artifacts.
+   */
+  static KEYSTORE_FORMAT_VERSION = "2.0.0";
+  static KEYSTORE_FORMAT_TYPE = "hardkas.encryptedKeystore.v2";
+  /**
+   * Creates an encrypted keystore from a payload and password.
+   */
+  static async createEncryptedKeystore(payload, password, options) {
+    if (!password) throw new Error("Password cannot be empty.");
+    if (password.length < 8)
+      throw new Error("Password must be at least 8 characters long.");
+    const salt = crypto.randomBytes(16);
+    const nonce = crypto.randomBytes(12);
+    const iterations = options.iterations || 3;
+    const memory = options.memory || 65536;
+    const parallelism = options.parallelism || 1;
+    const derivedKeyHex = await argon2id({
+      password,
+      salt,
+      parallelism,
+      iterations,
+      memorySize: memory,
+      hashLength: 32,
+      // 256 bits for AES-256
+      outputType: "hex"
+    });
+    const derivedKey = Buffer.from(derivedKeyHex, "hex");
+    const cipher = crypto.createCipheriv("aes-256-gcm", derivedKey, nonce);
+    const encryptedPayload = Buffer.concat([
+      cipher.update(JSON.stringify(payload), "utf8"),
+      cipher.final()
+    ]);
+    const tag = cipher.getAuthTag();
+    derivedKey.fill(0);
+    return {
+      version: this.KEYSTORE_FORMAT_VERSION,
+      type: this.KEYSTORE_FORMAT_TYPE,
+      kdf: {
+        algorithm: "argon2id",
+        memory,
+        iterations,
+        parallelism,
+        salt: salt.toString("base64")
       },
-      signatureScript: toHex(i.inner.signatureScript),
-      sequence: i.inner.sequence || 0,
-      sigOpCount: i.inner.sigOpCount || 1
-    })),
-    outputs: (txInner.outputs || []).map((o) => ({
-      amount: o.inner.value.toString(),
-      scriptPublicKey: {
-        version: parseInt(o.inner.scriptPublicKey.substring(0, 4), 16) || 0,
-        scriptPublicKey: o.inner.scriptPublicKey.substring(4)
+      cipher: {
+        algorithm: "aes-256-gcm",
+        nonce: nonce.toString("base64"),
+        tag: tag.toString("base64")
+      },
+      encryptedPayload: encryptedPayload.toString("base64"),
+      createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+      metadata: {
+        label: options.label,
+        network: options.network,
+        address: payload.address
       }
-    })),
-    lockTime: txInner.lockTime || 0,
-    subnetworkId: txInner.subnetworkId || "0000000000000000000000000000000000000000",
-    gas: txInner.gas || 0,
-    payload: txInner.payload && txInner.payload.length > 0 ? toHex(txInner.payload) : ""
-  };
-}
-var KaspaWasmPrivateKeySigner = class {
-  constructor(options) {
-    this.options = options;
+    };
   }
-  options;
-  kind = "kaspa-private-key";
-  async signTxPlan(input) {
-    const plan = input.planArtifact;
-    const account = this.options.account;
-    const sdk = await loadKaspaWasm();
-    assertSigningNetworkAllowed({
-      network: plan.networkId,
-      mode: plan.mode,
-      allowMainnet: this.options.allowMainnet
-    });
-    let pkValue = account.privateKeyEnv ? process.env[account.privateKeyEnv] : void 0;
-    if (!pkValue && account.privateKey) {
-      if (plan.networkId === "mainnet") {
-        throw new Error(`Mainnet guard: Unsafe plaintext privateKey fallback is forbidden on mainnet for account '${account.name}'. Use privateKeyEnv instead.`);
-      }
-      pkValue = account.privateKey;
-    }
-    if (!pkValue) {
-      throw new Error(`Missing required private key for account '${account.name}'.`);
+  /**
+   * Decrypts an encrypted keystore using a password.
+   */
+  static async decryptEncryptedKeystore(keystore, password) {
+    if (keystore.version !== this.KEYSTORE_FORMAT_VERSION) {
+      return {
+        success: false,
+        error: `Unsupported keystore version: ${keystore.version}`
+      };
     }
     try {
-      const privateKey = new sdk.PrivateKey(pkValue);
-      const utxos = plan.inputs.map((u) => {
-        if (!u.outpoint.transactionId || u.outpoint.index === void 0) {
-          throw new Error(`UTXO is missing transactionId or index. Re-run tx plan.`);
-        }
-        const spk = u.scriptPublicKey;
-        if (!spk) {
-          throw new Error(
-            "UTXO is missing scriptPublicKey. Real signing flows must never fabricate cryptographic state."
-          );
-        }
-        return {
-          address: plan.from.address,
-          outpoint: {
-            transactionId: u.outpoint.transactionId,
-            index: u.outpoint.index
-          },
-          utxoEntry: {
-            amount: BigInt(u.amountSompi),
-            scriptPublicKey: spk,
-            blockDaaScore: BigInt(u.blockDaaScore || "0"),
-            isCoinbase: !!u.isCoinbase
-          }
-        };
-      });
-      const outputs = plan.outputs.map((o) => {
-        if (!o.address) throw new Error("Output is missing address.");
-        return {
-          address: o.address,
-          amount: BigInt(o.amountSompi)
-        };
+      const salt = Buffer.from(keystore.kdf.salt, "base64");
+      const nonce = Buffer.from(keystore.cipher.nonce, "base64");
+      const tag = Buffer.from(keystore.cipher.tag, "base64");
+      const encryptedData = Buffer.from(keystore.encryptedPayload, "base64");
+      const derivedKeyHex = await argon2id({
+        password,
+        salt,
+        parallelism: keystore.kdf.parallelism,
+        iterations: keystore.kdf.iterations,
+        memorySize: keystore.kdf.memory,
+        hashLength: 32,
+        outputType: "hex"
       });
-      const changeAddress = plan.change?.address ? new sdk.Address(plan.change.address) : void 0;
-      const priorityFee = BigInt(plan.estimatedFeeSompi);
-      const unsignedTx = sdk.createTransaction(
-        utxos,
-        outputs,
-        changeAddress,
-        priorityFee
-      );
-      const signedTx = sdk.signTransaction(unsignedTx, [privateKey], true);
-      const rawTx = JSON.stringify(parseWasmTxToRpc(signedTx.toString()));
-      return {
-        signatureKind: "kaspa-private-key",
-        signerAddress: account.address || privateKey.toAddress(plan.networkId).toString(),
-        signedTransaction: {
-          format: "hex",
-          payload: rawTx
-        },
-        txId: signedTx.id,
-        signature: {
-          // We use the txid as the signature identifier in the artifact
-          value: signedTx.id || calculateContentHash(plan)
-        }
-      };
-    } catch (error) {
+      const derivedKey = Buffer.from(derivedKeyHex, "hex");
+      const decipher = crypto.createDecipheriv("aes-256-gcm", derivedKey, nonce);
+      decipher.setAuthTag(tag);
+      const decrypted = Buffer.concat([decipher.update(encryptedData), decipher.final()]);
+      derivedKey.fill(0);
+      const payload = JSON.parse(decrypted.toString("utf8"));
+      return { success: true, payload };
+    } catch (e) {
+      return { success: false, error: "Invalid password or corrupted keystore." };
+    }
+  }
+  /**
+   * Verifies if the password is correct for the keystore.
+   */
+  static async verifyKeystorePassword(keystore, password) {
+    const result = await this.decryptEncryptedKeystore(keystore, password);
+    return result.success;
+  }
+  /**
+   * Changes the password of an encrypted keystore.
+   */
+  static async changeKeystorePassword(keystore, oldPassword, newPassword) {
+    const unlock = await this.decryptEncryptedKeystore(keystore, oldPassword);
+    if (!unlock.success || !unlock.payload) {
+      throw new Error("Invalid current password.");
+    }
+    return this.createEncryptedKeystore(unlock.payload, newPassword, {
+      label: keystore.metadata.label,
+      network: keystore.metadata.network,
+      iterations: keystore.kdf.iterations,
+      memory: keystore.kdf.memory,
+      parallelism: keystore.kdf.parallelism
+    });
+  }
+  /**
+   * Loads an encrypted keystore from the filesystem.
+   */
+  static async loadEncryptedKeystore(filePath) {
+    try {
+      const data = await fs3.promises.readFile(filePath, "utf-8");
+      const keystore = JSON.parse(data);
+      if (keystore.type !== this.KEYSTORE_FORMAT_TYPE) {
+        throw new Error(`Invalid keystore type: ${keystore.type}`);
+      }
+      return keystore;
+    } catch (e) {
       throw new Error(
-        `Kaspa WASM signing failed: ${error instanceof Error ? error.message : String(error)}`
+        `Failed to load keystore at ${filePath}: ${e instanceof Error ? e.message : String(e)}`
       );
     }
   }
-};
-function assertSigningNetworkAllowed(input) {
-  const isMainnet = input.network === "mainnet";
-  if (isMainnet && !input.allowMainnet) {
-    throw new Error(
-      "Mainnet signing is disabled by default. Use --allow-mainnet-signing only if you understand the risks."
-    );
-  }
-}
-
-// src/signer.ts
-var SimulatedTxPlanSigner = class {
-  kind = "simulated";
-  async signTxPlan(input) {
-    const plan = input.planArtifact;
-    return {
-      signatureKind: "simulated",
-      signerAddress: plan.from.address,
-      signedTransaction: {
-        format: "simulated",
-        payload: `simulated-signed-tx:${plan.planId}`
+  /**
+   * Saves an encrypted keystore to the filesystem.
+   */
+  static async saveEncryptedKeystore(filePath, keystore) {
+    try {
+      const dir = path3.dirname(filePath);
+      if (!fs3.existsSync(dir)) {
+        await fs3.promises.mkdir(dir, { recursive: true });
       }
-    };
-  }
-};
-var UnsupportedRealKaspaSigner = class {
-  kind = "unsupported";
-  async signTxPlan(_input) {
-    throw new Error(
-      "Real Kaspa signing requires an official Kaspa transaction signing library. No supported signer backend is configured."
-    );
-  }
-};
-async function signTxPlanArtifact(input) {
-  const { planArtifact, account } = input;
-  const planRecord = planArtifact;
-  if (planArtifact.schema === "hardkas.txPlan") {
-  } else if (planRecord.status !== "built" && planRecord.status !== "unsigned") {
-    throw new Error(`Cannot sign artifact with status: ${planRecord.status}`);
-  }
-  if (planArtifact.mode === "simulated") {
-    if (account.kind !== "simulated") {
-      throw new Error(
-        `Simulated plans must be signed with simulated accounts (account '${account.name}' is '${account.kind}').`
-      );
-    }
-  } else {
-    if (account.kind === "simulated") {
+      await writeFileAtomic(filePath, JSON.stringify(keystore, null, 2), {
+        encoding: "utf-8",
+        mode: 384
+      });
+    } catch (e) {
       throw new Error(
-        `Real Kaspa transaction plans (mode: ${planArtifact.mode}) cannot be signed with simulated accounts.`
+        `Failed to save keystore at ${filePath}: ${e instanceof Error ? e.message : String(e)}`
       );
     }
   }
-  if (planArtifact.networkId === "mainnet" && !input.allowMainnet) {
-    throw new Error(
-      "Mainnet signing is disabled by default. Use --allow-mainnet-signing only if you understand the risks."
-    );
+};
+
+// src/dev-accounts.ts
+import fs4 from "fs";
+import path4 from "path";
+import crypto2 from "crypto";
+import { deterministicCompare } from "@hardkas/core";
+var DEV_ACCOUNTS_PASSWORD = "hardkas-local-dev";
+var SIMNET_DETERMINISTIC_SEED = "hardkas-deterministic-simnet-seed-v1";
+async function ensureDevAccounts(workspaceDir) {
+  const devAccountsDir = path4.join(workspaceDir, ".hardkas", "dev-accounts");
+  if (!fs4.existsSync(devAccountsDir)) {
+    await fs4.promises.mkdir(devAccountsDir, { recursive: true });
   }
-  if (account.kind === "simulated") {
-    return createSimulatedSignedTxArtifact(
-      planArtifact,
-      `simulated-signed-tx:${planArtifact.planId}`,
-      systemRuntimeContext
+  await getOrCreateDevAccount(workspaceDir, 0, "alice");
+  await getOrCreateDevAccount(workspaceDir, 1, "bob");
+}
+async function getOrCreateDevAccount(workspaceDir, index, alias) {
+  const devAccountsDir = path4.join(workspaceDir, ".hardkas", "dev-accounts");
+  const filePath = path4.join(devAccountsDir, `${alias}.json`);
+  if (fs4.existsSync(filePath)) {
+    const keystore2 = await KeystoreManager.loadEncryptedKeystore(filePath);
+    const unlock = await KeystoreManager.decryptEncryptedKeystore(
+      keystore2,
+      DEV_ACCOUNTS_PASSWORD
     );
-  }
-  if (account.kind === "kaspa-private-key") {
-    const status = await getKaspaSigningBackendStatus();
-    if (!status.available) {
+    if (!unlock.success || !unlock.payload) {
       throw new Error(
-        `Real Kaspa signing is not available: ${status.error || "Unknown error"}. Ensure 'kaspa' package is installed.`
+        `Failed to decrypt dev account ${alias}. Expected password: ${DEV_ACCOUNTS_PASSWORD}`
       );
     }
-    const signer = new KaspaWasmPrivateKeySigner({
-      account,
-      allowMainnet: input.allowMainnet
-    });
-    const result = await signer.signTxPlan({
-      planArtifact,
-      accountName: account.name
-    });
-    const artifact = {
-      schema: "hardkas.signedTx",
-      hardkasVersion: HARDKAS_VERSION2,
-      version: "1.0.0-alpha",
-      status: "signed",
-      createdAt: (/* @__PURE__ */ new Date()).toISOString(),
-      txId: result.txId || "",
-      // Ensure txId is present
-      sourcePlanId: planArtifact.planId,
-      networkId: planArtifact.networkId,
-      mode: planArtifact.mode,
-      from: { address: planArtifact.from.address },
-      to: { address: planArtifact.to.address },
-      amountSompi: planArtifact.amountSompi,
-      signedTransaction: {
-        format: result.signedTransaction?.format === "hex" ? "hex" : "unknown",
-        payload: result.signedTransaction?.payload || ""
-      },
-      lineage: createLineageTransition(planArtifact, "hardkas.signedTx"),
-      ...planArtifact.workflowId ? { workflowId: planArtifact.workflowId } : {},
-      ...planArtifact.assumptionLevel ? { assumptionLevel: planArtifact.assumptionLevel } : {},
-      ...planArtifact.policyRefs ? { policyRefs: planArtifact.policyRefs } : {},
-      ...planArtifact.networkProfileRef ? { networkProfileRef: planArtifact.networkProfileRef } : {},
-      ...planArtifact.assumptionRef ? { assumptionRef: planArtifact.assumptionRef } : {}
+    return {
+      address: unlock.payload.address,
+      privateKey: unlock.payload.privateKey,
+      publicKey: unlock.payload.publicKey
     };
-    const contentHash = calculateContentHash2(artifact);
-    artifact.signedId = `signed-${contentHash.slice(0, 16)}`;
-    artifact.contentHash = contentHash;
-    if (artifact.lineage) {
-      artifact.lineage.artifactId = contentHash;
-    }
-    return artifact;
-  }
-  if (account.kind === "external-wallet") {
-    throw new Error("External wallet signing is not implemented yet.");
   }
-  if (account.kind === "evm-private-key") {
-    throw new Error(
-      "EVM accounts are reserved for future Igra support and cannot sign Kaspa L1 transactions."
-    );
-  }
-  const accountRecord = account;
-  throw new Error(`Unsupported account kind for signing: ${accountRecord.kind}`);
-}
-
-// src/kaspa-sdk-keygen.ts
-var KaspaSdkKeyGenerator = class {
-  networkId;
-  sdkLoader;
-  constructor(options) {
-    this.networkId = options?.networkId || "simnet";
-    const rawLoader = options?.sdkLoader || (async () => {
-      return await import("kaspa-wasm");
-    });
-    this.sdkLoader = async () => {
+  const seedString = `${SIMNET_DETERMINISTIC_SEED}-${index}`;
+  const privateKeyHex = crypto2.createHash("sha256").update(seedString).digest("hex");
+  const network = "simnet";
+  const isSimnet = ["simnet", "kaspasim", "local"].includes(network);
+  let address = "";
+  let privateKey = "";
+  let publicKey = "";
+  try {
+    if (isSimnet) {
+      let kaspaWasm;
       try {
-        return await rawLoader();
+        kaspaWasm = await import(
+          /* @vite-ignore */
+          "kaspa-wasm"
+        );
       } catch (e) {
-        const err = new Error(
-          "WALLET_BACKEND_UNAVAILABLE: Kaspa cryptography adapter missing. Real account generation requires WASM execution.\nUse 'hardkas accounts real import' to add a test fixture manually for now."
+        console.warn(`
+[Warning] kaspa-wasm is not installed. Required for simnet.`);
+        return { address: "", privateKey: "", publicKey: "" };
+      }
+      const privKey = new kaspaWasm.PrivateKey(privateKeyHex);
+      const kp = privKey.toKeypair();
+      address = kp.toAddress(network).toString();
+      publicKey = kp.publicKey;
+      privateKey = kp.privateKey;
+    } else {
+      let sdkModule;
+      try {
+        sdkModule = await import(
+          /* @vite-ignore */
+          "@kaspa/core-lib"
         );
-        err.code = "WALLET_BACKEND_UNAVAILABLE";
-        throw err;
+      } catch (e) {
+        console.warn(`
+[Warning] @kaspa/core-lib is not installed.`);
+        return { address: "", privateKey: "", publicKey: "" };
       }
-    };
-  }
-  async generateAccount(options) {
-    const sdk = await this.sdkLoader();
-    const network = options?.networkId || this.networkId;
-    try {
-      if (typeof sdk.PrivateKey === "function") {
-        const crypto3 = await import("crypto");
-        const randomBytes = crypto3.randomBytes(32);
-        const hex = randomBytes.toString("hex");
-        const privKey = new sdk.PrivateKey(hex);
-        const kp = privKey.toKeypair();
-        const address = kp.toAddress(network).toString();
-        const privateKeyStr = kp.privateKey;
-        const publicKeyStr = kp.publicKey;
-        return {
-          address,
-          publicKey: publicKeyStr,
-          privateKey: privateKeyStr
-        };
+      const sdk = sdkModule.default || sdkModule;
+      if (typeof sdk.initRuntime === "function") {
+        await sdk.initRuntime();
       }
-      throw new Error(
-        "Loaded Kaspa SDK does not expose expected PrivateKey constructor."
-      );
-    } catch (e) {
-      throw new Error(
-        `Failed to generate account using SDK: ${e instanceof Error ? e.message : String(e)}`
-      );
+      const privKey = new sdk.PrivateKey(privateKeyHex);
+      const pubKey = privKey.toPublicKey();
+      try {
+        address = pubKey.toAddress(network).toString();
+      } catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        if (msg.includes("Second argument must be") || msg.includes("Unsupported")) {
+          const err = new Error("DEV_ACCOUNT_BACKEND_UNSUPPORTED_NETWORK");
+          err.code = "DEV_ACCOUNT_BACKEND_UNSUPPORTED_NETWORK";
+          throw err;
+        }
+        throw e;
+      }
+      publicKey = pubKey.toString();
+      privateKey = privKey.toString();
+    }
+  } catch (e) {
+    if (e.message === "DEV_ACCOUNT_BACKEND_UNSUPPORTED_NETWORK") {
+      throw e;
     }
+    console.warn(`
+[Warning] Could not generate dev account '${alias}'.
+${e.message}`);
+    return { address: "", privateKey: "", publicKey: "" };
   }
-};
-
-// src/kaspa-wallet.ts
-async function createLocalKaspaWallet(options) {
-  const keygen = new KaspaSdkKeyGenerator({
-    networkId: options?.networkId || "simnet"
-  });
-  return await keygen.generateAccount();
+  const accountData = {
+    address,
+    privateKey,
+    publicKey
+  };
+  if (!fs4.existsSync(devAccountsDir)) {
+    await fs4.promises.mkdir(devAccountsDir, { recursive: true });
+  }
+  const payload = {
+    address: accountData.address,
+    privateKey: accountData.privateKey,
+    network: "simnet"
+  };
+  if (accountData.publicKey) {
+    payload.publicKey = accountData.publicKey;
+  }
+  const keystore = await KeystoreManager.createEncryptedKeystore(
+    payload,
+    DEV_ACCOUNTS_PASSWORD,
+    {
+      label: alias,
+      network: "simnet"
+    }
+  );
+  await KeystoreManager.saveEncryptedKeystore(filePath, keystore);
+  return accountData;
+}
+function listDevAccountsSync(workspaceDir) {
+  const devAccountsDir = path4.join(workspaceDir, ".hardkas", "dev-accounts");
+  if (!fs4.existsSync(devAccountsDir)) {
+    return [];
+  }
+  const accounts = [];
+  const files = fs4.readdirSync(devAccountsDir);
+  for (const file of files) {
+    if (file.endsWith(".json")) {
+      const name = path4.basename(file, ".json");
+      try {
+        const data = fs4.readFileSync(path4.join(devAccountsDir, file), "utf-8");
+        const keystore = JSON.parse(data);
+        if (keystore.type === "hardkas.encryptedKeystore.v2") {
+          accounts.push({
+            name,
+            address: keystore.metadata?.address || ""
+          });
+        }
+      } catch (e) {
+      }
+    }
+  }
+  accounts.sort((a, b) => deterministicCompare(a.name, b.name));
+  return accounts;
 }
 
-// src/fixture-signer.ts
-import { calculateContentHash as calculateContentHash3, HARDKAS_VERSION as HARDKAS_VERSION3, ARTIFACT_VERSION as ARTIFACT_VERSION2, CURRENT_HASH_VERSION } from "@hardkas/artifacts";
-function toHex2(arr) {
+// src/kaspa-wasm-signer.ts
+function toHex(arr) {
   return Buffer.from(arr).toString("hex");
 }
-function parseWasmTxToRpc2(wasmTxStr) {
+function parseWasmTxToRpc(wasmTxStr) {
   let parsed = JSON.parse(wasmTxStr);
-  while (typeof parsed === "string") {
+  if (typeof parsed === "string") {
     parsed = JSON.parse(parsed);
   }
   const txInner = parsed.tx ? parsed.tx.inner : parsed.inner;
@@ -802,204 +842,97 @@ function parseWasmTxToRpc2(wasmTxStr) {
         transactionId: i.inner.previousOutpoint.inner.transactionId,
         index: i.inner.previousOutpoint.inner.index
       },
-      signatureScript: toHex2(i.inner.signatureScript),
+      signatureScript: toHex(i.inner.signatureScript),
       sequence: i.inner.sequence || 0,
       sigOpCount: i.inner.sigOpCount || 1
     })),
     outputs: (txInner.outputs || []).map((o) => ({
-      value: o.inner.value,
+      amount: o.inner.value.toString(),
       scriptPublicKey: {
         version: parseInt(o.inner.scriptPublicKey.substring(0, 4), 16) || 0,
-        script: o.inner.scriptPublicKey.substring(4)
+        scriptPublicKey: o.inner.scriptPublicKey.substring(4)
       }
     })),
     lockTime: txInner.lockTime || 0,
     subnetworkId: txInner.subnetworkId || "0000000000000000000000000000000000000000",
     gas: txInner.gas || 0,
-    payload: txInner.payload && txInner.payload.length > 0 ? toHex2(txInner.payload) : "",
-    mass: txInner.mass || 0
+    payload: txInner.payload && txInner.payload.length > 0 ? toHex(txInner.payload) : ""
   };
 }
-var HardkasFixtureSigner = class {
-  networkId;
-  // A deterministic, known private key exclusively for Docker tests.
-  FIXTURE_PK = "b7e151628aed2a6abf7158809cf4f3c762e7160f38b4da56a784d9045190cfef";
-  constructor(networkId = "simnet") {
-    this.networkId = networkId;
-    if (networkId === "mainnet") {
-      throw new Error("FixtureSigner cannot be used on mainnet.");
-    }
-  }
-  async loadKaspa() {
-    try {
-      return await import("kaspa-wasm");
-    } catch (e) {
-      const err = new Error("SIGNER_BACKEND_UNAVAILABLE: Official Kaspa WASM backend is required to sign transactions.\nInstall it via: npm install kaspa-wasm");
-      err.code = "SIGNER_BACKEND_UNAVAILABLE";
-      throw err;
-    }
-  }
-  async getAddress() {
-    const kaspa = await this.loadKaspa();
-    const privKey = new kaspa.PrivateKey(this.FIXTURE_PK);
-    return privKey.toKeypair().toAddress(this.networkId).toString();
+var KaspaWasmPrivateKeySigner = class {
+  constructor(options) {
+    this.options = options;
   }
-  async signTransaction(plan) {
-    if (plan.networkId === "mainnet") {
-      throw new Error("FixtureSigner refuses to sign mainnet transactions.");
-    }
-    const kaspa = await this.loadKaspa();
-    const privateKey = new kaspa.PrivateKey(this.FIXTURE_PK);
-    const utxos = plan.inputs.map((u) => {
-      if (!u.outpoint.transactionId || u.outpoint.index === void 0) {
-        throw new Error(`UTXO is missing transactionId or index. Re-run tx plan.`);
-      }
-      const spk = u.scriptPublicKey;
-      if (!spk) {
-        throw new Error("UTXO is missing scriptPublicKey. Real signing flows must never fabricate cryptographic state.");
-      }
-      return {
-        address: plan.from.address,
-        outpoint: {
-          transactionId: u.outpoint.transactionId,
-          index: u.outpoint.index
-        },
-        utxoEntry: {
-          amount: BigInt(u.amountSompi),
-          scriptPublicKey: spk,
-          blockDaaScore: BigInt(u.blockDaaScore || "0"),
-          isCoinbase: !!u.isCoinbase
-        }
-      };
-    });
-    const outputs = plan.outputs.map((o) => {
-      if (!o.address) throw new Error("Output is missing address.");
-      return {
-        address: o.address,
-        amount: BigInt(o.amountSompi)
-      };
+  options;
+  kind = "kaspa-private-key";
+  async signTxPlan(input) {
+    const plan = input.planArtifact;
+    const account = this.options.account;
+    const sdk = await loadKaspaWasm();
+    assertSigningNetworkAllowed({
+      network: plan.networkId,
+      mode: plan.mode,
+      allowMainnet: this.options.allowMainnet
     });
-    let changeAddress;
-    if (plan.change && plan.change.address) {
-      changeAddress = new kaspa.Address(plan.change.address);
-    } else {
-      changeAddress = new kaspa.Address(plan.from.address);
+    let pkValue = account.privateKeyEnv ? process.env[account.privateKeyEnv] : void 0;
+    if (!pkValue && account.privateKey) {
+      if (plan.networkId === "mainnet") {
+        throw new Error(`Mainnet guard: Unsafe plaintext privateKey fallback is forbidden on mainnet for account '${account.name}'. Use privateKeyEnv instead.`);
+      }
+      pkValue = account.privateKey;
     }
-    const priorityFee = BigInt(plan.estimatedFeeSompi || "0");
-    const unsignedTx = kaspa.createTransaction(
-      utxos,
-      outputs,
-      changeAddress,
-      priorityFee
-    );
-    const signedTx = kaspa.signTransaction(unsignedTx, [privateKey], true);
-    console.log("SIGNED TX TOSTRING:", signedTx.toString());
-    const rawTx = JSON.stringify(parseWasmTxToRpc2(signedTx.toString()));
-    const draft = {
-      schema: "hardkas.signedTx",
-      schemaVersion: "hardkas.artifact.v1",
-      hardkasVersion: HARDKAS_VERSION3,
-      version: ARTIFACT_VERSION2,
-      hashVersion: CURRENT_HASH_VERSION,
-      createdAt: (/* @__PURE__ */ new Date()).toISOString(),
-      status: "signed",
-      txId: signedTx.id,
-      sourcePlanId: plan.planId,
-      networkId: plan.networkId,
-      mode: plan.mode,
-      from: plan.from,
-      to: plan.to,
-      amountSompi: plan.amountSompi,
-      unsignedPayloadHash: plan.contentHash,
-      signedTransaction: {
-        format: "hex",
-        payload: rawTx
-      },
-      metadata: {
-        signerBackend: "kaspa-wasm",
-        fixture: true,
-        networkGuard: "mainnet_rejected"
-      },
-      signatureMetadata: [
-        {
-          signer: "hardkas-local-docker-test-only",
-          signedAt: (/* @__PURE__ */ new Date()).toISOString()
+    if (!pkValue && account.keystorePath) {
+      try {
+        const keystore = await KeystoreManager.loadEncryptedKeystore(account.keystorePath);
+        const unlock = await KeystoreManager.decryptEncryptedKeystore(
+          keystore,
+          DEV_ACCOUNTS_PASSWORD
+        );
+        if (unlock.success && unlock.payload) {
+          pkValue = unlock.payload.privateKey;
         }
-      ],
-      lineage: {
-        artifactId: "",
-        lineageId: plan.lineage?.lineageId || plan.contentHash || "0".repeat(64),
-        parentArtifactId: plan.contentHash || plan.planId,
-        rootArtifactId: plan.lineage?.rootArtifactId || plan.contentHash || plan.planId
+      } catch (e) {
       }
-    };
-    const hash = calculateContentHash3(draft, CURRENT_HASH_VERSION);
-    draft.signedId = `signed-${hash.slice(0, 16)}`;
-    draft.contentHash = hash;
-    if (draft.lineage) draft.lineage.artifactId = hash;
-    return draft;
-  }
-};
-
-// src/real-signer.ts
-var UnsupportedRealTxSigner = class {
-  async sign() {
-    throw new Error(
-      "Real transaction signing is not configured yet. Install/configure a supported Kaspa SDK signer adapter."
-    );
-  }
-};
-
-// src/kaspa-sdk-real-signer.ts
-var KaspaSdkRealTxSigner = class {
-  sdkLoader;
-  constructor(options) {
-    this.sdkLoader = options?.sdkLoader || loadKaspaWasm;
-  }
-  async sign(input) {
-    const { plan, account } = input;
-    let sdk;
-    try {
-      sdk = await this.sdkLoader();
-    } catch (e) {
-      throw new Error(
-        "Kaspa SDK real transaction signer dependency is not installed. Install/configure the supported Kaspa WASM SDK adapter."
-      );
-    }
-    if (!sdk) {
-      throw new Error(
-        "Kaspa SDK real transaction signer dependency is not installed. Install/configure the supported Kaspa WASM SDK adapter."
-      );
-    }
-    if (!account.privateKey) {
-      throw new Error("Account has no private key available for signing.");
     }
-    if (plan.from.address !== account.address) {
-      throw new Error(
-        `Address mismatch: Plan requires ${plan.from.address}, but account has ${account.address}.`
-      );
+    if (!pkValue) {
+      const err = new Error(`DEV_ACCOUNT_KEY_UNAVAILABLE: Missing required private key for account '${account.name}'.`);
+      err.code = "DEV_ACCOUNT_KEY_UNAVAILABLE";
+      throw err;
     }
     try {
-      const privateKey = new sdk.PrivateKey(account.privateKey);
+      const privateKey = new sdk.PrivateKey(pkValue);
       const utxos = plan.inputs.map((u) => {
-        if (!u.scriptPublicKey) {
-          throw new Error(
-            `UTXO ${u.outpoint.transactionId}:${u.outpoint.index} is missing scriptPublicKey required for signing.`
-          );
+        if (!u.outpoint.transactionId || u.outpoint.index === void 0) {
+          throw new Error(`UTXO is missing transactionId or index. Re-run tx plan.`);
         }
         const spk = u.scriptPublicKey;
-        return new sdk.UtxoEntry(
-          BigInt(u.amountSompi),
-          spk,
-          u.outpoint.transactionId,
-          u.outpoint.index,
-          plan.from.address
-        );
+        if (!spk) {
+          throw new Error(
+            "UTXO is missing scriptPublicKey. Real signing flows must never fabricate cryptographic state."
+          );
+        }
+        return {
+          address: plan.from.address,
+          outpoint: {
+            transactionId: u.outpoint.transactionId,
+            index: u.outpoint.index
+          },
+          utxoEntry: {
+            amount: BigInt(u.amountSompi),
+            scriptPublicKey: spk,
+            blockDaaScore: BigInt(u.blockDaaScore || "0"),
+            isCoinbase: !!u.isCoinbase
+          }
+        };
       });
-      const outputs = [
-        new sdk.PaymentOutput(new sdk.Address(plan.to.address), BigInt(plan.amountSompi))
-      ];
-      const changeAddress = plan.change ? new sdk.Address(plan.change.address) : void 0;
+      const outputs = plan.outputs.map((o) => {
+        if (!o.address) throw new Error("Output is missing address.");
+        return {
+          address: o.address,
+          amount: BigInt(o.amountSompi)
+        };
+      });
+      const changeAddress = plan.change?.address ? new sdk.Address(plan.change.address) : void 0;
       const priorityFee = BigInt(plan.estimatedFeeSompi);
       const unsignedTx = sdk.createTransaction(
         utxos,
@@ -1008,353 +941,464 @@ var KaspaSdkRealTxSigner = class {
         priorityFee
       );
       const signedTx = sdk.signTransaction(unsignedTx, [privateKey], true);
-      const payload = signedTx.serialize ? signedTx.serialize() : JSON.stringify(signedTx.toRpcTransaction());
-      const txId = signedTx.id;
+      const rawTx = JSON.stringify(parseWasmTxToRpc(signedTx.toString()));
       return {
+        signatureKind: "kaspa-private-key",
+        signerAddress: account.address || privateKey.toAddress(plan.networkId).toString(),
         signedTransaction: {
-          format: "kaspa-sdk",
-          payload
+          format: "hex",
+          payload: rawTx
         },
-        txId
+        txId: signedTx.id,
+        signature: {
+          // We use the txid as the signature identifier in the artifact
+          value: signedTx.id || calculateContentHash(plan)
+        }
       };
-    } catch (e) {
-      const msg = e instanceof Error ? e.message : String(e);
-      if (msg.includes("is not a constructor") || msg.includes("is not a function")) {
-        throw new Error(
-          `Kaspa SDK signer adapter could not find required transaction signing primitives: ${msg}`
-        );
-      }
-      throw new Error(`Real transaction signing failed in Kaspa SDK: ${msg}`);
+    } catch (error) {
+      throw new Error(
+        `Kaspa WASM signing failed: ${error instanceof Error ? error.message : String(error)}`
+      );
     }
   }
 };
-
-// src/real-keygen.ts
-var UnsupportedKaspaKeyGenerator = class {
-  async generateAccount() {
+function assertSigningNetworkAllowed(input) {
+  const isMainnet = input.network === "mainnet";
+  if (isMainnet && !input.allowMainnet) {
     throw new Error(
-      "Real Kaspa key generation is not configured. Install/configure a supported Kaspa SDK adapter."
+      "Mainnet signing is disabled by default. Use --allow-mainnet-signing only if you understand the risks."
     );
   }
-};
+}
 
-// src/keystore.ts
-import fs3 from "fs";
-import path3 from "path";
-import crypto from "crypto";
-import { argon2id } from "hash-wasm";
-import { writeFileAtomic } from "@hardkas/core";
-var KeystoreManager = class {
-  /**
-   * Keystore container format version. Separate from ARTIFACT_VERSION.
-   * This versions the encrypted keystore envelope, not HardKAS artifacts.
-   */
-  static KEYSTORE_FORMAT_VERSION = "2.0.0";
-  static KEYSTORE_FORMAT_TYPE = "hardkas.encryptedKeystore.v2";
-  /**
-   * Creates an encrypted keystore from a payload and password.
-   */
-  static async createEncryptedKeystore(payload, password, options) {
-    if (!password) throw new Error("Password cannot be empty.");
-    if (password.length < 8)
-      throw new Error("Password must be at least 8 characters long.");
-    const salt = crypto.randomBytes(16);
-    const nonce = crypto.randomBytes(12);
-    const iterations = options.iterations || 3;
-    const memory = options.memory || 65536;
-    const parallelism = options.parallelism || 1;
-    const derivedKeyHex = await argon2id({
-      password,
-      salt,
-      parallelism,
-      iterations,
-      memorySize: memory,
-      hashLength: 32,
-      // 256 bits for AES-256
-      outputType: "hex"
-    });
-    const derivedKey = Buffer.from(derivedKeyHex, "hex");
-    const cipher = crypto.createCipheriv("aes-256-gcm", derivedKey, nonce);
-    const encryptedPayload = Buffer.concat([
-      cipher.update(JSON.stringify(payload), "utf8"),
-      cipher.final()
-    ]);
-    const tag = cipher.getAuthTag();
-    derivedKey.fill(0);
+// src/signer.ts
+var SimulatedTxPlanSigner = class {
+  kind = "simulated";
+  async signTxPlan(input) {
+    const plan = input.planArtifact;
     return {
-      version: this.KEYSTORE_FORMAT_VERSION,
-      type: this.KEYSTORE_FORMAT_TYPE,
-      kdf: {
-        algorithm: "argon2id",
-        memory,
-        iterations,
-        parallelism,
-        salt: salt.toString("base64")
-      },
-      cipher: {
-        algorithm: "aes-256-gcm",
-        nonce: nonce.toString("base64"),
-        tag: tag.toString("base64")
-      },
-      encryptedPayload: encryptedPayload.toString("base64"),
-      createdAt: (/* @__PURE__ */ new Date()).toISOString(),
-      metadata: {
-        label: options.label,
-        network: options.network,
-        address: payload.address
+      signatureKind: "simulated",
+      signerAddress: plan.from.address,
+      signedTransaction: {
+        format: "simulated",
+        payload: `simulated-signed-tx:${plan.planId}`
       }
     };
   }
-  /**
-   * Decrypts an encrypted keystore using a password.
-   */
-  static async decryptEncryptedKeystore(keystore, password) {
-    if (keystore.version !== this.KEYSTORE_FORMAT_VERSION) {
-      return {
-        success: false,
-        error: `Unsupported keystore version: ${keystore.version}`
-      };
-    }
-    try {
-      const salt = Buffer.from(keystore.kdf.salt, "base64");
-      const nonce = Buffer.from(keystore.cipher.nonce, "base64");
-      const tag = Buffer.from(keystore.cipher.tag, "base64");
-      const encryptedData = Buffer.from(keystore.encryptedPayload, "base64");
-      const derivedKeyHex = await argon2id({
-        password,
-        salt,
-        parallelism: keystore.kdf.parallelism,
-        iterations: keystore.kdf.iterations,
-        memorySize: keystore.kdf.memory,
-        hashLength: 32,
-        outputType: "hex"
-      });
-      const derivedKey = Buffer.from(derivedKeyHex, "hex");
-      const decipher = crypto.createDecipheriv("aes-256-gcm", derivedKey, nonce);
-      decipher.setAuthTag(tag);
-      const decrypted = Buffer.concat([decipher.update(encryptedData), decipher.final()]);
-      derivedKey.fill(0);
-      const payload = JSON.parse(decrypted.toString("utf8"));
-      return { success: true, payload };
-    } catch (e) {
-      return { success: false, error: "Invalid password or corrupted keystore." };
-    }
+};
+var UnsupportedRealKaspaSigner = class {
+  kind = "unsupported";
+  async signTxPlan(_input) {
+    throw new Error(
+      "Real Kaspa signing requires an official Kaspa transaction signing library. No supported signer backend is configured."
+    );
   }
-  /**
-   * Verifies if the password is correct for the keystore.
-   */
-  static async verifyKeystorePassword(keystore, password) {
-    const result = await this.decryptEncryptedKeystore(keystore, password);
-    return result.success;
+};
+async function signTxPlanArtifact(input) {
+  const { planArtifact, account } = input;
+  const planRecord = planArtifact;
+  if (planArtifact.schema === "hardkas.txPlan") {
+  } else if (planRecord.status !== "built" && planRecord.status !== "unsigned") {
+    throw new Error(`Cannot sign artifact with status: ${planRecord.status}`);
   }
-  /**
-   * Changes the password of an encrypted keystore.
-   */
-  static async changeKeystorePassword(keystore, oldPassword, newPassword) {
-    const unlock = await this.decryptEncryptedKeystore(keystore, oldPassword);
-    if (!unlock.success || !unlock.payload) {
-      throw new Error("Invalid current password.");
+  if (planArtifact.mode === "simulated") {
+    if (account.kind !== "simulated") {
+      throw new Error(
+        `Simulated plans must be signed with simulated accounts (account '${account.name}' is '${account.kind}').`
+      );
     }
-    return this.createEncryptedKeystore(unlock.payload, newPassword, {
-      label: keystore.metadata.label,
-      network: keystore.metadata.network,
-      iterations: keystore.kdf.iterations,
-      memory: keystore.kdf.memory,
-      parallelism: keystore.kdf.parallelism
-    });
-  }
-  /**
-   * Loads an encrypted keystore from the filesystem.
-   */
-  static async loadEncryptedKeystore(filePath) {
-    try {
-      const data = await fs3.promises.readFile(filePath, "utf-8");
-      const keystore = JSON.parse(data);
-      if (keystore.type !== this.KEYSTORE_FORMAT_TYPE) {
-        throw new Error(`Invalid keystore type: ${keystore.type}`);
-      }
-      return keystore;
-    } catch (e) {
+  } else {
+    if (account.kind === "simulated") {
       throw new Error(
-        `Failed to load keystore at ${filePath}: ${e instanceof Error ? e.message : String(e)}`
+        `Real Kaspa transaction plans (mode: ${planArtifact.mode}) cannot be signed with simulated accounts.`
       );
     }
   }
-  /**
-   * Saves an encrypted keystore to the filesystem.
-   */
-  static async saveEncryptedKeystore(filePath, keystore) {
-    try {
-      const dir = path3.dirname(filePath);
-      if (!fs3.existsSync(dir)) {
-        await fs3.promises.mkdir(dir, { recursive: true });
-      }
-      await writeFileAtomic(filePath, JSON.stringify(keystore, null, 2), {
-        encoding: "utf-8",
-        mode: 384
-      });
-    } catch (e) {
-      throw new Error(
-        `Failed to save keystore at ${filePath}: ${e instanceof Error ? e.message : String(e)}`
-      );
-    }
-  }
-};
-
-// src/dev-accounts.ts
-import fs4 from "fs";
-import path4 from "path";
-import crypto2 from "crypto";
-import { deterministicCompare } from "@hardkas/core";
-var DEV_ACCOUNTS_PASSWORD = "hardkas-local-dev";
-var SIMNET_DETERMINISTIC_SEED = "hardkas-deterministic-simnet-seed-v1";
-async function ensureDevAccounts(workspaceDir) {
-  const devAccountsDir = path4.join(workspaceDir, ".hardkas", "dev-accounts");
-  if (!fs4.existsSync(devAccountsDir)) {
-    await fs4.promises.mkdir(devAccountsDir, { recursive: true });
+  if (planArtifact.networkId === "mainnet" && !input.allowMainnet) {
+    throw new Error(
+      "Mainnet signing is disabled by default. Use --allow-mainnet-signing only if you understand the risks."
+    );
   }
-  await getOrCreateDevAccount(workspaceDir, 0, "alice");
-  await getOrCreateDevAccount(workspaceDir, 1, "bob");
-}
-async function getOrCreateDevAccount(workspaceDir, index, alias) {
-  const devAccountsDir = path4.join(workspaceDir, ".hardkas", "dev-accounts");
-  const filePath = path4.join(devAccountsDir, `${alias}.json`);
-  if (fs4.existsSync(filePath)) {
-    const keystore2 = await KeystoreManager.loadEncryptedKeystore(filePath);
-    const unlock = await KeystoreManager.decryptEncryptedKeystore(
-      keystore2,
-      DEV_ACCOUNTS_PASSWORD
+  if (account.kind === "simulated") {
+    return createSimulatedSignedTxArtifact(
+      planArtifact,
+      `simulated-signed-tx:${planArtifact.planId}`,
+      systemRuntimeContext
     );
-    if (!unlock.success || !unlock.payload) {
+  }
+  if (account.kind === "kaspa-private-key") {
+    const status = await getKaspaSigningBackendStatus();
+    if (!status.available) {
       throw new Error(
-        `Failed to decrypt dev account ${alias}. Expected password: ${DEV_ACCOUNTS_PASSWORD}`
+        `Real Kaspa signing is not available: ${status.error || "Unknown error"}. Ensure 'kaspa' package is installed.`
       );
     }
-    return {
-      address: unlock.payload.address,
-      privateKey: unlock.payload.privateKey,
-      publicKey: unlock.payload.publicKey
+    const signer = new KaspaWasmPrivateKeySigner({
+      account,
+      allowMainnet: input.allowMainnet
+    });
+    const result = await signer.signTxPlan({
+      planArtifact,
+      accountName: account.name
+    });
+    const artifact = {
+      schema: "hardkas.signedTx",
+      hardkasVersion: HARDKAS_VERSION2,
+      version: "1.0.0-alpha",
+      status: "signed",
+      createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+      txId: result.txId || "",
+      // Ensure txId is present
+      sourcePlanId: planArtifact.planId,
+      networkId: planArtifact.networkId,
+      mode: planArtifact.mode,
+      from: { address: planArtifact.from.address },
+      to: { address: planArtifact.to.address },
+      amountSompi: planArtifact.amountSompi,
+      signedTransaction: {
+        format: result.signedTransaction?.format === "hex" ? "hex" : "unknown",
+        payload: result.signedTransaction?.payload || ""
+      },
+      lineage: createLineageTransition(planArtifact, "hardkas.signedTx"),
+      ...planArtifact.workflowId ? { workflowId: planArtifact.workflowId } : {},
+      ...planArtifact.assumptionLevel ? { assumptionLevel: planArtifact.assumptionLevel } : {},
+      ...planArtifact.policyRefs ? { policyRefs: planArtifact.policyRefs } : {},
+      ...planArtifact.networkProfileRef ? { networkProfileRef: planArtifact.networkProfileRef } : {},
+      ...planArtifact.assumptionRef ? { assumptionRef: planArtifact.assumptionRef } : {}
     };
+    const contentHash = calculateContentHash2(artifact);
+    artifact.signedId = `signed-${contentHash.slice(0, 16)}`;
+    artifact.contentHash = contentHash;
+    if (artifact.lineage) {
+      artifact.lineage.artifactId = contentHash;
+    }
+    return artifact;
   }
-  const seedString = `${SIMNET_DETERMINISTIC_SEED}-${index}`;
-  const privateKeyHex = crypto2.createHash("sha256").update(seedString).digest("hex");
-  const network = "simnet";
-  const isSimnet = ["simnet", "kaspasim", "local"].includes(network);
-  let address = "";
-  let privateKey = "";
-  let publicKey = "";
-  try {
-    if (isSimnet) {
-      let kaspaWasm;
+  if (account.kind === "external-wallet") {
+    throw new Error("External wallet signing is not implemented yet.");
+  }
+  if (account.kind === "evm-private-key") {
+    throw new Error(
+      "EVM accounts are reserved for future Igra support and cannot sign Kaspa L1 transactions."
+    );
+  }
+  const accountRecord = account;
+  throw new Error(`Unsupported account kind for signing: ${accountRecord.kind}`);
+}
+
+// src/kaspa-sdk-keygen.ts
+var KaspaSdkKeyGenerator = class {
+  networkId;
+  sdkLoader;
+  constructor(options) {
+    this.networkId = options?.networkId || "simnet";
+    const rawLoader = options?.sdkLoader || (async () => {
+      return await import("kaspa-wasm");
+    });
+    this.sdkLoader = async () => {
       try {
-        kaspaWasm = await import(
-          /* @vite-ignore */
-          "kaspa-wasm"
-        );
+        return await rawLoader();
       } catch (e) {
-        console.warn(`
-[Warning] kaspa-wasm is not installed. Required for simnet.`);
-        return { address: "", privateKey: "", publicKey: "" };
-      }
-      const privKey = new kaspaWasm.PrivateKey(privateKeyHex);
-      const kp = privKey.toKeypair();
-      address = kp.toAddress(network).toString();
-      publicKey = kp.publicKey;
-      privateKey = kp.privateKey;
-    } else {
-      let sdkModule;
-      try {
-        sdkModule = await import(
-          /* @vite-ignore */
-          "@kaspa/core-lib"
+        const err = new Error(
+          "WALLET_BACKEND_UNAVAILABLE: Kaspa cryptography adapter missing. Real account generation requires WASM execution.\nUse 'hardkas accounts real import' to add a test fixture manually for now."
         );
-      } catch (e) {
-        console.warn(`
-[Warning] @kaspa/core-lib is not installed.`);
-        return { address: "", privateKey: "", publicKey: "" };
-      }
-      const sdk = sdkModule.default || sdkModule;
-      if (typeof sdk.initRuntime === "function") {
-        await sdk.initRuntime();
+        err.code = "WALLET_BACKEND_UNAVAILABLE";
+        throw err;
       }
-      const privKey = new sdk.PrivateKey(privateKeyHex);
-      const pubKey = privKey.toPublicKey();
-      try {
-        address = pubKey.toAddress(network).toString();
-      } catch (e) {
-        const msg = e instanceof Error ? e.message : String(e);
-        if (msg.includes("Second argument must be") || msg.includes("Unsupported")) {
-          const err = new Error("DEV_ACCOUNT_BACKEND_UNSUPPORTED_NETWORK");
-          err.code = "DEV_ACCOUNT_BACKEND_UNSUPPORTED_NETWORK";
-          throw err;
-        }
-        throw e;
+    };
+  }
+  async generateAccount(options) {
+    const sdk = await this.sdkLoader();
+    const network = options?.networkId || this.networkId;
+    try {
+      if (typeof sdk.PrivateKey === "function") {
+        const crypto3 = await import("crypto");
+        const randomBytes = crypto3.randomBytes(32);
+        const hex = randomBytes.toString("hex");
+        const privKey = new sdk.PrivateKey(hex);
+        const kp = privKey.toKeypair();
+        const address = kp.toAddress(network).toString();
+        const privateKeyStr = kp.privateKey;
+        const publicKeyStr = kp.publicKey;
+        return {
+          address,
+          publicKey: publicKeyStr,
+          privateKey: privateKeyStr
+        };
       }
-      publicKey = pubKey.toString();
-      privateKey = privKey.toString();
-    }
-  } catch (e) {
-    if (e.message === "DEV_ACCOUNT_BACKEND_UNSUPPORTED_NETWORK") {
-      throw e;
+      throw new Error(
+        "Loaded Kaspa SDK does not expose expected PrivateKey constructor."
+      );
+    } catch (e) {
+      throw new Error(
+        `Failed to generate account using SDK: ${e instanceof Error ? e.message : String(e)}`
+      );
     }
-    console.warn(`
-[Warning] Could not generate dev account '${alias}'.
-${e.message}`);
-    return { address: "", privateKey: "", publicKey: "" };
   }
-  const accountData = {
-    address,
-    privateKey,
-    publicKey
-  };
-  if (!fs4.existsSync(devAccountsDir)) {
-    await fs4.promises.mkdir(devAccountsDir, { recursive: true });
+};
+
+// src/kaspa-wallet.ts
+async function createLocalKaspaWallet(options) {
+  const keygen = new KaspaSdkKeyGenerator({
+    networkId: options?.networkId || "simnet"
+  });
+  return await keygen.generateAccount();
+}
+
+// src/fixture-signer.ts
+import { calculateContentHash as calculateContentHash3, HARDKAS_VERSION as HARDKAS_VERSION3, ARTIFACT_VERSION as ARTIFACT_VERSION2, CURRENT_HASH_VERSION } from "@hardkas/artifacts";
+function toHex2(arr) {
+  return Buffer.from(arr).toString("hex");
+}
+function parseWasmTxToRpc2(wasmTxStr) {
+  let parsed = JSON.parse(wasmTxStr);
+  while (typeof parsed === "string") {
+    parsed = JSON.parse(parsed);
   }
-  const payload = {
-    address: accountData.address,
-    privateKey: accountData.privateKey,
-    network: "simnet"
+  const txInner = parsed.tx ? parsed.tx.inner : parsed.inner;
+  if (!txInner) throw new Error("Could not find inner tx data");
+  return {
+    version: txInner.version || 0,
+    inputs: (txInner.inputs || []).map((i) => ({
+      previousOutpoint: {
+        transactionId: i.inner.previousOutpoint.inner.transactionId,
+        index: i.inner.previousOutpoint.inner.index
+      },
+      signatureScript: toHex2(i.inner.signatureScript),
+      sequence: i.inner.sequence || 0,
+      sigOpCount: i.inner.sigOpCount || 1
+    })),
+    outputs: (txInner.outputs || []).map((o) => ({
+      value: o.inner.value,
+      scriptPublicKey: {
+        version: parseInt(o.inner.scriptPublicKey.substring(0, 4), 16) || 0,
+        script: o.inner.scriptPublicKey.substring(4)
+      }
+    })),
+    lockTime: txInner.lockTime || 0,
+    subnetworkId: txInner.subnetworkId || "0000000000000000000000000000000000000000",
+    gas: txInner.gas || 0,
+    payload: txInner.payload && txInner.payload.length > 0 ? toHex2(txInner.payload) : "",
+    mass: txInner.mass || 0
   };
-  if (accountData.publicKey) {
-    payload.publicKey = accountData.publicKey;
+}
+var HardkasFixtureSigner = class {
+  networkId;
+  // A deterministic, known private key exclusively for Docker tests.
+  FIXTURE_PK = "b7e151628aed2a6abf7158809cf4f3c762e7160f38b4da56a784d9045190cfef";
+  constructor(networkId = "simnet") {
+    this.networkId = networkId;
+    if (networkId === "mainnet") {
+      throw new Error("FixtureSigner cannot be used on mainnet.");
+    }
   }
-  const keystore = await KeystoreManager.createEncryptedKeystore(
-    payload,
-    DEV_ACCOUNTS_PASSWORD,
-    {
-      label: alias,
-      network: "simnet"
+  async loadKaspa() {
+    try {
+      return await import("kaspa-wasm");
+    } catch (e) {
+      const err = new Error("SIGNER_BACKEND_UNAVAILABLE: Official Kaspa WASM backend is required to sign transactions.\nInstall it via: npm install kaspa-wasm");
+      err.code = "SIGNER_BACKEND_UNAVAILABLE";
+      throw err;
     }
-  );
-  await KeystoreManager.saveEncryptedKeystore(filePath, keystore);
-  return accountData;
-}
-function listDevAccountsSync(workspaceDir) {
-  const devAccountsDir = path4.join(workspaceDir, ".hardkas", "dev-accounts");
-  if (!fs4.existsSync(devAccountsDir)) {
-    return [];
   }
-  const accounts = [];
-  const files = fs4.readdirSync(devAccountsDir);
-  for (const file of files) {
-    if (file.endsWith(".json")) {
-      const name = path4.basename(file, ".json");
-      try {
-        const data = fs4.readFileSync(path4.join(devAccountsDir, file), "utf-8");
-        const keystore = JSON.parse(data);
-        if (keystore.type === "hardkas.encryptedKeystore.v2") {
-          accounts.push({
-            name,
-            address: keystore.metadata?.address || ""
-          });
+  async getAddress() {
+    const kaspa = await this.loadKaspa();
+    const privKey = new kaspa.PrivateKey(this.FIXTURE_PK);
+    return privKey.toKeypair().toAddress(this.networkId).toString();
+  }
+  async signTransaction(plan) {
+    if (plan.networkId === "mainnet") {
+      throw new Error("FixtureSigner refuses to sign mainnet transactions.");
+    }
+    const kaspa = await this.loadKaspa();
+    const privateKey = new kaspa.PrivateKey(this.FIXTURE_PK);
+    const utxos = plan.inputs.map((u) => {
+      if (!u.outpoint.transactionId || u.outpoint.index === void 0) {
+        throw new Error(`UTXO is missing transactionId or index. Re-run tx plan.`);
+      }
+      const spk = u.scriptPublicKey;
+      if (!spk) {
+        throw new Error("UTXO is missing scriptPublicKey. Real signing flows must never fabricate cryptographic state.");
+      }
+      return {
+        address: plan.from.address,
+        outpoint: {
+          transactionId: u.outpoint.transactionId,
+          index: u.outpoint.index
+        },
+        utxoEntry: {
+          amount: BigInt(u.amountSompi),
+          scriptPublicKey: spk,
+          blockDaaScore: BigInt(u.blockDaaScore || "0"),
+          isCoinbase: !!u.isCoinbase
         }
-      } catch (e) {
+      };
+    });
+    const outputs = plan.outputs.map((o) => {
+      if (!o.address) throw new Error("Output is missing address.");
+      return {
+        address: o.address,
+        amount: BigInt(o.amountSompi)
+      };
+    });
+    let changeAddress;
+    if (plan.change && plan.change.address) {
+      changeAddress = new kaspa.Address(plan.change.address);
+    } else {
+      changeAddress = new kaspa.Address(plan.from.address);
+    }
+    const priorityFee = BigInt(plan.estimatedFeeSompi || "0");
+    const unsignedTx = kaspa.createTransaction(
+      utxos,
+      outputs,
+      changeAddress,
+      priorityFee
+    );
+    const signedTx = kaspa.signTransaction(unsignedTx, [privateKey], true);
+    console.log("SIGNED TX TOSTRING:", signedTx.toString());
+    const rawTx = JSON.stringify(parseWasmTxToRpc2(signedTx.toString()));
+    const draft = {
+      schema: "hardkas.signedTx",
+      schemaVersion: "hardkas.artifact.v1",
+      hardkasVersion: HARDKAS_VERSION3,
+      version: ARTIFACT_VERSION2,
+      hashVersion: CURRENT_HASH_VERSION,
+      createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+      status: "signed",
+      txId: signedTx.id,
+      sourcePlanId: plan.planId,
+      networkId: plan.networkId,
+      mode: plan.mode,
+      from: plan.from,
+      to: plan.to,
+      amountSompi: plan.amountSompi,
+      unsignedPayloadHash: plan.contentHash,
+      signedTransaction: {
+        format: "hex",
+        payload: rawTx
+      },
+      metadata: {
+        signerBackend: "kaspa-wasm",
+        fixture: true,
+        networkGuard: "mainnet_rejected"
+      },
+      signatureMetadata: [
+        {
+          signer: "hardkas-local-docker-test-only",
+          signedAt: (/* @__PURE__ */ new Date()).toISOString()
+        }
+      ],
+      lineage: {
+        artifactId: "",
+        lineageId: plan.lineage?.lineageId || plan.contentHash || "0".repeat(64),
+        parentArtifactId: plan.contentHash || plan.planId,
+        rootArtifactId: plan.lineage?.rootArtifactId || plan.contentHash || plan.planId
       }
+    };
+    const hash = calculateContentHash3(draft, CURRENT_HASH_VERSION);
+    draft.signedId = `signed-${hash.slice(0, 16)}`;
+    draft.contentHash = hash;
+    if (draft.lineage) draft.lineage.artifactId = hash;
+    return draft;
+  }
+};
+
+// src/real-signer.ts
+var UnsupportedRealTxSigner = class {
+  async sign() {
+    throw new Error(
+      "Real transaction signing is not configured yet. Install/configure a supported Kaspa SDK signer adapter."
+    );
+  }
+};
+
+// src/kaspa-sdk-real-signer.ts
+var KaspaSdkRealTxSigner = class {
+  sdkLoader;
+  constructor(options) {
+    this.sdkLoader = options?.sdkLoader || loadKaspaWasm;
+  }
+  async sign(input) {
+    const { plan, account } = input;
+    let sdk;
+    try {
+      sdk = await this.sdkLoader();
+    } catch (e) {
+      throw new Error(
+        "Kaspa SDK real transaction signer dependency is not installed. Install/configure the supported Kaspa WASM SDK adapter."
+      );
+    }
+    if (!sdk) {
+      throw new Error(
+        "Kaspa SDK real transaction signer dependency is not installed. Install/configure the supported Kaspa WASM SDK adapter."
+      );
+    }
+    if (!account.privateKey) {
+      throw new Error("Account has no private key available for signing.");
+    }
+    if (plan.from.address !== account.address) {
+      throw new Error(
+        `Address mismatch: Plan requires ${plan.from.address}, but account has ${account.address}.`
+      );
+    }
+    try {
+      const privateKey = new sdk.PrivateKey(account.privateKey);
+      const utxos = plan.inputs.map((u) => {
+        if (!u.scriptPublicKey) {
+          throw new Error(
+            `UTXO ${u.outpoint.transactionId}:${u.outpoint.index} is missing scriptPublicKey required for signing.`
+          );
+        }
+        const spk = u.scriptPublicKey;
+        return new sdk.UtxoEntry(
+          BigInt(u.amountSompi),
+          spk,
+          u.outpoint.transactionId,
+          u.outpoint.index,
+          plan.from.address
+        );
+      });
+      const outputs = [
+        new sdk.PaymentOutput(new sdk.Address(plan.to.address), BigInt(plan.amountSompi))
+      ];
+      const changeAddress = plan.change ? new sdk.Address(plan.change.address) : void 0;
+      const priorityFee = BigInt(plan.estimatedFeeSompi);
+      const unsignedTx = sdk.createTransaction(
+        utxos,
+        outputs,
+        changeAddress,
+        priorityFee
+      );
+      const signedTx = sdk.signTransaction(unsignedTx, [privateKey], true);
+      const payload = signedTx.serialize ? signedTx.serialize() : JSON.stringify(signedTx.toRpcTransaction());
+      const txId = signedTx.id;
+      return {
+        signedTransaction: {
+          format: "kaspa-sdk",
+          payload
+        },
+        txId
+      };
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      if (msg.includes("is not a constructor") || msg.includes("is not a function")) {
+        throw new Error(
+          `Kaspa SDK signer adapter could not find required transaction signing primitives: ${msg}`
+        );
+      }
+      throw new Error(`Real transaction signing failed in Kaspa SDK: ${msg}`);
     }
   }
-  accounts.sort((a, b) => deterministicCompare(a.name, b.name));
-  return accounts;
-}
+};
+
+// src/real-keygen.ts
+var UnsupportedKaspaKeyGenerator = class {
+  async generateAccount() {
+    throw new Error(
+      "Real Kaspa key generation is not configured. Install/configure a supported Kaspa SDK adapter."
+    );
+  }
+};
 export {
   DEV_ACCOUNTS_PASSWORD,
   HardkasFixtureSigner,
@@ -1393,5 +1437,6 @@ export {
   saveRealAccountStore,
   signTxPlanArtifact,
   validateAccountName,
+  validateAddressNetwork,
   validateAddressPrefix
 };