✨ (signer-solana): Restructure sign transaction device action with clear sign child machines

Author: fAnselmi-Ledger

.changeset/pink-mangos-sin-two.md

@@ -0,0 +1,5 @@
+---
+"@ledgerhq/context-module": minor
+---
+
+Support changes for generic clear sign device action

.changeset/pink-mangos-sin.md

@@ -0,0 +1,5 @@
+---
+"@ledgerhq/device-signer-kit-solana": minor
+---
+
+Add generic clear-sign device action

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

@@ -1,7 +1,4 @@
-import {
-  type ContextModule,
-  type SolanaTransactionContextResultSuccess,
-} from "@ledgerhq/context-module";
+import { type ContextModule } from "@ledgerhq/context-module";
 import {
   type DeviceActionState,
   type ExecuteDeviceActionReturnType,
@@ -17,26 +14,40 @@ import { type SolanaTransactionOptionalConfig } from "@api/model/SolanaTransacti
 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";
+import { type SigningOperationsDAStateStep } from "./SigningOperationsDeviceActionTypes";
 
 export const signTransactionDAStateSteps = Object.freeze({
   OPEN_APP: "signer.sol.steps.openApp",
   GET_APP_CONFIG: "signer.sol.steps.getAppConfig",
   WEB3_CHECKS_OPT_IN: "signer.sol.steps.web3ChecksOptIn",
   WEB3_CHECKS_OPT_IN_RESULT: "signer.sol.steps.web3ChecksOptInResult",
+  WEB3_CHECKS_PROVIDE: "signer.sol.steps.web3ChecksProvide",
   INSPECT_TRANSACTION: "signer.sol.steps.inspectTransaction",
   GET_PUB_KEY: "signer.sol.steps.getPubKey",
-  BUILD_TRANSACTION_CONTEXT: "signer.sol.steps.buildTransactionContext",
-  PROVIDE_TRANSACTION_CONTEXT: "signer.sol.steps.provideTransactionContext",
+  BUILD_BASIC_CLEAR_SIGN_CONTEXT: "signer.sol.steps.buildBasicClearSignContext",
+  PROVIDE_BASIC_CLEAR_SIGN_CONTEXT:
+    "signer.sol.steps.provideBasicClearSignContext",
+  BUILD_GENERIC_CLEAR_SIGN_CONTEXT:
+    "signer.sol.steps.buildGenericClearSignContext",
+  PROVIDE_GENERIC_CLEAR_SIGN_CONTEXT:
+    "signer.sol.steps.provideGenericClearSignContext",
+  PROMPT_UI_DISPLAY: "signer.sol.steps.promptUiDisplay",
   SIGN_TRANSACTION: "signer.sol.steps.signTransaction",
   DELAYED_SIGN: "signer.sol.steps.delayedSign",
 } as const);
 
+/**
+ * Which clear-signing path produced the signature.
+ * `full` = device ran the merge engine
+ * `srfc39-only` = partial CAL coverage, device auto-rendered per-instruction without merge
+ * `none` = blind/legacy fallback (no instruction recognised or capability absent).
+ */
+export type ClearSignMode = "full" | "srfc39-only" | "none";
+
 export type SignTransactionDAStateStep =
   | (typeof signTransactionDAStateSteps)[keyof typeof signTransactionDAStateSteps]
-  | DelayedSignDAStateStep;
+  | SigningOperationsDAStateStep;
 
 export type SignTransactionDAOutput = Signature;
 
@@ -81,9 +92,9 @@ export type SignTransactionDAInternalState = {
   readonly error: SignTransactionDAError | null;
   readonly signature: Signature | null;
   readonly appConfig: AppConfiguration | null;
-  readonly solanaTransactionContext: SolanaTransactionContextResultSuccess | null;
-  readonly inspectorResult: TxInspectorResult | null;
-  readonly signerAddress: string | null;
+  // Set when the generic clear-sign path armed the device, so the terminal
+  // sign skips its own preview.
+  readonly clearSignArmed: boolean;
 };
 
 export type SignTransactionDAReturnType = ExecuteDeviceActionReturnType<

…layedSignTransactionDeviceActionTypes.ts …er/SigningOperationsDeviceActionTypes.tspackages/signer/signer-solana/src/api/app-binder/DelayedSignTransactionDeviceActionTypes.ts renamed to packages/signer/signer-solana/src/api/app-binder/SigningOperationsDeviceActionTypes.ts packages/signer/signer-solana/src/api/app-binder/DelayedSignTransactionDeviceActionTypes.ts renamed to packages/signer/signer-solana/src/api/app-binder/SigningOperationsDeviceActionTypes.ts

@@ -12,59 +12,65 @@ 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({
+export const signingOperationsDAStateSteps = 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",
+  SIGN_TRANSACTION: "signer.sol.steps.signTransaction",
   FALLBACK_TO_NON_DELAYED_SIGN: "signer.sol.steps.fallbackToNonDelayedSign",
 } as const);
 
-export type DelayedSignDAStateStep =
-  (typeof delayedSignDAStateSteps)[keyof typeof delayedSignDAStateSteps];
+export type SigningOperationsDAStateStep =
+  (typeof signingOperationsDAStateSteps)[keyof typeof signingOperationsDAStateSteps];
 
-export type DelayedSignDAOutput = Signature;
+export type SigningOperationsDAOutput = Signature;
 
-export type DelayedSignDAInput = {
+export type SigningOperationsDAInput = {
   readonly derivationPath: string;
   readonly transaction: Uint8Array;
   readonly rpcUrl?: string;
   readonly fetchBlockhash?: () => Promise<Uint8Array>;
   readonly userInputType?: UserInputType;
   readonly blockhashService?: BlockhashService;
+  // When the device fingerprint is already armed (e.g. by generic clear-sign's
+  // PROMPT UI DISPLAY), skip the SIGN MESSAGE PREVIEW step and go straight to
+  // the blockhash refresh + SIGN MESSAGE DELAYED. Without a blockhash source the
+  // original transaction is signed as-is.
+  readonly alreadyArmed?: boolean;
 };
 
-export type DelayedSignDAError =
+export type SigningOperationsDAError =
   | OpenAppDAError
   | SendCommandInAppDAError<SolanaAppErrorCodes>;
 
-type DelayedSignDARequiredInteraction =
+type SigningOperationsDARequiredInteraction =
   | UserInteractionRequired
   | OpenAppDARequiredInteraction;
 
-export type DelayedSignDAIntermediateValue = {
-  requiredUserInteraction: DelayedSignDARequiredInteraction;
-  step: DelayedSignDAStateStep;
+export type SigningOperationsDAIntermediateValue = {
+  requiredUserInteraction: SigningOperationsDARequiredInteraction;
+  step: SigningOperationsDAStateStep;
 };
 
-export type DelayedSignDAState = DeviceActionState<
-  DelayedSignDAOutput,
-  DelayedSignDAError,
-  DelayedSignDAIntermediateValue
+export type SigningOperationsDAState = DeviceActionState<
+  SigningOperationsDAOutput,
+  SigningOperationsDAError,
+  SigningOperationsDAIntermediateValue
 >;
 
-export type DelayedSignDAInternalState = {
-  readonly error: DelayedSignDAError | null;
+export type SigningOperationsDAInternalState = {
+  readonly error: SigningOperationsDAError | 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
+export type SigningOperationsDAReturnType = ExecuteDeviceActionReturnType<
+  SigningOperationsDAOutput,
+  SigningOperationsDAError,
+  SigningOperationsDAIntermediateValue
 >;

packages/signer/signer-solana/src/internal/app-binder/SolanaApplicationResolver.ts

@@ -1,18 +1,25 @@
 import {
   type AppConfig,
+  ApplicationChecker,
   type ApplicationResolver,
   DeviceModelId,
   type DeviceSessionState,
   DeviceSessionStateType,
+  type InternalApi,
   type ResolvedApp,
 } from "@ledgerhq/device-management-kit";
 
+import { type AppConfiguration } from "@api/model/AppConfiguration";
+
 import { APP_NAME } from "./constants";
 
+const UNRELEASED_MIN_VERSION = "10.0.0";
 const DEFAULT_VERSION = "0.0.1";
 export const SOLANA_MIN_SPL_VERSION = "1.9.2";
 export const SOLANA_MIN_DELAYED_SIGNING_VERSION = "1.14.0";
-export const SOLANA_MIN_WEB3_CHECKS_VERSION = "1.15.0";
+
+export const SOLANA_MIN_WEB3_CHECKS_VERSION = UNRELEASED_MIN_VERSION;
+export const SOLANA_MIN_GENERIC_CLEAR_SIGN_VERSION = UNRELEASED_MIN_VERSION;
 
 export const SOLANA_FEATURES = {
   spl: {
@@ -34,8 +41,34 @@ export const SOLANA_FEATURES = {
     excludedModels: [] as DeviceModelId[],
     excludedApps: [] as string[],
   },
+  genericClearSign: {
+    minVersion: SOLANA_MIN_GENERIC_CLEAR_SIGN_VERSION,
+    excludedModels: [DeviceModelId.NANO_S],
+    excludedApps: ["Exchange"],
+  },
 } as const;
 
+/**
+ * Whether the connected Solana app supports a given feature, applying its
+ * minimum version plus device-model / orchestrating-app exclusions.
+ */
+export function isSolanaFeatureSupported(
+  internalApi: InternalApi,
+  feature: keyof typeof SOLANA_FEATURES,
+  appConfig: AppConfiguration,
+): boolean {
+  const { minVersion, excludedModels, excludedApps } = SOLANA_FEATURES[feature];
+  return new ApplicationChecker(
+    internalApi.getDeviceSessionState(),
+    appConfig,
+    new SolanaApplicationResolver(),
+  )
+    .withMinVersionInclusive(minVersion)
+    .excludeDeviceModels(...excludedModels)
+    .excludeApps(...excludedApps)
+    .check();
+}
+
 export class SolanaApplicationResolver implements ApplicationResolver {
   resolve(deviceState: DeviceSessionState, appConfig: AppConfig): ResolvedApp {
     if (deviceState.sessionStateType === DeviceSessionStateType.Connected) {