@hardkas/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Javier Rodriguez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,160 @@
+import * as _hardkas_config from '@hardkas/config';
+import { LoadedHardkasConfig } from '@hardkas/config';
+import { KaspaRpcClient } from '@hardkas/kaspa-rpc';
+import { NetworkId } from '@hardkas/core';
+export { ArtifactId, HardkasError, KaspaAddress, LineageId, NetworkId, SOMPI_PER_KAS, TxId, formatSompi, parseKasToSompi } from '@hardkas/core';
+import { TxPlanArtifact, SignedTxArtifact, TxReceiptArtifact } from '@hardkas/artifacts';
+export { ARTIFACT_SCHEMAS, HARDKAS_VERSION, SignedTxArtifact, TxPlanArtifact, TxReceiptArtifact, TxTraceArtifact, createTxPlanArtifact, writeArtifact } from '@hardkas/artifacts';
+import { HardkasAccount } from '@hardkas/accounts';
+export { signTxPlanArtifact } from '@hardkas/accounts';
+import { L2NetworkProfile } from '@hardkas/l2';
+export { buildPaymentPlan } from '@hardkas/tx-builder';
+
+/**
+ * HardKAS Accounts Module
+ * @alpha
+ */
+declare class HardkasAccounts {
+    private sdk;
+    constructor(sdk: Hardkas);
+    /**
+     * Resolves an account by name or address.
+     */
+    resolve(nameOrAddress: string): Promise<HardkasAccount>;
+    /**
+     * Fetches the balance for an account.
+     */
+    getBalance(accountNameOrAddress: string): Promise<{
+        sompi: bigint;
+        formatted: string;
+    }>;
+}
+
+/**
+ * HardKAS Transaction Module
+ * @alpha
+ */
+declare class HardkasTx {
+    private sdk;
+    constructor(sdk: Hardkas);
+    /**
+     * Plans a transaction.
+     */
+    plan(options: {
+        from: string | HardkasAccount;
+        to: string | HardkasAccount;
+        amount: string | bigint;
+        feeRate?: bigint;
+    }): Promise<TxPlanArtifact>;
+    /**
+     * Signs a transaction plan.
+     */
+    sign(plan: TxPlanArtifact, account?: HardkasAccount | string): Promise<SignedTxArtifact>;
+    /**
+     * Sends a signed transaction.
+     */
+    send(signed: SignedTxArtifact): Promise<TxReceiptArtifact>;
+}
+
+/**
+ * HardKAS L2 Module
+ * @alpha
+ */
+declare class HardkasL2 {
+    /**
+     * Lists all available L2 network profiles.
+     */
+    listProfiles(): readonly L2NetworkProfile[];
+    /**
+     * Gets a specific L2 network profile by name.
+     */
+    getProfile(name: string): L2NetworkProfile | null;
+}
+
+/**
+ * HardKAS Operational Query Module
+ *
+ * Note: readEvents, correlate, and correlation types were removed from
+ * @hardkas/query. These will be re-implemented when the query API stabilizes.
+ * @alpha
+ */
+declare class HardkasQuery {
+    private sdk;
+    private _engine;
+    constructor(sdk: Hardkas);
+    /**
+     * Internal lazy-loaded query engine.
+     */
+    private getEngine;
+}
+
+/**
+ * HardKAS Localnet Simulation Module
+ */
+declare class HardkasLocalnet {
+    private sdk;
+    constructor(sdk: Hardkas);
+    /**
+     * Status check for the localnet simulation.
+     */
+    isAlive(): Promise<boolean>;
+    /**
+     * Future: control localnet process/container from here.
+     */
+    start(): Promise<void>;
+}
+
+interface TaskArgs {
+    [key: string]: string | boolean | undefined;
+}
+interface TaskContext {
+    hardkas: Hardkas;
+    args: TaskArgs;
+}
+type TaskAction = (ctx: TaskContext) => Promise<void>;
+/**
+ * Defines a new HardKAS task.
+ * Used in hardkas.config.ts to extend CLI functionality.
+ */
+declare const defineTask: {
+    (name: string, action: TaskAction): void;
+    (name: string, description: string, action: TaskAction): void;
+};
+
+interface HardkasOptions {
+    cwd?: string;
+    configPath?: string;
+}
+/**
+ * HardKAS SDK - Main Entry Point
+ *
+ * Provides a high-level facade for interacting with the Kaspa ecosystem.
+ * Acts as a DI container and coordinator.
+ */
+declare class Hardkas {
+    readonly config: LoadedHardkasConfig;
+    readonly accounts: HardkasAccounts;
+    readonly tx: HardkasTx;
+    readonly l2: HardkasL2;
+    readonly query: HardkasQuery;
+    readonly localnet: HardkasLocalnet;
+    readonly rpc: KaspaRpcClient;
+    private constructor();
+    private resolveRpcUrl;
+    /**
+     * Opens a HardKAS project in the given directory.
+     */
+    static open(dirOrOptions?: string | HardkasOptions): Promise<Hardkas>;
+    /**
+     * Alias for open(). Used in most examples.
+     */
+    static create(dirOrOptions?: string | HardkasOptions): Promise<Hardkas>;
+    /**
+     * Current active network name.
+     */
+    get network(): NetworkId;
+    get sdkConfig(): _hardkas_config.HardkasConfig;
+    get cwd(): string;
+}
+
+export { Hardkas, HardkasAccounts, HardkasL2, HardkasLocalnet, type HardkasOptions, HardkasQuery, HardkasTx, type TaskArgs, type TaskContext, defineTask };

package/dist/index.js

@@ -0,0 +1,338 @@
+// src/index.ts
+import { loadHardkasConfig as loadConfig } from "@hardkas/config";
+import { JsonWrpcKaspaClient } from "@hardkas/kaspa-rpc";
+
+// src/accounts.ts
+import {
+  resolveHardkasAccount
+} from "@hardkas/accounts";
+import { formatSompi } from "@hardkas/core";
+var HardkasAccounts = class {
+  constructor(sdk) {
+    this.sdk = sdk;
+  }
+  sdk;
+  /**
+   * Resolves an account by name or address.
+   */
+  async resolve(nameOrAddress) {
+    return resolveHardkasAccount({
+      nameOrAddress,
+      config: this.sdk.config.config
+    });
+  }
+  /**
+   * Fetches the balance for an account.
+   */
+  async getBalance(accountNameOrAddress) {
+    const account = await this.resolve(accountNameOrAddress);
+    if (!account.address) throw new Error(`Account ${accountNameOrAddress} has no address`);
+    const { balanceSompi } = await this.sdk.rpc.getBalanceByAddress(account.address);
+    const sompi = BigInt(balanceSompi);
+    return {
+      sompi,
+      formatted: formatSompi(sompi)
+    };
+  }
+};
+
+// src/tx.ts
+import {
+  buildPaymentPlan
+} from "@hardkas/tx-builder";
+import {
+  HARDKAS_VERSION,
+  getBroadcastableSignedTransaction,
+  writeArtifact,
+  getDefaultReceiptPath,
+  createTxPlanArtifact,
+  calculateContentHash
+} from "@hardkas/artifacts";
+import { signTxPlanArtifact } from "@hardkas/accounts";
+import { parseKasToSompi } from "@hardkas/core";
+var HardkasTx = class {
+  constructor(sdk) {
+    this.sdk = sdk;
+  }
+  sdk;
+  /**
+   * Plans a transaction.
+   */
+  async plan(options) {
+    const fromAccount = typeof options.from === "string" ? await this.sdk.accounts.resolve(options.from) : options.from;
+    const toAccount = typeof options.to === "string" ? await this.sdk.accounts.resolve(options.to) : options.to;
+    if (!fromAccount.address) throw new Error(`From account ${fromAccount.name} has no address.`);
+    if (!toAccount.address) throw new Error(`To account ${toAccount.name} has no address.`);
+    const amountSompi = typeof options.amount === "string" ? parseKasToSompi(options.amount) : options.amount;
+    const rpcUtxos = await this.sdk.rpc.getUtxosByAddress(fromAccount.address);
+    const builderUtxos = rpcUtxos.map((u) => ({
+      outpoint: {
+        transactionId: u.outpoint.transactionId,
+        index: u.outpoint.index
+      },
+      address: u.address,
+      amountSompi: u.amountSompi,
+      scriptPublicKey: u.scriptPublicKey || ""
+    }));
+    const builderPlan = buildPaymentPlan({
+      fromAddress: fromAccount.address,
+      availableUtxos: builderUtxos,
+      outputs: [{
+        address: toAccount.address,
+        amountSompi
+      }],
+      feeRateSompiPerMass: options.feeRate ?? 1n
+    });
+    return createTxPlanArtifact({
+      networkId: this.sdk.network,
+      mode: "simulated",
+      from: {
+        input: fromAccount.name || fromAccount.address,
+        address: fromAccount.address,
+        accountName: fromAccount.name
+      },
+      to: {
+        input: toAccount.name || toAccount.address,
+        address: toAccount.address
+      },
+      amountSompi,
+      plan: builderPlan
+    });
+  }
+  /**
+   * Signs a transaction plan.
+   */
+  async sign(plan, account) {
+    let resolvedAccount;
+    if (typeof account === "string") {
+      resolvedAccount = await this.sdk.accounts.resolve(account);
+    } else if (account) {
+      resolvedAccount = account;
+    } else {
+      if (!plan.from.accountName) throw new Error("Plan does not specify an account name and no account was provided for signing.");
+      resolvedAccount = await this.sdk.accounts.resolve(plan.from.accountName);
+    }
+    return signTxPlanArtifact({
+      planArtifact: plan,
+      account: resolvedAccount,
+      config: this.sdk.config.config
+    });
+  }
+  /**
+   * Sends a signed transaction.
+   */
+  async send(signed) {
+    const broadcastable = getBroadcastableSignedTransaction(signed);
+    const result = await this.sdk.rpc.submitTransaction(broadcastable.rawTransaction);
+    const txId = result.transactionId;
+    if (!txId) throw new Error("Broadcast failed: RPC returned no transaction ID.");
+    const receipt = {
+      schema: "hardkas.txReceipt",
+      hardkasVersion: HARDKAS_VERSION,
+      version: "1.0.0-alpha",
+      networkId: signed.networkId,
+      mode: signed.mode,
+      status: "accepted",
+      createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+      txId,
+      from: {
+        address: signed.from.address
+      },
+      to: {
+        address: signed.to.address
+      },
+      amountSompi: String(signed.amountSompi),
+      feeSompi: String(signed.estimatedFeeSompi || "0")
+    };
+    receipt.contentHash = calculateContentHash(receipt);
+    const receiptPath = getDefaultReceiptPath(txId, this.sdk.config.cwd);
+    await writeArtifact(receiptPath, receipt);
+    return {
+      ...receipt,
+      receiptPath
+    };
+  }
+};
+
+// src/l2.ts
+import {
+  listL2Profiles,
+  getL2Profile
+} from "@hardkas/l2";
+var HardkasL2 = class {
+  /**
+   * Lists all available L2 network profiles.
+   */
+  listProfiles() {
+    return listL2Profiles();
+  }
+  /**
+   * Gets a specific L2 network profile by name.
+   */
+  getProfile(name) {
+    return getL2Profile(name);
+  }
+};
+
+// src/query.ts
+var HardkasQuery = class {
+  constructor(sdk) {
+    this.sdk = sdk;
+  }
+  sdk;
+  _engine = null;
+  /**
+   * Internal lazy-loaded query engine.
+   */
+  async getEngine() {
+    if (this._engine) return this._engine;
+    const { QueryEngine } = await import("@hardkas/query");
+    this._engine = new QueryEngine({
+      artifactDir: this.sdk.config.cwd
+    });
+    return this._engine;
+  }
+};
+
+// src/localnet.ts
+var HardkasLocalnet = class {
+  constructor(sdk) {
+    this.sdk = sdk;
+  }
+  sdk;
+  /**
+   * Status check for the localnet simulation.
+   */
+  async isAlive() {
+    try {
+      const info = await this.sdk.rpc.getInfo();
+      return info.isSynced === true;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Future: control localnet process/container from here.
+   */
+  async start() {
+    console.log("Localnet control via SDK is not yet implemented.");
+    console.log("Please use 'hardkas localnet' CLI command.");
+  }
+};
+
+// src/tasks.ts
+var TaskRegistry = class {
+  tasks = /* @__PURE__ */ new Map();
+  defineTask(name, descriptionOrAction, action) {
+    let description;
+    let finalAction;
+    if (typeof descriptionOrAction === "string") {
+      description = descriptionOrAction;
+      finalAction = action;
+    } else {
+      finalAction = descriptionOrAction;
+    }
+    this.tasks.set(name, {
+      name,
+      description,
+      action: finalAction
+    });
+  }
+  getTask(name) {
+    return this.tasks.get(name);
+  }
+  getTasks() {
+    return Array.from(this.tasks.values());
+  }
+};
+var taskRegistry = new TaskRegistry();
+var defineTask = taskRegistry.defineTask.bind(taskRegistry);
+
+// src/index.ts
+import { buildPaymentPlan as buildPaymentPlan2 } from "@hardkas/tx-builder";
+import { signTxPlanArtifact as signTxPlanArtifact2 } from "@hardkas/accounts";
+import {
+  writeArtifact as writeArtifact2,
+  createTxPlanArtifact as createTxPlanArtifact2,
+  ARTIFACT_SCHEMAS,
+  HARDKAS_VERSION as HARDKAS_VERSION2
+} from "@hardkas/artifacts";
+import {
+  SOMPI_PER_KAS,
+  HardkasError,
+  parseKasToSompi as parseKasToSompi2,
+  formatSompi as formatSompi2
+} from "@hardkas/core";
+var Hardkas = class _Hardkas {
+  constructor(config, rpc) {
+    this.config = config;
+    this.rpc = rpc || new JsonWrpcKaspaClient({
+      rpcUrl: this.resolveRpcUrl()
+    });
+    this.accounts = new HardkasAccounts(this);
+    this.tx = new HardkasTx(this);
+    this.l2 = new HardkasL2();
+    this.query = new HardkasQuery(this);
+    this.localnet = new HardkasLocalnet(this);
+  }
+  config;
+  accounts;
+  tx;
+  l2;
+  query;
+  localnet;
+  rpc;
+  resolveRpcUrl() {
+    const networkId = this.config.config.defaultNetwork || "simnet";
+    const target = this.config.config.networks?.[networkId];
+    if (target && (target.kind === "kaspa-rpc" || target.kind === "igra" || target.kind === "kaspa-node")) {
+      return target.rpcUrl || "ws://127.0.0.1:18210";
+    }
+    return "ws://127.0.0.1:18210";
+  }
+  /**
+   * Opens a HardKAS project in the given directory.
+   */
+  static async open(dirOrOptions = ".") {
+    const options = typeof dirOrOptions === "string" ? { cwd: dirOrOptions } : dirOrOptions;
+    const loaded = await loadConfig(options);
+    return new _Hardkas(loaded);
+  }
+  /**
+   * Alias for open(). Used in most examples.
+   */
+  static async create(dirOrOptions = ".") {
+    return this.open(dirOrOptions);
+  }
+  /**
+   * Current active network name.
+   */
+  get network() {
+    return this.sdkConfig.defaultNetwork || "simnet";
+  }
+  get sdkConfig() {
+    return this.config.config;
+  }
+  get cwd() {
+    return this.config.cwd;
+  }
+};
+export {
+  ARTIFACT_SCHEMAS,
+  HARDKAS_VERSION2 as HARDKAS_VERSION,
+  Hardkas,
+  HardkasAccounts,
+  HardkasError,
+  HardkasL2,
+  HardkasLocalnet,
+  HardkasQuery,
+  HardkasTx,
+  SOMPI_PER_KAS,
+  buildPaymentPlan2 as buildPaymentPlan,
+  createTxPlanArtifact2 as createTxPlanArtifact,
+  defineTask,
+  formatSompi2 as formatSompi,
+  parseKasToSompi2 as parseKasToSompi,
+  signTxPlanArtifact2 as signTxPlanArtifact,
+  writeArtifact2 as writeArtifact
+};

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@hardkas/sdk",
+  "version": "0.1.0",
+  "type": "module",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "dependencies": {
+    "@hardkas/accounts": "0.1.0",
+    "@hardkas/artifacts": "0.1.0",
+    "@hardkas/kaspa-rpc": "0.1.0",
+    "@hardkas/config": "0.1.0",
+    "@hardkas/query": "0.1.0",
+    "@hardkas/core": "0.1.0",
+    "@hardkas/l2": "0.1.0",
+    "@hardkas/simulator": "0.1.0",
+    "@hardkas/tx-builder": "0.1.0",
+    "@hardkas/wallet-adapter": "0.1.0",
+    "@hardkas/localnet": "0.1.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  },
+  "license": "MIT",
+  "author": "Javier Rodriguez",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jrodrg92/Hardkas.git",
+    "directory": "packages/sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/jrodrg92/Hardkas/issues"
+  },
+  "homepage": "https://github.com/jrodrg92/Hardkas/tree/main/packages/sdk#readme",
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint ."
+  }
+}