@usebutr/ledger
Per-platform Ledger factories (EVM, SVM, Sui, Bitcoin), their options, and the device-app signers.
Ledger hardware wallets over WebUSB. Requires the optional peer dependency
@ledgerhq/hw-transport-webusb plus the Ledger app package for each platform
you use, loaded on first connect:
@ledgerhq/hw-app-ethfor EVM@ledgerhq/hw-app-solanafor SVM@ledgerhq/hw-app-suifor Sui@ledgerhq/hw-app-btcfor Bitcoin
Factories
createLedgerAdapter(options: LedgerOptions): Promise<WalletAdapterFor<"bitcoin" | "evm" | "sui" | "svm">>
Dispatches on options.platform to the per-platform factory; import that
factory directly for the narrower adapter type. The adapter is
un-paired until connect(); hand it to the manager with fromAdapters:
import type { WalletManagerConfig } from "@usebutr/core";
import { EVM_CHAINS, fromAdapters } from "@usebutr/core";
import { createLedgerAdapter } from "@usebutr/ledger";
const config: WalletManagerConfig = {
sources: [
fromAdapters(
createLedgerAdapter({ chainId: EVM_CHAINS.sepolia.id, id: "ledger-evm", platform: "evm" }),
),
fromAdapters(createLedgerAdapter({ accountCount: 3, id: "ledger-svm", platform: "svm" })),
],
};The factory rejects when chainId is outside the platform's namespace.
Per-platform factories
createEvmLedgerAdapter(options: EvmLedgerOptions): Promise<EvmAdapter>createSvmLedgerAdapter(options: SvmLedgerOptions): Promise<SvmAdapter>createSuiLedgerAdapter(options: SuiLedgerOptions): Promise<SuiAdapter>createBitcoinLedgerAdapter(options: BitcoinLedgerOptions): Promise<BitcoinAdapter>
LedgerOptions is the union of the four.
Options
Every factory takes:
| Field | Type | Default |
|---|---|---|
platform | "evm" | "svm" | "sui" | "bitcoin" | Required. |
chainId | string (CAIP-2) | The platform's mainnet. Ledger apps have no network switch: build one adapter per chain. |
accountCount | number | 1. Addresses read during connect(), one device round trip each. |
derivationPathPrefix | string | Per platform, below. The account index is appended as the last segment. |
id | string | "ledger" |
name | string | "Ledger" |
icon | string | LEDGER_DEFAULT_ICON |
transport | TransportFactory | A dynamic import of @ledgerhq/hw-transport-webusb (replace it in tests). |
| Platform | Default chain | Default prefix | Index | App override |
|---|---|---|---|---|
evm | eip155:1 | 44'/60'/0'/0 | /<n> | eth?: EthAppConstructor |
svm | solana:mainnet | 44'/501'/0' | /<n>' | solana?: SolanaAppConstructor |
sui | sui:mainnet | 44'/784'/0'/0' | /<n>' | sui?: SuiAppConstructor |
bitcoin | bip122:000000000019d6689c085ae165831e93 | 84'/0'/0'/0 | /<n> | btc?: BtcAppConstructor |
BitcoinLedgerOptions adds addressFormat?: BitcoinAddressFormat
("legacy" | "p2sh" | "bech32" | "bech32m", default "bech32"), which must
agree with the path's purpose. Bitcoin testnet needs the Bitcoin Test app, a
1' coin type and chainId: BITCOIN_CHAINS.testnet.id.
What each adapter defines
A Ledger signs; your chain client reads state and broadcasts. No adapter has
sendTx, getBalance, getTransactionReceipt, subscribe,
requestAccounts or switchChain.
| Platform | signMessage | signTransaction |
|---|---|---|
evm | EIP-191, r ‖ s ‖ v | none: use the signer's app.signTransaction |
svm | Off-chain message | Serialized transaction, legacy or v0; resolves it signed |
sui | none | BCS transaction bytes; resolves { bytes, signature } |
bitcoin | BIP-137 compact signature | PSBT bytes; resolves the signed PSBT |
Signers
Importing the package registers one kind per app, each carrying the device app bound to the open transport:
kind | app |
|---|---|
ledger-evm | EthAppLike |
ledger-svm | SolanaAppLike |
ledger-sui | SuiAppLike |
ledger-bitcoin | BtcAppLike |
The derivation path of an account is derivationPathPrefix plus its index in
getAccounts(). getSigner() rejects with a NotConnected
ConnectionError before connect().
Constants
LEDGER_DEFAULT_ICON: the generic Ledger device icon.
Types
LedgerOptions, EvmLedgerOptions, SvmLedgerOptions, SuiLedgerOptions,
BitcoinLedgerOptions, BitcoinAddressFormat, EthAppLike,
EthAppConstructor, SolanaAppLike, SolanaAppConstructor, SuiAppLike,
SuiAppConstructor, BtcAppLike, BtcAppConstructor, TransportLike,
TransportFactory.
See the Ledger connector for browser support and signing caveats.
Source: packages/ledger/src/index.ts.