From d88c832f06249f43096dfccd4933f322af49f961 Mon Sep 17 00:00:00 2001 From: BTChip github Date: Sun, 21 Feb 2021 23:38:44 +0100 Subject: [PATCH] Update starkexv2 documentation --- doc/eth_starkware_extensions.asc | 155 +++++++++++++++++++++++++++++-- 1 file changed, 148 insertions(+), 7 deletions(-) diff --git a/doc/eth_starkware_extensions.asc b/doc/eth_starkware_extensions.asc index 6ee288d..48e91fd 100644 --- a/doc/eth_starkware_extensions.asc +++ b/doc/eth_starkware_extensions.asc @@ -1,11 +1,14 @@ Ethereum application : Starkware extensions ============================================ Ledger Firmware Team -Application version 1.3.0 - 15th of February 2020 +Application version 1.5.0 - 4th of October 2020 ## 1.3.0 - Initial release +## 1.5.0 + - Update with Starkex v2 APIs + ## About This specification describes the APDU messages interface implementing the Starkware extensions for the Ethereum appilcation @@ -45,6 +48,8 @@ None 0x02 : ERC 20 Token information needs to be provided externally 0x04 : Stark extensions are supported + + 0x08 : Stark protocol v2 is supported | 01 | Application major version | 01 | Application minor version | 01 @@ -104,6 +109,8 @@ This command signs an order or a transfer on the Starkware curve. The contract addressed associated to the token shall have be provisioned previously with the PROVIDE ERC 20 TOKEN INFORMATION command or this command will fail. +The quantum type for v2 messages is encoded as p1 for the PROVIDE QUANTUM command + #### Coding 'Command' @@ -112,14 +119,20 @@ The contract addressed associated to the token shall have be provisioned previou |============================================================================================================================== | *CLA* | *INS* | *P1* | *P2* | *Lc* | *Le* | F0 | 04 | - 01 : sign a Stark Order + 01 : sign a Stark Order (protocol v1, handles ETH and regular ERC 20) - 02 : sign a Stark Transfer + 02 : sign a Stark Transfer (protocol v1, handles ETH and regular ERC 20) + + 03 : sign a Stark Order (since protocol v2) + + 04 : sign a Stark Transfer (since protocol v2) + + 05 : sign a Stark Conditional Transfer (since protocol v2) | 00 | variable | variable |============================================================================================================================== -'Input data for a Stark Order' +'Input data for a Stark Order (v1)' [width="80%"] |============================================================================================================================== @@ -140,7 +153,7 @@ The contract addressed associated to the token shall have be provisioned previou | Transaction timestamp (big endian encoded) | 4 |============================================================================================================================== -'Input data for a Stark Transfer' +'Input data for a Stark Transfer (v1)' [width="80%"] |============================================================================================================================== @@ -159,6 +172,74 @@ The contract addressed associated to the token shall have be provisioned previou | Transaction timestamp (big endian encoded) | 4 |============================================================================================================================== +'Input data for a Stark Order (v2)' + +[width="80%"] +|============================================================================================================================== +| *Description* | *Length* +| Number of BIP 32 derivations to perform (max 10) | 1 +| First derivation index (big endian) | 4 +| ... | 4 +| Last derivation index (big endian) | 4 +| Quantization type of the token to be sold | 1 +| Contract address of the token to be sold (or 00..00 for ETH) | 20 +| Quantization or Token ID of the token to be sold (big endian) | 32 +| Minting blob of the token to be sold (ignored if non mintable) | 32 +| Quantization type of the token to be bought | 1 +| Contract address of the token to be bought (or 00..00 for ETH) | 20 +| Quantization or Token ID of the token to be bought (big endian) | 32 +| Minting blob of the token to be bought (ignored if non mintable) | 32 +| ID of the source vault (big endian encoded) | 4 +| ID of the destination vault (big endian encoded) | 4 +| Amount to be sold (big endian encoded) | 8 +| Amount to buy (big endian encoded) | 8 +| Transaction nonce (big endian encoded) | 4 +| Transaction timestamp (big endian encoded) | 4 +|============================================================================================================================== + +'Input data for a Stark Transfer (v2)' + +[width="80%"] +|============================================================================================================================== +| *Description* | *Length* +| Number of BIP 32 derivations to perform (max 10) | 1 +| First derivation index (big endian) | 4 +| ... | 4 +| Last derivation index (big endian) | 4 +| Quantization type of the token to be transferred | 1 +| Contract address of the token to be transferred (or 00..00 for ETH) | 20 +| Quantization or Token ID of the token to be transferred (big endian) | 32 +| Minting blob of the token to be transferred (ignored if non mintable) | 32 +| Token target public key | 32 +| ID of the source vault (big endian encoded) | 4 +| ID of the destination vault (big endian encoded) | 4 +| Amount to be transferred (big endian encoded) | 8 +| Transaction nonce (big endian encoded) | 4 +| Transaction timestamp (big endian encoded) | 4 +|============================================================================================================================== + +'Input data for a Stark Conditional Transfer' + +[width="80%"] +|============================================================================================================================== +| *Description* | *Length* +| Number of BIP 32 derivations to perform (max 10) | 1 +| First derivation index (big endian) | 4 +| ... | 4 +| Last derivation index (big endian) | 4 +| Quantization type of the token to be transferred | 1 +| Contract address of the token to be transferred (or 00..00 for ETH) | 20 +| Quantization or Token ID of the token to be transferred (big endian) | 32 +| Minting blob of the token to be transferred (ignored if non mintable) | 32 +| Token target public key | 32 +| ID of the source vault (big endian encoded) | 4 +| ID of the destination vault (big endian encoded) | 4 +| Amount to be transferred (big endian encoded) | 8 +| Transaction nonce (big endian encoded) | 4 +| Transaction timestamp (big endian encoded) | 4 +| Conditional transfer fact (big endian) | 32 +| Conditional transfer L1 condition logic address | 20 +|============================================================================================================================== 'Output data' @@ -187,12 +268,22 @@ It shall be called following a PROVIDE ERC 20 TOKEN INFORMATION command called f |============================================================================================================================== | *CLA* | *INS* | *P1* | *P2* | *Lc* | *Le* | F0 | 08 | - 00 + 00 : legacy (protocol v1, handles ETH and regular ERC 20) + + 01 : quantum encoded for ETH (since protocol v2) + + 02 : quantum encoded for a regular ERC 20 (since protocol v2) + + 03 : quantum encoded for a regular ERC 721 (since protocol v2) + + 04 : quantum encoded for a mintable ERC 20 (since protocol v2) + + 05 : quantum encoded for a mintable ERC 721 (since protocol v2) | 00 | variable | variable |============================================================================================================================== -'Input data' +'Legacy Input data' [width="80%"] |============================================================================================================================== @@ -201,7 +292,57 @@ It shall be called following a PROVIDE ERC 20 TOKEN INFORMATION command called f | Quantization to be used in the next transaction | 32 |============================================================================================================================== +'v2 Input data' + +[width="80%"] +|============================================================================================================================== +| *Description* | *Length* +| Contract address used in the next transaction (ignored for ETH) | 20 +| Quantization to be used in the next transaction (ignored for ERC 721s) | 32 +| Minting blob to be used in the next transaction (ignored for non mintable) | 32 +|============================================================================================================================== 'Output data' None + +### UNSAFE SIGN + +#### Description + +This command signs an arbitrary hash on the Starkware Curve after presenting the hash to the user. It is intended for speed of execution in case an unknown Stark model is pushed and should be avoided as much as possible. + +#### Coding + +'Command' + +[width="80%"] +|============================================================================================================================== +| *CLA* | *INS* | *P1* | *P2* | *Lc* | *Le* +| F0 | 0A | + 00 + | 00 | variable | variable +|============================================================================================================================== + +'Input data' + +[width="80%"] +|============================================================================================================================== +| *Description* | *Length* +| Number of BIP 32 derivations to perform (max 10) | 1 +| First derivation index (big endian) | 4 +| ... | 4 +| Last derivation index (big endian) | 4 +| Hash to sign | 32 +|============================================================================================================================== + +'Output data' + +[width="80%"] +|============================================================================================================================== +| *Description* | *Length* +| RFU (00) | 1 +| r | 32 +| s | 32 +|============================================================================================================================== +