Overview

This PR adds support for passing htlc_id in the signer interfaces by adding an htlc_id field to the HTLCDescriptor struct and populating it from the channel context. This enables signers to uniquely identify HTLCs within a channel when signing HTLC transactions.

Changes

Core Changes

• Added pub htlc_id: Option<u64> field to HTLCDescriptor struct in lightning/src/sign/mod.rs
• Updated the TLV serialization macro to include the new field with tag 13, ensuring backward compatibility
• Added htlc_ids: Vec<u64> field to CommitmentData struct to track HTLC IDs during commitment transaction building
• Added pub htlc_ids: Vec<u64> field to HolderCommitmentTransaction to persist HTLC IDs
• Updated commitment transaction building process to capture and track HTLC IDs from pending HTLCs

HTLC ID Tracking Flow

1. Channel State: When building commitment transactions, HTLC IDs are captured from pending_inbound_htlcs and pending_outbound_htlcs which contain the original htlc_id values
2. CommitmentData: HTLC IDs are tracked in parallel with htlcs_included and sorted together to maintain correspondence
3. HolderCommitmentTransaction: HTLC IDs are stored alongside the transaction for later retrieval
4. HTLCDescriptor: When creating descriptors for signing, HTLC IDs are extracted from HolderCommitmentTransaction using the HTLC index

Updated Construction Sites

All locations where HTLCDescriptor is instantiated now populate htlc_id from the HolderCommitmentTransaction context:

• lightning/src/chain/package.rs: Extracts htlc_id using HTLC index from HolderCommitmentTransaction
• lightning/src/chain/channelmonitor.rs: Retrieves htlc_id from HolderCommitmentTransaction during HTLC descriptor creation
• lightning/src/chain/onchaintx.rs: Populates htlc_id from HolderCommitmentTransaction when building claim packages
• lightning/src/ln/channel.rs: Updated to track and pass htlc_ids through commitment transaction building

Design Rationale

The htlc_id field is Option<u64> rather than a required u64 because:

1. Backward Compatibility: Using Option<u64> allows the field to be None when deserializing old data that doesn't contain htlc_ids
2. Test Code: Some test scenarios may not require or provide htlc_ids
3. Graceful Degradation: The system can still function if htlc_ids are unavailable in edge cases

The implementation tracks HTLC IDs from their source in the channel state through to the signer interface, ensuring that whenever possible, signers receive the HTLC ID for proper identification.

Testing

• All existing tests pass (1162+ unit tests)
• No breaking changes to the signer interface
• Backward compatible through TLV serialization with the option modifier
• HTLC IDs are properly populated when creating HTLCDescriptors from commitment transactions with available context

Related

This change provides signers with HTLC ID information, which is useful for:

• Enhanced logging and debugging
• HTLC-specific signing policies
• Better correlation between off-chain and on-chain HTLC operations
• Improved signer functionality and decision-making capabilities

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.