Ethereum application : Starkware extensions
============================================
Ledger Firmware Team <hello@ledger.fr>
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

## Modified general purpose APDUs

### GET APP CONFIGURATION

#### Description

This command returns specific application configuration

It is modified to notify Stark extensions support on flag 0x04

#### Coding

'Command'

[width="80%"]
|==============================================================================================================================
| *CLA* | *INS*  | *P1*               | *P2*       | *Lc*     | *Le*   
|   E0  |   06   |  00                |   00       | 00       | 04
|==============================================================================================================================

'Input data'

None

'Output data'

[width="80%"]
|==============================================================================================================================
| *Description*                                                                     | *Length*
| Flags            
        0x01 : arbitrary data signature enabled by user

        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
| Application patch version                                                         | 01
|==============================================================================================================================


## Additional APDUs

Additional APDUs use the APDU CLA F0

### GET STARK PUBLIC KEY

#### Description

This command returns the public Stark key (X and Y coordinates) for the given BIP 32 path.

The key can be optionally checked on the device before being returned - in that case, only the X coordinate is displayed, as this is what is used in the contract

#### Coding

'Command'

[width="80%"]
|==============================================================================================================================
| *CLA* | *INS*  | *P1*               | *P2*       | *Lc*     | *Le*   
|   F0  |   02   |  00 : return address

                    01 : display address and confirm before returning
                                      |   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
|==============================================================================================================================

'Output data'

[width="80%"]
|==============================================================================================================================
| *Description*                                                                     | *Length*
| Stark key                                                                         | 65
|==============================================================================================================================

### SIGN STARK MESSAGE

#### Description

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'

[width="80%"]
|==============================================================================================================================
| *CLA* | *INS*  | *P1*               | *P2*       | *Lc*     | *Le*   
|   F0  |   04   | 
                    01 : sign a Stark Order (protocol v1, handles ETH and regular ERC 20)

                    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 (v1)'

[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
| Contract address of the token to be sold (or 00..00 for ETH)                      | 20 
| Quantization of the token to be sold (big endian)                                 | 32
| Contract address of the token to be bought (or 00..00 for ETH)                    | 20
| Quantization of the token to be bought (big endian)                               | 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 (v1)'

[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
| Contract address of the token to be transferred (or 00..00 for ETH)               | 20 
| Quantization of the token to be transferred (big endian)                          | 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 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'

[width="80%"]
|==============================================================================================================================
| *Description*                                                                     | *Length*
| RFU (00)                                                                          | 1
| r                                                                                 | 32
| s                                                                                 | 32
|==============================================================================================================================


### PROVIDES QUANTUM

#### Description

This command provides quantization data used to compute a tokenId and provide additional information to the user before signing a transaction performing a deposit or withdrawal call on a Stark powered smart contract.

It shall be called following a PROVIDE ERC 20 TOKEN INFORMATION command called for the associated contract

#### Coding

'Command'

[width="80%"]
|==============================================================================================================================
| *CLA* | *INS*  | *P1*               | *P2*       | *Lc*     | *Le*   
|   F0  |   08   | 
                    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
|==============================================================================================================================

'Legacy Input data'

[width="80%"]
|==============================================================================================================================
| *Description*                                                                     | *Length*
| Contract address used in the next transaction                                     | 20
| 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
|==============================================================================================================================

