Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
93 changes: 64 additions & 29 deletions chanevents/analyzer.go
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ import (
"github.com/btcsuite/btcd/btcutil"
"github.com/btcsuite/btclog/v2"
"github.com/lightninglabs/lndclient"
"github.com/lightningnetwork/lnd/lnwire"
)

var (
Expand Down Expand Up @@ -75,8 +76,31 @@ type ForwardingAbility struct {
EffectiveUptime time.Duration

// ForwardedAmount is the total successfully forwarded amount over the
// window.
// window, at satoshi granularity.
ForwardedAmount btcutil.Amount

// FeeMsat is the total fee earned on the pair's forwards over the
// window.
FeeMsat lnwire.MilliSatoshi

// Forwards is how many successful forwards the pair carried. It decides
// whether the pair forwarded at all, since both sums can be zero for
// one that did: sub-satoshi volume floors away and a zero-fee policy
// earns nothing.
Forwards int64
}

// pairForwards accumulates what one direction of a peer pair carried over the
// analysis window.
type pairForwards struct {
// amount is the total forwarded amount, at satoshi granularity.
amount btcutil.Amount

// feeMsat is the total fee earned on those forwards.
feeMsat lnwire.MilliSatoshi

// forwards is how many successful forwards were carried.
forwards int64
}

// PeerPair identifies a unidirectional routing edge from PeerIn to PeerOut.
Expand Down Expand Up @@ -166,10 +190,10 @@ func (a *ForwardingAnalyzer) EffectiveUptime(ctx context.Context, startTime,

// getForwardingData queries lnd's forwarding history sequentially in paginated
// batches to retrieve successful forwarding events within the specified time
// range, indexing the results by peer pair.
// range, accumulating the volume, fees and count of each peer pair's forwards.
func (a *ForwardingAnalyzer) getForwardingData(ctx context.Context, startTime,
endTime time.Time, scidToPeer map[uint64]string) (
map[PeerPair][]btcutil.Amount, map[uint64]string, error) {
map[PeerPair]*pairForwards, map[uint64]string, error) {

var events []lndclient.ForwardingEvent
var offset uint32
Expand Down Expand Up @@ -214,7 +238,7 @@ func (a *ForwardingAnalyzer) getForwardingData(ctx context.Context, startTime,
)

channelPeersConsidered := make(map[uint64]string)
successfulForwards := make(map[PeerPair][]btcutil.Amount)
successfulForwards := make(map[PeerPair]*pairForwards)
for _, fwd := range events {
inPeer, ok := scidToPeer[fwd.ChannelIn]
if !ok {
Expand Down Expand Up @@ -242,8 +266,15 @@ func (a *ForwardingAnalyzer) getForwardingData(ctx context.Context, startTime,
PeerOut: outPeer,
}

amt := fwd.AmountMsatOut.ToSatoshis()
successfulForwards[pair] = append(successfulForwards[pair], amt)
totals, ok := successfulForwards[pair]
if !ok {
totals = &pairForwards{}
successfulForwards[pair] = totals
}

totals.amount += fwd.AmountMsatOut.ToSatoshis()
totals.feeMsat += fwd.FeeMsat
totals.forwards++
}

return successfulForwards, channelPeersConsidered, nil
Expand Down Expand Up @@ -427,7 +458,7 @@ func (a *ForwardingAnalyzer) getInitialChannelState(ctx context.Context,
// computing both directions (A→B and B→A) in a single pass.
func calculateAllPairsUptime(ctx context.Context, store EventsSource, startTime,
endTime time.Time, liquidityFloor btcutil.Amount,
successfulForwards map[PeerPair][]btcutil.Amount,
successfulForwards map[PeerPair]*pairForwards,
initialStates map[string]map[int64]*channelState,
peerChannels map[string][]int64) (
map[PeerPair]ForwardingAbility, error) {
Expand Down Expand Up @@ -506,10 +537,10 @@ func calculateAllPairsUptime(ctx context.Context, store EventsSource, startTime,
statesB := initialStates[peerB]
sumsB := initialSums[peerB]

forwardedAB := pairForwardedTotal(
totalsAB := pairForwardTotals(
successfulForwards, peerA, peerB,
)
forwardedBA := pairForwardedTotal(
totalsBA := pairForwardTotals(
successfulForwards, peerB, peerA,
)

Expand All @@ -529,7 +560,7 @@ func calculateAllPairsUptime(ctx context.Context, store EventsSource, startTime,
sumsA.remote, sumsA.local,
sumsB.remote, sumsB.local,
mergeEventSlices(sliceA, sliceB),
forwardedAB, forwardedBA,
totalsAB, totalsBA,
)
if err != nil {
return nil, err
Expand Down Expand Up @@ -594,32 +625,34 @@ func loadPeerEvents(ctx context.Context, store EventsSource, startTime,
return events, nil
}

// pairForwardedTotal sums the successfully forwarded amounts for one direction
// of a peer pair over the analysis window.
func pairForwardedTotal(successfulForwards map[PeerPair][]btcutil.Amount,
peerIn, peerOut string) btcutil.Amount {
// pairForwardTotals returns the accumulated forwards for one direction of a
// peer pair over the analysis window. A pair with no recorded forwards yields
// the zero value, whose zero count marks it as having carried nothing.
func pairForwardTotals(successfulForwards map[PeerPair]*pairForwards,
peerIn, peerOut string) pairForwards {

var total btcutil.Amount
for _, amt := range successfulForwards[PeerPair{
totals, ok := successfulForwards[PeerPair{
PeerIn: peerIn, PeerOut: peerOut,
}] {
total += amt
}]
if !ok {
return pairForwards{}
}

return total
return *totals
}

// calculateBothDirectionsUptime computes the effective forwarding uptime for
// both directions of a peer pair in a single chronological walk of the merged
// event stream. Only the liquidity-direction roles differ between the two
// accumulators, as both share the same uniform liquidityFloor. forwardedAB and
// forwardedBA carry each direction's total forwarded volume through to the
// returned abilities. For self-pair calls both returned abilities are equal.
// accumulators, as both share the same uniform liquidityFloor. totalsAB and
// totalsBA carry each direction's forwarded volume, fees and count through to
// the returned abilities. For self-pair calls both returned abilities are
// equal.
func calculateBothDirectionsUptime(ctx context.Context, startTime,
endTime time.Time, liquidityFloor btcutil.Amount, statesA,
statesB map[int64]*channelState, sumARemote, sumALocal, sumBRemote,
sumBLocal btcutil.Amount, mergedEvents channelEventSeq,
forwardedAB, forwardedBA btcutil.Amount) (
totalsAB, totalsBA pairForwards) (
*ForwardingAbility, *ForwardingAbility, error) {

traceOn := log.Level() <= btclog.LevelTrace
Expand Down Expand Up @@ -787,8 +820,8 @@ func calculateBothDirectionsUptime(ctx context.Context, startTime,
)
}

abilityAB := makeAbility(uptimeAB, forwardedAB)
abilityBA := makeAbility(uptimeBA, forwardedBA)
abilityAB := makeAbility(uptimeAB, totalsAB)
abilityBA := makeAbility(uptimeBA, totalsBA)

return abilityAB, abilityBA, nil
}
Expand Down Expand Up @@ -882,14 +915,16 @@ func applyEvent(state *channelState, event *ChannelEvent) error {
return nil
}

// makeAbility folds an accumulated uptime and successful-amount total into a
// ForwardingAbility carrying the raw facts. Derived rates and categories are
// makeAbility folds an accumulated uptime and a direction's forward totals into
// a ForwardingAbility carrying the raw facts. Derived rates and categories are
// left to the consumer.
func makeAbility(totalUptime time.Duration,
totalAmt btcutil.Amount) *ForwardingAbility {
totals pairForwards) *ForwardingAbility {

return &ForwardingAbility{
EffectiveUptime: totalUptime,
ForwardedAmount: totalAmt,
ForwardedAmount: totals.amount,
FeeMsat: totals.feeMsat,
Forwards: totals.forwards,
}
}
53 changes: 41 additions & 12 deletions chanevents/analyzer_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ import (
"github.com/lightninglabs/lndclient"
"github.com/lightningnetwork/lnd/clock"
"github.com/lightningnetwork/lnd/fn/v2"
"github.com/lightningnetwork/lnd/lnwire"
"github.com/lightningnetwork/lnd/routing/route"
"github.com/stretchr/testify/require"
)
Expand Down Expand Up @@ -596,9 +597,20 @@ func TestCalculateBothDirectionsUptime(t *testing.T) {
func(t *testing.T) {
t.Parallel()

var totalSuccessfulAmount btcutil.Amount
forwards := pairForwards{
forwards: int64(len(tc.successAmts)),
}
for _, amt := range tc.successAmts {
totalSuccessfulAmount += amt
forwards.amount += amt

// Two msat of fee per satoshi
// forwarded, so the fee total is
// distinct from the volume total and a
// crossed assignment fails the
// assertion below.
forwards.feeMsat += lnwire.MilliSatoshi(
amt,
) * 2
}

mergedEvents := mergeEventSlices(
Expand All @@ -622,9 +634,9 @@ func TestCalculateBothDirectionsUptime(t *testing.T) {
}
}

// The (B→A) forwarded total is not asserted by
// this test; pass zero so the second ability is
// well-defined but ignored.
// The (B→A) forwarded totals are not asserted
// by this test; pass the zero value so the
// second ability is well-defined but ignored.
abilityAB, _, err :=
calculateBothDirectionsUptime(
context.Background(),
Expand All @@ -634,12 +646,14 @@ func TestCalculateBothDirectionsUptime(t *testing.T) {
sumARemote, sumALocal,
sumBRemote, sumBLocal,
mergedEvents,
totalSuccessfulAmount, 0,
forwards, pairForwards{},
)
require.NoError(t, err)
require.Equal(t, &ForwardingAbility{
EffectiveUptime: tc.expectedUptime,
ForwardedAmount: totalSuccessfulAmount,
ForwardedAmount: forwards.amount,
FeeMsat: forwards.feeMsat,
Forwards: forwards.forwards,
}, abilityAB)
},
)
Expand Down Expand Up @@ -702,22 +716,27 @@ func TestCalculateBothDirectionsUptimeAsymmetric(t *testing.T) {
liquidityFloor, statesA, statesB,
sumARemote, sumALocal, sumBRemote, sumBLocal,
mergeEventSlices(nil, nil),
100, 50,
pairForwards{amount: 100, feeMsat: 200, forwards: 2},
pairForwards{amount: 50, feeMsat: 100, forwards: 1},
)
require.NoError(t, err)

require.Equal(
t, &ForwardingAbility{
EffectiveUptime: 100 * time.Second,
ForwardedAmount: 100,
FeeMsat: 200,
Forwards: 2,
}, abilityAB,
)
require.Equal(
t, &ForwardingAbility{
// Forwards landed but BA never crossed the floor: zero
// uptime, volume still reported.
// uptime, volume and fees still reported.
EffectiveUptime: 0,
ForwardedAmount: 50,
FeeMsat: 100,
Forwards: 1,
}, abilityBA,
)
}
Expand Down Expand Up @@ -1003,11 +1022,13 @@ func TestEffectiveUptimeArgs(t *testing.T) {
ChannelIn: testShortChanID1,
ChannelOut: testShortChanID2,
AmountMsatOut: 100_000_000, // 100k sat
FeeMsat: 100_000,
},
{
ChannelIn: testShortChanID1,
ChannelOut: testShortChanID2,
AmountMsatOut: 300_000_000, // 300k sat
FeeMsat: 300_000,
},
},
},
Expand All @@ -1020,22 +1041,30 @@ func TestEffectiveUptimeArgs(t *testing.T) {

// Case 1: liquidityFloor = 50k. Liquidity of 1M exceeds the floor for
// the whole 60s window, so effective uptime is the full minute and the
// forwarded volume is the 400k sat total.
// forwarded volume is the 400k sat total, earning 400k msat.
abilities, err := a.EffectiveUptime(ctx, startTime, endTime, 50_000)
require.NoError(t, err)

pair := PeerPair{PeerIn: validPubKey1, PeerOut: validPubKey2}
require.Contains(t, abilities, pair)
require.Equal(t, time.Minute, abilities[pair].EffectiveUptime)
require.Equal(t, btcutil.Amount(400_000), abilities[pair].ForwardedAmount)
require.Equal(
t, lnwire.MilliSatoshi(400_000), abilities[pair].FeeMsat,
)
require.EqualValues(t, 2, abilities[pair].Forwards)

// Case 2: liquidityFloor = 1.5M, above the 1M liquidity, so the floor is
// never crossed and effective uptime is zero. The forwarded volume is
// still reported so the consumer keeps the demand signal.
// never crossed and effective uptime is zero. The forwarded volume and
// fees are still reported so the consumer keeps the signal.
abilities, err = a.EffectiveUptime(ctx, startTime, endTime, 1_500_000)
require.NoError(t, err)

require.Contains(t, abilities, pair)
require.Zero(t, abilities[pair].EffectiveUptime)
require.Equal(t, btcutil.Amount(400_000), abilities[pair].ForwardedAmount)
require.Equal(
t, lnwire.MilliSatoshi(400_000), abilities[pair].FeeMsat,
)
require.EqualValues(t, 2, abilities[pair].Forwards)
}
19 changes: 17 additions & 2 deletions cmd/frcli/forwarding_ability.go
Original file line number Diff line number Diff line change
Expand Up @@ -46,8 +46,11 @@ type pairView struct {
PeerOut string `json:"peer_out"`
EffectiveUptimeS int64 `json:"effective_uptime_s"`
ForwardedSat int64 `json:"forwarded_sat"`
FeeMsat int64 `json:"fee_msat"`
Forwards int64 `json:"forwards"`
UptimeFraction float64 `json:"uptime_fraction"`
Velocity float64 `json:"velocity"`
FeeRate float64 `json:"fee_rate"`
}

func queryForwardingAbility(ctx *cli.Context) error {
Expand All @@ -72,8 +75,8 @@ func queryForwardingAbility(ctx *cli.Context) error {
return err
}

// The metrics are raw, so derive uptime fraction and velocity here from
// the window the server reported.
// The metrics are raw, so derive uptime fraction, velocity and fee rate
// here from the window the server reported.
windowSeconds := resp.EndTime - resp.StartTime

var views []pairView
Expand All @@ -91,14 +94,26 @@ func queryForwardingAbility(ctx *cli.Context) error {
float64(ability.EffectiveUptimeS)
}

// Fees over volume. A pair with only sub-satoshi
// forwards has no volume to divide by, so it keeps a
// zero rate rather than an infinite one.
var feeRate float64
if ability.ForwardedSat > 0 {
feeRate = float64(ability.FeeMsat) /
(float64(ability.ForwardedSat) * 1000)
}

views = append(
views, pairView{
PeerIn: inPeer,
PeerOut: outPeer,
EffectiveUptimeS: ability.EffectiveUptimeS,
ForwardedSat: ability.ForwardedSat,
FeeMsat: ability.FeeMsat,
Forwards: ability.Forwards,
UptimeFraction: uptimeFraction,
Velocity: velocity,
FeeRate: feeRate,
},
)
}
Expand Down
Loading
Loading