hak-ledger-plugin 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jmgomezl
+
+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/README.md

@@ -0,0 +1,83 @@
+# hak-ledger-plugin
+
+**The first Ledger hardware-wallet plugin for the [Hedera Agent Kit](https://github.com/hashgraph/hedera-agent-kit).**
+
+Gives a Hedera agent a **human-in-the-loop signer**: a high-risk EVM transaction is **Clear-Signed on a physical Ledger** before it executes. The device is the final confirmation gate — nothing high-value leaves the agent without an explicit on-device approval.
+
+Part of the [Aivy](https://aivylabs.xyz) ecosystem.
+
+## Why
+
+Autonomous agents are great until they move real value. This plugin adds **device-backed security** to a HAK agent: keep small actions autonomous, and gate high-risk ones behind a hardware Clear-Sign. It pairs directly with [`hak-uniswap-plugin`](https://github.com/jmgomezl/hak-uniswap-plugin), which returns `{ status: 'requires_ledger_approval', unsignedTx }` above a threshold — hand that `unsignedTx` straight to `ledger_clear_sign`.
+
+## Install
+
+```bash
+npm i hak-ledger-plugin
+# USB transport (Node) is an optional dep; install if you sign over USB:
+npm i @ledgerhq/hw-transport-node-hid
+```
+
+## Use
+
+```js
+import { HederaLangchainToolkit } from 'hedera-agent-kit';
+import { ledgerPlugin } from 'hak-ledger-plugin';
+
+const toolkit = new HederaLangchainToolkit({
+  client,
+  configuration: { plugins: [ledgerPlugin] },
+});
+```
+
+## Tools
+
+### `ledger_clear_sign` — human-in-the-loop signer
+
+Clear-Signs an unsigned EVM transaction on the device and (optionally) broadcasts it.
+
+| param | type | notes |
+|---|---|---|
+| `unsignedTx` | string \| object | RLP-serialized unsigned tx (hex), or `{ to, value, data, … }` |
+| `chainId` | number | e.g. `296` Hedera testnet, `11155111` Sepolia |
+| `rpcUrl` | string? | RPC for nonce/gas fill + broadcast (defaults by `chainId`) |
+| `derivationPath` | string | default `44'/60'/0'/0/0` |
+| `broadcast` | boolean | default `true`; `false` returns the signed raw tx |
+
+Returns `{ status: 'executed', txHash }`, or `{ status: 'signed', rawSigned }`, or `{ status: 'rejected' }` if the human declines on the device.
+
+### `ledger_get_address` — hardware-backed identity
+
+| param | type | notes |
+|---|---|---|
+| `derivationPath` | string | default `44'/60'/0'/0/0` |
+| `verify` | boolean | `true` shows the address on the device to confirm |
+
+## Pairing with `hak-uniswap-plugin` (HITL settlement)
+
+```js
+const quote = await tools.uniswap_swap({ /* … large swap … */ });
+if (quote.status === 'requires_ledger_approval') {
+  // the agent proposes; the human Clear-Signs on the Ledger; then it executes
+  const res = await tools.ledger_clear_sign({ unsignedTx: quote.unsignedTx, chainId: quote.chainId });
+  // res.status === 'executed' (or 'rejected' if the human declined)
+}
+```
+
+A runnable example is in [`examples/sample-agent.js`](examples/sample-agent.js).
+
+## Transport
+
+USB over `@ledgerhq/hw-transport-node-hid` by default (Node + a plugged-in Ledger).
+Browser **WebHID** or **Speculos** consumers can inject their own transport via
+`context.ledgerTransport` — the plugin uses it instead of opening USB.
+
+## Security
+
+The Ledger device is the **final confirmation gate**. Keep on-device confirmation
+intact: do not auto-approve or bypass it. Clear Signing shows human-readable
+details (recipient, amount, contract action) so the approver sees what they sign.
+
+## License
+
+MIT

package/examples/sample-agent.js

@@ -0,0 +1,27 @@
+// Minimal sample: a HAK-style agent that derives its Ledger-secured address and
+// Clear-Signs a high-risk EVM transaction on the device before broadcasting.
+//
+//   npm i hak-ledger-plugin @ledgerhq/hw-transport-node-hid
+//   node examples/sample-agent.js
+//
+// Plug in your Ledger, unlock it, and open the Ethereum app first.
+import { ledgerPlugin } from 'hak-ledger-plugin';
+
+const [getAddress, clearSign] = ledgerPlugin.tools(/* context */ {});
+
+// 1. Hardware-backed identity — verify the address on the device screen.
+const id = await getAddress.execute(null, {}, { verify: true });
+console.log('Ledger-secured agent address:', id.address);
+
+// 2. A high-risk action the agent wants to take (e.g. a settlement payout).
+//    In practice this `unsignedTx` is what hak-uniswap-plugin returns as
+//    `requires_ledger_approval`. Here we hand-build a small transfer.
+const result = await clearSign.execute(null, {}, {
+  unsignedTx: { to: id.address, value: '100000000000000', data: '0x' }, // 0.0001 (self, demo)
+  chainId: 296, // Hedera EVM testnet
+  broadcast: true,
+});
+
+if (result.status === 'executed') console.log('Ledger-approved & broadcast:', result.txHash);
+else if (result.status === 'rejected') console.log('Declined on device — nothing executed.');
+else console.log(result);

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "hak-ledger-plugin",
+  "version": "0.1.0",
+  "description": "The first Ledger hardware-wallet plugin for the Hedera Agent Kit — a human-in-the-loop signer that Clear-Signs high-risk EVM transactions on a physical Ledger before a Hedera agent executes them. The device is the final gate.",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src",
+    "examples",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "hedera",
+    "hedera-agent-kit",
+    "hak-plugin",
+    "ledger",
+    "hardware-wallet",
+    "clear-signing",
+    "human-in-the-loop",
+    "hitl",
+    "ai-agent",
+    "evm"
+  ],
+  "peerDependencies": {
+    "hedera-agent-kit": ">=3.0.0",
+    "zod": "^3.25.76"
+  },
+  "dependencies": {
+    "@ledgerhq/hw-app-eth": "^6.47.1",
+    "ethers": "^6.16.0"
+  },
+  "optionalDependencies": {
+    "@ledgerhq/hw-transport-node-hid": "^6.29.0"
+  },
+  "license": "MIT",
+  "author": "jmgomezl",
+  "repository": "https://github.com/jmgomezl/hak-ledger-plugin",
+  "homepage": "https://github.com/jmgomezl/hak-ledger-plugin#readme"
+}

package/src/index.js

@@ -0,0 +1,166 @@
+// hak-ledger-plugin — the first Ledger hardware-wallet plugin for the Hedera
+// Agent Kit. Gives a HAK agent a human-in-the-loop signer: a high-risk EVM
+// action is Clear-Signed on a physical Ledger before it executes, so the device
+// is the final confirmation gate. Pairs with plugins (e.g. hak-uniswap-plugin)
+// that return `{ status: 'requires_ledger_approval', unsignedTx }` above a
+// threshold — feed that unsignedTx straight into `ledger_clear_sign`.
+//
+// Plugin shape matches hedera-agent-kit@3.x:
+//   Plugin { name, version, description, tools: (context) => Tool[] }
+//   Tool   { method, name, description, parameters: ZodObject, execute(client, context, params) }
+//
+// Transport: USB via @ledgerhq/hw-transport-node-hid (Node). Browser/WebHID and
+// Speculos consumers can inject their own transport via context.ledgerTransport.
+import { z } from 'zod';
+import { ethers } from 'ethers';
+
+const DEFAULT_PATH = "44'/60'/0'/0/0";
+
+// Minimal EVM chain registry for optional broadcast — extend as needed.
+const CHAINS = {
+  1: { name: 'ethereum', rpc: 'https://eth.llamarpc.com' },
+  11155111: { name: 'ethereum-sepolia', rpc: 'https://ethereum-sepolia-rpc.publicnode.com' },
+  296: { name: 'hedera-testnet', rpc: 'https://testnet.hashio.io/api' },
+  295: { name: 'hedera-mainnet', rpc: 'https://mainnet.hashio.io/api' },
+  130: { name: 'unichain', rpc: 'https://mainnet.unichain.org' },
+  8453: { name: 'base', rpc: 'https://mainnet.base.org' },
+};
+
+// Open a Ledger Ethereum-app connection. Prefer an injected transport (WebHID,
+// Speculos, BLE); otherwise fall back to a USB (node-hid) transport.
+async function openEth(context) {
+  const { default: Eth, ledgerService } = await import('@ledgerhq/hw-app-eth');
+  let transport = context?.ledgerTransport ?? null;
+  if (!transport) {
+    try {
+      const { default: TransportNodeHid } = await import('@ledgerhq/hw-transport-node-hid');
+      transport = await TransportNodeHid.create();
+    } catch (err) {
+      throw new Error(
+        'No Ledger transport. Plug in a Ledger and `npm i @ledgerhq/hw-transport-node-hid`, ' +
+          'or pass context.ledgerTransport (WebHID / Speculos). Cause: ' + err.message
+      );
+    }
+  }
+  return { eth: new Eth(transport), ledgerService, transport };
+}
+
+// Normalize an unsigned tx (object or RLP hex) → an ethers Transaction we can
+// serialize, plus the device-ready unsigned hex (no 0x prefix).
+async function toUnsigned(unsignedTx, { chainId, rpcUrl }) {
+  let tx;
+  if (typeof unsignedTx === 'string') {
+    tx = ethers.Transaction.from(unsignedTx); // already-serialized unsigned tx
+  } else {
+    tx = ethers.Transaction.from({ type: 0, ...unsignedTx });
+  }
+  // Fill nonce / gas / chainId from chain if missing (only when an RPC is known).
+  const rpc = rpcUrl || CHAINS[chainId]?.rpc;
+  if (rpc && (tx.nonce == null || tx.gasLimit == null || tx.gasPrice == null || tx.chainId == null)) {
+    const provider = new ethers.JsonRpcProvider(rpc);
+    const from = tx.from;
+    if (tx.chainId == null) tx.chainId = BigInt(chainId ?? (await provider.getNetwork()).chainId);
+    if (tx.nonce == null && from) tx.nonce = await provider.getTransactionCount(from);
+    if (tx.gasPrice == null) {
+      const fee = await provider.getFeeData();
+      tx.gasPrice = fee.gasPrice ? (fee.gasPrice * 12n) / 10n : ethers.parseUnits('600', 'gwei');
+    }
+    if (tx.gasLimit == null) tx.gasLimit = 21000n;
+  }
+  const unsignedHex = tx.unsignedSerialized.slice(2); // hw-app-eth wants no 0x
+  return { tx, unsignedHex };
+}
+
+// ── Tool 1: derive + (optionally) verify the Ledger Ethereum address ──
+const getAddressTool = (context) => ({
+  method: 'ledger_get_address',
+  name: 'Ledger Get Address',
+  description:
+    "Derive the agent's Ledger-secured Ethereum address. Set verify=true to display " +
+    'it on the device for the human to confirm. Use to bind an agent to a hardware identity.',
+  parameters: z.object({
+    derivationPath: z.string().default(DEFAULT_PATH).describe("BIP-32 path, e.g. 44'/60'/0'/0/0"),
+    verify: z.boolean().default(false).describe('show the address on the device for confirmation'),
+  }),
+  async execute(_client, _ctx, params) {
+    const { eth } = await openEth(context);
+    const { address, publicKey } = await eth.getAddress(params.derivationPath, params.verify);
+    return { address: ethers.getAddress(address), publicKey };
+  },
+});
+
+// ── Tool 2: Clear-Sign a high-risk EVM transaction on the Ledger ──
+const clearSignTool = (context) => ({
+  method: 'ledger_clear_sign',
+  name: 'Ledger Clear-Sign Transaction',
+  description:
+    'Human-in-the-loop signer: Clear-Sign an unsigned EVM transaction on a physical Ledger and ' +
+    "(optionally) broadcast it. The device is the final gate — nothing executes without the human's " +
+    'on-device approval. Pass the `unsignedTx` returned by a plugin that requires Ledger approval.',
+  parameters: z.object({
+    unsignedTx: z.union([z.string(), z.record(z.any())]).describe('RLP-serialized unsigned tx (hex) or a tx object {to,value,data,...}'),
+    chainId: z.number().describe('EVM chain id (e.g. 296 Hedera testnet, 11155111 Sepolia)'),
+    rpcUrl: z.string().optional().describe('RPC for nonce/gas fill + broadcast (defaults by chainId)'),
+    derivationPath: z.string().default(DEFAULT_PATH),
+    broadcast: z.boolean().default(true).describe('broadcast after signing; false returns the signed raw tx'),
+  }),
+  async execute(_client, _ctx, params) {
+    const { unsignedTx, chainId, rpcUrl, derivationPath, broadcast } = params;
+    const { eth, ledgerService } = await openEth(context);
+    const { tx, unsignedHex } = await toUnsigned(unsignedTx, { chainId, rpcUrl });
+
+    // Resolve Clear-Signing metadata (ERC-20 / known contracts / external plugins)
+    // so the device shows human-readable details, not raw hex.
+    let resolution = null;
+    try {
+      resolution = await ledgerService.resolveTransaction(unsignedHex, eth.loadConfig ?? {}, {
+        externalPlugins: true,
+        erc20: true,
+      });
+    } catch {
+      /* fall back to blind signing if CAL metadata is unavailable */
+    }
+
+    let sig;
+    try {
+      sig = await eth.signTransaction(derivationPath, unsignedHex, resolution);
+    } catch (err) {
+      // user declined on the device, or app/locked
+      return { status: 'rejected', reason: err.message };
+    }
+
+    tx.signature = ethers.Signature.from({
+      r: '0x' + sig.r,
+      s: '0x' + sig.s,
+      v: parseInt(sig.v, 16),
+    });
+    const rawSigned = tx.serialized;
+
+    if (!broadcast) {
+      return { status: 'signed', from: tx.from, hash: tx.hash, rawSigned, chainId };
+    }
+    const rpc = rpcUrl || CHAINS[chainId]?.rpc;
+    if (!rpc) return { status: 'signed', rawSigned, chainId, note: 'no rpc to broadcast — returned signed tx' };
+    const provider = new ethers.JsonRpcProvider(rpc);
+    const sent = await provider.broadcastTransaction(rawSigned);
+    return {
+      status: 'executed',
+      txHash: sent.hash,
+      from: tx.from,
+      to: tx.to,
+      chainId,
+      explorer: CHAINS[chainId]?.name ? `${CHAINS[chainId].name}:${sent.hash}` : sent.hash,
+    };
+  },
+});
+
+export const ledgerPlugin = {
+  name: 'hak-ledger-plugin',
+  version: '0.1.0',
+  description:
+    'Human-in-the-loop Ledger signer for Hedera Agent Kit agents: Clear-Sign high-risk EVM ' +
+    'transactions on a physical Ledger before they execute. The device is the final gate.',
+  tools: (context) => [getAddressTool(context), clearSignTool(context)],
+};
+
+export default ledgerPlugin;