Add ResourceManager trait

Trait that will be used by the
`ChannelManager` to mitigate slow
jamming. Core responsibility will
be to track resource usage to
evaluate HTLC forwarding decisions.

Author: elnosh

lightning/src/ln/resource_manager.rs

@@ -1,10 +1,75 @@
 use bitcoin::hashes::{sha256d::Hash as Sha256dHash, Hash};
-use core::time::Duration;
+use core::{fmt::Display, time::Duration};
 use hashbrown::hash_map::Entry;
 use std::time::{SystemTime, UNIX_EPOCH};
 
 use crate::prelude::{new_hash_map, HashMap};
 
+/// A trait for managing channel resources and making HTLC forwarding decisions.
+pub trait ResourceManager {
+	/// Registers a new channel with the resource manager for tracking.
+	///
+	/// This should be called when a channel becomes ready for forwarding
+	fn add_channel(
+		&self, channel_id: u64, max_htlc_value_in_flight_msat: u64, max_accepted_htlcs: u16,
+	) -> Result<(), ()>;
+
+	/// Removes a channel from the resource manager.
+	///
+	/// This should be called when a channel is closing.
+	fn remove_channel(&self, channel_id: u64) -> Result<(), ()>;
+
+	/// Evaluates whether an HTLC should be forwarded and updates resource tracking.
+	///
+	/// This is called when deciding whether to accept and forward an incoming HTLC. The
+	/// implementation determines if sufficient resources are available on the incoming
+	/// channel and whether the outgoing channel is suitable for forwarding.
+	///
+	/// Returns a [`ForwardingOutcome`] indicating the forwarding decision:
+	/// - `ForwardingOutcome::Forward(accountable)`: The HTLC should be forwarded. The boolean
+	///   flag indicates the accountable signal to use for the outgoing HTLC.
+	/// - `ForwardingOutcome::Fail`: The HTLC should be failed back to the sender.
+	fn add_htlc<ES: EntropySource>(
+		&self, incoming_channel_id: u64, incoming_amount_msat: u64, incoming_cltv_expiry: u32,
+		outgoing_channel_id: u64, outgoing_amount_msat: u64, incoming_accountable: bool,
+		htlc_id: u64, height_added: u32, added_at: u64, entropy_source: &ES,
+	) -> Result<ForwardingOutcome, ()>;
+
+	/// Records the resolution of a forwarded HTLC.
+	///
+	/// This must be called when an HTLC previously accepted via [`add_htlc`] is resolved,
+	/// either successfully settled or failed. This allows the implementation to release
+	/// resources and update any internal tracking state.
+	///
+	/// [`add_htlc`]: ResourceManager::add_htlc
+	fn resolve_htlc(
+		&self, incoming_channel_id: u64, htlc_id: u64, outgoing_channel_id: u64, settled: bool,
+		resolved_at: u64,
+	) -> Result<(), ()>;
+}
+
+/// The outcome of an HTLC forwarding decision.
+#[derive(PartialEq, Eq, Debug)]
+pub enum ForwardingOutcome {
+	/// Forward the HTLC with the specified accountable signal.
+	Forward(bool),
+	/// Fail to forward the HTLC.
+	Fail,
+}
+
+impl Display for ForwardingOutcome {
+	fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
+		match self {
+			ForwardingOutcome::Forward(signal) => {
+				write!(f, "Forward as {}", if *signal { "accountable " } else { "unaccountable" })
+			},
+			ForwardingOutcome::Fail => {
+				write!(f, "Fail")
+			},
+		}
+	}
+}
+
 #[derive(Clone, PartialEq, Eq, Debug)]
 enum BucketAssigned {
 	General,