@hardkas/tx-builder 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,150 @@
+interface MassBreakdown {
+    base: bigint;
+    inputs: bigint;
+    outputs: bigint;
+    payload: bigint;
+    total: bigint;
+}
+interface MassEstimateResult {
+    mass: bigint;
+    feeSompi: bigint;
+    breakdown: MassBreakdown;
+    assumptions: string[];
+    warnings: string[];
+}
+/**
+ * Protocol-aware mass estimation constants for Kaspa (approximate).
+ * These values align with standard P2PK/Schnorr transactions.
+ */
+declare const KASPA_MASS_CONSTANTS: {
+    /** Base transaction overhead (version, locktime, subnetwork id, gas, etc.) */
+    readonly BASE_TRANSACTION: 100n;
+    /** Mass per input (Outpoint + Sequence + SigScript + SigOpCount) */
+    readonly INPUT_P2PK: 150n;
+    /** Mass per output (Amount + ScriptPublicKey length prefix + ScriptPublicKey) */
+    readonly OUTPUT_P2PK: 50n;
+    /** Fallback mass for unknown script types (P2SH, etc.) */
+    readonly SCRIPT_FALLBACK: 150n;
+    /** Mass per byte of payload */
+    readonly PAYLOAD_BYTE: 1n;
+};
+/**
+ * Estimates the mass of a transaction based on its structure and script types.
+ *
+ * Note: alpha mass estimation is protocol-aware but still validated
+ * as best-effort until parity tests with kaspad/rusty-kaspa are complete.
+ */
+declare function estimateTransactionMass(input: {
+    inputCount: number;
+    outputs: readonly {
+        address: string;
+        scriptPublicKey?: string;
+    }[];
+    payloadBytes?: number;
+    hasChange?: boolean;
+}): MassEstimateResult;
+/**
+ * Calculates fee from mass and fee rate.
+ */
+declare function estimateFeeFromMass(mass: bigint, feeRateSompiPerMass: bigint): bigint;
+
+type SemanticVerificationSeverity = "info" | "warning" | "error" | "critical";
+interface SemanticVerificationIssue {
+    code: string;
+    severity: SemanticVerificationSeverity;
+    message: string;
+    path?: string | undefined;
+}
+interface SemanticVerificationResult {
+    ok: boolean;
+    issues: SemanticVerificationIssue[];
+    recomputedFeeSompi: bigint;
+    recomputedMass: bigint;
+    inputTotalSompi: bigint;
+    outputTotalSompi: bigint;
+    changeAmountSompi: bigint;
+}
+interface SemanticVerifyContext {
+    /** Known UTXOs to verify lineage against */
+    utxoContext?: {
+        address: string;
+        amountSompi: bigint;
+        outpoint: {
+            transactionId: string;
+            index: number;
+        };
+    }[];
+    /** Expected change address */
+    expectedChangeAddress?: string;
+    /** Minimum fee rate required by the node */
+    minFeeRate?: bigint;
+}
+/**
+ * Performs deep semantic verification of a transaction plan.
+ * Validates economic invariants, mass computation, and operational consistency.
+ */
+declare function verifyTxPlanSemantics(plan: TxPlan, context?: SemanticVerifyContext): SemanticVerificationResult;
+/**
+ * Performs semantic verification of a signed transaction artifact.
+ */
+declare function verifySignedTxSemantics(signed: any, // Using any for artifact structure compatibility without circular deps
+plan?: TxPlan): {
+    ok: boolean;
+    issues: SemanticVerificationIssue[];
+};
+/**
+ * Performs semantic verification of a transaction receipt artifact.
+ */
+declare function verifyTxReceiptSemantics(receipt: any): {
+    ok: boolean;
+    issues: SemanticVerificationIssue[];
+};
+
+type Sompi = bigint;
+
+interface Outpoint {
+    readonly transactionId: string;
+    readonly index: number;
+}
+interface Utxo {
+    readonly outpoint: Outpoint;
+    readonly address: string;
+    readonly amountSompi: Sompi;
+    readonly scriptPublicKey: string;
+    readonly blockDaaScore?: bigint;
+    readonly isCoinbase?: boolean;
+}
+interface TxOutput {
+    readonly address: string;
+    readonly amountSompi: Sompi;
+    /** Future: Silverscript / custom script support */
+    readonly scriptPublicKey?: string;
+}
+interface TxBuildRequest {
+    readonly fromAddress: string;
+    readonly outputs: readonly TxOutput[];
+    readonly availableUtxos: readonly Utxo[];
+    readonly feeRateSompiPerMass: bigint;
+    readonly changeAddress?: string;
+    readonly payloadBytes?: number;
+}
+interface TxPlan {
+    readonly inputs: readonly Utxo[];
+    readonly outputs: readonly TxOutput[];
+    readonly change?: TxOutput | undefined;
+    readonly estimatedMass: bigint;
+    readonly estimatedFeeSompi: bigint;
+}
+declare function buildPaymentPlan(request: TxBuildRequest): TxPlan;
+declare function estimateMass(input: {
+    readonly inputCount: number;
+    readonly outputCount: number;
+    readonly payloadBytes: number;
+}): bigint;
+declare function createMockUtxo(input: {
+    readonly address: string;
+    readonly amountSompi: bigint;
+    readonly index?: number;
+}): Utxo;
+
+export { KASPA_MASS_CONSTANTS, type MassBreakdown, type MassEstimateResult, type Outpoint, type SemanticVerificationIssue, type SemanticVerificationResult, type SemanticVerificationSeverity, type SemanticVerifyContext, type Sompi, type TxBuildRequest, type TxOutput, type TxPlan, type Utxo, buildPaymentPlan, createMockUtxo, estimateFeeFromMass, estimateMass, estimateTransactionMass, verifySignedTxSemantics, verifyTxPlanSemantics, verifyTxReceiptSemantics };

package/dist/index.js

@@ -0,0 +1,280 @@
+// src/mass.ts
+var KASPA_MASS_CONSTANTS = {
+  /** Base transaction overhead (version, locktime, subnetwork id, gas, etc.) */
+  BASE_TRANSACTION: 100n,
+  /** Mass per input (Outpoint + Sequence + SigScript + SigOpCount) */
+  INPUT_P2PK: 150n,
+  /** Mass per output (Amount + ScriptPublicKey length prefix + ScriptPublicKey) */
+  OUTPUT_P2PK: 50n,
+  /** Fallback mass for unknown script types (P2SH, etc.) */
+  SCRIPT_FALLBACK: 150n,
+  /** Mass per byte of payload */
+  PAYLOAD_BYTE: 1n
+};
+function estimateTransactionMass(input) {
+  const assumptions = [];
+  const warnings = [];
+  const base = KASPA_MASS_CONSTANTS.BASE_TRANSACTION;
+  const inputs = BigInt(input.inputCount) * KASPA_MASS_CONSTANTS.INPUT_P2PK;
+  assumptions.push(`Inputs assumed P2PK/Schnorr (${input.inputCount})`);
+  let outputs = 0n;
+  for (const out of input.outputs) {
+    if (isP2PK(out.scriptPublicKey || out.address)) {
+      outputs += KASPA_MASS_CONSTANTS.OUTPUT_P2PK;
+    } else {
+      outputs += KASPA_MASS_CONSTANTS.SCRIPT_FALLBACK;
+      warnings.push(`P2SH/Other script detected for address: ${out.address}. Mass is estimated using placeholder script-size assumptions.`);
+    }
+  }
+  if (input.hasChange) {
+    outputs += KASPA_MASS_CONSTANTS.OUTPUT_P2PK;
+  }
+  const payload = BigInt(input.payloadBytes || 0) * KASPA_MASS_CONSTANTS.PAYLOAD_BYTE;
+  const total = base + inputs + outputs + payload;
+  return {
+    mass: total,
+    feeSompi: 0n,
+    // Placeholder, calculated by caller
+    breakdown: {
+      base,
+      inputs,
+      outputs,
+      payload,
+      total
+    },
+    assumptions,
+    warnings
+  };
+}
+function isP2PK(addressOrScript) {
+  if (/^[0-9a-fA-F]+$/.test(addressOrScript)) {
+    return addressOrScript.length === 68;
+  }
+  if (addressOrScript.includes(":")) {
+    const parts = addressOrScript.split(":");
+    const body = parts[1];
+    return !!body && (body.startsWith("q") || body.startsWith("sim_"));
+  }
+  return true;
+}
+function estimateFeeFromMass(mass, feeRateSompiPerMass) {
+  return mass * feeRateSompiPerMass;
+}
+
+// src/verify.ts
+function verifyTxPlanSemantics(plan, context = {}) {
+  const issues = [];
+  const addIssue = (code, severity, message, path) => {
+    issues.push({ code, severity, message, ...path ? { path } : {} });
+  };
+  if (plan.mode === "simulated" && plan.networkId !== "simnet") {
+    addIssue("ENV_CONSISTENCY_FAILURE", "error", `Environment mismatch: simulated plan must target 'simnet', but targets '${plan.networkId}'`);
+  }
+  if (!plan.inputs.every((i) => i.address.includes(":"))) {
+    addIssue("INVALID_ADDRESS_FORMAT", "error", "One or more input addresses are missing prefix (e.g. kaspa:)");
+  }
+  if (!plan.outputs.every((o) => o.address.includes(":"))) {
+    addIssue("INVALID_ADDRESS_FORMAT", "error", "One or more output addresses are missing prefix (e.g. kaspa:)");
+  }
+  const inputTotalSompi = plan.inputs.reduce((sum, i) => sum + BigInt(i.amountSompi), 0n);
+  const outputTotalSompi = plan.outputs.reduce((sum, o) => sum + BigInt(o.amountSompi), 0n);
+  const changeAmountSompi = plan.change ? BigInt(plan.change.amountSompi) : 0n;
+  const planFeeSompi = BigInt(plan.estimatedFeeSompi);
+  const recomputedFeeSompi = inputTotalSompi - outputTotalSompi - changeAmountSompi;
+  if (inputTotalSompi <= 0n) {
+    addIssue("ZERO_INPUTS", "critical", "Transaction has zero or negative total inputs.");
+  }
+  if (outputTotalSompi <= 0n) {
+    addIssue("ZERO_OUTPUTS", "error", "Transaction has zero or negative total outputs (excluding change).");
+  }
+  if (recomputedFeeSompi < 0n) {
+    addIssue("NEGATIVE_FEE", "critical", `Negative fee detected: inputs (${inputTotalSompi}) < outputs + change (${outputTotalSompi + changeAmountSompi})`);
+  }
+  const massResult = estimateTransactionMass({
+    inputCount: plan.inputs.length,
+    outputs: plan.outputs,
+    hasChange: !!plan.change
+  });
+  const recomputedMass = massResult.mass;
+  if (recomputedMass !== BigInt(plan.estimatedMass)) {
+    addIssue("MASS_MISMATCH", "critical", `Mass mismatch: plan says ${plan.estimatedMass}, recomputed ${recomputedMass}`);
+  }
+  if (planFeeSompi !== recomputedFeeSompi) {
+    addIssue("FEE_MISMATCH", "critical", `Fee mismatch: estimatedFeeSompi (${planFeeSompi}) does not match input-output delta (${recomputedFeeSompi})`);
+  }
+  plan.outputs.forEach((o, i) => {
+    if (BigInt(o.amountSompi) <= 0n) {
+      addIssue("INVALID_OUTPUT_AMOUNT", "error", `Output ${i} has non-positive amount: ${o.amountSompi}`, `outputs[${i}]`);
+    }
+    if (BigInt(o.amountSompi) < 600n) {
+      addIssue("DUST_OUTPUT", "warning", `Output ${i} might be dust: ${o.amountSompi} sompi`, `outputs[${i}]`);
+    }
+  });
+  if (plan.change && BigInt(plan.change.amountSompi) < 600n) {
+    addIssue("DUST_CHANGE", "warning", `Change output might be dust: ${plan.change.amountSompi} sompi`, "change");
+  }
+  const seenInputs = /* @__PURE__ */ new Set();
+  plan.inputs.forEach((input, i) => {
+    const id = `${input.outpoint.transactionId}:${input.outpoint.index}`;
+    if (seenInputs.has(id)) {
+      addIssue("DUPLICATE_INPUT", "critical", `Duplicate input detected: ${id}`, `inputs[${i}]`);
+    }
+    seenInputs.add(id);
+  });
+  if (context.utxoContext) {
+    plan.inputs.forEach((input, i) => {
+      const match = context.utxoContext?.find(
+        (u) => u.outpoint.transactionId === input.outpoint.transactionId && u.outpoint.index === input.outpoint.index
+      );
+      if (!match) {
+        addIssue("UNKNOWN_INPUT", "error", `Input ${i} not found in provided UTXO context`, `inputs[${i}]`);
+      } else if (BigInt(match.amountSompi) !== BigInt(input.amountSompi)) {
+        addIssue("INPUT_AMOUNT_MISMATCH", "critical", `Input ${i} amount mismatch: plan says ${input.amountSompi}, context says ${match.amountSompi}`, `inputs[${i}]`);
+      }
+    });
+  }
+  if (context.expectedChangeAddress && plan.change) {
+    if (plan.change.address !== context.expectedChangeAddress) {
+      addIssue("CHANGE_ADDRESS_MISMATCH", "error", `Change address mismatch: expected ${context.expectedChangeAddress}, got ${plan.change.address}`, "change.address");
+    }
+  }
+  return {
+    ok: issues.every((i) => i.severity !== "error" && i.severity !== "critical"),
+    issues,
+    recomputedFeeSompi,
+    recomputedMass,
+    inputTotalSompi,
+    outputTotalSompi,
+    changeAmountSompi
+  };
+}
+function verifySignedTxSemantics(signed, plan) {
+  const issues = [];
+  const addIssue = (code, severity, message) => {
+    issues.push({ code, severity, message });
+  };
+  if (plan) {
+    if (signed.sourcePlanId !== plan.planId && signed.sourcePlanId !== plan.contentHash) {
+    }
+    if (BigInt(signed.amountSompi) !== BigInt(plan.amountSompi)) {
+      addIssue("IMMUTABLE_FIELD_MUTATION", "critical", `Security violation: amountSompi changed from ${plan.amountSompi} to ${signed.amountSompi} after signing`);
+    }
+    if (signed.networkId !== plan.networkId) {
+      addIssue("NETWORK_MISMATCH", "critical", `Security violation: networkId changed from ${plan.networkId} to ${signed.networkId} after signing`);
+    }
+  }
+  if (!signed.signedTransaction?.payload) {
+    addIssue("MISSING_PAYLOAD", "error", "Signed transaction is missing its raw payload");
+  }
+  return {
+    ok: issues.every((i) => i.severity !== "error" && i.severity !== "critical"),
+    issues
+  };
+}
+function verifyTxReceiptSemantics(receipt) {
+  const issues = [];
+  const addIssue = (code, severity, message) => {
+    issues.push({ code, severity, message });
+  };
+  if (receipt.status === "accepted" && !receipt.txId) {
+    addIssue("MISSING_TXID", "error", "Accepted receipt is missing transaction ID");
+  }
+  if (receipt.mode === "simulated" && !receipt.tracePath) {
+    addIssue("MISSING_TRACE", "warning", "Simulated receipt is missing trace path");
+  }
+  return {
+    ok: issues.every((i) => i.severity !== "error" && i.severity !== "critical"),
+    issues
+  };
+}
+
+// src/index.ts
+function buildPaymentPlan(request) {
+  if (request.outputs.length === 0) {
+    throw new Error("At least one transaction output is required.");
+  }
+  const target = request.outputs.reduce(
+    (sum, output) => sum + output.amountSompi,
+    0n
+  );
+  if (target <= 0n) {
+    throw new Error("Transaction amount must be positive.");
+  }
+  const sortedUtxos = [...request.availableUtxos].sort(
+    (a, b) => a.amountSompi < b.amountSompi ? -1 : a.amountSompi > b.amountSompi ? 1 : 0
+  );
+  const selected = [];
+  let selectedAmount = 0n;
+  for (const utxo of sortedUtxos) {
+    selected.push(utxo);
+    selectedAmount += utxo.amountSompi;
+    if (selectedAmount < target) continue;
+    const result = estimateTransactionMass({
+      inputCount: selected.length,
+      outputs: request.outputs,
+      payloadBytes: request.payloadBytes ?? 0,
+      hasChange: true
+      // Optimistic assumption for the loop
+    });
+    const estimatedMass = result.mass;
+    const estimatedFeeSompi = estimatedMass * request.feeRateSompiPerMass;
+    if (selectedAmount >= target + estimatedFeeSompi) {
+      const changeAmount = selectedAmount - target - estimatedFeeSompi;
+      const hasActualChange = changeAmount > 0n;
+      let finalMass = estimatedMass;
+      let finalFee = estimatedFeeSompi;
+      if (!hasActualChange) {
+        const noChangeResult = estimateTransactionMass({
+          inputCount: selected.length,
+          outputs: request.outputs,
+          payloadBytes: request.payloadBytes ?? 0,
+          hasChange: false
+        });
+        finalMass = noChangeResult.mass;
+        finalFee = finalMass * request.feeRateSompiPerMass;
+        if (selectedAmount < target + finalFee) continue;
+      }
+      return {
+        inputs: selected,
+        outputs: request.outputs,
+        change: hasActualChange ? {
+          address: request.changeAddress ?? request.fromAddress,
+          amountSompi: changeAmount
+        } : void 0,
+        estimatedMass: finalMass,
+        estimatedFeeSompi: finalFee
+      };
+    }
+  }
+  throw new Error("Insufficient funds for transaction amount plus estimated fee.");
+}
+function estimateMass(input) {
+  return estimateTransactionMass({
+    inputCount: input.inputCount,
+    outputs: Array(input.outputCount - 1).fill({ address: "" }),
+    payloadBytes: input.payloadBytes,
+    hasChange: true
+  }).mass;
+}
+function createMockUtxo(input) {
+  return {
+    outpoint: {
+      transactionId: `mock-${input.address}-${input.index ?? 0}`,
+      index: input.index ?? 0
+    },
+    address: input.address,
+    amountSompi: input.amountSompi,
+    scriptPublicKey: "mock-script"
+  };
+}
+export {
+  KASPA_MASS_CONSTANTS,
+  buildPaymentPlan,
+  createMockUtxo,
+  estimateFeeFromMass,
+  estimateMass,
+  estimateTransactionMass,
+  verifySignedTxSemantics,
+  verifyTxPlanSemantics,
+  verifyTxReceiptSemantics
+};

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@hardkas/tx-builder",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "dependencies": {
+    "@hardkas/core": "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/tx-builder"
+  },
+  "bugs": {
+    "url": "https://github.com/jrodrg92/Hardkas/issues"
+  },
+  "homepage": "https://github.com/jrodrg92/Hardkas/tree/main/packages/tx-builder#readme",
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint ."
+  }
+}