--- title: "Solana Signer Kit" category: reference --- # Solana Signer Kit This module provides the implementation of the Ledger Solana signer of the Device Management Kit. It enables interaction with the Solana application on a Ledger device including: - Retrieving the Solana address using a given derivation path; - Signing a Solana transaction; - Signing an offchain message displayed on a Ledger device; - Retrieving the app configuration; ## 🔹 Index 1. [How it works](#-how-it-works) 2. [Installation](#-installation) 3. [Initialisation](#-initialisation) 4. [Use Cases](#-use-cases) - [Get Address](#use-case-1-get-address) - [Sign Transaction](#use-case-2-sign-transaction) - [Sign Message](#use-case-3-sign-message) - [Get App Configuration](#use-case-4-get-app-configuration) 5. [Observable Behavior](#-observable-behavior) 6. [Example](#-example) ## 🔹 How it works The Ledger Solana Signer utilizes the advanced capabilities of the Ledger device to provide secure operations for end users. It takes advantage of the interface provided by the Device Management Kit to establish communication with the Ledger device and execute various operations. The communication with the Ledger device is performed using [APDU](https://en.wikipedia.org/wiki/Smart_card_application_protocol_data_unit)s (Application Protocol Data Units), which are encapsulated within the `Command` object. These commands are then organized into tasks, allowing for the execution of complex operations with one or more APDUs. The tasks are further encapsulated within `DeviceAction` objects to handle different real-world scenarios. Finally, the Signer exposes dedicated and independent use cases that can be directly utilized by end users. ## 🔹 Installation > **Note:** This module is not standalone; it depends on the [@ledgerhq/device-management-kit](https://github.com/LedgerHQ/device-sdk-ts/tree/develop/packages/device-management-kit) package, so you need to install it first. To install the `device-signer-kit-solana` package, run the following command: ```sh npm install @ledgerhq/device-signer-kit-solana ``` ## 🔹 Initialisation To initialise a Solana signer instance, you need a Ledger Device Management Kit instance and the ID of the session of the connected device. Use the `SignerSolanaBuilder` along with the [Context Module](https://github.com/LedgerHQ/device-sdk-ts/tree/develop/packages/signer/context-module) by default developed by Ledger: ```typescript const signerSolana = new SignerSolanaBuilder({ dmk, sessionId, solanaRPCURL: "https://api.mainnet-beta.solana.com/", }).build(); ``` - **solanaRPCURL** _(optional)_ — Default Solana RPC endpoint for transaction inspection (SPL token resolution) and fetching a fresh `recentBlockhash` during delayed signing. Override per call with `SolanaTransactionOptionalConfig.solanaRPCURL`. In browser environments, use a CORS-enabled RPC URL. ## 🔹 Use Cases The `SignerSolanaBuilder.build()` method will return a `SignerSolana` instance that exposes 4 dedicated methods, each of which calls an independent use case. Each use case will return an object that contains an observable and a method called `cancel`. --- ### Use Case 1: Get Address This method allows users to retrieve the Solana address based on a given `derivationPath`. ```typescript const { observable, cancel } = signerSolana.getAddress(derivationPath, options); ``` #### **Parameters** - `derivationPath` - **Required** - **Type:** `string` (e.g., `"44'/501'/0'"`) - The derivation path used for the Solana address. See [here](https://www.ledger.com/blog/understanding-crypto-addresses-and-derivation-paths) for more information. - `options` - Optional - Type: `AddressOptions` ```typescript type AddressOptions = { checkOnDevice?: boolean; }; ``` - `checkOnDevice`: An optional boolean indicating whether user confirmation on the device is required (`true`) or not (`false`). #### **Returns** - `observable` Emits DeviceActionState updates, including the following details: ```typescript type GetAddressDAOutput = string; // base58-encoded Solana address ``` - `cancel` A function to cancel the action on the Ledger device. --- ### Use Case 2: Sign Transaction Securely sign a Solana or SPL transaction using **Clear Signing** on Ledger devices. ```ts const { observable, cancel } = signerSolana.signTransaction( derivationPath, transaction, transactionOptions, ); ``` --- ### Parameters **Required** - **derivationPath** `string`\ The derivation path used in the transaction.\ See [Ledger’s guide](https://www.ledger.com/blog/understanding-crypto-addresses-and-derivation-paths) for more information. - **transaction** `Uint8Array`\ The serialized transaction to sign. **Optional** - **transactionOptions** `SolanaTransactionOptionalConfig`\ Provides additional context for transaction signing. - **solanaRPCURL** `string` _(optional)_\ Overrides the RPC URL from `SignerSolanaBuilder` for this call (inspection and delayed signing). - **transactionResolutionContext** `object`\ Lets you explicitly pass `tokenAddress` and ATA details, bypassing extraction from the transaction itself. - **tokenAddress** `string`\ SPL token address being transferred. - **createATA** `object`\ Information about creating an associated token account (ATA). - **address** `string` – Address (owner) of the ATA. - **mintAddress** `string` – Mint address of the ATA. - **tokenInternalId** `string` Ledger internal token ID - **skipOpenApp** `boolean`\ If `true`, skips opening the Solana app on the device. --- ### Returns - `observable` That emits DeviceActionState updates, including the following details: ```ts type SignTransactionDAOutput = Uint8Array; // raw signature (64 bytes) ``` - `cancel` A function to cancel the action on the Ledger device. --- ### Internal Flow Under the hood, this method subscribes to an\ `Observable>`. #### DeviceActionState Represents the lifecycle of a device action: ```ts type DeviceActionState = | { status: DeviceActionStatus.NotStarted } | { status: DeviceActionStatus.Pending; intermediateValue: IntermediateValue } | { status: DeviceActionStatus.Stopped } | { status: DeviceActionStatus.Completed; output: Output } | { status: DeviceActionStatus.Error; error: Error }; enum DeviceActionStatus { NotStarted = "not-started", Pending = "pending", Stopped = "stopped", Completed = "completed", Error = "error", } ``` - **NotStarted** → Action hasn’t begun. - **Pending** → Waiting for user confirmation on the device.\ Includes an `intermediateValue` of type `IntermediateValue`. - **Stopped** → Action was cancelled before completion. - **Completed** → Provides the raw 64-byte Ed25519 signature (`Uint8Array`). - **Error** → The device or signing operation failed (`SignTransactionDAError`). --- ### Example ```ts const { observable } = dmkSigner.signTransaction( "m/44'/501'/0'/0'", serializedTx, { transactionResolutionContext: resolution, }, ); const subscription = observable.subscribe({ next: (state) => { switch (state.status) { case DeviceActionStatus.Pending: console.log("Waiting for user action...", state.intermediateValue); break; case DeviceActionStatus.Completed: console.log("Signature:", state.output); break; case DeviceActionStatus.Error: console.error("Error:", state.error); break; } }, error: (err) => console.error("Observable error:", err), complete: () => console.log("Signing flow ended"), }); // Later if needed: // subscription.unsubscribe(); ``` #### **Notes** - Clear signing only supports simple instructions like a single `transfer` or combos like `createAccount + fundAccount` or `createAccount + transfer`. If you are receiving `6808` error from device, most likely the instructions are not supported and blind signing is required. --- ### Use Case 3: Sign Message Sign a Solana off-chain message on Ledger devices. Supports multiple signing modes via `SignMessageVersion`: - **V0** (default) — original [off-chain message](https://docs.anza.xyz/proposals/off-chain-message-signing) header with `appDomain` and signer fields. Supported on all firmware with off-chain signing. Falls back to Legacy on `6a81`. - **V1** — simplified header without `appDomain`; supports lexicographically sorted multi-signer payloads. Requires Solana device app version 1.14+. Falls back to V0 then Legacy on `6a81`. - **Legacy** — compact header for backward compatibility with very old Solana app firmware. Current firmware will reject it. - **Raw** — pass-through: the caller provides the fully formatted payload as a `Uint8Array` and the SDK sends it as-is with no header wrapping. ```typescript const { observable, cancel } = signerSolana.signMessage( derivationPath, message, options, ); ``` --- ### Parameters **Required** - **derivationPath** `string` The derivation path used for signing (e.g., `"44'/501'/0'"`). See [here](https://www.ledger.com/blog/understanding-crypto-addresses-and-derivation-paths) for more information. - **message** `string | Uint8Array` The message to sign. Pass a `string` for V0/V1/Legacy modes (UTF-8 encoded automatically). Pass a `Uint8Array` for Raw mode when you have an already-formatted payload. **Optional** - **options** `MessageOptions` - **version** `SignMessageVersion` Off-chain message signing mode. Defaults to `SignMessageVersion.V0`. - **appDomain** `string` V0 only: application domain included in the off-chain message header (UTF-8 encoded, padded/truncated to 32 bytes). Defaults to 32 zero bytes. Ignored for V1, Legacy, and Raw. - **skipOpenApp** `boolean` If `true`, skips opening the Solana app on the device. ```typescript import { SignMessageVersion } from "@ledgerhq/device-signer-kit-solana"; type MessageOptions = { version?: SignMessageVersion; appDomain?: string; skipOpenApp?: boolean; }; ``` #### Fallback Cascade When the device rejects an off-chain message header with `6a81` (invalid data), the SDK automatically retries with an older format: | Starting Version | Fallback Path | | ---------------- | ---------------- | | V1 | V1 → V0 → Legacy | | V0 | V0 → Legacy | | Legacy / Raw | No fallback | --- ### Returns - `observable` Emits DeviceActionState updates, including the following details: ```typescript type SignMessageDAOutput = { signature: string; // base58-encoded signature envelope (V0/V1/Legacy) or raw base58 signature (Raw) }; ``` - `cancel` A function to cancel the action on the Ledger device. --- ### Example ```typescript import { SignMessageVersion } from "@ledgerhq/device-signer-kit-solana"; // V0 (default) — sign a simple text message const { observable } = signerSolana.signMessage( "44'/501'/0'/0'", "Hello World", { version: SignMessageVersion.V0 }, ); observable.subscribe({ next: (state) => { switch (state.status) { case DeviceActionStatus.Pending: console.log("Waiting for user action...", state.intermediateValue); break; case DeviceActionStatus.Completed: console.log("Signature:", state.output.signature); break; case DeviceActionStatus.Error: console.error("Error:", state.error); break; } }, error: (err) => console.error("Observable error:", err), complete: () => console.log("Signing flow ended"), }); ``` #### Raw Mode In Raw mode, the caller is responsible for constructing the full off-chain message payload. Pass it as a `Uint8Array`: ```typescript const rawPayload = new Uint8Array([ /* pre-built OCM bytes */ ]); const { observable } = signerSolana.signMessage("44'/501'/0'/0'", rawPayload, { version: SignMessageVersion.Raw, }); ``` #### **Notes** - The output `signature` is a base58-encoded string. For V0/V1/Legacy modes it is a full envelope (signature count + signature + serialized off-chain message). For Raw mode it is the plain base58-encoded 64-byte Ed25519 signature. --- ### Use Case 4: Get App Configuration This method allows the user to fetch the current app configuration. ```typescript const { observable, cancel } = signerSolana.getAppConfiguration(); ``` #### **Returns** - `observable` Emits DeviceActionState updates, including the following details: ```typescript type AppConfiguration = { blindSigningEnabled: boolean; pubKeyDisplayMode: PublicKeyDisplayMode; version: string; }; ``` - `cancel` A function to cancel the action on the Ledger device. ## 🔹 Observable Behavior Each method returns an [Observable](https://rxjs.dev/guide/observable) emitting updates structured as [`DeviceActionState`](https://github.com/LedgerHQ/device-sdk-ts/blob/develop/packages/device-management-kit/src/api/device-action/model/DeviceActionState.ts). These updates reflect the operation’s progress and status: - **NotStarted**: The operation hasn’t started. - **Pending**: The operation is in progress and may require user interaction. - **Stopped**: The operation was canceled or stopped. - **Completed**: The operation completed successfully, with results available. - **Error**: An error occurred. **Example Observable Subscription:** ```typescript observable.subscribe({ next: (state: DeviceActionState) => { switch (state.status) { case DeviceActionStatus.NotStarted: { console.log("The action is not started yet."); break; } case DeviceActionStatus.Pending: { const { intermediateValue: { requiredUserInteraction }, } = state; // Access the intermediate value here, explained below console.log( "The action is pending and the intermediate value is: ", intermediateValue, ); break; } case DeviceActionStatus.Stopped: { console.log("The action has been stopped."); break; } case DeviceActionStatus.Completed: { const { output } = state; // Access the output of the completed action here console.log("The action has been completed: ", output); break; } case DeviceActionStatus.Error: { const { error } = state; // Access the error here if occurred console.log("An error occurred during the action: ", error); break; } } }, }); ``` **Intermediate Values in Pending Status:** When the status is DeviceActionStatus.Pending, the state will include an `intermediateValue` object that provides useful information for interaction: ```typescript const { requiredUserInteraction } = intermediateValue; switch (requiredUserInteraction) { case UserInteractionRequired.VerifyAddress: { // User needs to verify the address displayed on the device console.log("User needs to verify the address displayed on the device."); break; } case UserInteractionRequired.SignTransaction: { // User needs to sign the transaction displayed on the device console.log("User needs to sign the transaction displayed on the device."); break; } case UserInteractionRequired.SignTypedData: { // User needs to sign the typed data displayed on the device console.log("User needs to sign the typed data displayed on the device."); break; } case UserInteractionRequired.SignPersonalMessage: { // User needs to sign the message displayed on the device console.log("User needs to sign the message displayed on the device."); break; } case UserInteractionRequired.None: { // No user action required console.log("No user action needed."); break; } case UserInteractionRequired.UnlockDevice: { // User needs to unlock the device console.log("The user needs to unlock the device."); break; } case UserInteractionRequired.ConfirmOpenApp: { // User needs to confirm on the device to open the app console.log("The user needs to confirm on the device to open the app."); break; } default: // Type guard to ensure all cases are handled const uncaughtUserInteraction: never = requiredUserInteraction; console.error("Unhandled user interaction case:", uncaughtUserInteraction); } ``` ## 🔹 Example We encourage you to explore the Solana Signer by trying it out in our online [sample application](https://app.devicesdk.ledger-test.com/). Experience how it works and see its capabilities in action. Of course, you will need a Ledger device connected.