Ledger

@usebutr/ledger connects Ledger hardware wallets over WebUSB, with a factory per platform: EVM, Solana, Sui and Bitcoin. It signs; it does not broadcast, read chain state or push events.

InstallCopy Anchor Link

npm install @usebutr/ledger @ledgerhq/hw-transport-webusb

Then add the Ledger app package for each platform you use; each is an optional peer loaded on first connect:

npm install @ledgerhq/hw-app-eth      # EVM
npm install @ledgerhq/hw-app-solana   # Solana
npm install @ledgerhq/hw-app-sui      # Sui
npm install @ledgerhq/hw-app-btc      # Bitcoin

Register itCopy Anchor Link

createLedgerAdapter resolves an un-paired adapter; fromAdapters takes the promise and hands the adapter to the manager, and it appears in useDiscoveredWallets():

import type { WalletManagerConfig } from "@usebutr/core";
import { EVM_CHAINS, SVM_CHAINS, fromAdapters } from "@usebutr/core";
import { createLedgerAdapter } from "@usebutr/ledger";
import { WalletManagerProvider } from "@usebutr/react";
import { autoDiscovery } from "@usebutr/wallets";

const config: WalletManagerConfig = {
  sources: [
    autoDiscovery(),
    fromAdapters(
      createLedgerAdapter({ chainId: EVM_CHAINS.sepolia.id, id: "ledger-evm", platform: "evm" }),
    ),
    fromAdapters(
      createLedgerAdapter({
        accountCount: 3,
        chainId: SVM_CHAINS.devnet.id,
        id: "ledger-svm",
        platform: "svm",
      }),
    ),
  ],
  storageKeyPrefix: "my-app",
};

export const Providers = ({ children }: { children: React.ReactNode }) => (
  <WalletManagerProvider config={config}>{children}</WalletManagerProvider>
);

Give each adapter its own id: they all default to "ledger", and the first adapter announced for an id wins. On connect() the browser shows the WebUSB permission prompt, the user unlocks the device and opens the platform's app (Ethereum, Solana, Sui or Bitcoin), and the adapter reads accountCount addresses, active first.

OptionsCopy Anchor Link

What each adapter definesCopy Anchor Link

No Ledger adapter has sendTx, getBalance, getTransactionReceipt, subscribe, requestAccounts or switchChain. To submit a transaction, sign it here and broadcast it with your own chain client. For an EVM transaction, use the device app from getSigner():

import type { ConnectedWallet } from "@usebutr/core";

const signEvmTransaction = async (wallet: ConnectedWallet<"evm">, unsignedTxHex: string) => {
  const signer = await wallet.connector.getSigner();
  if (signer.kind !== "ledger-evm") {
    throw new Error(`${wallet.connector.name} is not a Ledger`);
  }
  // The first account's path: the prefix plus its index in `getAccounts()`.
  return signer.app.signTransaction("44'/60'/0'/0/0", unsignedTxHex);
};

The Solana, Sui and Bitcoin adapters resolve ledger-svm, ledger-sui and ledger-bitcoin, each with its device app.

Chains and accountsCopy Anchor Link

A Ledger app has no network to switch, so each adapter signs for the one chain in chainId. A call whose chain differs rejects with a ChainMismatch ConnectionError: build one adapter per chain, with distinct ids. Bitcoin testnet needs the Bitcoin Test app, a 1' coin type (derivationPathPrefix: "84'/1'/0'/0") and chainId: BITCOIN_CHAINS.testnet.id.

Pass { account } to sign as another address the device exposed; one it did not expose rejects.

CaveatsCopy Anchor Link