@hardkas/bridge-local 0.4.0-alpha

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,74 @@
+import { NetworkId } from '@hardkas/core';
+import { TxPlan, Utxo } from '@hardkas/tx-builder';
+import { LoadedHardkasConfig } from '@hardkas/config';
+
+interface BridgeEntryPayload {
+    readonly marker: string;
+    readonly targetEvmAddress: string;
+    readonly amountSompi: bigint;
+    readonly networkId: NetworkId;
+    readonly nonce?: number;
+}
+/**
+ * Deterministically serializes a bridge entry payload to hex.
+ */
+declare function serializeBridgePayload(payload: BridgeEntryPayload): string;
+declare function deserializeBridgePayload(hex: string): BridgeEntryPayload;
+
+interface MiningResult {
+    readonly nonce: number;
+    readonly hash: string;
+    readonly attempts: number;
+}
+/**
+ * Simulates prefix mining by incrementing a nonce until the deterministic hash
+ * of the payload matches the desired prefix.
+ */
+declare function simulatePrefixMining(payloadBase: Omit<BridgeEntryPayload, "nonce">, prefix: string, options?: {
+    initialNonce?: number;
+    maxAttempts?: number;
+    timeoutMs?: number;
+}): MiningResult;
+
+interface BridgePlanRequest {
+    readonly fromAddress: string;
+    readonly targetEvmAddress: string;
+    readonly amountSompi: bigint;
+    readonly networkId: NetworkId;
+    readonly availableUtxos: readonly Utxo[];
+}
+interface BridgePlan extends TxPlan {
+    readonly bridgePayload: BridgeEntryPayload;
+    readonly serializedPayload: string;
+}
+declare function planBridgeEntry(request: BridgePlanRequest): BridgePlan;
+
+type BridgeLocalResolutionSource = "explicit" | "named-session" | "active-session";
+interface ResolvedBridgeLocalContext {
+    source: BridgeLocalResolutionSource;
+    sessionName?: string;
+    l1: {
+        walletName: string;
+        address: string;
+    };
+    l2: {
+        accountName?: string;
+        address: `0x${string}`;
+    };
+    bridgeMode: "local-simulated";
+}
+interface ResolveBridgeOptions {
+    config: LoadedHardkasConfig;
+    sessionName?: string;
+    from?: string;
+    toIgra?: string;
+}
+/**
+ * Resolves the L1/L2 bridge context with the following priority:
+ * 1. Explicit flags (--from, --to-igra)
+ * 2. Named session (--session)
+ * 3. Active session
+ */
+declare function resolveBridgeLocalContext(options: ResolveBridgeOptions): Promise<ResolvedBridgeLocalContext>;
+
+export { type BridgeEntryPayload, type BridgeLocalResolutionSource, type BridgePlan, type BridgePlanRequest, type MiningResult, type ResolveBridgeOptions, type ResolvedBridgeLocalContext, deserializeBridgePayload, planBridgeEntry, resolveBridgeLocalContext, serializeBridgePayload, simulatePrefixMining };

package/dist/index.js

@@ -0,0 +1,132 @@
+// src/payload.ts
+function serializeBridgePayload(payload) {
+  const markerHex = Buffer.from(payload.marker.padEnd(4).slice(0, 4)).toString("hex");
+  const addrHex = payload.targetEvmAddress.replace("0x", "").toLowerCase().padStart(40, "0");
+  const amountHex = payload.amountSompi.toString(16).padStart(16, "0");
+  const networkHex = Buffer.from(payload.networkId.padEnd(2).slice(0, 2)).toString("hex");
+  const nonceHex = (payload.nonce ?? 0).toString(16).padStart(8, "0");
+  return `${markerHex}${addrHex}${amountHex}${networkHex}${nonceHex}`;
+}
+function deserializeBridgePayload(hex) {
+  const marker = Buffer.from(hex.slice(0, 8), "hex").toString().trim();
+  const targetEvmAddress = `0x${hex.slice(8, 48)}`;
+  const amountSompi = BigInt(`0x${hex.slice(48, 64)}`);
+  const networkId = Buffer.from(hex.slice(64, 68), "hex").toString().trim();
+  const nonce = parseInt(hex.slice(68, 76), 16);
+  return { marker, targetEvmAddress, amountSompi, networkId, nonce };
+}
+
+// src/prefix-miner.ts
+import { calculateContentHash } from "@hardkas/artifacts";
+function simulatePrefixMining(payloadBase, prefix, options = {}) {
+  const initialNonce = options.initialNonce ?? 0;
+  const maxAttempts = options.maxAttempts ?? 1e5;
+  const timeoutMs = options.timeoutMs ?? 5e3;
+  const startTime = Date.now();
+  let nonce = initialNonce;
+  let attempts = 0;
+  while (attempts < maxAttempts) {
+    if (Date.now() - startTime > timeoutMs) {
+      throw new Error(`Mining simulation timed out after ${timeoutMs}ms`);
+    }
+    const payload = { ...payloadBase, nonce };
+    const serialized = serializeBridgePayload(payload);
+    const hash = calculateContentHash({ payload: serialized });
+    if (hash.startsWith(prefix)) {
+      return { nonce, hash, attempts: attempts + 1 };
+    }
+    nonce++;
+    attempts++;
+  }
+  throw new Error(`Failed to find prefix "${prefix}" after ${attempts} attempts.`);
+}
+
+// src/planner.ts
+import { buildPaymentPlan } from "@hardkas/tx-builder";
+function planBridgeEntry(request) {
+  const bridgePayload = {
+    marker: "IGRA",
+    targetEvmAddress: request.targetEvmAddress,
+    amountSompi: request.amountSompi,
+    networkId: request.networkId
+  };
+  const serializedPayload = serializeBridgePayload(bridgePayload);
+  const payloadBytes = serializedPayload.length / 2;
+  const txPlan = buildPaymentPlan({
+    fromAddress: request.fromAddress,
+    outputs: [
+      // In a real bridge, this might be a specific bridge multisig or script
+      { address: request.fromAddress, amountSompi: request.amountSompi }
+    ],
+    availableUtxos: request.availableUtxos,
+    feeRateSompiPerMass: 1n,
+    payloadBytes
+  });
+  return {
+    ...txPlan,
+    bridgePayload,
+    serializedPayload
+  };
+}
+
+// src/session-resolver.ts
+import { getActiveSession, loadSessionStore } from "@hardkas/sessions";
+import { resolveHardkasAccountAddress, listHardkasAccounts } from "@hardkas/accounts";
+async function resolveBridgeLocalContext(options) {
+  const { config, sessionName, from, toIgra } = options;
+  if (from && toIgra) {
+    const l1Address = resolveHardkasAccountAddress(from, config.config);
+    return {
+      source: "explicit",
+      l1: { walletName: from, address: l1Address },
+      l2: { address: toIgra.startsWith("0x") ? toIgra : `0x${toIgra}` },
+      bridgeMode: "local-simulated"
+    };
+  }
+  if (sessionName) {
+    const store = loadSessionStore();
+    const session = store.sessions[sessionName];
+    if (!session) {
+      throw new Error(`Session "${sessionName}" not found.`);
+    }
+    return validateAndFormatSession(session, "named-session", config);
+  }
+  const activeSession = getActiveSession();
+  if (activeSession) {
+    return validateAndFormatSession(activeSession, "active-session", config);
+  }
+  throw new Error(
+    "No bridge context resolved.\n\nProvide one of:\n  hardkas bridge local plan --amount 100 --session <name>\n  hardkas bridge local plan --amount 100 --from <wallet> --to-igra <0x...>\n  hardkas session use <name>"
+  );
+}
+function validateAndFormatSession(session, source, config) {
+  if (session.bridge.mode !== "local-simulated") {
+    throw new Error(`Session "${session.name}" has bridge mode "${session.bridge.mode}". Only "local-simulated" is supported in this command.`);
+  }
+  const accounts = listHardkasAccounts(config.config);
+  const l1Found = accounts.find((a) => a.name === session.l1.wallet);
+  const l2Found = accounts.find((a) => a.name === session.l2.account);
+  if (!l1Found) {
+    throw new Error(`Session "${session.name}" refers to missing L1 wallet "${session.l1.wallet}".`);
+  }
+  return {
+    source,
+    sessionName: session.name,
+    l1: {
+      walletName: session.l1.wallet,
+      address: l1Found.address || session.l1.address || ""
+    },
+    l2: {
+      accountName: session.l2.account,
+      address: session.l2.address || ""
+    },
+    bridgeMode: "local-simulated"
+  };
+}
+export {
+  deserializeBridgePayload,
+  planBridgeEntry,
+  resolveBridgeLocalContext,
+  serializeBridgePayload,
+  simulatePrefixMining
+};

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@hardkas/bridge-local",
+  "version": "0.4.0-alpha",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "dependencies": {
+    "@hardkas/accounts": "0.4.0-alpha",
+    "@hardkas/core": "0.4.0-alpha",
+    "@hardkas/artifacts": "0.4.0-alpha",
+    "@hardkas/sessions": "0.4.0-alpha",
+    "@hardkas/tx-builder": "0.4.0-alpha",
+    "@hardkas/config": "0.4.0-alpha"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  },
+  "license": "MIT",
+  "author": "Javier Rodriguez",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "test": "vitest run --passWithNoTests",
+    "typecheck": "tsc --noEmit"
+  }
+}