sim-node: add channel state tracking for channels

This commit adds a ChannelState struct which is used to track the
policy and state of a channel in the *outgoing* direction. This will
be used to check forwards against the node's advertised policy and
track the movement of outgoing HTLCs through the channel.

Note that we choose to implement this state *unidirectionally*, so a
single channel will be represented by two ChannelState structs (one in
each direction).

Author: carlaKC

sim-lib/src/lib.rs

@@ -27,6 +27,7 @@ mod defined_activity;
 pub mod lnd;
 mod random_activity;
 mod serializers;
+pub mod sim_node;
 #[cfg(test)]
 mod test_utils;
 
@@ -84,6 +85,37 @@ impl std::fmt::Display for NodeId {
     }
 }
 
+/// Represents a short channel ID, expressed as a struct so that we can implement display for the trait.
+#[derive(Debug)]
+pub struct ShortChannelID(u64);
+
+/// Utility function to easily convert from u64 to `ShortChannelID`
+impl From<u64> for ShortChannelID {
+    fn from(value: u64) -> Self {
+        ShortChannelID(value)
+    }
+}
+
+/// Utility function to easily convert `ShortChannelID` into u64
+impl From<ShortChannelID> for u64 {
+    fn from(scid: ShortChannelID) -> Self {
+        scid.0
+    }
+}
+
+/// See https://github.com/lightning/bolts/blob/60de4a09727c20dea330f9ee8313034de6e50594/07-routing-gossip.md#definition-of-short_channel_id.
+impl std::fmt::Display for ShortChannelID {
+    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+        write!(
+            f,
+            "{}:{}:{}",
+            (self.0 >> 40) as u32,
+            ((self.0 >> 16) & 0xFFFFFF) as u32,
+            (self.0 & 0xFFFF) as u16,
+        )
+    }
+}
+
 #[derive(Debug, Serialize, Deserialize, Clone)]
 pub struct SimParams {
     pub nodes: Vec<NodeConnection>,

sim-lib/src/sim_node.rs

@@ -0,0 +1,192 @@
+use bitcoin::secp256k1::PublicKey;
+use lightning::ln::PaymentHash;
+use std::collections::HashMap;
+
+use crate::ShortChannelID;
+
+/// ForwardingError represents the various errors that we can run into when forwarding payments in a simulated network.
+/// Since we're not using real lightning nodes, these errors are not obfuscated and can be propagated to the sending
+/// node and used for analysis.
+#[derive(Debug)]
+pub enum ForwardingError {
+    /// Zero amount htlcs are invalid in the protocol.
+    ZeroAmountHtlc,
+    /// The outgoing channel id was not found in the network graph.
+    ChannelNotFound(ShortChannelID),
+    /// The node pubkey provided was not associated with the channel in the network graph.
+    NodeNotFound(PublicKey),
+    /// The channel has already forwarded an HTLC with the payment hash provided.
+    /// TODO: remove if MPP support is added.
+    PaymentHashExists(PaymentHash),
+    /// An htlc with the payment hash provided could not be found to resolve.
+    PaymentHashNotFound(PaymentHash),
+    /// The forwarding node did not have sufficient outgoing balance to forward the htlc (htlc amount / balance).
+    InsufficientBalance(u64, u64),
+    /// The htlc forwarded is less than the channel's advertised minimum htlc amount (htlc amount / minimum).
+    LessThanMinimum(u64, u64),
+    /// The htlc forwarded is more than the chanenl's advertised maximum htlc amount (htlc amount / maximum).
+    MoreThanMaximum(u64, u64),
+    /// The channel has reached its maximum allowable number of htlcs in flight (total in flight / maximim).
+    ExceedsInFlightCount(u64, u64),
+    /// The forwarded htlc's amount would push the channel over its maximum allowable in flight total
+    /// (total in flight / maximum).
+    ExceedsInFlightTotal(u64, u64),
+    /// The forwarded htlc's cltv expiry exceeds the maximum value used to express block heights in Bitcoin.
+    ExpiryInSeconds(u32, u32),
+    /// The forwarded htlc has insufficient cltv delta for the channel's minimum delta (cltv delta / minimum).
+    InsufficientCltvDelta(u32, u32),
+    /// The forwarded htlc has insufficient fee for the channel's policy (fee / expected fee / base fee / prop fee).
+    InsufficientFee(u64, u64, u64, u64),
+    /// The fee policy for a htlc amount would overflow with the given fee policy (htlc amount / base fee / prop fee).
+    FeeOverflow(u64, u64, u64),
+    /// Sanity check on channel balances failed (node balances / channel capacity).
+    SanityCheckFailed(u64, u64),
+}
+
+/// Represents an in-flight htlc that has been forwarded over a channel that is awaiting resolution.
+#[derive(Copy, Clone)]
+struct Htlc {
+    amount_msat: u64,
+    cltv_expiry: u32,
+}
+
+/// Represents one node in the channel's forwarding policy and restrictions. Note that this doesn't directly map to
+/// a single concept in the protocol, a few things have been combined for the sake of simplicity. Used to manage the
+/// lightning "state machine" and check that HTLCs are added in accordance of the advertised policy.
+#[derive(Clone)]
+pub struct ChannelPolicy {
+    pub pubkey: PublicKey,
+    pub max_htlc_count: u64,
+    pub max_in_flight_msat: u64,
+    pub min_htlc_size_msat: u64,
+    pub max_htlc_size_msat: u64,
+    pub cltv_expiry_delta: u32,
+    pub base_fee: u64,
+    pub fee_rate_prop: u64,
+}
+
+/// Fails with the forwarding error provided if the value provided fails its inequality check.
+macro_rules! fail_forwarding_inequality {
+    ($value_1:expr, $op:tt, $value_2:expr, $error_variant:ident $(, $opt:expr)*) => {
+        if $value_1 $op $value_2 {
+            return Err(ForwardingError::$error_variant(
+                    $value_1,
+                    $value_2
+                    $(
+                        , $opt
+                    )*
+             ));
+        }
+    };
+}
+
+/// The internal state of one side of a simulated channel, including its forwarding parameters. This struct is
+/// primarily responsible for handling our view of what's currently in-flight on the channel, and how much
+/// liquidity we have.
+#[derive(Clone)]
+struct ChannelState {
+    local_balance_msat: u64,
+    in_flight: HashMap<PaymentHash, Htlc>,
+    policy: ChannelPolicy,
+}
+
+impl ChannelState {
+    /// Creates a new channel with local liquidity as allocated by the caller. The responsibility of ensuring that the
+    /// local balance of each side of the channel equals its total capacity is on the caller, as we are only dealing
+    /// with a one-sided view of the channel's state.
+    fn new(policy: ChannelPolicy, local_balance_msat: u64) -> Self {
+        ChannelState {
+            local_balance_msat,
+            in_flight: HashMap::new(),
+            policy,
+        }
+    }
+
+    /// Returns the sum of all the *in flight outgoing* HTLCs on the channel.
+    fn in_flight_total(&self) -> u64 {
+        self.in_flight.values().map(|h| h.amount_msat).sum()
+    }
+
+    /// Checks whether the proposed HTLC abides by the channel policy advertised for using this channel as the
+    /// *outgoing* link in a forward.
+    fn check_htlc_forward(
+        &self,
+        cltv_delta: u32,
+        amt: u64,
+        fee: u64,
+    ) -> Result<(), ForwardingError> {
+        fail_forwarding_inequality!(cltv_delta, <, self.policy.cltv_expiry_delta, InsufficientCltvDelta);
+
+        let expected_fee = amt
+            .checked_mul(self.policy.fee_rate_prop)
+            .and_then(|prop_fee| (prop_fee / 1000000).checked_add(self.policy.base_fee))
+            .ok_or(ForwardingError::FeeOverflow(
+                amt,
+                self.policy.base_fee,
+                self.policy.fee_rate_prop,
+            ))?;
+
+        fail_forwarding_inequality!(
+            fee, <, expected_fee, InsufficientFee, self.policy.base_fee, self.policy.fee_rate_prop
+        );
+
+        Ok(())
+    }
+
+    /// Checks whether the proposed HTLC can be added to the channel as an outgoing HTLC. This requires that we have
+    /// sufficient liquidity, and that the restrictions on our in flight htlc balance and count are not violated by
+    /// the addition of the HTLC. Specification sanity checks (such as reasonable CLTV) are also included, as this
+    /// is where we'd check it in real life.
+    fn check_outgoing_addition(&self, htlc: &Htlc) -> Result<(), ForwardingError> {
+        fail_forwarding_inequality!(htlc.amount_msat, >, self.policy.max_htlc_size_msat, MoreThanMaximum);
+        fail_forwarding_inequality!(htlc.amount_msat, <, self.policy.min_htlc_size_msat, LessThanMinimum);
+        fail_forwarding_inequality!(
+            self.in_flight.len() as u64 + 1, >, self.policy.max_htlc_count, ExceedsInFlightCount
+        );
+        fail_forwarding_inequality!(
+            self.in_flight_total() + htlc.amount_msat, >, self.policy.max_in_flight_msat, ExceedsInFlightTotal
+        );
+        fail_forwarding_inequality!(htlc.amount_msat, >, self.local_balance_msat, InsufficientBalance);
+        fail_forwarding_inequality!(htlc.cltv_expiry, >, 500000000, ExpiryInSeconds);
+
+        Ok(())
+    }
+
+    /// Adds the HTLC to our set of outgoing in-flight HTLCs. [`check_outgoing_addition`] must be called before
+    /// this to ensure that the restrictions on outgoing HTLCs are not violated. Local balance is decreased by the
+    /// HTLC amount, as this liquidity is no longer available.
+    ///
+    /// Note: MPP payments are not currently supported, so this function will fail if a duplicate payment hash is
+    /// reported.
+    fn add_outgoing_htlc(&mut self, hash: PaymentHash, htlc: Htlc) -> Result<(), ForwardingError> {
+        self.check_outgoing_addition(&htlc)?;
+        if self.in_flight.get(&hash).is_some() {
+            return Err(ForwardingError::PaymentHashExists(hash));
+        }
+        self.local_balance_msat -= htlc.amount_msat;
+        self.in_flight.insert(hash, htlc);
+        Ok(())
+    }
+
+    /// Removes the HTLC from our set of outgoing in-flight HTLCs, failing if the payment hash is not found. If the
+    /// HTLC failed, the balance is returned to our local liquidity. Note that this function is not responsible for
+    /// reflecting that the balance has moved to the other side of the channel in the success-case, calling code is
+    /// responsible for that.
+    fn remove_outgoing_htlc(
+        &mut self,
+        hash: &PaymentHash,
+        success: bool,
+    ) -> Result<Htlc, ForwardingError> {
+        match self.in_flight.remove(hash) {
+            Some(v) => {
+                // If the HTLC failed, pending balance returns to local balance.
+                if !success {
+                    self.local_balance_msat += v.amount_msat;
+                }
+
+                Ok(v)
+            },
+            None => Err(ForwardingError::PaymentHashNotFound(*hash)),
+        }
+    }
+}