@hardkas/accounts 0.8.4-alpha → 0.8.9-alpha

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { HardkasConfig } from '@hardkas/config';
-import { TxPlanArtifact, SignedTxArtifact, HardkasArtifactBase } from '@hardkas/artifacts';
+import { TxPlanArtifact, SignedTxArtifact, ExternalHardkasSigner, HardkasArtifactBase } from '@hardkas/artifacts';
 import { NetworkId } from '@hardkas/core';
 
 type HardkasAccountKind = "simulated" | "kaspa-private-key" | "external-wallet" | "evm-private-key";
@@ -108,7 +108,7 @@ interface ResolveAccountOptions {
 }
 declare function resolveHardkasAccount(options: ResolveAccountOptions): HardkasAccount;
 declare function listHardkasAccounts(config?: HardkasConfig): HardkasAccount[];
-declare function resolveHardkasAccountAddress(accountOrAddress: string, config?: HardkasConfig, context?: "L1" | "L2"): string;
+declare function resolveHardkasAccountAddress(accountOrAddress: string, config?: HardkasConfig, context?: "L1" | "L2"): Promise<string>;
 declare function describeAccount(account: HardkasAccount): Record<string, unknown>;
 
 interface EvmExportResult {
@@ -222,6 +222,19 @@ declare function assertSigningNetworkAllowed(input: {
     allowMainnet?: boolean | undefined;
 }): void;
 
+/**
+ * Deterministic fixture signer for Docker testing on simnet.
+ * Never to be used with real funds or mainnet.
+ */
+declare class HardkasFixtureSigner implements ExternalHardkasSigner {
+    private networkId;
+    private readonly FIXTURE_PK;
+    constructor(networkId?: string);
+    private loadKaspa;
+    getAddress(): Promise<string>;
+    signTransaction(plan: TxPlanArtifact): Promise<SignedTxArtifact>;
+}
+
 interface RealAccountStore extends HardkasArtifactBase {
     readonly schema: "hardkas.realAccountStore.v1";
     readonly networkId: NetworkId;
@@ -375,4 +388,4 @@ declare function listDevAccountsSync(workspaceDir: string): {
     address: string;
 }[];
 
-export { type CreateKaspaWalletOptions, DEV_ACCOUNTS_PASSWORD, type EncryptedKeystoreV2, type EvmExportResult, type GeneratedKaspaDevAccount, type HardkasAccount, type HardkasAccountKind, type HardkasBaseAccount, type HardkasEvmPrivateKeyAccount, type HardkasExternalWalletAccount, type HardkasKaspaPrivateKeyAccount, type HardkasSigner, type HardkasSignerKind, type HardkasSimulatedAccount, type HardkasTxPlanSigner, type KaspaKeyGenerator, KaspaSdkKeyGenerator, type KaspaSdkKeyGeneratorOptions, KaspaSdkRealTxSigner, type KaspaSdkRealTxSignerOptions, type KaspaSigningBackendStatus, KaspaWasmPrivateKeySigner, type KeystoreCipherParams, type KeystoreKdfParams, KeystoreManager, type KeystorePayload, type KeystoreUnlockResult, type RealAccountStore, type RealDevAccount, type RealTxSigner, type RealTxSigningInput, type RealTxSigningResult, type ResolveAccountOptions, type SignTxPlanInput, type SignTxPlanResult, SimulatedSigner, SimulatedTxPlanSigner, UnsupportedKaspaKeyGenerator, UnsupportedRealKaspaSigner, UnsupportedRealTxSigner, assertSigningNetworkAllowed, createEmptyRealAccountStore, createLocalKaspaWallet, describeAccount, ensureDevAccounts, getDefaultRealAccountsPath, getKaspaSigningBackendStatus, getOrCreateDevAccount, getRealDevAccount, getRequiredEnv, importRealDevAccount, listDevAccountsSync, listHardkasAccounts, listRealDevAccounts, loadKaspaWasm, loadOrCreateRealAccountStore, loadRealAccountStore, loadRealAccountStoreSync, prepareEvmAccountExport, removeRealDevAccount, resolveHardkasAccount, resolveHardkasAccountAddress, resolveRealAccountOrAddress, saveRealAccountStore, signTxPlanArtifact, validateAccountName, validateAddressPrefix };
+export { type CreateKaspaWalletOptions, DEV_ACCOUNTS_PASSWORD, type EncryptedKeystoreV2, type EvmExportResult, type GeneratedKaspaDevAccount, type HardkasAccount, type HardkasAccountKind, type HardkasBaseAccount, type HardkasEvmPrivateKeyAccount, type HardkasExternalWalletAccount, HardkasFixtureSigner, type HardkasKaspaPrivateKeyAccount, type HardkasSigner, type HardkasSignerKind, type HardkasSimulatedAccount, type HardkasTxPlanSigner, type KaspaKeyGenerator, KaspaSdkKeyGenerator, type KaspaSdkKeyGeneratorOptions, KaspaSdkRealTxSigner, type KaspaSdkRealTxSignerOptions, type KaspaSigningBackendStatus, KaspaWasmPrivateKeySigner, type KeystoreCipherParams, type KeystoreKdfParams, KeystoreManager, type KeystorePayload, type KeystoreUnlockResult, type RealAccountStore, type RealDevAccount, type RealTxSigner, type RealTxSigningInput, type RealTxSigningResult, type ResolveAccountOptions, type SignTxPlanInput, type SignTxPlanResult, SimulatedSigner, SimulatedTxPlanSigner, UnsupportedKaspaKeyGenerator, UnsupportedRealKaspaSigner, UnsupportedRealTxSigner, assertSigningNetworkAllowed, createEmptyRealAccountStore, createLocalKaspaWallet, describeAccount, ensureDevAccounts, getDefaultRealAccountsPath, getKaspaSigningBackendStatus, getOrCreateDevAccount, getRealDevAccount, getRequiredEnv, importRealDevAccount, listDevAccountsSync, listHardkasAccounts, listRealDevAccounts, loadKaspaWasm, loadOrCreateRealAccountStore, loadRealAccountStore, loadRealAccountStoreSync, prepareEvmAccountExport, removeRealDevAccount, resolveHardkasAccount, resolveHardkasAccountAddress, resolveRealAccountOrAddress, saveRealAccountStore, signTxPlanArtifact, validateAccountName, validateAddressPrefix };

package/dist/index.js

@@ -277,11 +277,7 @@ function listHardkasAccounts(config) {
   }
   const keystoreDir = path2.join(process.cwd(), ".hardkas", "keystore");
   if (fs2.existsSync(keystoreDir)) {
-    if (!config || !config.cwd) {
-      throw new Error(
-        "Workspace root/cwd is required for hermetic keystore path resolution"
-      );
-    }
+    const cwd = config?.cwd || process.cwd();
     const files = fs2.readdirSync(keystoreDir);
     for (const file of files) {
       if (file.endsWith(".json")) {
@@ -312,13 +308,35 @@ function listHardkasAccounts(config) {
   }
   return Array.from(accounts.values());
 }
-function resolveHardkasAccountAddress(accountOrAddress, config, context = "L1") {
+async function resolveHardkasAccountAddress(accountOrAddress, config, context = "L1") {
   if (accountOrAddress.startsWith("kaspa:") || accountOrAddress.startsWith("kaspatest:") || accountOrAddress.startsWith("kaspasim:")) {
     if (context === "L2") {
       throw new Error(
         `Invalid L2 address provided: ${accountOrAddress}. Expected EVM address or account alias.`
       );
     }
+    if (!accountOrAddress.startsWith("kaspa:sim_")) {
+      try {
+        const kaspa = await import("kaspa-wasm");
+        try {
+          if (typeof kaspa.Address === "function" || kaspa.Address) {
+            new kaspa.Address(accountOrAddress);
+          }
+        } catch (e) {
+          const err = new Error(`HARDKAS_INVALID_ADDRESS: Invalid Kaspa address format or checksum.`);
+          err.code = "HARDKAS_INVALID_ADDRESS";
+          throw err;
+        }
+      } catch (e) {
+        if (e.code === "HARDKAS_INVALID_ADDRESS") throw e;
+        if (e.code === "ERR_MODULE_NOT_FOUND" || e.message.includes("Cannot find module") || e.message.includes("kaspa-wasm")) {
+          const err = new Error("ADDRESS_VALIDATOR_UNAVAILABLE: The Kaspa address validator backend is not available.");
+          err.code = "ADDRESS_VALIDATOR_UNAVAILABLE";
+          throw err;
+        }
+        throw e;
+      }
+    }
     return accountOrAddress;
   }
   if (accountOrAddress.startsWith("0x") && accountOrAddress.length === 42) {
@@ -420,19 +438,21 @@ function getRequiredEnv(name) {
 import {
   createSimulatedSignedTxArtifact,
   calculateContentHash as calculateContentHash2,
-  HARDKAS_VERSION as HARDKAS_VERSION2
+  HARDKAS_VERSION as HARDKAS_VERSION2,
+  createLineageTransition
 } from "@hardkas/artifacts";
 import { systemRuntimeContext } from "@hardkas/core";
 
 // src/signer-backend.ts
 async function loadKaspaWasm() {
   try {
-    const sdk = await import("kaspa");
-    return sdk;
+    return await import("kaspa-wasm");
   } catch (error) {
-    throw new Error(
-      "Kaspa WASM signing backend is not available. Please install the official 'kaspa' package: pnpm add kaspa"
+    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 function getKaspaSigningBackendStatus() {
@@ -454,6 +474,40 @@ 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
+      },
+      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)
+      }
+    })),
+    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;
@@ -485,17 +539,26 @@ var KaspaWasmPrivateKeySigner = class {
             "UTXO is missing scriptPublicKey. Real signing flows must never fabricate cryptographic state."
           );
         }
-        return new sdk.UtxoEntry(
-          BigInt(u.amountSompi),
-          spk,
-          u.outpoint.transactionId,
-          u.outpoint.index,
-          plan.from.address
-        );
+        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 new sdk.PaymentOutput(new sdk.Address(o.address), BigInt(o.amountSompi));
+        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);
@@ -506,7 +569,7 @@ var KaspaWasmPrivateKeySigner = class {
         priorityFee
       );
       const signedTx = sdk.signTransaction(unsignedTx, [privateKey], true);
-      const rawTx = signedTx.serialize ? signedTx.serialize() : JSON.stringify(signedTx.toRpcTransaction());
+      const rawTx = JSON.stringify(parseWasmTxToRpc(signedTx.toString()));
       return {
         signatureKind: "kaspa-private-key",
         signerAddress: account.address || privateKey.toAddress(plan.networkId).toString(),
@@ -624,11 +687,15 @@ async function signTxPlanArtifact(input) {
         format: result.signedTransaction?.format === "hex" ? "hex" : "unknown",
         payload: result.signedTransaction?.payload || ""
       },
+      lineage: createLineageTransition(planArtifact, "hardkas.signedTx"),
       ...planArtifact.workflowId ? { workflowId: planArtifact.workflowId } : {}
     };
     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") {
@@ -650,15 +717,17 @@ var KaspaSdkKeyGenerator = class {
   constructor(options) {
     this.networkId = options?.networkId || "simnet";
     const rawLoader = options?.sdkLoader || (async () => {
-      return await import("kaspa");
+      return await import("kaspa-wasm");
     });
     this.sdkLoader = async () => {
       try {
         return await rawLoader();
       } catch (e) {
-        throw new Error(
-          "Kaspa cryptography adapter missing. Real account generation requires WASM execution.\nRun: npm install @kaspa/wallet-wasm\nUse 'hardkas accounts real import' to add accounts manually for now."
+        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."
         );
+        err.code = "WALLET_BACKEND_UNAVAILABLE";
+        throw err;
       }
     };
   }
@@ -667,11 +736,14 @@ var KaspaSdkKeyGenerator = class {
     const network = options?.networkId || this.networkId;
     try {
       if (typeof sdk.PrivateKey === "function") {
-        const privKey = new sdk.PrivateKey();
-        const pubKey = privKey.toPublicKey();
-        const address = pubKey.toAddress(network).toString();
-        const privateKeyStr = privKey.toString();
-        const publicKeyStr = pubKey.toString();
+        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,
@@ -697,6 +769,164 @@ async function createLocalKaspaWallet(options) {
   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 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
+  };
+}
+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();
+  }
+  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)
+      };
+    });
+    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.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() {
@@ -1067,6 +1297,7 @@ function listDevAccountsSync(workspaceDir) {
 }
 export {
   DEV_ACCOUNTS_PASSWORD,
+  HardkasFixtureSigner,
   KaspaSdkKeyGenerator,
   KaspaSdkRealTxSigner,
   KaspaWasmPrivateKeySigner,

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@hardkas/accounts",
-  "version": "0.8.4-alpha",
+  "version": "0.8.9-alpha",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
+      "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "default": "./dist/index.js"
     }
   },
   "files": [
@@ -17,10 +18,11 @@
   ],
   "dependencies": {
     "hash-wasm": "^4.12.0",
-    "@hardkas/artifacts": "0.8.4-alpha",
-    "@hardkas/core": "0.8.4-alpha",
-    "@hardkas/config": "0.8.4-alpha",
-    "@hardkas/localnet": "0.8.4-alpha"
+    "kaspa-wasm": "0.13.0",
+    "@hardkas/artifacts": "0.8.9-alpha",
+    "@hardkas/config": "0.8.9-alpha",
+    "@hardkas/localnet": "0.8.9-alpha",
+    "@hardkas/core": "0.8.9-alpha"
   },
   "devDependencies": {
     "tsup": "^8.3.5",
@@ -39,8 +41,8 @@
   },
   "homepage": "https://github.com/KasLabDevs/HardKas/tree/main/packages/accounts#readme",
   "scripts": {
-    "build": "tsup src/index.ts --format esm --dts --clean --external kaspa",
-    "dev": "tsup src/index.ts --format esm --watch --dts --external kaspa",
+    "build": "tsup src/index.ts --format esm --dts --clean --external kaspa-wasm",
+    "dev": "tsup src/index.ts --format esm --watch --dts --external kaspa-wasm",
     "test": "vitest run",
     "typecheck": "tsc --noEmit"
   }