Add `XFindBaseLocalChanAlias` RPC #10133

GeorgeTsagk · 2025-08-06T12:14:55Z

Description

This PR exposes a new RPC method XFindBaseLocalChanAlias which enhances the set of alias-related RPCs by allowing the user to look up the base scid for an alias that they added.

We also enhance the alias manager with an extra flag that explicitly indicates that we want the backwards mapping (baseScid -> aliasScid) to be stored. This flag is used when calling XAddLocalChanAlias

gemini-code-assist

Summary of Changes

Hello @GeorgeTsagk, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

I've introduced a new RPC endpoint, XFindBaseLocalChanAlias, to enhance the alias management capabilities. This RPC allows users to easily retrieve the base Short Channel ID (SCID) associated with a local channel alias they've added. To support this, I've updated the alias manager to explicitly store the reverse mapping from alias to base SCID when a new alias is added, ensuring that these lookups are possible.

Highlights

New RPC Endpoint: Added a new experimental RPC, XFindBaseLocalChanAlias, enabling users to query the base SCID for a given local channel alias.
Alias Manager Enhancement: Enhanced the AddLocalAlias function in the alias manager with a baseLookup flag to control the explicit storage of the alias-to-base SCID mapping.
RPC Integration: Modified the XAddLocalChanAlias RPC to utilize this new baseLookup flag, ensuring that manually added aliases can be looked up using the new XFindBaseLocalChanAlias RPC.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point in your pull request via creating an issue comment (i.e. comment on the pull request page) using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in issue comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments or fill out our survey to provide feedback.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

gemini-code-assist · 2025-08-06T12:24:52Z

Warning

Gemini encountered an error creating the review. You can try again by commenting /gemini review.

lightninglabs-deploy · 2025-09-10T14:34:49Z

@GeorgeTsagk, remember to re-request review from reviewers when ready

ellemouton · 2025-09-15T06:31:09Z

aliasmgr/aliasmgr.go

+	// explicitly asked to store this reverse mapping.
+	if gossip || baseLookup {


i dont think we can do this cause now it will be stored in the m.aliasToBase map if gossip is false but baseLookup is true.. meaning it will be available in the map when the gossiper calls FindBaseByAlias which we explicitly dont want, right?

Yeah, now baseLookup flag alone is sufficient to store this in the map.

meaning it will be available in the map when the gossiper calls FindBaseByAlias which we explicitly dont want, right?

The gossiper will only look up scids from received channel updates, so whether we have more values there stored for reverse look-up doesn't seem like an issue as it's unlikely that the gossiper will look-up an scid that we manually created.

W.r.t conflicts in the alias scid range:
we will currently fail if the alias that we're trying to add via RPC already exists for another base scid, so it's even more unlikely that the gossiper will get a bad value out of the lookup, as we explicitly care about the uniqueness of the alias (see related code)

GeorgeTsagk · 2025-09-15T09:08:36Z

/gemini review

GeorgeTsagk · 2025-09-15T09:08:49Z

(previous run failed)

gemini-code-assist

Code Review

This pull request introduces a new RPC, XFindBaseLocalChanAlias, which allows users to look up the base SCID for a given alias. To support this, the alias manager's AddLocalAlias function is updated with a baseLookup flag to control the creation of the in-memory reverse mapping. The changes are logical and include corresponding tests. My feedback includes a few minor suggestions to improve comment clarity, fix a style issue, and correct a typo in the release notes.

aliasmgr/aliasmgr.go

aliasmgr/aliasmgr_test.go

docs/release-notes/release-notes-0.19.3.md

We add an extra flag to the AddLocalAlias method which only controls whether we store a reverse lookup from the alias back to the base scid it corresponds to. The previous flag "gossip" is still maintained, and in a way supercedes the new flag (it will also store the base scid lookup even if the base lookup flag isn't set). Any existing calls to this method will use "false" for the base lookup. The only call that sets this flag is the XAddLocalChanAlias RPC endpoint, where we want to make sure that a reverse lookup is stored in the alias manager in order to later expose it via the new RPC method.

Add the new RPC method that looks up the base scid for a given alias. Given the previous stepping stones this commit is fairly simple, we just call into the alias manager and return the lookup result.

ellemouton · 2025-09-17T11:09:43Z

aliasmgr/aliasmgr.go

-	if gossip {
+	// Only store the gossiper map if gossip is true, or if the caller
+	// explicitly asked to store this reverse mapping.
+	if gossip || baseLookup {


is it the desired behaviour that this reverse lookup is not persisted? currently, all these mappings added will be lost on restart

When we add a local alias we also store a (kvdb) entry that maps the alias to its base

lnd/aliasmgr/aliasmgr.go

Line 297 in d821318

return aliasToBaseBucket.Put(aliasBytes[:], baseBytes[:])

Then on restart when we call the helper populateMaps() we read the entries from the map:

lnd/aliasmgr/aliasmgr.go

Line 178 in d821318

err = aliasToBaseBucket.ForEach(func(k, v []byte) error {

and populate aliasToBase accordingly for each entry:

lnd/aliasmgr/aliasmgr.go

Lines 225 to 234 in d821318

for aliasSCID, baseSCID := range aliasMap {

m.baseToSet[baseSCID] = append(m.baseToSet[baseSCID], aliasSCID)

// Skip if baseSCID is in the baseConfMap.

if _, ok := baseConfMap[baseSCID]; ok {

continue

}

m.aliasToBase[aliasSCID] = baseSCID

}

Ok now I realise that baseConfMap is causing issues here.

After looking over the baseConfMap its entries only affect whether a baseScid will get the aliasToBase values populated on restart:

When we call DeleteSixConfs we mark the base scid in the conf bucket

If an alias entry's base scid is in the conf bucket we skip adding it to aliasToBase on startup

If we make sure to also delete the alias entries from the kvdb aliasToBase bucket here

lnd/aliasmgr/aliasmgr.go

Lines 385 to 391 in d821318

// Now that the database state has been updated, we'll delete all of

// the aliasToBase mappings for this SCID.

for alias, base := range m.aliasToBase {

if base.ToUint64() == baseScid.ToUint64() {

delete(m.aliasToBase, alias)

}

}

Then we can totally strip away the baseToConf bucket, as it won't be needed anymore:

When a baseScid is marked as confirmed we'll purge all previous aliases both from memory and the bucket.

This way on restart any conf'd baseScids will by default not populate any aliasToBase entries, as there won't be any left.

We're now free to add any manual aliasToBase entries which will persist and be restored by default on startup.

Note: if an RPC user added custom aliases before six confs, then those would also be deleted by above approach. In this case:
a) Can make it super clear in the docs that custom aliases are persisted only post-confirmation.
b) Keep the conf bucket after all, only to prohibit RPC user from adding custom entries before the channel is confirmed.

I lean towards a) for the last note.

Also worth investigating how this affects interaction with other systems

ellemouton · 2025-09-17T11:10:27Z

docs/release-notes/release-notes-0.20.0.md

@@ -62,6 +62,10 @@ a certain amount of msats.
 - Added support for [P2TR Fallback Addresses](
  https://github.com/lightningnetwork/lnd/pull/9975) in BOLT-11 invoices.

+- A new experimental RPC endpoint
+  [XFindBaseLocalChanAlias](https://github.com/lightningnetwork/lnd/pull/10133)


re my previous comment, if that is the desired behaviour, then we should warn here that the mappings are lost on restart

GeorgeTsagk self-assigned this Aug 6, 2025

gemini-code-assist bot reviewed Aug 6, 2025

View reviewed changes

GeorgeTsagk force-pushed the rpc-find-base-alias branch from 5b49f62 to c98792e Compare August 6, 2025 12:17

GeorgeTsagk mentioned this pull request Aug 6, 2025

Add XFindBaseLocalChanAlias lightninglabs/lndclient#236

Open

GeorgeTsagk force-pushed the rpc-find-base-alias branch from c98792e to 86ebd6d Compare August 6, 2025 12:27

This was referenced Aug 6, 2025

Delete channel alias scids when quotes expire lightninglabs/taproot-assets#1710

Open

Bump dependencies and go to 1.23.10 lightninglabs/lightning-terminal#1127

Closed

saubyk added this to lnd v0.20 Sep 10, 2025

saubyk added this to the v0.20.0 milestone Sep 10, 2025

saubyk moved this to In progress in lnd v0.20 Sep 10, 2025

saubyk requested review from ellemouton and Roasbeef September 11, 2025 14:23

saubyk moved this from In progress to In review in lnd v0.20 Sep 15, 2025

ellemouton requested changes Sep 15, 2025

View reviewed changes

gemini-code-assist bot reviewed Sep 15, 2025

View reviewed changes

aliasmgr/aliasmgr.go Outdated Show resolved Hide resolved

aliasmgr/aliasmgr_test.go Outdated Show resolved Hide resolved

docs/release-notes/release-notes-0.19.3.md Outdated Show resolved Hide resolved

GeorgeTsagk force-pushed the rpc-find-base-alias branch from 86ebd6d to 4d15b66 Compare September 17, 2025 10:37

GeorgeTsagk added 3 commits September 17, 2025 12:37

lnrpc: add XFindBaseLocalChanAlias rpc

a2deb45

Add the new RPC method that looks up the base scid for a given alias. Given the previous stepping stones this commit is fairly simple, we just call into the alias manager and return the lookup result.

docs: add release note

d821318

GeorgeTsagk force-pushed the rpc-find-base-alias branch from 4d15b66 to d821318 Compare September 17, 2025 10:39

GeorgeTsagk requested a review from ellemouton September 17, 2025 10:39

ellemouton reviewed Sep 17, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add `XFindBaseLocalChanAlias` RPC #10133

Add `XFindBaseLocalChanAlias` RPC #10133

Uh oh!

GeorgeTsagk commented Aug 6, 2025

Uh oh!

gemini-code-assist bot left a comment

Uh oh!

gemini-code-assist bot commented Aug 6, 2025

Uh oh!

lightninglabs-deploy commented Sep 10, 2025

Uh oh!

ellemouton Sep 15, 2025

Uh oh!

GeorgeTsagk Sep 15, 2025

Uh oh!

GeorgeTsagk commented Sep 15, 2025

Uh oh!

GeorgeTsagk commented Sep 15, 2025

Uh oh!

gemini-code-assist bot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ellemouton Sep 17, 2025

Uh oh!

GeorgeTsagk Sep 17, 2025

Uh oh!

GeorgeTsagk Sep 17, 2025

Uh oh!

ellemouton Sep 17, 2025

Uh oh!

Uh oh!

		// explicitly asked to store this reverse mapping.
		if gossip \|\| baseLookup {

	for aliasSCID, baseSCID := range aliasMap {
	m.baseToSet[baseSCID] = append(m.baseToSet[baseSCID], aliasSCID)

	// Skip if baseSCID is in the baseConfMap.
	if _, ok := baseConfMap[baseSCID]; ok {
	continue
	}

	m.aliasToBase[aliasSCID] = baseSCID
	}

	// Now that the database state has been updated, we'll delete all of
	// the aliasToBase mappings for this SCID.
	for alias, base := range m.aliasToBase {
	if base.ToUint64() == baseScid.ToUint64() {
	delete(m.aliasToBase, alias)
	}
	}

Add XFindBaseLocalChanAlias RPC #10133

Are you sure you want to change the base?

Add XFindBaseLocalChanAlias RPC #10133

Uh oh!

Conversation

GeorgeTsagk commented Aug 6, 2025

Description

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Summary of Changes

Highlights

Footnotes

Uh oh!

gemini-code-assist bot commented Aug 6, 2025

Uh oh!

lightninglabs-deploy commented Sep 10, 2025

Uh oh!

ellemouton Sep 15, 2025

Choose a reason for hiding this comment

Uh oh!

GeorgeTsagk Sep 15, 2025

Choose a reason for hiding this comment

Uh oh!

GeorgeTsagk commented Sep 15, 2025

Uh oh!

GeorgeTsagk commented Sep 15, 2025

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ellemouton Sep 17, 2025

Choose a reason for hiding this comment

Uh oh!

GeorgeTsagk Sep 17, 2025

Choose a reason for hiding this comment

Uh oh!

GeorgeTsagk Sep 17, 2025

Choose a reason for hiding this comment

Uh oh!

ellemouton Sep 17, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Add `XFindBaseLocalChanAlias` RPC #10133

Add `XFindBaseLocalChanAlias` RPC #10133