Support Ledger signer

.github/workflows/checks.yml

@@ -160,6 +160,9 @@ jobs:
       fail-fast: false
       matrix:
         python-version: [ "3.8", "3.9", "3.10", "3.11", "3.12" ]
+    env:
+      LEDGER_PROXY_ADDRESS: 127.0.0.1
+      LEDGER_PROXY_PORT: 9999
     steps:
       - uses: actions/checkout@v4
 
@@ -197,6 +200,48 @@ jobs:
       - name: Install devnet
         run: ./starknet_py/tests/install_devnet.sh
 
+      # ====================== SETUP LEDGER SPECULOS ====================== #
+
+      - name: Pull speculos image
+        run: docker pull ghcr.io/ledgerhq/ledger-app-builder/ledger-app-dev-tools
+
+
+      - name: Clone LedgerHQ Starknet app repository
+        run: git clone https://github.com/LedgerHQ/app-starknet.git
+
+      - name: Build the app inside Docker container
+        uses: addnab/docker-run-action@v3
+        with:
+          image: ghcr.io/ledgerhq/ledger-app-builder/ledger-app-dev-tools
+          options: --rm -v ${{ github.workspace }}:/apps
+          run: |
+            cd /apps/app-starknet
+            cargo clean
+            cargo ledger build nanox
+
+      - name: Start Speculos emulator container
+        uses: addnab/docker-run-action@v3
+        with:
+          image: ghcr.io/ledgerhq/ledger-app-builder/ledger-app-dev-tools
+          options: --rm -d --name speculos-emulator -v ${{ github.workspace }}:/apps --publish 5000:5000 --publish 9999:9999
+          run: |
+            speculos \
+            -m nanox \
+            --apdu-port 9999 \
+            --api-port 5000 \
+            --display headless \
+            /apps/app-starknet/target/nanox/release/starknet
+
+      - name: Wait for Speculos to start
+        run: sleep 5
+
+      - name: Update automation rules
+        working-directory: starknet_py/net/signer
+        run: |
+          curl -X POST http://127.0.0.1:5000/automation \
+          -H "Content-Type: application/json" \
+          -d @speculos_automation.json
+
       # ====================== RUN TESTS ====================== #
 
       - name: Check circular imports

docs/api/signer.rst

@@ -32,3 +32,12 @@ KeyPair
     :undoc-members:
     :member-order: groupwise
 
+------------
+LedgerSigner
+------------
+
+.. py:module:: starknet_py.net.signer.ledger_signer
+
+.. autoclass:: LedgerSigner
+    :members:
+    :member-order: groupwise

docs/guide/signing.rst

@@ -12,6 +12,21 @@ signing algorithm, it is possible to create ``Account`` with custom
     :language: python
     :dedent: 4
 
+Signing with Ledger
+-------------------
+:ref:`LedgerSigner` allows you to sign transactions using a Ledger device. The device must be unlocked and Starknet app needs to be open.
+
+.. codesnippet:: ../../starknet_py/net/signer/test_ledger_signer.py
+    :language: python
+    :dedent: 4
+
+Deploying account and transferring ETH
+--------------------------------------
+.. codesnippet:: ../../starknet_py/net/signer/test_ledger_signer.py
+    :language: python
+    :dedent: 4
+    :start-after: docs-deploy-account-and-transfer: start
+    :end-before: docs-deploy-account-and-transfer: end
 
 Signing off-chain messages
 -------------------------------

pyproject.toml

@@ -29,6 +29,8 @@ furo = { version = "^2024.5.6", optional = true }
 pycryptodome = "^3.17"
 crypto-cpp-py = "1.4.4"
 eth-keyfile = "^0.8.1"
+ledgerwallet = "^0.5.0"
+bip-utils = "^2.9.3"
 
 [tool.poetry.extras]
 docs = ["sphinx", "enum-tools", "furo"]

starknet_py/constants.py

@@ -37,3 +37,11 @@
 QUERY_VERSION_BASE = 2**128
 
 ROOT_PATH = Path(__file__).parent
+
+# Ledger constants
+STARKNET_CLA = 0x5A
+EIP_2645_PURPOSE = 0x80000A55
+EIP_2645_PATH_LENGTH = 6
+PUBLIC_KEY_RESPONSE_LENGTH = 65
+SIGNATURE_RESPONSE_LENGTH = 65
+VERSION_RESPONSE_LENGTH = 3

starknet_py/net/signer/ledger_signer.py

@@ -0,0 +1,172 @@
+from typing import List
+
+from bip_utils import Bip32KeyIndex, Bip32Path, Bip32Utils
+from ledgerwallet.client import LedgerClient
+
+from starknet_py.constants import (
+    EIP_2645_PATH_LENGTH,
+    EIP_2645_PURPOSE,
+    PUBLIC_KEY_RESPONSE_LENGTH,
+    SIGNATURE_RESPONSE_LENGTH,
+    STARKNET_CLA,
+    VERSION_RESPONSE_LENGTH,
+)
+from starknet_py.net.models import AccountTransaction
+from starknet_py.net.models.chains import ChainId
+from starknet_py.net.signer import BaseSigner
+from starknet_py.utils.typed_data import TypedData
+
+
+class LedgerStarknetApp:
+    def __init__(self):
+        self.client: LedgerClient = LedgerClient(cla=STARKNET_CLA)
+
+    @property
+    def version(self) -> str:
+        """
+        Get the Ledger app version.
+
+        :return: Version string.
+        """
+        response = self.client.apdu_exchange(ins=0)
+        if len(response) != VERSION_RESPONSE_LENGTH:
+            raise ValueError(
+                f"Unexpected response length (expected: {VERSION_RESPONSE_LENGTH}, actual: {len(response)}"
+            )
+        major, minor, patch = list(response)
+        return f"{major}.{minor}.{patch}"
+
+    def get_public_key(
+        self, derivation_path: Bip32Path, device_confirmation: bool = False
+    ) -> int:
+        """
+        Get public key for the given derivation path.
+
+        :param derivation_path: Derivation path of the account.
+        :param device_confirmation: Whether to display confirmation on the device for extra security.
+        :return: Public key.
+        """
+
+        data = _derivation_path_to_bytes(derivation_path)
+        response = self.client.apdu_exchange(
+            ins=1,
+            data=data,
+            p1=int(device_confirmation),
+            p2=0,
+        )
+
+        if len(response) != PUBLIC_KEY_RESPONSE_LENGTH:
+            raise ValueError(
+                f"Unexpected response length (expected: {PUBLIC_KEY_RESPONSE_LENGTH}, actual: {len(response)}"
+            )
+
+        public_key = int.from_bytes(response[1:33], byteorder="big")
+        return public_key
+
+    def sign_hash(self, derivation_path: Bip32Path, hash_val: int) -> List[int]:
+        """
+        Request a signature for a raw hash with the given derivation path.
+        Currently, the Ledger app only supports blind signing raw hashes.
+
+        :param derivation_path: Derivation path of the account.
+        :param hash_val: Hash to sign.
+        :return: Signature as a list of two integers.
+        """
+
+        data = _derivation_path_to_bytes(derivation_path)
+        self.client.apdu_exchange(
+            ins=0,
+            data=data,
+            p1=0,
+            p2=0,
+        )
+
+        # for some reason the Ledger app expects the data to be left shifted by 4 bits
+        shifted_int = hash_val << 4
+        shifted_bytes = shifted_int.to_bytes(32, byteorder="big")
+
+        response = self.client.apdu_exchange(
+            ins=0x02,
+            data=shifted_bytes,
+            p1=0x01,
+            p2=0x00,
+        )
+
+        if (
+            len(response) != SIGNATURE_RESPONSE_LENGTH + 1
+            or response[0] != SIGNATURE_RESPONSE_LENGTH
+        ):
+            raise ValueError(
+                f"Unexpected response length (expected: {SIGNATURE_RESPONSE_LENGTH}, actual: {len(response)}"
+            )
+
+        r, s = int.from_bytes(response[1:33], byteorder="big"), int.from_bytes(
+            response[33:65], byteorder="big"
+        )
+        return [r, s]
+
+
+class LedgerSigner(BaseSigner):
+    def __init__(self, derivation_path_str: str, chain_id: ChainId):
+        """
+        :param derivation_path_str: Derivation path string of the account.
+        :param chain_id: ChainId of the chain.
+        """
+
+        self.app: LedgerStarknetApp = LedgerStarknetApp()
+        self.derivation_path: Bip32Path = _parse_derivation_path_str(
+            derivation_path_str
+        )
+        self.chain_id: ChainId = chain_id
+
+    @property
+    def public_key(self) -> int:
+        return self.app.get_public_key(derivation_path=self.derivation_path)
+
+    def sign_transaction(self, transaction: AccountTransaction) -> List[int]:
+        tx_hash = transaction.calculate_hash(self.chain_id)
+        return self.app.sign_hash(
+            derivation_path=self.derivation_path, hash_val=tx_hash
+        )
+
+    def sign_message(self, typed_data: TypedData, account_address: int) -> List[int]:
+        msg_hash = typed_data.message_hash(account_address)
+        return self.app.sign_hash(
+            derivation_path=self.derivation_path, hash_val=msg_hash
+        )
+
+
+def _parse_derivation_path_str(derivation_path_str) -> Bip32Path:
+    """
+    Parse a derivation path string to a Bip32Path object.
+
+    :param derivation_path_str: Derivation path string.
+    :return: Bip32Path object.
+    """
+    if not derivation_path_str:
+        raise ValueError("Empty derivation path")
+
+    path_parts = derivation_path_str.lstrip("m/").split("/")
+    path_elements = [
+        Bip32KeyIndex(
+            Bip32Utils.HardenIndex(int(part[:-1])) if part.endswith("'") else int(part)
+        )
+        for part in path_parts
+    ]
+
+    if len(path_elements) != EIP_2645_PATH_LENGTH:
+        raise ValueError(f"Derivation path is not {EIP_2645_PATH_LENGTH}-level long")
+    if path_elements[0] != EIP_2645_PURPOSE:
+        raise ValueError("Derivation path is not prefixed with m/2645.")
+
+    return Bip32Path(path_elements)
+
+
+def _derivation_path_to_bytes(derivation_path: Bip32Path) -> bytes:
+    """
+    Convert a derivation path to a bytes object.
+
+    :param derivation_path: Derivation path.
+    :return: Bytes object.
+    """
+    return b"".join(index.ToBytes() for index in derivation_path)

starknet_py/net/signer/speculos_automation.json

@@ -0,0 +1,39 @@
+{
+  "version": 1,
+  "rules": [
+    {
+      "text": "Confirm Hash to sign",
+      "conditions": [],
+      "actions": [
+        ["button", 2, true],
+        ["button", 2, false]
+      ]
+    },
+    {
+      "regexp": ".*Hash \\(.*\\)",
+      "conditions": [],
+      "actions": [
+        ["button", 2, true],
+        ["button", 2, false]
+      ]
+    },
+    {
+      "text": "Reject",
+      "conditions": [],
+      "actions": [
+        ["button", 2, true],
+        ["button", 2, false]
+      ]
+    },
+    {
+      "text": "Approve",
+      "conditions": [],
+      "actions": [
+        ["button", 1, true],
+        ["button", 2, true],
+        ["button", 1, false],
+        ["button", 2, false]
+      ]
+    }
+  ]
+}