Repository navigation
docs(apdu): describe the v byte returned by SIGN ETH TRANSACTION - #1109
Closed
IronicDeGawd wants to merge 1 commit into
Closed
IronicDeGawd wants to merge 1 commit into
IronicDeGawd wants to merge 1 commit into
Conversation
Contributor
|
Same content as #1108, closing both. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
doc/apdu.mddocuments theSIGN ETH TRANSACTION(E0 04) response as:There is no description of what that
vbyte contains. It is in fact three differentencodings depending on the type of the transaction that was signed, and only one of them
can be used as is.
From
src/features/sign_tx/ui_common_sign_tx.c:signature parity,
0or1.chainId * 2 + 35, plus the parity, plus2whenCX_ECCINFO_xGTnis set, truncated to one byte.ETHEREUM_SIGNATURE_V_BASE(27) plus the sameoffsets.
The same document already documents the convention correctly for
SIGN EIP 7702 AUTHORIZATION, whose output row reads"Signature parity (0 even, 1 odd) - use as is in EIP 7702". This PR brings
SIGN ETH TRANSACTIONin line with that, and adds the recovery formula for the truncatedlegacy case.
Why this is worth documenting
The failure is silent and points away from its cause. Applying the legacy recovery to a
typed transaction produces a valid signature over a different recovered sender, so the
node accepts the transaction as well-formed and rejects it with
insufficient funds for gas * price + value: balance 0. That reads as an unfunded account,not a signature problem. We spent time looking at the wrong thing.
The information is currently only recoverable by reading the app's C source or
@ledgerhq/hw-app-eth. Integrators not using the JS libraries — we hit this writing atransport in C for an embedded target — have no documented path to it.
What is in the patch
vrow and links it to a new subsection.v: a three-row table mapping transaction type toencoding and to what the client should do with it.
vfor a legacy EIP-155 transaction with the formula, andstates explicitly that no recovery is applicable to a typed transaction.
recovery_offsetcarries thexGTn+2case in addition to the parity.Documentation only. No behavior change.
Verification
The recovery formula was checked against a faithful reproduction of the byte arithmetic in
ui_common_sign_tx.cacross 17 chain IDs (including 1, 5, 137, 8453, 42161, 11155111, andthe boundary values 109/110/111, 255, 256,
2^31,2^32 - 1) and all four combinations ofparity and
xGTn— 68 cases, no mismatches.The typed-transaction rule was confirmed on hardware: a Nano X running the Ethereum app
signed an EIP-1559 transaction whose
vbyte was0and which was accepted on Sepoliawith
yParity = 0x0(
0xb7cb3e4a…c074).Deriving the parity the legacy way for that same signature gives
1, and the resultingtransaction is rejected.
The one limitation left undocumented on purpose: for a chain ID wider than four bytes the
device reads only its four most significant bytes, so the byte cannot be mapped back to a
full
vat all. The patch says the formula holds for four-byte chain IDs, which coversevery chain in use, rather than describing a case that cannot currently arise. Happy to
expand or drop that sentence.
Changes include
Additional comments
Found while building Amulet for ETHOnline 2026: an ESP32-S3 pendant that talks to a
Nano X over BLE and is the only path by which an AI agent's proposed transactions can reach
the device for on-device confirmation. The transport and the transaction encoders are in C,
which is how we ended up needing the
vbyte's exact semantics rather than inheriting themfrom
hw-app-eth. Source: https://github.com/IronicDeGawd/EthOnline2026-AmuletHappy to adjust wording, table shape, or heading level to match the maintainers'
preference.