SFT-8674: warned about timelocks when reviewing a transaction
What changed, and why it matters
This commit adds on-screen warnings to the Passport hardware wallet when a Bitcoin transaction being reviewed includes a timelock that could delay confirmation. Before this change, a user could unknowingly sign a transaction that is blocked from confirming until a future date or until its inputs have aged. The amounts cannot change, but the payment can be held up. The fix flags only date-based and relative timelocks, not the common anti-fee-sniping block-height locks that most wallets set.
Users should update to firmware containing this commit and carefully read any new 'Timelock' or 'Relative Timelock' warnings during transaction review. Wallet coordinators and reviewers should verify that legitimate timelocked transactions now display the expected delay information.
Security signals we found
UI now warns users about transaction timelocks that delay confirmation
Previously undisclosed to the signer: absolute date locks and BIP68 relative locks
Height-based nLockTime intentionally not flagged to avoid warning fatigue
Custom UTC formatting avoids 30-year epoch offset bug on device
New test coverage for both flagged and non-flagged timelock cases
Evidence from the diff
The patch introduces a new consider_timelocks() method in psbt.py and a timelock_warnings() helper in psbt_display.py. During PSBT validation, the firmware now inspects nLockTime and each input’s nSequence. If nLockTime is a Unix timestamp (>= 500,000,000) and any input is not final, a warning shows the unlock UTC date. For version-2 transactions, BIP68 relative timelocks are decoded per input and listed as block counts or durations. Height-based nLockTime is deliberately not flagged because Passport lacks the current chain height and most wallets set it for fee-sniping deterrence. A custom format_utc_time() is used because the device’s utime epoch is 2000, not 1970. Unit and host tests are added.
Changed components
ports/stm32/boards/Passport/modules/psbt.pyports/stm32/boards/Passport/modules/psbt_display.pyports/stm32/boards/Passport/modules/tasks/validate_psbt_task.pyports/stm32/boards/Passport/modules/tests/host/test_psbt_display.pyports/stm32/boards/Passport/modules/tests/test_unit.pyports/stm32/boards/Passport/modules/tests/unit/psbt_timelock_warnings.pyInspect captured patch +176 / −1
### ports/stm32/boards/Passport/modules/psbt.py
@@ -1697,6 +1697,12 @@ def consider_inputs(self):
seq_to_str(self.presigned_inputs)))
gc.collect()
+ def consider_timelocks(self):
+ # Warn about timelocks that delay when the transaction can confirm.
+ from psbt_display import timelock_warnings
+ sequences = [txi.nSequence for _, txi in self.input_iter()]
+ self.warnings.extend(timelock_warnings(self.txn_version, self.lock_time, sequences))
+
def calculate_fee(self):
# what miner's reward is included in txn?
if self.total_value_in is None:
### ports/stm32/boards/Passport/modules/psbt_display.py
@@ -93,3 +93,73 @@ def format_signed_psbt_message(updated_path, finalized_path=None, txid=None):
'finalize, and broadcast.',
])
return '\n'.join(lines)
+
+
+# nLockTime values at or above this are Unix times; below it, block heights.
+LOCKTIME_THRESHOLD = 500000000
+SEQUENCE_FINAL = 0xffffffff
+# BIP68 relative lock fields of an input's nSequence.
+SEQUENCE_DISABLE_FLAG = 1 << 31
+SEQUENCE_TYPE_FLAG = 1 << 22
+SEQUENCE_VALUE_MASK = 0xffff
+SEQUENCE_SECONDS_PER_UNIT = 512
+
+
+def timelock_warnings(txn_version, lock_time, sequences):
+ """Return review warnings for timelocks that delay when the transaction can confirm.
+
+ Wallets routinely set nLockTime to the current block height, and Passport
+ doesn't know the current height, so a height lock can't be told apart from
+ one far in the future. Only a lock to a date, and a relative lock on an
+ input, are flagged: wallets rarely set either.
+ """
+ warnings = []
+ if lock_time >= LOCKTIME_THRESHOLD and any(sequence != SEQUENCE_FINAL for sequence in sequences):
+ warnings.append(('Timelock', "This transaction can't be confirmed until after {} UTC.".format(
+ format_utc_time(lock_time))))
+
+ # Relative locks apply from version 2 on (BIP68).
+ lines = []
+ if txn_version >= 2:
+ for index, sequence in enumerate(sequences):
+ value = sequence & SEQUENCE_VALUE_MASK
+ if sequence & SEQUENCE_DISABLE_FLAG or not value:
+ continue
+ if sequence & SEQUENCE_TYPE_FLAG:
+ wait = format_duration(value * SEQUENCE_SECONDS_PER_UNIT)
+ else:
+ wait = '{} block{}'.format(value, '' if value == 1 else 's')
+ lines.append('Input {}: {}'.format(index + 1, wait))
+ if lines:
+ warnings.append(('Relative Timelock',
+ "This transaction can't be confirmed until these inputs have waited this long "
+ 'after they were confirmed:\n\n' + '\n'.join(lines)))
+ return warnings
+
+
+def format_utc_time(timestamp):
+ """Format a Unix time as YYYY-MM-DD HH:MM.
+
+ utime counts from 2000 on this port, so the date is computed here
+ (Howard Hinnant's civil-from-days).
+ """
+ days, seconds = divmod(timestamp, 86400)
+ days += 719468
+ era = days // 146097
+ day_of_era = days - era * 146097
+ year_of_era = (day_of_era - day_of_era // 1460 + day_of_era // 36524 - day_of_era // 146096) // 365
+ day_of_year = day_of_era - (365 * year_of_era + year_of_era // 4 - year_of_era // 100)
+ month_index = (5 * day_of_year + 2) // 153
+ day = day_of_year - (153 * month_index + 2) // 5 + 1
+ month = month_index + 3 if month_index < 10 else month_index - 9
+ year = year_of_era + era * 400 + (1 if month <= 2 else 0)
+ return '{:04d}-{:02d}-{:02d} {:02d}:{:02d}'.format(year, month, day, seconds // 3600, seconds % 3600 // 60)
+
+
+def format_duration(seconds):
+ """Round seconds to the largest whole unit, e.g. 'about 2 days'."""
+ for unit, size in (('day', 86400), ('hour', 3600), ('minute', 60)):
+ if seconds >= size:
+ count = (seconds + size // 2) // size
+ return 'about {} {}{}'.format(count, unit, '' if count == 1 else 's')
+ return '{} seconds'.format(seconds)
### ports/stm32/boards/Passport/modules/tasks/validate_psbt_task.py
@@ -35,6 +35,8 @@ async def validate_psbt_task(on_done, psbt_len):
gc.collect()
psbt.consider_keys()
gc.collect()
+ psbt.consider_timelocks()
+ gc.collect()
psbt.consider_outputs()
# All went well!
### ports/stm32/boards/Passport/modules/tests/host/test_psbt_display.py
@@ -9,7 +9,8 @@
if MODULES not in sys.path:
sys.path.insert(0, MODULES)
-from psbt_display import format_psbt_error, format_signed_psbt_message # noqa: E402
+from psbt_display import ( # noqa: E402
+ format_psbt_error, format_signed_psbt_message, format_utc_time, timelock_warnings)
def test_missing_input_script_explains_coordinator_action_before_technical_detail():
@@ -65,3 +66,55 @@ def test_complete_psbt_success_distinguishes_psbt_from_final_transaction():
assert 'also saved a finalized transaction that is ready to broadcast' in text
assert '/card/payment-final.txn' in text
assert 'Transaction ID\nabc123' in text
+
+
+# Sequences a normal wallet sets: final, final with locktime, and RBF.
+FINAL = 0xffffffff
+LOCKTIME_ENABLED = 0xfffffffe
+RBF = 0xfffffffd
+# A relative lock of 144 blocks, and of 169 units of 512 seconds (about a day).
+BLOCKS_144 = 144
+ABOUT_A_DAY = (1 << 22) | 169
+DISABLED_LOCK = (1 << 31) | 144
+
+
+def test_normal_wallet_timelocks_are_not_flagged():
+ # Anti-fee-sniping sets the current block height, which Passport can't tell from a future one.
+ assert timelock_warnings(2, 925000, [RBF, RBF]) == []
+ assert timelock_warnings(2, 0, [FINAL, LOCKTIME_ENABLED, RBF]) == []
+ assert timelock_warnings(1, 0, [0]) == []
+
+
+def test_lock_to_a_date_is_flagged_with_the_date():
+ warnings = timelock_warnings(2, 1798761600, [FINAL, RBF])
+ assert warnings == [('Timelock', "This transaction can't be confirmed until after 2027-01-01 00:00 UTC.")]
+
+
+def test_lock_to_a_date_is_ignored_when_every_input_is_final():
+ assert timelock_warnings(2, 1798761600, [FINAL, FINAL]) == []
+
+
+def test_relative_locks_are_listed_per_input():
+ warnings = timelock_warnings(2, 0, [RBF, BLOCKS_144, ABOUT_A_DAY, 1])
+ assert len(warnings) == 1
+ title, text = warnings[0]
+ assert title == 'Relative Timelock'
+ assert text.endswith('\n\nInput 2: 144 blocks\nInput 3: about 1 day\nInput 4: 1 block')
+ assert 'Input 1' not in text
+
+
+def test_relative_locks_need_version_2_and_a_non_zero_value():
+ assert timelock_warnings(1, 0, [BLOCKS_144, ABOUT_A_DAY]) == []
+ assert timelock_warnings(2, 0, [0, 1 << 22, DISABLED_LOCK]) == []
+
+
+def test_both_kinds_of_lock_are_flagged_together():
+ titles = [title for title, _ in timelock_warnings(2, 1798761600, [BLOCKS_144])]
+ assert titles == ['Timelock', 'Relative Timelock']
+
+
+def test_utc_time_matches_the_standard_library():
+ import datetime
+ for timestamp in (500000000, 951782400, 951868799, 1798761600, 4102444800, 4107542400, 0xffffffff):
+ expected = datetime.datetime.fromtimestamp(timestamp, datetime.timezone.utc).strftime('%Y-%m-%d %H:%M')
+ assert format_utc_time(timestamp) == expected
### ports/stm32/boards/Passport/modules/tests/test_unit.py
@@ -152,6 +152,10 @@ def test_psbt_fee(test):
assert test('psbt_fee.py') == b'OK'
+def test_psbt_timelock_warnings(test):
+ assert test('psbt_timelock_warnings.py') == b'OK'
+
+
def test_psbt_history(test):
assert test('psbt_history.py') == b'OK'
### ports/stm32/boards/Passport/modules/tests/unit/psbt_timelock_warnings.py
@@ -0,0 +1,40 @@
+# SPDX-FileCopyrightText: © 2026 Foundation Devices, Inc. <hello@foundation.xyz>
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# Test timelock warnings on the device's Python.
+
+from psbt import psbtObject
+from psbt_display import format_utc_time, timelock_warnings
+from serializations import CTxIn
+
+
+class MockPSBT:
+ def __init__(self, txn_version, lock_time, sequences):
+ self.txn_version = txn_version
+ self.lock_time = lock_time
+ self.sequences = sequences
+ self.warnings = []
+
+ def input_iter(self):
+ txin = CTxIn()
+ for index, sequence in enumerate(self.sequences):
+ txin.nSequence = sequence
+ yield index, txin
+
+
+assert format_utc_time(1798761600) == '2027-01-01 00:00'
+assert format_utc_time(0xffffffff) == '2106-02-07 06:28'
+
+# A wallet's usual anti-fee-sniping locktime isn't flagged.
+normal = MockPSBT(2, 925000, [0xfffffffd, 0xfffffffd])
+psbtObject.consider_timelocks(normal)
+assert normal.warnings == []
+
+locked = MockPSBT(2, 1798761600, [0xfffffffd, 144, (1 << 22) | 169])
+psbtObject.consider_timelocks(locked)
+assert [title for title, _ in locked.warnings] == ['Timelock', 'Relative Timelock']
+assert '2027-01-01 00:00 UTC' in locked.warnings[0][1]
+assert locked.warnings[1][1].endswith('Input 2: 144 blocks\nInput 3: about 1 day')
+assert timelock_warnings(1, 0, [144]) == []
+
+return_value.write(b'OK')Why this scored 52/100
Community notes
Notes can correct, qualify, or add evidence to the AI analysis. Every note shown here has been validated by a human moderator.
The AI analysis stands alone for now. Submit a note if you can add evidence or important context.