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
🔹 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 APDUs (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 package, so you need to install it first.
To install the device-signer-kit-solana package, run the following command:
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 by default developed by Ledger:
const signerSolana = new SignerSolanaBuilder({ sdk, sessionId }).build();🔹 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.
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 for more information.
-
options-
Optional
-
Type:
AddressOptionstype AddressOptions = { checkOnDevice?: boolean; }; -
checkOnDevice: An optional boolean indicating whether user confirmation on the device is required (true) or not (false).
-
Returns
observableEmits DeviceActionState updates, including the following details:
type GetAddressCommandResponse = {
publicKey: string; // Address in base58 format
};cancelA function to cancel the action on the Ledger device.
Use Case 2: Sign Transaction
This method enables users to securely sign transactions using clear signing on Ledger devices.
const { observable, cancel } = signerSolana.signTransaction(
derivationPath,
transaction,
options,
);Parameters
-
derivationPath- Required
- Type:
string(e.g.,"44'/501'/0'") - The derivation path used in the transaction. See here for more information.
-
transaction- Required
- Type:
Uint8Array - The transaction object that needs to be signed.
-
options-
Optional
-
Type:
TBD -
No option defined yet, but will be used for clear signing in a near future.
type TransactionOptions = {};
-
Returns
observableEmits DeviceActionState updates, including the following details:
type Signature = Uint8Array; // Signed transaction bytescancelA function to cancel the action on the Ledger device.
Use Case 3: Sign Message
This method allows users to sign a text string that is displayed on Ledger devices.
const { observable, cancel } = signerSolana.signMessage(
derivationPath,
message,
);Parameters
-
derivationPath- Required
- Type:
string(e.g.,"44'/501'/0'") - The derivation path used by the Solana message. See here for more information.
-
message- Required
- Type:
string - The message to be signed, which will be displayed on the Ledger device.
Returns
observableEmits DeviceActionState updates, including the following details:
type Signature = Uint8Array; // Signed message bytescancelA function to cancel the action on the Ledger device.
Use Case 4: Get App Configuration
This method allows the user to fetch the current app configuration.
const { observable, cancel } = signerSolana.getAppConfiguration();Returns
observableEmits DeviceActionState updates, including the following details:
type AppConfiguration = {
blindSigningEnabled: boolean;
pubKeyDisplayMode: PublicKeyDisplayMode;
version: string;
};cancelA function to cancel the action on the Ledger device.
🔹 Observable Behavior
Each method returns an Observable emitting updates structured as DeviceActionState. 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:
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:
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. Experience how it works and see its capabilities in action. Of course, you will need a Ledger device connected.
