@hardkas/sdk 0.7.5-alpha → 0.7.7-alpha

package/dist/index.d.ts

@@ -30,6 +30,24 @@ declare class HardkasAccounts {
         sompi: bigint;
         formatted: string;
     }>;
+    /**
+     * Alias for getBalance.
+     */
+    balance(accountNameOrAddress: string): Promise<{
+        sompi: bigint;
+        formatted: string;
+    }>;
+    /**
+     * Lists all configured account names.
+     */
+    list(): Promise<string[]>;
+    /**
+     * Funds an account from another account (defaults to 'default' account).
+     */
+    fund(accountNameOrAddress: string, options?: {
+        from?: string;
+        amount?: string | bigint;
+    }): Promise<any>;
 }
 
 /**
@@ -73,6 +91,14 @@ declare class HardkasTx {
         receipt: TxReceiptArtifact;
         receiptPath: string;
     }>;
+    /**
+     * Explicitly appends a signature to a partially signed transaction.
+     */
+    appendSignature(plan: SignedTxArtifact, account?: HardkasAccount | string): Promise<SignedTxArtifact>;
+    /**
+     * Fetches the current status of a transaction by ID.
+     */
+    status(txId: string): Promise<any>;
 }
 
 /**
@@ -217,6 +243,14 @@ declare class HardkasArtifactsManager {
      * Reads an artifact by path or ID/hash from the workspace.
      */
     read(id: string): Promise<any>;
+    /**
+     * Alias for read().
+     */
+    get(id: string): Promise<any>;
+    /**
+     * Lists all artifacts in the workspace.
+     */
+    list(): Promise<any[]>;
 }
 
 interface WorkflowRunOptions {

package/dist/index.js

@@ -40,6 +40,36 @@ var HardkasAccounts = class {
       formatted: formatSompi(sompi)
     };
   }
+  /**
+   * Alias for getBalance.
+   */
+  async balance(accountNameOrAddress) {
+    return this.getBalance(accountNameOrAddress);
+  }
+  /**
+   * Lists all configured account names.
+   */
+  async list() {
+    return Object.keys(this.sdk.config.config.accounts || {});
+  }
+  /**
+   * Funds an account from another account (defaults to 'default' account).
+   */
+  async fund(accountNameOrAddress, options) {
+    const from = options?.from || "default";
+    const amount = options?.amount || "1000000000";
+    const plan = await this.sdk.tx.plan({
+      from,
+      to: accountNameOrAddress,
+      amount
+    });
+    const signed = await this.sdk.tx.sign(plan, from);
+    if (this.sdk.network === "simulated") {
+      return this.sdk.tx.simulate(signed);
+    } else {
+      return this.sdk.tx.send(signed);
+    }
+  }
 };
 
 // src/tx.ts
@@ -78,6 +108,9 @@ var HardkasTx = class {
     if (!toAccount.address)
       throw new Error(`To account ${toAccount.name} has no address.`);
     const amountSompi = typeof options.amount === "string" ? parseKasToSompi(options.amount) : typeof options.amount === "number" ? BigInt(options.amount) : options.amount;
+    if (amountSompi === 0n) {
+      throw new Error("Kaspa value-transfer outputs require amount > 0.\nFor metadata/notary/DID marker transactions use --amount 1.\nFuture: hardkas tx anchor.");
+    }
     let builderUtxos = [];
     if (this.sdk.network === "simulated") {
       const { loadOrCreateLocalnetState, getSpendableUtxos } = await import("@hardkas/localnet");
@@ -160,6 +193,9 @@ var HardkasTx = class {
           "Cannot append signature to an already completed signed transaction."
         );
       }
+      if (options?.append === void 0 && plan.status === "partially_signed") {
+        options = { ...options, append: true };
+      }
       if (!options?.append) {
         throw new Error(
           "Input file is a partially signed transaction. Use the --append flag to add your signature."
@@ -247,7 +283,12 @@ var HardkasTx = class {
         if (!signerAddress) {
           throw new Error(`Signer account '${resolvedAccount.name}' has no address.`);
         }
-        const requiredSigners = options?.requiredSigners || [signerAddress];
+        const requiredSignersList = options?.requiredSigners || [signerAddress];
+        const requiredSigners = [];
+        for (const r of requiredSignersList) {
+          const acc = await this.sdk.accounts.resolve(r);
+          requiredSigners.push(acc.address || r);
+        }
         if (!requiredSigners.includes(signerAddress)) {
           throw new Error(
             `Signer '${signerAddress}' is not an authorized signer for this transaction.`
@@ -378,7 +419,10 @@ var HardkasTx = class {
       endpoint: "simulated://local"
     });
     events.push({ type: "phase.completed", phase: "send", timestamp: Date.now() });
-    await saveLocalnetState(simResult.state, getDefaultLocalnetStatePath(this.sdk.workspace.root));
+    await saveLocalnetState(
+      simResult.state,
+      getDefaultLocalnetStatePath(this.sdk.workspace.root)
+    );
     const receiptPath = await saveSimulatedReceipt(
       simResult.receipt,
       { cwd: this.sdk.workspace.root }
@@ -431,11 +475,14 @@ var HardkasTx = class {
       steps: traceSteps
     };
     traceBase.contentHash = calculateContentHash(traceBase, CURRENT_HASH_VERSION);
-    await saveSimulatedTrace({
-      ...traceBase,
-      events,
-      receiptPath
-    }, { cwd: this.sdk.workspace.root });
+    await saveSimulatedTrace(
+      {
+        ...traceBase,
+        events,
+        receiptPath
+      },
+      { cwd: this.sdk.workspace.root }
+    );
     coreEvents.normalizeAndEmit({
       kind: "artifact.created",
       schema: receipt.schema,
@@ -508,6 +555,23 @@ var HardkasTx = class {
       receiptPath
     };
   }
+  /**
+   * Explicitly appends a signature to a partially signed transaction.
+   */
+  async appendSignature(plan, account) {
+    return this.sign(plan, account, { append: true });
+  }
+  /**
+   * Fetches the current status of a transaction by ID.
+   */
+  async status(txId) {
+    const isLocal = txId.startsWith("simulated-");
+    if (isLocal) {
+      return { status: "simulated_confirmed" };
+    }
+    const result = await this.sdk.rpc.getTransaction(txId);
+    return result;
+  }
 };
 
 // src/l2.ts
@@ -588,6 +652,124 @@ import {
   verifyArtifactIntegrity,
   writeArtifact as writeArtifact2
 } from "@hardkas/artifacts";
+function resolveReplayTargets(cwd, options) {
+  if (options.path) {
+    const fullPath = path.resolve(cwd, options.path);
+    if (!fs.existsSync(fullPath)) {
+      throw new Error(`Path not found: ${options.path}`);
+    }
+    if (fs.statSync(fullPath).isFile()) {
+      const dir = path.dirname(fullPath);
+      let planId = "";
+      try {
+        const data = JSON.parse(fs.readFileSync(fullPath, "utf-8"));
+        planId = data.planId || "";
+      } catch {
+      }
+      let receiptPath = "";
+      if (planId) {
+        receiptPath = findReceiptByPlanId(dir, planId);
+      }
+      return {
+        planPath: fullPath,
+        receiptPath,
+        artifactDir: dir,
+        source: "explicit-file"
+      };
+    }
+    return resolveFromDirectory(fullPath, "explicit-dir");
+  }
+  if (options.workflowId) {
+    return {
+      planPath: path.join(cwd, "tx-plan.json"),
+      receiptPath: path.join(cwd, "tx-receipt.json"),
+      artifactDir: cwd,
+      source: "workflow-id"
+    };
+  }
+  const artifactsDir = path.join(cwd, ".hardkas", "artifacts");
+  if (!fs.existsSync(artifactsDir) || !fs.statSync(artifactsDir).isDirectory()) {
+    throw new Error(
+      `No .hardkas/artifacts/ directory found.
+  Hint: Run 'hardkas init' first, then execute a transaction.`
+    );
+  }
+  return resolveFromDirectory(artifactsDir, "artifact-scan");
+}
+function resolveFromDirectory(dir, source) {
+  const allFiles = fs.readdirSync(dir).filter((f) => f.endsWith(".json"));
+  const plans = [];
+  const receipts = [];
+  for (const f of allFiles) {
+    try {
+      const raw = fs.readFileSync(path.join(dir, f), "utf-8");
+      const data = JSON.parse(raw);
+      if (!data || !data.schema) continue;
+      if (data.schema === "hardkas.txPlan") {
+        plans.push({
+          file: f,
+          planId: data.planId || "",
+          createdAt: data.createdAt || ""
+        });
+      } else if (data.schema === "hardkas.txReceipt") {
+        receipts.push({
+          file: f,
+          sourcePlanId: data.sourcePlanId || data.lineage?.parentArtifactId || data.lineage?.rootArtifactId || "",
+          txId: data.txId || "",
+          createdAt: data.createdAt || ""
+        });
+      }
+    } catch {
+    }
+  }
+  if (plans.length === 0) {
+    throw new Error(
+      `No plan artifacts found in ${dir}.
+  Hint: Run a transaction first: hardkas tx send --from alice --to bob --amount 10 --network simulated --yes`
+    );
+  }
+  plans.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+  for (const plan of plans) {
+    const matchingReceipt = receipts.find(
+      (r) => (
+        // Direct sourcePlanId match
+        r.sourcePlanId && r.sourcePlanId === plan.planId || // txId derived from planId (e.g., "simulated-plan-xxx-tx" contains "plan-xxx")
+        r.txId && plan.planId && r.txId.includes(plan.planId)
+      )
+    );
+    if (matchingReceipt) {
+      return {
+        planPath: path.join(dir, plan.file),
+        receiptPath: path.join(dir, matchingReceipt.file),
+        artifactDir: dir,
+        source
+      };
+    }
+  }
+  const bestPlan = plans[0];
+  return {
+    planPath: path.join(dir, bestPlan.file),
+    receiptPath: "",
+    // Will trigger actionable error downstream
+    artifactDir: dir,
+    source
+  };
+}
+function findReceiptByPlanId(dir, planId) {
+  if (!fs.existsSync(dir)) return "";
+  const files = fs.readdirSync(dir).filter((f) => f.endsWith(".json"));
+  for (const f of files) {
+    try {
+      const raw = fs.readFileSync(path.join(dir, f), "utf-8");
+      const data = JSON.parse(raw);
+      if (data && data.schema === "hardkas.txReceipt" && (data.sourcePlanId && data.sourcePlanId === planId || data.lineage?.parentArtifactId && data.lineage.parentArtifactId === planId || data.lineage?.rootArtifactId && data.lineage.rootArtifactId === planId || data.txId && data.txId.includes(planId))) {
+        return path.join(dir, f);
+      }
+    } catch {
+    }
+  }
+  return "";
+}
 var HardkasReplay = class {
   constructor(sdk) {
     this.sdk = sdk;
@@ -598,36 +780,8 @@ var HardkasReplay = class {
    * against the mathematically reconstructed localnet state.
    */
   async verify(options) {
-    let artifactDir = this.sdk.config.cwd;
-    let planPath = path.join(artifactDir, "tx-plan.json");
-    let receiptPath = path.join(artifactDir, "tx-receipt.json");
-    if (options.path) {
-      const fullPath = path.resolve(this.sdk.config.cwd, options.path);
-      if (fs.existsSync(fullPath)) {
-        if (fs.statSync(fullPath).isFile()) {
-          planPath = fullPath;
-          artifactDir = path.dirname(fullPath);
-          receiptPath = fullPath.replace("tx-plan", "tx-receipt");
-          try {
-            let content = fs.readFileSync(fullPath, "utf-8");
-            if (content.charCodeAt(0) === 65279) {
-              content = content.slice(1);
-            }
-            const json = JSON.parse(content);
-            if (json && json.schema === "hardkas.workflow.v1" && json.workflowId) {
-              options.workflowId = json.workflowId;
-            }
-          } catch (e) {
-          }
-        } else {
-          artifactDir = fullPath;
-          planPath = path.join(artifactDir, "tx-plan.json");
-          receiptPath = path.join(artifactDir, "tx-receipt.json");
-        }
-      } else {
-        throw new Error(`Path not found: ${options.path}`);
-      }
-    }
+    const targets = resolveReplayTargets(this.sdk.config.cwd, options);
+    let { planPath, receiptPath, artifactDir } = targets;
     if (!fs.existsSync(path.join(this.sdk.config.cwd, "hardkas.config.ts"))) {
       throw new Error(`Workspace not found at ${this.sdk.config.cwd}`);
     }
@@ -737,12 +891,15 @@ var HardkasReplay = class {
         lineageOk = false;
         determinismOk = false;
       }
-    } else if (options.path) {
+    } else if (targets.source !== "none") {
       try {
         if (!fs.existsSync(planPath))
           throw new Error(`Transaction plan artifact is missing at: ${planPath}`);
-        if (!fs.existsSync(receiptPath))
-          throw new Error(`Transaction receipt artifact is missing at: ${receiptPath}`);
+        if (!receiptPath || !fs.existsSync(receiptPath))
+          throw new Error(
+            `No matching receipt artifact found for plan at: ${planPath}
+  Hint: Run 'hardkas tx send --from alice --to bob --amount 10 --network simulated --yes' to create a complete plan\u2192sign\u2192send chain.`
+          );
         plan = await readTxPlanArtifact(planPath);
         receipt = await readTxReceiptArtifact2(receiptPath);
       } catch (err) {
@@ -920,6 +1077,33 @@ var HardkasArtifactsManager = class {
     }
     return readArtifact(filePath);
   }
+  /**
+   * Alias for read().
+   */
+  async get(id) {
+    return this.read(id);
+  }
+  /**
+   * Lists all artifacts in the workspace.
+   */
+  async list() {
+    if (!fs3.existsSync(this.workspace.artifactsDir)) {
+      return [];
+    }
+    const { readArtifact } = await import("@hardkas/artifacts");
+    const files = fs3.readdirSync(this.workspace.artifactsDir);
+    const artifacts = [];
+    for (const file of files) {
+      if (file.endsWith(".json")) {
+        try {
+          const artifact = await readArtifact(path3.join(this.workspace.artifactsDir, file));
+          artifacts.push(artifact);
+        } catch (e) {
+        }
+      }
+    }
+    return artifacts;
+  }
 };
 
 // src/workflow.ts
@@ -1003,7 +1187,9 @@ var HardkasWorkflow = class {
               },
               sign: async (plan, account) => {
                 const signed = await this.sdk.tx.sign(plan, account);
-                await this.sdk.artifacts.write(signed, { dryRun: options.dryRun ?? false });
+                await this.sdk.artifacts.write(signed, {
+                  dryRun: options.dryRun ?? false
+                });
                 const signedRecord = signed;
                 const id = signedRecord.contentHash || signedRecord.artifactId || signed.signedId;
                 if (id) producedArtifacts.push(id);
@@ -1016,7 +1202,9 @@ var HardkasWorkflow = class {
                   "Workflow script requested real broadcast"
                 );
                 const res = this.sdk.network === "simulated" ? await this.sdk.tx.simulate(signed) : await this.sdk.tx.send(signed);
-                await this.sdk.artifacts.write(res.receipt, { dryRun: options.dryRun ?? false });
+                await this.sdk.artifacts.write(res.receipt, {
+                  dryRun: options.dryRun ?? false
+                });
                 const receiptRecord = res.receipt;
                 const id = receiptRecord.contentHash || receiptRecord.artifactId || receiptRecord.txId;
                 if (id) producedArtifacts.push(id);
@@ -1024,7 +1212,9 @@ var HardkasWorkflow = class {
               },
               simulate: async (signed) => {
                 const res = await this.sdk.tx.simulate(signed);
-                await this.sdk.artifacts.write(res.receipt, { dryRun: options.dryRun ?? false });
+                await this.sdk.artifacts.write(res.receipt, {
+                  dryRun: options.dryRun ?? false
+                });
                 const receiptRecord = res.receipt;
                 const id = receiptRecord.contentHash || receiptRecord.artifactId || receiptRecord.txId;
                 if (id) producedArtifacts.push(id);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hardkas/sdk",
-  "version": "0.7.5-alpha",
+  "version": "0.7.7-alpha",
   "type": "module",
   "files": [
     "dist",
@@ -23,23 +23,23 @@
     }
   },
   "dependencies": {
-    "@hardkas/accounts": "0.7.5-alpha",
-    "@hardkas/artifacts": "0.7.5-alpha",
-    "@hardkas/l2": "0.7.5-alpha",
-    "@hardkas/core": "0.7.5-alpha",
-    "@hardkas/config": "0.7.5-alpha",
-    "@hardkas/query": "0.7.5-alpha",
-    "@hardkas/kaspa-rpc": "0.7.5-alpha",
-    "@hardkas/simulator": "0.7.5-alpha",
-    "@hardkas/tx-builder": "0.7.5-alpha",
-    "@hardkas/localnet": "0.7.5-alpha",
-    "@hardkas/wallet-adapter": "0.7.5-alpha"
+    "@hardkas/artifacts": "0.7.7-alpha",
+    "@hardkas/accounts": "0.7.7-alpha",
+    "@hardkas/core": "0.7.7-alpha",
+    "@hardkas/kaspa-rpc": "0.7.7-alpha",
+    "@hardkas/localnet": "0.7.7-alpha",
+    "@hardkas/query": "0.7.7-alpha",
+    "@hardkas/config": "0.7.7-alpha",
+    "@hardkas/simulator": "0.7.7-alpha",
+    "@hardkas/tx-builder": "0.7.7-alpha",
+    "@hardkas/l2": "0.7.7-alpha",
+    "@hardkas/wallet-adapter": "0.7.7-alpha"
   },
   "devDependencies": {
     "tsup": "^8.3.5",
     "typescript": "^5.7.2",
     "vitest": "^2.1.8",
-    "@hardkas/query-store": "0.7.5-alpha"
+    "@hardkas/query-store": "0.7.7-alpha"
   },
   "license": "MIT",
   "author": "Javier Rodriguez",