clearsign v2: static-schema serializer, tests, and PDF report coverage

BitHighlander · claude · BitHighlander · commit 5307888be7b6 · 2026-07-03T01:06:08.000-05:00
Adds the python-keepkey test-framework support for firmware v2 (static schema,
METADATA_VERSION_SCHEMA): a blob that attests only the decode schema (no tx_hash,
no arg values) so it can be signed once offline — the device decodes the arg
values from the calldata it signs.

- keepkeylib/signed_metadata.py: serialize_schema_metadata() (v2 wire format) +
  schema_calldata() (ABI fixed-word calldata a v2 schema decodes).
- tests: TestClearSignV2SchemaOffline (7 offline byte-format tests incl. a frozen
  body snapshot as a drift gate) + TestClearSignV2Device (on-device decode+sign+
  recover, gated requires_firmware('7.16.0') so it skips until a v2 firmware ships).
- report: VS1-VS5 in the EVM Clear-Signing section documenting v2 (no tx_hash,
  static decimals/symbol, frozen format, fixed-word scope, on-device round-trip).

Mirrors firmware feat/clearsign-static-schema (keepkey-firmware PR #284).

Co-Authored-By: Claude Fable 5 &lt;noreply@anthropic.com&gt;
diff --git a/keepkeylib/signed_metadata.py b/keepkeylib/signed_metadata.py
@@ -246,6 +246,111 @@ def serialize_metadata(
     return bytes(buf)
 
 
+# ── v2: static schema (no tx_hash, no values; device decodes calldata) ──
+#
+# METADATA_VERSION_SCHEMA blobs attest only HOW to decode a curated
+# (chainId, contract, selector): the method label and, per argument, a name +
+# display format (+ static decimals/symbol for token amounts). They carry NO
+# tx_hash and NO argument values — the device decodes the values from the exact
+# calldata it is about to sign. Signed once, OFFLINE; no per-tx signer.
+#
+# Firmware format (parse_v2_args in lib/firmware/signed_metadata.c):
+#   version(1)=0x02 + chain_id(4 BE) + contract(20) + selector(4) +
+#   method_len(2 BE) + method + num_args(1) +
+#   [per arg: name_len(1) + name + display_format(1) +
+#             (if TOKEN_AMOUNT: decimals(1) + symbol_len(1) + symbol)] +
+#   classification(1) + timestamp(4 BE) + key_id(1) + signature(64) + recovery(1)
+#
+# Supported display formats (fixed single ABI word at offset 4 + 32*i):
+#   ARG_FORMAT_ADDRESS, ARG_FORMAT_AMOUNT, ARG_FORMAT_TOKEN_AMOUNT.
+METADATA_VERSION_SCHEMA = 2
+
+
+def serialize_schema_metadata(
+    chain_id: int,
+    contract_address: bytes,
+    selector: bytes,
+    method_name: str,
+    args: list,
+    classification: int = CLASSIFICATION_VERIFIED,
+    timestamp: int = None,
+    key_id: int = 3,
+) -> bytes:
+    """Serialize a v2 (static schema) metadata payload (unsigned).
+
+    Args mirror serialize_metadata(), minus tx_hash. Each entry of `args` is a
+    dict: {name, format, [decimals, symbol]} — NO 'value' (the device decodes it
+    from the calldata). `decimals`/`symbol` are required for TOKEN_AMOUNT and
+    ignored otherwise. Call sign_metadata() on the result.
+    """
+    if timestamp is None:
+        timestamp = int(time.time())
+
+    assert len(contract_address) == 20
+    assert len(selector) == 4
+    assert len(method_name.encode('utf-8')) <= 64
+    assert len(args) <= 8
+
+    buf = bytearray()
+    buf.append(METADATA_VERSION_SCHEMA)
+    buf.extend(struct.pack('>I', chain_id))
+    buf.extend(contract_address)
+    buf.extend(selector)
+
+    name_bytes = method_name.encode('utf-8')
+    buf.extend(struct.pack('>H', len(name_bytes)))
+    buf.extend(name_bytes)
+
+    buf.append(len(args))
+    for arg in args:
+        arg_name = arg['name'].encode('utf-8')
+        assert len(arg_name) <= 32
+        buf.append(len(arg_name))
+        buf.extend(arg_name)
+
+        fmt = arg['format']
+        assert fmt in (ARG_FORMAT_ADDRESS, ARG_FORMAT_AMOUNT,
+                       ARG_FORMAT_TOKEN_AMOUNT), \
+            'v2 supports only fixed-word ADDRESS/AMOUNT/TOKEN_AMOUNT'
+        buf.append(fmt)
+        if fmt == ARG_FORMAT_TOKEN_AMOUNT:
+            sym = arg['symbol'].encode('ascii')
+            assert 0 < len(sym) <= 10 and sym.isalnum()
+            assert 0 <= arg['decimals'] <= 36
+            buf.append(arg['decimals'])
+            buf.append(len(sym))
+            buf.extend(sym)
+
+    buf.append(classification)
+    buf.extend(struct.pack('>I', timestamp))
+    buf.append(key_id)
+
+    return bytes(buf)
+
+
+def schema_calldata(selector: bytes, args: list) -> bytes:
+    """ABI-encode the calldata a v2 schema decodes: selector + one 32-byte head
+    word per arg. ADDRESS -> left-zero-padded 20-byte address; AMOUNT /
+    TOKEN_AMOUNT -> big-endian uint256. Used to build a tx whose calldata the
+    device will decode against a serialize_schema_metadata() blob.
+
+    Each arg dict needs 'format' plus a concrete value: 'address' (20 bytes) for
+    ADDRESS, or 'amount' (int) for AMOUNT/TOKEN_AMOUNT.
+    """
+    data = bytearray(selector)
+    for arg in args:
+        fmt = arg['format']
+        if fmt == ARG_FORMAT_ADDRESS:
+            addr = arg['address']
+            assert len(addr) == 20
+            data.extend(b'\x00' * 12 + addr)
+        elif fmt in (ARG_FORMAT_AMOUNT, ARG_FORMAT_TOKEN_AMOUNT):
+            data.extend(int(arg['amount']).to_bytes(32, 'big'))
+        else:
+            raise AssertionError('unsupported v2 arg format %r' % fmt)
+    return bytes(data)
+
+
 def sign_metadata(payload: bytes, private_key: bytes = None) -> bytes:
     """Sign the canonical binary payload and return the complete signed blob.
 
diff --git a/scripts/generate-test-report.py b/scripts/generate-test-report.py
@@ -1028,6 +1028,51 @@ def _arg_shown(a):
           'device accepts them; deviate by one byte and it refuses.' % (
               len(CLEARSIGN_FLOWS) if CLEARSIGN_FLOWS else 0),
           []),
+
+         # ── v2 static schema (no online signer) ──────────────────────
+         # v2 attests only the decode SCHEMA (no tx_hash, no arg values); the
+         # DEVICE decodes the argument values from the calldata it signs. This
+         # removes the per-tx online signer: the catalog is signed once, offline.
+         # Offline format tests run every cycle; the on-device decode test is
+         # gated to the release that ships v2 (METADATA_VERSION_SCHEMA).
+         ('VS1', 'test_msg_ethereum_clear_signing', 'test_layout_has_no_tx_hash',
+          'v2 schema blob carries no tx_hash / no values',
+          'The v2 (static schema) blob attests only how to decode a curated '
+          '(chainId, contract, selector): method + per-arg name/format (+ static '
+          'decimals/symbol). It has NO committed tx_hash and NO argument values — '
+          'so it can be signed ONCE, offline, and served from a CDN with no hot '
+          'key. The device decodes the values itself from the calldata it signs.',
+          []),
+         ('VS2', 'test_msg_ethereum_clear_signing',
+          'test_token_arg_carries_static_decimals_symbol_not_value',
+          'v2 token arg = static decimals/symbol, value decoded on-device',
+          'A TOKEN_AMOUNT arg encodes the token\'s static decimals + symbol (a '
+          'property of the contract), but NOT the amount — the amount is decoded '
+          'from the calldata word on-device, then rendered "1.5 USDC".',
+          []),
+         ('VS3', 'test_msg_ethereum_clear_signing', 'test_frozen_body_snapshot',
+          'v2 wire format frozen vs firmware parser',
+          'The canonical v2 body\'s length + sha256 are frozen, so the '
+          'serializer can never drift from firmware\'s parse_v2_args() undetected '
+          '— the same byte-parity discipline the v1 reference vectors use.',
+          []),
+         ('VS4', 'test_msg_ethereum_clear_signing', 'test_rejects_dynamic_format',
+          'v2 scope: fixed-word types only',
+          'v2 decodes fixed single ABI words (ADDRESS / AMOUNT / TOKEN_AMOUNT) — '
+          'approve/transfer/transferFrom and fixed-arg calls. Dynamic types '
+          '(string/bytes/arrays) are rejected by the serializer and fall to the '
+          'blind-sign path on-device; a bounded dynamic decoder is future work.',
+          []),
+         ('VS5', 'test_msg_ethereum_clear_signing',
+          'test_v2_transfer_decodes_signs_and_recovers',
+          'v2 on-device: decode from calldata, sign, recover',
+          'END-TO-END with AdvancedMode OFF: a v2 transfer() schema blob + a real '
+          'transfer(to, amount) tx. The device decodes to/amount from the calldata '
+          'and clear-signs; the signature recovers to this device\'s signer over '
+          'the tx digest — so the who/what/why shown was bound to the exact tx, '
+          'with no tx_hash. The offline format tests above pin the wire format '
+          'the device decodes.',
+          ['Clearsign warning', 'v2 decoded transfer to/amount', 'Sign transaction']),
      ]),
 
     ('G', 'Hive', '7.15.0',
diff --git a/tests/test_msg_ethereum_clear_signing.py b/tests/test_msg_ethereum_clear_signing.py
@@ -36,6 +36,8 @@
 
 from keepkeylib.signed_metadata import (
     serialize_metadata,
+    serialize_schema_metadata,
+    schema_calldata,
     sign_metadata,
     build_test_metadata,
     token_amount_value,
@@ -45,6 +47,7 @@
     ARG_FORMAT_BYTES,
     ARG_FORMAT_STRING,
     ARG_FORMAT_TOKEN_AMOUNT,
+    METADATA_VERSION_SCHEMA,
     CLASSIFICATION_VERIFIED,
     CLASSIFICATION_OPAQUE,
     CLASSIFICATION_MALFORMED,
@@ -696,6 +699,121 @@ def test_catalog_uses_only_hexfree_formats(self):
                     (flow['key'], arg['name']))
 
 
+# ═══════════════════════════════════════════════════════════════════════
+# v2 static-schema blobs (offline) — no device required
+#
+# v2 attests only the decode SCHEMA (no tx_hash, no arg values); the device
+# decodes the argument values from the calldata it signs. These offline tests
+# pin the wire format serialize_schema_metadata() emits so it can never drift
+# from firmware's parse_v2_args() / decode_v2_args() undetected.
+# ═══════════════════════════════════════════════════════════════════════
+
+# transfer(to, amount) on USDC — the canonical v2 fixture. amount is a token
+# amount (6 decimals, "USDC"); the value is NOT in the blob, it is decoded from
+# the calldata word by the device.
+USDC_ADDRESS = bytes.fromhex('a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48')
+ERC20_TRANSFER_SELECTOR = bytes.fromhex('a9059cbb')
+V2_SCHEMA_ARGS = [
+    {'name': 'to', 'format': ARG_FORMAT_ADDRESS},
+    {'name': 'amount', 'format': ARG_FORMAT_TOKEN_AMOUNT,
+     'decimals': 6, 'symbol': 'USDC'},
+]
+
+
+def _v2_transfer_blob():
+    body = serialize_schema_metadata(
+        chain_id=1, contract_address=USDC_ADDRESS,
+        selector=ERC20_TRANSFER_SELECTOR, method_name='transfer',
+        args=V2_SCHEMA_ARGS, timestamp=0, key_id=TEST_KEY_ID)
+    return body, sign_metadata(body)
+
+
+class TestClearSignV2SchemaOffline(unittest.TestCase):
+    """Offline byte-format tests for the v2 static-schema serializer."""
+
+    def test_version_byte_is_schema(self):
+        body, _ = _v2_transfer_blob()
+        self.assertEqual(body[0], METADATA_VERSION_SCHEMA)
+
+    def test_layout_has_no_tx_hash(self):
+        """v2 body = version(1)+chain(4)+contract(20)+selector(4)+method... —
+        the selector sits at offset 25, immediately after the contract, with NO
+        32-byte tx_hash in between (that is the whole point of v2)."""
+        body, _ = _v2_transfer_blob()
+        self.assertEqual(body[1:5], b'\x00\x00\x00\x01')            # chain_id
+        self.assertEqual(body[5:25], USDC_ADDRESS)                  # contract
+        self.assertEqual(body[25:29], ERC20_TRANSFER_SELECTOR)     # selector @25
+        # method_len(2) + 'transfer'(8) then num_args
+        self.assertEqual(body[29:31], b'\x00\x08')
+        self.assertEqual(body[31:39], b'transfer')
+        self.assertEqual(body[39], len(V2_SCHEMA_ARGS))
+
+    def test_token_arg_carries_static_decimals_symbol_not_value(self):
+        """The token arg encodes name + format + decimals + symbol, and NO
+        value — decimals/symbol are static (a property of the contract), the
+        amount is decoded on-device from the calldata."""
+        body, _ = _v2_transfer_blob()
+        # after num_args @39: arg0 'to' = len(1)+'to'(2)+format(1) = 4 bytes
+        p = 40
+        self.assertEqual(body[p], 2)                    # name_len 'to'
+        self.assertEqual(body[p + 1:p + 3], b'to')
+        self.assertEqual(body[p + 3], ARG_FORMAT_ADDRESS)
+        p += 4
+        # arg1 'amount' = len(1)+'amount'(6)+format(1)+decimals(1)+symlen(1)+'USDC'(4)
+        self.assertEqual(body[p], 6)
+        self.assertEqual(body[p + 1:p + 7], b'amount')
+        self.assertEqual(body[p + 7], ARG_FORMAT_TOKEN_AMOUNT)
+        self.assertEqual(body[p + 8], 6)                # decimals
+        self.assertEqual(body[p + 9], 4)                # symbol_len
+        self.assertEqual(body[p + 10:p + 14], b'USDC')
+
+    def test_signed_blob_is_body_plus_65(self):
+        body, blob = _v2_transfer_blob()
+        self.assertEqual(len(blob), len(body) + 65)
+
+    def test_frozen_body_snapshot(self):
+        """Freeze the canonical v2 UNSIGNED body's length + sha256. The body is
+        key-independent (no signature) and deterministic (timestamp=0), so this
+        is a pure wire-format drift gate: it trips iff serialize_schema_metadata()
+        changes the bytes, which must stay in lockstep with firmware's
+        parse_v2_args(). (The signature is exercised separately.)"""
+        body, _ = _v2_transfer_blob()
+        got = (len(body), hashlib.sha256(body).hexdigest())
+        self.assertEqual(got, V2_BODY_SNAPSHOT,
+                         'v2 body drift: only update V2_BODY_SNAPSHOT if the wire '
+                         'format intentionally changed (and firmware too)')
+
+    def test_calldata_matches_schema_shape(self):
+        """schema_calldata() builds selector + one 32-byte word per arg, so the
+        device decodes exactly num_args words (the structural binding)."""
+        cd = schema_calldata(ERC20_TRANSFER_SELECTOR, [
+            {'format': ARG_FORMAT_ADDRESS, 'address': VITALIK},
+            {'format': ARG_FORMAT_TOKEN_AMOUNT, 'amount': 1500000},
+        ])
+        self.assertEqual(len(cd), 4 + 32 * 2)
+        self.assertEqual(cd[:4], ERC20_TRANSFER_SELECTOR)
+        self.assertEqual(cd[4:16], b'\x00' * 12)     # address left-padding
+        self.assertEqual(cd[16:36], VITALIK)
+        self.assertEqual(int.from_bytes(cd[36:68], 'big'), 1500000)
+
+    def test_rejects_dynamic_format(self):
+        """v2 only encodes fixed single-word types; STRING/BYTES are rejected by
+        the serializer (they have no fixed on-chain word)."""
+        with self.assertRaises(AssertionError):
+            serialize_schema_metadata(
+                chain_id=1, contract_address=USDC_ADDRESS,
+                selector=ERC20_TRANSFER_SELECTOR, method_name='x',
+                args=[{'name': 'label', 'format': ARG_FORMAT_STRING}])
+
+
+# Frozen len + sha256 of the canonical v2 UNSIGNED transfer body (timestamp=0,
+# key-independent). Regenerate ONLY on an intentional wire-format change:
+#   python3 -c "from tests.test_msg_ethereum_clear_signing import _v2_transfer_blob; \
+#     import hashlib; b,_=_v2_transfer_blob(); print(len(b), hashlib.sha256(b).hexdigest())"
+V2_BODY_SNAPSHOT = (
+    64, '01a24001460f8a69684f3d2a10f75b14e7449d8912a3833f7f8758e8fccadc05')
+
+
 # ═══════════════════════════════════════════════════════════════════════
 # Device tests — require KeepKey connected with test firmware
 # ═══════════════════════════════════════════════════════════════════════
@@ -1102,6 +1220,61 @@ def test_load_signer_key_id_out_of_range_rejected(self):
                 alias=CI_SIGNER_ALIAS)
 
 
+class TestClearSignV2Device(common.KeepKeyTest):
+    """Device integration for v2 (static schema) blobs.
+
+    A v2 blob attests only the decode schema; the device decodes the argument
+    values from the calldata it signs. This exercises the full round-trip: load
+    signer -> send v2 metadata -> sign a matching transfer() tx -> the signature
+    recovers to this device's signer over the tx digest (so the who/what/why
+    shown was bound to the exact tx, with no committed tx_hash).
+
+    v2 (METADATA_VERSION_SCHEMA) lands in the in-progress 7.15.0 line, so this
+    runs against the develop firmware alongside the v1 clear-sign device tests.
+    """
+
+    V2_FIRMWARE = "7.15.0"
+
+    def setUp(self):
+        super().setUp()
+        self.requires_firmware(self.V2_FIRMWARE)
+        self.requires_message("EthereumTxMetadata")
+        self.requires_message("LoadClearsignSigner")
+        self.setup_mnemonic_nopin_nopassphrase()
+        self.client.load_clearsign_signer(
+            key_id=TEST_KEY_ID, pubkey=test_signer_compressed_pubkey(),
+            alias=CI_SIGNER_ALIAS)
+        self._drop_setup_screenshots()
+
+    def test_v2_transfer_decodes_signs_and_recovers(self):
+        self.client.apply_policy("AdvancedMode", 0)
+        self._drop_setup_screenshots()
+        n = parse_path(DEVICE_PATH)
+        chain_id, nonce, gas_price, gas_limit, value = 1, 3, 20000000000, 250000, 0
+        # transfer(to=VITALIK, amount=1.5 USDC) — the device decodes both from
+        # the calldata using the v2 schema (address word + token-amount word).
+        args = [
+            {'format': ARG_FORMAT_ADDRESS, 'address': VITALIK},
+            {'format': ARG_FORMAT_TOKEN_AMOUNT, 'amount': 1500000},
+        ]
+        data = schema_calldata(ERC20_TRANSFER_SELECTOR, args)
+        _, blob = _v2_transfer_blob()
+
+        resp = self.client.ethereum_send_tx_metadata(
+            signed_payload=blob, metadata_version=1, key_id=TEST_KEY_ID)
+        self.assertEqual(resp.classification, CLASSIFICATION_VERIFIED)
+
+        sig_v, sig_r, sig_s = self.client.ethereum_sign_tx(
+            n=n, nonce=nonce, gas_price=gas_price, gas_limit=gas_limit,
+            to=USDC_ADDRESS, value=value, data=data, chain_id=chain_id)
+        self.assertIsNotNone(sig_r)
+        self.assertIsNotNone(sig_s)
+        tx_hash = eth_sighash_legacy(nonce, gas_price, gas_limit, USDC_ADDRESS,
+                                     value, data, chain_id)
+        signer = recover_eth_signer(sig_r, sig_s, sig_v, tx_hash, chain_id)
+        self.assertEqual(signer, self.client.ethereum_get_address(n))
+
+
 # ═══════════════════════════════════════════════════════════════════════
 # Dynamically generate one full-confirm device test per CLEARSIGN_FLOWS
 # entry (mirrors keepkey-sdk tests/evm-clearsign): every real-world flow a
