From a840c39e418b5e5af592cfacd6bd66ed128aee51 Mon Sep 17 00:00:00 2001 From: Charles-Edouard de la Vergne Date: Wed, 12 Feb 2025 14:47:27 +0100 Subject: [PATCH] Update feature doc --- doc/ethapp.adoc | 73 +++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 62 insertions(+), 11 deletions(-) diff --git a/doc/ethapp.adoc b/doc/ethapp.adoc index 4d04363f7..44cb82c42 100644 --- a/doc/ethapp.adoc +++ b/doc/ethapp.adoc @@ -1212,7 +1212,7 @@ For the configuration, the following tags are supported: [width="80%"] |=============================================================== | *Tag name* | *Tag value* | *Length (byte)* | *Value* -| STRUCTURE_TYPE | 0x01 | 0x01 | 0x08 (for TYPE_DYNAMIC_NETWORK) +| STRUCTURE_TYPE | 0x01 | 0x01 | 0x08 (for `TYPE_DYNAMIC_NETWORK`) | STRUCTURE_VERSION | 0x02 | 0x01 | 0x01 | BLOCKCHAIN_FAMILY | 0x51 | 0x01 | 0x01 (for Ethereum) | CHAIN_ID | 0x23 | 0x08 | (`uint64_t` value) @@ -1285,7 +1285,17 @@ _Output data_ This command handles the Transaction Simulation information, allowing to evaluate and verify the risk. -This information must be sent before any transaction to be verified and confirmed. +There are 2 sub-commands: + +- One command to request the Opt-In flow, to inform the user a new parameter is available +- One command to send the payload data with the simulation information + +> Notes: +> +> - The Opt-In should be sent only once + + +The Transaction Simulation information must be sent before any transaction to be verified and confirmed. It will be displayed in the review flow only if the corresponding setting is _Enabled_. The information is sent in TLV (Tag-Length-Value) mode. The following tags are supported: @@ -1293,46 +1303,87 @@ The information is sent in TLV (Tag-Length-Value) mode. The following tags are s [width="80%"] |=============================================================================================== | *Tag name* | *Tag value* | *Length (byte)* | *Value* -| STRUCTURE_TYPE | 0x01 | 0x01 | 0x09 (for TYPE_TX_SIMULATION) +| STRUCTURE_TYPE | 0x01 | 0x01 | 0x09 (for `TYPE_TX_SIMULATION`) | STRUCTURE_VERSION | 0x02 | 0x01 | 0x01 | ADDRESS | 0x22 | 0x14 | Ethereum `From` Address | CHAIN_ID | 0x23 | 0x08 | (`uint64_t` value) | TX_HASH | 0x27 | 0x20 | Hash of the Tx that was simulated -| W3C_NORMALIZED_RISK | 0x80 | 0x02 | Normalized risk score of the transaction. +| DOMAIN_HASH | 0x28 | 0x20 | _Domain Hash_ for EIP712 +| W3C_NORMALIZED_RISK | 0x80 | 0x01 | Normalized risk score of the transaction. | W3C_NORMALIZED_CATEGORY | 0x81 | 0x01 | Main category explaining the risk score | W3C_PROVIDER_MSG | 0x82 | variable (max 30) | Provider specific message explaining the risk score -| W3C_TINY_URL | 0x33 | variable (max 30) | URL to access the full report +| W3C_TINY_URL | 0x83 | variable (max 30) | URL to access the full report +| W3C_SIMULATION_TYPE | 0x84 | 0x01 | Type of simulation | SIGNATURE | 0x15 | variable | Signature of the TLV payload data |=============================================================================================== The signature is mandatory, and is computed on the full payload data, using `CX_CURVE_SECP256K1`. -The App will verify the validity of this simulation using the fields: +Then, the App will verify the validity of this simulation using the fields: - `ADDRESS` - `CHAIN_ID` - `TX_HASH` +- `SIMULATION_TYPE` + +If one of those fields are not correct (or don't correspond to the current TX), the check status is considered _Unknown_. + +The _Risk Score_ is normalized and interpreted like this: + +- `0`: Benign +- `1`: Warning +- `2`: Malicious + +The _Simulation Type_ is normalized and interpreted like this: + +- `0`: Transaction +- `1`: Typed Data (EIP-712) +- `2`: Personal Message (EIP-191) + +#### Coding -If one of those 3 fields are not correct (and don't correspond to the current TX), the check status is considered _Unknown_. +_Command_ -The Risk score is normalized and interpreted like this: +[width="80%"] +|============================================================== +| *CLA* | *INS* | *P1* | *P2* | *LC* | *Le* +.3+| E0 .3+| 32 | 00 : TX Simulation Payload | 00 | variable | variable + | 01 : TX Simulation Opt-In | 00 | 00 | 00 +|============================================================== -- `0x0000` to `0x5555`: Benign -- `0x5556` to `0xAAAA`: Warning -- `0xAAAB` to `0xFFFF`: Malicious +|============================================================== +| *CLA* | *INS* | *P1* | *P2* | *LC* | *Le* +.2+| E0 .2+| 32 | 00 : TX Simulation Payload | 00 | variable | variable + | 01 : TX Simulation Opt-In | 00 | 00 | 00 +|============================================================== _Input data_ +##### If P1 == TX Simulation Payload + [width="80%"] |========================================== | *Description* | *Length (byte)* | TLV payload | variable |========================================== +##### If P1 == TX Simulation Opt-In + +None + _Output data_ +##### If P1 == TX Simulation Payload + None +##### If P1 == TX Simulation Opt-In + +[width="80%"] +|==================================== +| *Description* | *Length* +| Web3 Check setting status | 1 +|==================================== ## Transport protocol