Merge pull request #752 from Foundation-Devices/sft-8674-passport-core-signing-flow-does-not-show-a-non
What changed, and why it matters
This commit adds on-screen warnings to the Passport hardware wallet when a user is reviewing a Bitcoin transaction that contains timelocks. Timelocks can prevent a transaction from confirming until a future date or until certain inputs have aged, which could be used to trick someone into signing a payment that cannot actually be spent right away. The change does not alter transaction validation rules; it only makes existing timelock behavior visible to the user during signing.
No immediate action required. This is a defensive UX improvement. Users should ensure firmware is updated so that timelock warnings are shown during transaction review. Developers may want to confirm that the warning text is localized and that the custom UTC formatter correctly handles leap years and edge timestamps.
Security signals we found
UI warning for absolute time-based nLockTime
UI warning for BIP68 relative timelocks on version-2 transactions
Height-based nLockTime intentionally not flagged to avoid false positives
No consensus or validation rule changes; purely informational
Adds unit and host test coverage for the new warnings
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, it warns with the UTC date. If the transaction version is >= 2 and any nSequence encodes a BIP68 relative timelock, it lists the per-input delay. Height-based nLockTime values are deliberately not flagged because wallets commonly set them to the current block height for anti-fee-sniping. Unit and host tests are added to verify the warning logic.
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 41/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.