Repository navigation
Doc(apdu): describe the SIGN ETH TRANSACTION v byte per transaction type - #1108
Closed
IronicDeGawd wants to merge 1 commit into
Closed
IronicDeGawd wants to merge 1 commit into
IronicDeGawd wants to merge 1 commit into
Conversation
The response was documented as "v | 1" with no explanation. Per src/features/sign_tx/ui_common_sign_tx.c the byte carries three different encodings: the bare signature parity for Type 1/2/4, chainId*2+35 plus the parity plus 2 for the xGTn case truncated to one byte for legacy payloads carrying a chain ID, and ETHEREUM_SIGNATURE_V_BASE plus those offsets for a pre-EIP-155 payload. Adds a table mapping transaction type to encoding, the recovery formula for the truncated legacy case, and a note that no recovery applies to a typed transaction. This matches how SIGN EIP 7702 AUTHORIZATION already documents its own parity byte.
Contributor
|
Thanks a lot for this contribution, the analysis is accurate and the missing documentation was a real gap. We have integrated it through our internal repository, with a few adjustments:
Your authorship is preserved on the commit, which will show up on |
1 of 6 tasks
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.