✨ (solana-signer) [DSDK-1054]: Add delayed signing feature (#1358)

Author: fAnselmi-Ledger

.changeset/itchy-teams-join.md

@@ -0,0 +1,5 @@
+---
+"@ledgerhq/device-signer-kit-solana": minor
+---
+
+Add delayed transaction signing feature

.changeset/little-beans-spend.md

@@ -0,0 +1,5 @@
+---
+"@ledgerhq/device-management-kit": patch
+---
+
+deduplicate repeated state logs, log terminal states, include intermediateValue in debug output

apps/docs/pages/docs/references/signers/solana.mdx

@@ -39,9 +39,15 @@ npm install @ledgerhq/device-signer-kit-solana
 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 }).build();
+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`.
@@ -119,6 +125,9 @@ const { observable, cancel } = signerSolana.signTransaction(
 - **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.
 
@@ -134,13 +143,8 @@ const { observable, cancel } = signerSolana.signTransaction(
     - **tokenInternalId** `string`
       Ledger internal token ID
 
-  - **solanaRPCURL** `string`  
-    RPC endpoint used for address-lookup table resolution in versioned (v0) transactions.
-    Defaults to `https://api.mainnet-beta.solana.com/`. Override this to use a private RPC
-    or to avoid CORS issues in browser environments.
-
-  - **skipOpenApp** `boolean`  
-    If `true`, skips opening the Solana app on the device.
+- **skipOpenApp** `boolean`  
+  If `true`, skips opening the Solana app on the device.
 
 ---
 

apps/sample/src/components/SignerSolanaView/index.tsx

@@ -1,5 +1,5 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
-import React, { useCallback, useMemo, useState } from "react";
+import React, { useCallback, useMemo, useRef, useState } from "react";
 import {
   base64StringToBuffer,
   isBase64String,
@@ -42,6 +42,7 @@ type SignTransactionInput = {
   derivationPath: string;
   transaction: string;
   skipOpenApp: boolean;
+  delayed: boolean;
   templateId: string;
   tokenAddress: string;
   tokenInternalId: string;
@@ -53,6 +54,7 @@ const MAIN_KEYS: (keyof SignTransactionInput)[] = [
   "derivationPath",
   "transaction",
   "skipOpenApp",
+  "delayed",
 ];
 
 const CONTEXT_KEYS: (keyof SignTransactionInput)[] = [
@@ -70,6 +72,9 @@ const SignTransactionForm: React.FC<{
 }> = ({ initialValues, onChange, disabled }) => {
   const [expanded, setExpanded] = useState(false);
 
+  const initialValuesRef = useRef(initialValues);
+  initialValuesRef.current = initialValues;
+
   const mainValues = Object.fromEntries(
     MAIN_KEYS.map((k) => [k, initialValues[k]]),
   ) as Pick<SignTransactionInput, (typeof MAIN_KEYS)[number]>;
@@ -79,13 +84,15 @@ const SignTransactionForm: React.FC<{
   ) as Pick<SignTransactionInput, (typeof CONTEXT_KEYS)[number]>;
 
   const handleMainChange = useCallback(
-    (vals: typeof mainValues) => onChange({ ...initialValues, ...vals }),
-    [initialValues, onChange],
+    (vals: typeof mainValues) =>
+      onChange({ ...initialValuesRef.current, ...vals }),
+    [onChange],
   );
 
   const handleContextChange = useCallback(
-    (vals: typeof contextValues) => onChange({ ...initialValues, ...vals }),
-    [initialValues, onChange],
+    (vals: typeof contextValues) =>
+      onChange({ ...initialValuesRef.current, ...vals }),
+    [onChange],
   );
 
   return (
@@ -137,6 +144,7 @@ export const SignerSolanaView: React.FC<{ sessionId: string }> = ({
     dmk,
     sessionId,
     originToken: "Solana",
+    solanaRPCURL: "https://solana.coin.ledger.com",
   }).build();
   const solanaTools = new SolanaToolsBuilder({
     dmk,
@@ -186,6 +194,7 @@ export const SignerSolanaView: React.FC<{ sessionId: string }> = ({
         executeDeviceAction: ({
           derivationPath,
           transaction,
+          delayed,
           templateId,
           tokenAddress,
           tokenInternalId,
@@ -203,25 +212,23 @@ export const SignerSolanaView: React.FC<{ sessionId: string }> = ({
           const hasResolutionContext =
             templateId || tokenAddress || tokenInternalId || createATA;
 
-          return signer.signTransaction(
-            derivationPath,
-            serializedTransaction,
-            hasResolutionContext
-              ? {
-                  transactionResolutionContext: {
-                    templateId: templateId || undefined,
-                    tokenAddress: tokenAddress || undefined,
-                    tokenInternalId: tokenInternalId || undefined,
-                    createATA,
-                  },
-                }
-              : undefined,
-          );
+          return signer.signTransaction(derivationPath, serializedTransaction, {
+            ...(hasResolutionContext && {
+              transactionResolutionContext: {
+                templateId: templateId || undefined,
+                tokenAddress: tokenAddress || undefined,
+                tokenInternalId: tokenInternalId || undefined,
+                createATA,
+              },
+            }),
+            delayed,
+          });
         },
         initialValues: {
           derivationPath: DEFAULT_DERIVATION_PATH,
           transaction: "",
           skipOpenApp: false,
+          delayed: false,
           templateId: "",
           tokenAddress: "",
           tokenInternalId: "",

packages/device-management-kit/src/api/device-action/xstate-utils/XStateDeviceAction.ts

@@ -185,13 +185,16 @@ export abstract class XStateDeviceAction<
       }
 
       // Log internal state on each state transition
-      if (this.logger && status === "active") {
+      if (this.logger && (status === "active" || status === "done")) {
         const stateValue =
           typeof snapshot.value === "string"
             ? snapshot.value
             : JSON.stringify(snapshot.value);
         this.logger.debug(`[XStateDeviceAction] State: ${stateValue}`, {
-          data: { internalState: context._internalState },
+          data: {
+            internalState: context._internalState,
+            intermediateValue: context.intermediateValue,
+          },
         });
       }
 

packages/signer/signer-solana/README.md

@@ -39,9 +39,15 @@ npm install @ledgerhq/device-signer-kit-solana
 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 }).build();
+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. You can override it per `signTransaction` call via `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`.
@@ -119,6 +125,9 @@ const { observable, cancel } = signerSolana.signTransaction(
 - **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.
 
@@ -134,13 +143,8 @@ const { observable, cancel } = signerSolana.signTransaction(
     - **tokenInternalId** `string`
       Ledger internal token ID
 
-  - **solanaRPCURL** `string`  
-    RPC endpoint used for address-lookup table resolution in versioned (v0) transactions.
-    Defaults to `https://api.mainnet-beta.solana.com/`. Override this to use a private RPC
-    or to avoid CORS issues in browser environments.
-
-  - **skipOpenApp** `boolean`  
-    If `true`, skips opening the Solana app on the device.
+- **skipOpenApp** `boolean`  
+  If `true`, skips opening the Solana app on the device.
 
 ---
 

packages/signer/signer-solana/src/api/SignerSolanaBuilder.ts

@@ -13,6 +13,7 @@ type SignerSolanaBuilderConstructorArgs = {
   dmk: DeviceManagementKit;
   sessionId: DeviceSessionId;
   originToken?: string;
+  solanaRPCURL?: string;
 };
 
 /**
@@ -29,15 +30,18 @@ export class SignerSolanaBuilder {
   private _sessionId: DeviceSessionId;
   private _customContextModule: ContextModule | undefined;
   private _originToken: string | undefined;
+  private readonly _solanaRPCURL: string | undefined;
 
   constructor({
     dmk,
     sessionId,
     originToken,
+    solanaRPCURL,
   }: SignerSolanaBuilderConstructorArgs) {
     this._dmk = dmk;
     this._sessionId = sessionId;
     this._originToken = originToken;
+    this._solanaRPCURL = solanaRPCURL;
   }
 
   /**
@@ -60,6 +64,7 @@ export class SignerSolanaBuilder {
     return new DefaultSignerSolana({
       dmk: this._dmk,
       sessionId: this._sessionId,
+      solanaRPCURL: this._solanaRPCURL,
       contextModule:
         this._customContextModule ??
         new ContextModuleBuilder({

packages/signer/signer-solana/src/api/app-binder/DelayedSignTransactionDeviceActionTypes.ts

@@ -0,0 +1,70 @@
+import {
+  type DeviceActionState,
+  type ExecuteDeviceActionReturnType,
+  type OpenAppDAError,
+  type OpenAppDARequiredInteraction,
+  type SendCommandInAppDAError,
+  type UserInteractionRequired,
+} from "@ledgerhq/device-management-kit";
+
+import { type Signature } from "@api/model/Signature";
+import { type UserInputType } from "@api/model/TransactionResolutionContext";
+import { type SolanaAppErrorCodes } from "@internal/app-binder/command/utils/SolanaApplicationErrors";
+import { type BlockhashService } from "@internal/app-binder/services/BlockhashService";
+
+export const delayedSignDAStateSteps = Object.freeze({
+  ZERO_BLOCKHASH: "signer.sol.steps.zeroBlockhash",
+  PREVIEW_TRANSACTION: "signer.sol.steps.previewTransaction",
+  FETCH_BLOCKHASH: "signer.sol.steps.fetchBlockhash",
+  PATCH_TRANSACTION: "signer.sol.steps.patchTransaction",
+  DELAYED_SIGN: "signer.sol.steps.delayedSign",
+  FALLBACK_TO_NON_DELAYED_SIGN: "signer.sol.steps.fallbackToNonDelayedSign",
+} as const);
+
+export type DelayedSignDAStateStep =
+  (typeof delayedSignDAStateSteps)[keyof typeof delayedSignDAStateSteps];
+
+export type DelayedSignDAOutput = Signature;
+
+export type DelayedSignDAInput = {
+  readonly derivationPath: string;
+  readonly transaction: Uint8Array;
+  readonly rpcUrl?: string;
+  readonly fetchBlockhash?: () => Promise<Uint8Array>;
+  readonly userInputType?: UserInputType;
+  readonly blockhashService?: BlockhashService;
+};
+
+export type DelayedSignDAError =
+  | OpenAppDAError
+  | SendCommandInAppDAError<SolanaAppErrorCodes>;
+
+type DelayedSignDARequiredInteraction =
+  | UserInteractionRequired
+  | OpenAppDARequiredInteraction;
+
+export type DelayedSignDAIntermediateValue = {
+  requiredUserInteraction: DelayedSignDARequiredInteraction;
+  step: DelayedSignDAStateStep;
+};
+
+export type DelayedSignDAState = DeviceActionState<
+  DelayedSignDAOutput,
+  DelayedSignDAError,
+  DelayedSignDAIntermediateValue
+>;
+
+export type DelayedSignDAInternalState = {
+  readonly error: DelayedSignDAError | null;
+  readonly signature: Signature | null;
+  readonly zeroedTransaction: Uint8Array | null;
+  readonly freshBlockhash: Uint8Array | null;
+  readonly patchedTransaction: Uint8Array | null;
+  readonly previewFallback: boolean;
+};
+
+export type DelayedSignDAReturnType = ExecuteDeviceActionReturnType<
+  DelayedSignDAOutput,
+  DelayedSignDAError,
+  DelayedSignDAIntermediateValue
+>;

packages/signer/signer-solana/src/api/app-binder/SignTransactionDeviceActionTypes.ts

@@ -14,19 +14,24 @@ import { type Signature } from "@api/model/Signature";
 import { type SolanaTransactionOptionalConfig } from "@api/model/SolanaTransactionOptionalConfig";
 import { type Transaction } from "@api/model/Transaction";
 import { type SolanaAppErrorCodes } from "@internal/app-binder/command/utils/SolanaApplicationErrors";
+import { type BlockhashService } from "@internal/app-binder/services/BlockhashService";
 import { type TxInspectorResult } from "@internal/app-binder/services/TransactionInspector";
 
+import { type DelayedSignDAStateStep } from "./DelayedSignTransactionDeviceActionTypes";
+
 export const signTransactionDAStateSteps = Object.freeze({
   OPEN_APP: "signer.sol.steps.openApp",
   GET_APP_CONFIG: "signer.sol.steps.getAppConfig",
   INSPECT_TRANSACTION: "signer.sol.steps.inspectTransaction",
   BUILD_TRANSACTION_CONTEXT: "signer.sol.steps.buildTransactionContext",
   PROVIDE_TRANSACTION_CONTEXT: "signer.sol.steps.provideTransactionContext",
   SIGN_TRANSACTION: "signer.sol.steps.signTransaction",
+  DELAYED_SIGN: "signer.sol.steps.delayedSign",
 } as const);
 
 export type SignTransactionDAStateStep =
-  (typeof signTransactionDAStateSteps)[keyof typeof signTransactionDAStateSteps];
+  | (typeof signTransactionDAStateSteps)[keyof typeof signTransactionDAStateSteps]
+  | DelayedSignDAStateStep;
 
 export type SignTransactionDAOutput = Signature;
 
@@ -35,6 +40,8 @@ export type SignTransactionDAInput = {
   readonly transaction: Transaction;
   readonly contextModule: ContextModule;
   readonly transactionOptions?: SolanaTransactionOptionalConfig;
+  readonly solanaRPCURL?: string;
+  readonly blockhashService?: BlockhashService;
 };
 
 export type SignTransactionDAError =

packages/signer/signer-solana/src/api/model/SolanaTransactionOptionalConfig.ts

@@ -2,6 +2,9 @@ import { type TransactionResolutionContext } from "./TransactionResolutionContex
 
 export type SolanaTransactionOptionalConfig = {
   transactionResolutionContext?: TransactionResolutionContext;
+  /** When set, overrides the signer default RPC URL for this sign only. */
   solanaRPCURL?: string;
   skipOpenApp?: boolean;
+  delayed?: boolean;
+  fetchBlockhash?: () => Promise<Uint8Array>;
 };