Merge pull request #922 from LedgerHQ/fbe/swap_doc

fbeutin-ledger · web-flow · commit 5af9a281f622 · 2025-04-03T11:26:12.000+02:00
Add more comments for swap and add markers for SWAP documentation
diff --git a/lib_standard_app/main.c b/lib_standard_app/main.c
@@ -114,6 +114,13 @@ WEAK void standalone_app_main(void)
 }
 
 #ifdef HAVE_SWAP
+// --8<-- [start:library_app_main]
+/* This function is called by the main() function if this application was started by Exchange
+ * through an os_lib_call() as opposed to being started from the Dashboard.
+ *
+ * We dispatch the Exchange request to the correct handler.
+ * Handlers content are not defined in the `lib_standard_app`
+ */
 WEAK void library_app_main(libargs_t *args)
 {
     BEGIN_TRY
@@ -165,6 +172,7 @@ WEAK void library_app_main(libargs_t *args)
     }
     END_TRY;
 }
+// --8<-- [end:library_app_main]
 #endif  // HAVE_SWAP
 
 WEAK __attribute__((section(".boot"))) int main(int arg0)
diff --git a/lib_standard_app/swap_entrypoints.h b/lib_standard_app/swap_entrypoints.h
@@ -22,21 +22,46 @@
 #include "swap_lib_calls.h"
 
 /*
- * These functions must be defined by the application
- */
+--8<-- [start:swap_entry_point_intro]
+The handle functions must be defined by each Coin application implementing the SWAP feature.
+
+Handlers are called by Exchange through the `os_lib_call` API, and dispatched by the `main()`
+and `library_app_main()` functions of the lib_standard_app.
 
-/* Check check_address_parameters_t.address_to_check against specified parameters.
+The Exchange application is responsible for handling the flow and sequencing of the SWAP.
+--8<-- [end:swap_entry_point_intro]
+*/
+
+// --8<-- [start:swap_handle_check_address]
+/* This handle is called when the Exchange application wants to ensure that a
+ * given address belongs to the device.
  *
- * Must set params.result to 0 on error, 1 otherwise */
+ * If the address does belong to the device, result is set to 1. Otherwise it
+ * is set to 0.
+ */
 void swap_handle_check_address(check_address_parameters_t *params);
+// --8<-- [end:swap_handle_check_address]
 
-/* Format printable amount including the ticker from specified parameters.
+// --8<-- [start:swap_handle_get_printable_amount]
+/* This handle is called when the Exchange application wants to format for
+ * display an amount + ticker of a currency known by this application
  *
- * Must set empty printable_amount on error, printable amount otherwise */
+ * If the formatting succeeds, result is set to the formatted string. Otherwise
+ * it is set to '\0'.
+ */
 void swap_handle_get_printable_amount(get_printable_amount_parameters_t *params);
+// --8<-- [end:swap_handle_get_printable_amount]
 
-/* Backup up transaction parameters and wipe BSS to avoid collusion with
- * app-exchange BSS data.
+// --8<-- [start:swap_copy_transaction_parameters]
+/* This handle is called when the user has validated on screen the transaction
+ * proposal sent by the partner and started the FROM Coin application to sign
+ * the payment transaction.
+ *
+ * This handler needs to save in the heap the details of what has been validated
+ * in Exchange. These elements will be checked against the received transaction
+ * upon its reception from the Ledger Live.
  *
- * return false on error, true otherwise */
+ * return false on error, true otherwise
+ */
 bool swap_copy_transaction_parameters(create_transaction_parameters_t *sign_transaction_params);
+// --8<-- [end:swap_copy_transaction_parameters]
diff --git a/lib_standard_app/swap_error_code_helpers.h b/lib_standard_app/swap_error_code_helpers.h
@@ -6,7 +6,14 @@
 
 // clang-format off
 /*
-# Error response for applications started by Exchange in SWAP context
+--8<-- [start:intro]
+# Error responses for applications started by Exchange in SWAP context
+
+This specification applies to the error responses returned by the Coin applications when started by
+Exchange for the final payment transaction of a SWAP.
+
+Replying valuable data when a final payment transaction is refused eases a lot the analysis,
+especially if the issue happens in production context and / or is hard to reproduce.
 
 ## RAPDU status word
 
@@ -18,28 +25,33 @@ The first 2 bytes of the RAPDU data represent the error code. Format is 16 bits
 
 The upper byte is common between all applications. It must be one of the following value:
 
-| Name                          | Value  | Description                                                                   |
-| ----------------------------- | ------ | ----------------------------------------------------------------------------- |
-| ERROR_INTERNAL                | 0x00   | Internal application error, forward to the firmware team for analysis.        |
-| ERROR_WRONG_AMOUNT            | 0x01   | The amount does not match the one validated in Exchange.                      |
-| ERROR_WRONG_DESTINATION       | 0x02   | The destination address does not match the one validated in Exchange.         |
-| ERROR_WRONG_FEES              | 0x03   | The fees are different from what was validated in Exchange.                   |
-| ERROR_WRONG_METHOD            | 0x04   | The method used is invalid in Exchange context.                               |
-| ERROR_CROSSCHAIN_WRONG_MODE   | 0x05   | The mode used for the cross-chain hash validation is not supported.           |
-| ERROR_CROSSCHAIN_WRONG_METHOD | 0x06   | The method used is invalid in cross-chain Exchange context.                   |
-| ERROR_CROSSCHAIN_WRONG_HASH   | 0x07   | The hash for the cross-chain transaction does not match the validated value.  |
-| ERROR_GENERIC                 | 0xFF   | A generic or unspecified error not covered by the specific error codes above. |
-|                               |        |     Refer to the remaining bytes for further details on the error.            |
+| Name                          | Value  | Description                                                                                                                                     |
+| ----------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| ERROR_INTERNAL                | 0x00   | Internal application error, forward to the Firmware team for analysis.                                                                          |
+| ERROR_WRONG_AMOUNT            | 0x01   | The amount does not match the one validated in Exchange.                                                                                        |
+| ERROR_WRONG_DESTINATION       | 0x02   | The destination address does not match the one validated in Exchange.                                                                           |
+| ERROR_WRONG_FEES              | 0x03   | The fees are different from what was validated in Exchange.                                                                                     |
+| ERROR_WRONG_METHOD            | 0x04   | The method used is invalid in Exchange context.                                                                                                 |
+| ERROR_CROSSCHAIN_WRONG_MODE   | 0x05   | The mode used for the cross-chain hash validation is not supported.                                                                             |
+| ERROR_CROSSCHAIN_WRONG_METHOD | 0x06   | The method used is invalid in cross-chain Exchange context.                                                                                     |
+| ERROR_CROSSCHAIN_WRONG_HASH   | 0x07   | The hash for the cross-chain transaction does not match the validated value.                                                                    |
+| ERROR_GENERIC                 | 0xFF   | A generic or unspecified error not covered by the specific error codes above.<br>Refer to the remaining bytes for further details on the error. |
 
-The lower byte can be set by the application to refine the error code returned
+The lower byte can be set by the application to refine the error code returned.
 
-So the error code for ERROR_WRONG_METHOD would be 0x04XX with XX being application specific (can be 00 if there is nothing to refine)
+So the error code for `ERROR_WRONG_METHOD` would be `0x04XX` with `XX` being application specific
+(can be `00` if there is nothing to refine).
 
 The remaining bytes of the data are application-specific and can include, but are not limited to:
+
 - Debugging information (e.g., error logs or internal state).
 - Field values (e.g., expected vs actual amounts, destination, fees).
 - More specific error codes tailored to the application's context.
- */
+
+The standard application library define several helper function to return error codes from the Coin
+application.
+--8<-- [end:intro]
+*/
 // clang-format on
 
 typedef enum swap_error_common_code_e {
@@ -54,8 +66,10 @@ typedef enum swap_error_common_code_e {
     SWAP_EC_ERROR_GENERIC                 = 0xFF,
 } swap_error_common_code_t;
 
+// --8<-- [start:helpers]
 /**
  * Sends a basic swap error with no extra data.
+ *
  * @param status_word RAPDU status word.
  * @param common_error_code Common error code defined in swap_error_common_code_t.
  * @param application_specific_error_code Application-specific error code.
@@ -66,6 +80,7 @@ __attribute__((noreturn)) void send_swap_error_simple(uint16_t status_word,
 
 /**
  * Sends a swap error with one additional buffer data.
+ *
  * @param status_word RAPDU status word.
  * @param common_error_code Common error code.
  * @param application_specific_error_code Application-specific error code.
@@ -77,7 +92,8 @@ __attribute__((noreturn)) void send_swap_error_with_buffer(uint16_t status_word,
                                                            const buffer_t buffer_data);
 
 /**
- * Sends a swap error with multiple buffers containing error details.
+ * Sends a swap error with multiple buffers containing error details as data.
+ *
  * @param status_word RAPDU status word.
  * @param common_error_code Common error code.
  * @param application_specific_error_code Application-specific error code.
@@ -92,7 +108,8 @@ __attribute__((noreturn)) void send_swap_error_with_buffers(uint16_t status_word
                                                             size_t          count);
 
 /**
- * Macro to send a swap error using a formatted string.
+ * Macro to send a swap error with a formatted string as data.
+ *
  * Constructs a buffer from a formatted string and passes it to send_swap_error_with_buffers.
  * @param status_word RAPDU status word.
  * @param common_error_code Common error code.
@@ -120,5 +137,6 @@ __attribute__((noreturn)) void send_swap_error_with_buffers(uint16_t status_word
         send_swap_error_with_buffers(                                                            \
             status_word, common_error_code, application_specific_error_code, &string_buffer, 1); \
     } while (0)
+// --8<-- [end:helpers]
 
 #endif  // HAVE_SWAP
diff --git a/lib_standard_app/swap_lib_calls.h b/lib_standard_app/swap_lib_calls.h
@@ -1,20 +1,24 @@
 #pragma once
 
-/* This file is the shared API between Exchange and the apps started in Library mode for Exchange
- *
- * DO NOT MODIFY THIS FILE IN APPLICATIONS OTHER THAN EXCHANGE
- * On modification in Exchange, forward the changes to all applications supporting Exchange
- */
+/*
+ --8<-- [start:swap_lib_calls_intro]
+This file is the shared API between the Exchange application and the coin applications started in
+Library mode for Exchange.
+
+On Coin application side, the main() of the lib_standard_app has the logic to recognize a library
+start from a dashboard start and the logic to dispatch the library commands to the correct handler
+function.
+--8<-- [end:swap_lib_calls_intro]
+*/
 
 #include "stdbool.h"
 #include "stdint.h"
 
-#define RUN_APPLICATION 1
-
-#define SIGN_TRANSACTION 2
-
-#define CHECK_ADDRESS 3
-
+// The os_lib_calls commands that can be called by the Exchange application.
+// They are handled by the lib_standard_app main() function.
+#define RUN_APPLICATION      1
+#define SIGN_TRANSACTION     2
+#define CHECK_ADDRESS        3
 #define GET_PRINTABLE_AMOUNT 4
 
 /*
@@ -27,47 +31,91 @@
  */
 #define MAX_PRINTABLE_AMOUNT_SIZE 50
 
-// structure that should be send to specific coin application to get address
+// Structure parameter used by swap_handle_check_address
+// --8<-- [start:check_address_parameters_t]
 typedef struct check_address_parameters_s {
-    // IN
+    // INPUTS //
+    // Additional data when dealing with tokens
+    // Content is coin application specific
     uint8_t *coin_configuration;
     uint8_t  coin_configuration_length;
+
     // serialized path, segwit, version prefix, hash used, dictionary etc.
-    // fields and serialization format depends on specific coin app
+    // fields and serialization format are coin application specific
     uint8_t *address_parameters;
     uint8_t  address_parameters_length;
-    char    *address_to_check;
-    char    *extra_id_to_check;
-    // OUT
+
+    // The address to check
+    char *address_to_check;
+
+    // Extra content that may be relevant depending on context: memo, calldata, ...
+    // Content is coin application specific
+    char *extra_id_to_check;
+
+    // OUTPUT //
+    // Set to 1 if the address belongs to the device. 0 otherwise.
     int result;
 } check_address_parameters_t;
+// --8<-- [end:check_address_parameters_t]
 
-// structure that should be send to specific coin application to get printable amount
+// Structure parameter used by swap_handle_get_printable_amount
+// --8<-- [start:get_printable_amount_parameters_t]
 typedef struct get_printable_amount_parameters_s {
-    // IN
+    // INPUTS //
+    // Additional data when dealing with tokens
+    // Content is coin application specific
     uint8_t *coin_configuration;
     uint8_t  coin_configuration_length;
+
+    // Raw amount in big number format
     uint8_t *amount;
     uint8_t  amount_length;
-    bool     is_fee;
-    // OUT
+
+    // Set to true if the amount to format is the fee of the swap.
+    bool is_fee;
+
+    // OUTPUT //
+    // Set to the formatted string if the formatting succeeds. 0 otherwise.
     char printable_amount[MAX_PRINTABLE_AMOUNT_SIZE];
 } get_printable_amount_parameters_t;
+// --8<-- [end:get_printable_amount_parameters_t]
 
+// Structure parameter used by swap_copy_transaction_parameters
+// --8<-- [start:create_transaction_parameters_t]
 typedef struct create_transaction_parameters_s {
-    // IN
+    // INPUTS //
+    // Additional data when dealing with tokens
+    // Content is coin application specific
     uint8_t *coin_configuration;
     uint8_t  coin_configuration_length;
+
+    // The amount validated on the screen by the user
     uint8_t *amount;
     uint8_t  amount_length;
+
+    // The fees amount validated on the screen by the user
     uint8_t *fee_amount;
     uint8_t  fee_amount_length;
-    char    *destination_address;
-    char    *destination_address_extra_id;
-    // OUT
+
+    // The partner address that will receive the funds
+    char *destination_address;
+    char *destination_address_extra_id;
+
+    // OUTPUT //
+    // /!\ This parameter is handled by the lib_standard_app, DO NOT interact
+    // with it in the Coin application
+    //
+    // After reception and signature or refusal of the transaction, the Coin
+    // application will return to Exchange. This boolean is used to inform the
+    // Exchange application of the result.
+    // Set to 1 if the transaction was successfully signed, 0 otherwise.
     uint8_t result;
 } create_transaction_parameters_t;
+// --8<-- [end:create_transaction_parameters_t]
 
+// --8<-- [start:libargs_t]
+// Parameter given through os_lib_call() to the Coin application by the Exchange application.
+// They are handled by the lib_standard_app main() function.
 typedef struct libargs_s {
     unsigned int id;
     unsigned int command;
@@ -78,3 +126,4 @@ typedef struct libargs_s {
         get_printable_amount_parameters_t *get_printable_amount;
     };
 } libargs_t;
+// --8<-- [end:libargs_t]

Original file line number	Diff line number	Diff line change
`@@ -114,6 +114,13 @@ WEAK void standalone_app_main(void)`
`114`	`114`	`}`
`115`	`115`
`116`	`116`	`#ifdef HAVE_SWAP`
	`117`	`+// --8<-- [start:library_app_main]`
	`118`	`+/* This function is called by the main() function if this application was started by Exchange`
	`119`	`+ * through an os_lib_call() as opposed to being started from the Dashboard.`
	`120`	`+ *`
	`121`	`+ * We dispatch the Exchange request to the correct handler.`
	`122`	+ * Handlers content are not defined in the `lib_standard_app`
	`123`	`+ */`
`117`	`124`	`WEAK void library_app_main(libargs_t *args)`
`118`	`125`	`{`
`119`	`126`	`BEGIN_TRY`
`@@ -165,6 +172,7 @@ WEAK void library_app_main(libargs_t *args)`
`165`	`172`	`}`
`166`	`173`	`END_TRY;`
`167`	`174`	`}`
	`175`	`+// --8<-- [end:library_app_main]`
`168`	`176`	`#endif // HAVE_SWAP`
`169`	`177`
`170`	`178`	`WEAK __attribute__((section(".boot"))) int main(int arg0)`