recover L402 and static address

Author: hieblmi

README.md

@@ -64,6 +64,28 @@ To execute a Loop In:
 loop in <amt_in_satoshis>
 ```
 
+### Static Address Recovery
+Loop now keeps at most one encrypted immutable recovery backup per paid L402
+generation in the active network data directory. A backup is written only after
+Loop has both the paid `l402.token` and the concrete static-address parameters
+for that generation.
+
+The backup is encrypted with a key derived by the backing `lnd` wallet. It is
+therefore only useful with that same `lnd` instance, or with an `lnd` restored
+from the same seed/key material. The Loop backup file alone is not enough to
+recover static-address access.
+
+Existing static-address users get this backup backfilled on the next startup
+with the upgraded client. A fresh install that has no local L402 or
+static-address state first checks for an existing recovery backup in the active
+network directory. If none is restored, startup materializes the initial
+paid-L402/static-address generation and writes its backup.
+
+The follow-up multi-address work is expected to keep this one-backup-per-L402
+model and use the deterministic receive/change key-family metadata already
+stored in the backup. See [recovery/README.md](./recovery/README.md) for the
+full recovery model and the planned multi-address outlook.
+
 ### More info
 
 - [Loop FAQs](./docs/faqs.md)

cmd/loop/main.go

@@ -88,7 +88,8 @@ var (
 		monitorCommand, quoteCommand, listAuthCommand, fetchL402Command,
 		listSwapsCommand, swapInfoCommand, getLiquidityParamsCommand,
 		setLiquidityRuleCommand, suggestSwapCommand, setParamsCommand,
-		getInfoCommand, abandonSwapCommand, reservationsCommands,
+		getInfoCommand, abandonSwapCommand, recoverCommand,
+		reservationsCommands,
 		instantOutCommand, listInstantOutsCommand, stopCommand,
 		printManCommand, printMarkdownCommand,
 	}

cmd/loop/recover.go

@@ -0,0 +1,50 @@
+package main
+
+import (
+	"context"
+
+	"github.com/lightninglabs/loop/looprpc"
+	"github.com/urfave/cli/v3"
+)
+
+var recoverCommand = &cli.Command{
+	Name:  "recover",
+	Usage: "restore static address and L402 state from a local backup file",
+	Description: "Restores the local static-address state and L402 token " +
+		"from an encrypted backup file. If --backup_file is omitted, " +
+		"loopd selects the latest decryptable active-network backup " +
+		"candidate and fully validates it before restoring state.",
+	Flags: []cli.Flag{
+		&cli.StringFlag{
+			Name: "backup_file",
+			Usage: "path to an encrypted backup file; if omitted, " +
+				"loopd selects and validates the latest active-network " +
+				"backup candidate",
+		},
+	},
+	Action: runRecover,
+}
+
+func runRecover(ctx context.Context, cmd *cli.Command) error {
+	if cmd.NArg() > 0 {
+		return showCommandHelp(ctx, cmd)
+	}
+
+	client, cleanup, err := getClient(cmd)
+	if err != nil {
+		return err
+	}
+	defer cleanup()
+
+	resp, err := client.Recover(
+		ctx, &looprpc.RecoverRequest{
+			BackupFile: cmd.String("backup_file"),
+		},
+	)
+	if err != nil {
+		return err
+	}
+
+	printRespJSON(resp)
+	return nil
+}

cmd/loop/staticaddr.go

@@ -9,6 +9,7 @@ import (
 
 	"github.com/lightninglabs/loop/labels"
 	"github.com/lightninglabs/loop/looprpc"
+	"github.com/lightninglabs/loop/staticaddr/address"
 	"github.com/lightninglabs/loop/staticaddr/loopin"
 	"github.com/lightninglabs/loop/swapserverrpc"
 	lndcommands "github.com/lightningnetwork/lnd/cmd/commands"
@@ -43,13 +44,15 @@ var staticAddressCommands = &cli.Command{
 var newStaticAddressCommand = &cli.Command{
 	Name:    "new",
 	Aliases: []string{"n"},
-	Usage:   "Create a new static loop in address.",
+	Usage:   "Return the static loop in address.",
 	Description: `
-	Requests a new static loop in address from the server. Funds that are
-	sent to this address will be locked by a 2:2 multisig between us and the
-	loop server, or a timeout path that we can sweep once it opens up. The 
-	funds can either be cooperatively spent with a signature from the server
-	or looped in.
+	Returns the current static loop in address. On a fresh installation loopd
+	initializes the current static-address generation during startup. If the
+	address is still missing, this call will create it on demand. Funds sent
+	to the address will be locked by a 2:2 multisig between us and the loop
+	server, or a timeout path that we can sweep once it opens up. The funds
+	can either be cooperatively spent with a signature from the server or
+	looped in.
 	`,
 	Action: newStaticAddress,
 }
@@ -59,16 +62,16 @@ func newStaticAddress(ctx context.Context, cmd *cli.Command) error {
 		return showCommandHelp(ctx, cmd)
 	}
 
-	err := displayNewAddressWarning()
+	client, cleanup, err := getClient(cmd)
 	if err != nil {
 		return err
 	}
+	defer cleanup()
 
-	client, cleanup, err := getClient(cmd)
+	err = maybeDisplayNewAddressWarning(ctx, client)
 	if err != nil {
 		return err
 	}
-	defer cleanup()
 
 	resp, err := client.NewStaticAddress(
 		ctx, &looprpc.NewStaticAddressRequest{},
@@ -841,8 +844,26 @@ func lowConfDepositWarning(allDeposits []*looprpc.Deposit,
 	)
 }
 
+func maybeDisplayNewAddressWarning(ctx context.Context,
+	client looprpc.SwapClientClient) error {
+
+	_, err := client.GetStaticAddressSummary(
+		ctx, &looprpc.StaticAddressSummaryRequest{},
+	)
+	switch {
+	case err == nil:
+		return nil
+
+	case strings.Contains(err.Error(), address.ErrNoStaticAddress.Error()):
+		return displayNewAddressWarning()
+
+	default:
+		return nil
+	}
+}
+
 func displayNewAddressWarning() error {
-	fmt.Printf("\nWARNING: Be aware that loosing your l402.token file in " +
+	fmt.Printf("\nWARNING: Be aware that losing your l402.token file in " +
 		".loop under your home directory will take your ability to " +
 		"spend funds sent to the static address via loop-ins or " +
 		"withdrawals. You will have to wait until the deposit " +

docs/loop.1

@@ -403,6 +403,16 @@ abandon a swap with a given swap hash
 .PP
 \fB--i_know_what_i_am_doing\fP: Specify this flag if you made sure that you read and understood the following consequence of applying this command.
 
+.SH recover
+.PP
+restore static address and L402 state from a local backup file
+
+.PP
+\fB--backup_file\fP="": path to an encrypted backup file; if omitted, loopd selects and validates the latest active-network backup candidate
+
+.PP
+\fB--help, -h\fP: show help
+
 .SH reservations, r
 .PP
 manage reservations
@@ -456,7 +466,7 @@ perform on-chain to off-chain swaps using static addresses.
 
 .SS new, n
 .PP
-Create a new static loop in address.
+Return the static loop in address.
 
 .PP
 \fB--help, -h\fP: show help

docs/loop.md

@@ -418,6 +418,25 @@ The following flags are supported:
 | `--i_know_what_i_am_doing` | Specify this flag if you made sure that you read and understood the following consequence of applying this command | bool |    `false`    |
 | `--help` (`-h`)            | show help                                                                                                          | bool |    `false`    |
 
+### `recover` command
+
+restore static address and L402 state from a local backup file.
+
+Restores the local static-address state and L402 token from an encrypted backup file. If --backup_file is omitted, loopd selects the latest decryptable active-network backup candidate and fully validates it before restoring state.
+
+Usage:
+
+```bash
+$ loop [GLOBAL FLAGS] recover [COMMAND FLAGS] [ARGUMENTS...]
+```
+
+The following flags are supported:
+
+| Name                | Description                                                                                                          | Type   | Default value |
+|---------------------|----------------------------------------------------------------------------------------------------------------------|--------|:-------------:|
+| `--backup_file="…"` | path to an encrypted backup file; if omitted, loopd selects and validates the latest active-network backup candidate | string |
+| `--help` (`-h`)     | show help                                                                                                            | bool   |    `false`    |
+
 ### `reservations` command (aliases: `r`)
 
 manage reservations.
@@ -529,9 +548,9 @@ The following flags are supported:
 
 ### `static new` subcommand (aliases: `n`)
 
-Create a new static loop in address.
+Return the static loop in address.
 
-Requests a new static loop in address from the server. Funds that are 	sent to this address will be locked by a 2:2 multisig between us and the 	loop server, or a timeout path that we can sweep once it opens up. The  	funds can either be cooperatively spent with a signature from the server 	or looped in.
+Returns the current static loop in address. On a fresh installation loopd 	initializes the current static-address generation during startup. If the 	address is still missing, this call will create it on demand. Funds sent 	to the address will be locked by a 2:2 multisig between us and the loop 	server, or a timeout path that we can sweep once it opens up. The funds 	can either be cooperatively spent with a signature from the server or 	looped in.
 
 Usage:
 

go.mod

@@ -37,6 +37,7 @@ require (
 	github.com/urfave/cli-docs/v3 v3.1.1-0.20251020101624-bec07369b4f6
 	github.com/urfave/cli/v3 v3.4.1
 	go.etcd.io/bbolt v1.4.3
+	golang.org/x/crypto v0.46.0
 	golang.org/x/sync v0.19.0
 	google.golang.org/grpc v1.79.3
 	google.golang.org/protobuf v1.36.11
@@ -194,7 +195,6 @@ require (
 	go.uber.org/multierr v1.6.0 // indirect
 	go.uber.org/zap v1.24.0 // indirect
 	go.yaml.in/yaml/v3 v3.0.4 // indirect
-	golang.org/x/crypto v0.46.0 // indirect
 	golang.org/x/exp v0.0.0-20240909161429-701f63a606c0 // indirect
 	golang.org/x/mod v0.30.0 // indirect
 	golang.org/x/net v0.48.0 // indirect

loopd/daemon.go

@@ -22,6 +22,7 @@ import (
 	"github.com/lightninglabs/loop/loopdb"
 	loop_looprpc "github.com/lightninglabs/loop/looprpc"
 	"github.com/lightninglabs/loop/notifications"
+	"github.com/lightninglabs/loop/recovery"
 	"github.com/lightninglabs/loop/staticaddr/address"
 	"github.com/lightninglabs/loop/staticaddr/deposit"
 	"github.com/lightninglabs/loop/staticaddr/loopin"
@@ -597,13 +598,16 @@ func (d *Daemon) initialize(withMacaroonService bool) error {
 		withdrawalManager    *withdraw.Manager
 		openChannelManager   *openchannel.Manager
 		staticLoopInManager  *loopin.Manager
+		recoveryService      *recovery.Service
 	)
 
 	// Static address manager setup.
 	staticAddressStore := address.NewSqlStore(baseDb)
 	addrCfg := &address.ManagerConfig{
 		AddressClient: staticAddressClient,
-		FetchL402:     swapClient.Server.FetchL402,
+		FetchL402: func(ctx context.Context) error {
+			return swapClient.Server.FetchL402(ctx)
+		},
 		Store:         staticAddressStore,
 		WalletKit:     d.lnd.WalletKit,
 		ChainParams:   d.lnd.ChainParams,
@@ -705,6 +709,46 @@ func (d *Daemon) initialize(withMacaroonService bool) error {
 		return fmt.Errorf("unable to create loop-in manager: %w", err)
 	}
 
+	// Keep startup restore/write-backup free of deposit reconciliation so we
+	// don't create deposit FSMs before the deposit manager is running.
+	startupRecoveryService := recovery.NewService(
+		d.cfg.DataDir, d.cfg.Network, d.lnd.Signer, d.lnd.WalletKit,
+		staticAddressManager, nil,
+	)
+
+	restoreResult, restoredFromBackup, err :=
+		startupRecoveryService.RestoreLatestOnFreshInstall(d.mainCtx)
+	if err != nil {
+		return fmt.Errorf("unable to restore latest recovery "+
+			"backup on fresh install: %w", err)
+	}
+	if restoredFromBackup {
+		infof("Restored fresh install from encrypted recovery "+
+			"backup %s", restoreResult.BackupFile)
+	} else {
+		_, _, err = staticAddressManager.NewAddress(d.mainCtx)
+		if err != nil {
+			warnf("Unable to initialize static address generation "+
+				"during startup: %v", err)
+		}
+	}
+
+	backupFile, err := startupRecoveryService.WriteBackup(d.mainCtx)
+	if err != nil {
+		warnf("Unable to write startup recovery backup: %v", err)
+	}
+	if backupFile != "" {
+		infof("Wrote encrypted recovery backup to %s after "+
+			"initializing the current L402 generation", backupFile)
+	}
+
+	// Runtime recovery is wired with the deposit manager so explicit
+	// recovery RPCs can reconcile restored static-address deposits.
+	recoveryService = recovery.NewService(
+		d.cfg.DataDir, d.cfg.Network, d.lnd.Signer, d.lnd.WalletKit,
+		staticAddressManager, depositManager,
+	)
+
 	var (
 		reservationManager *reservation.Manager
 		instantOutManager  *instantout.Manager
@@ -769,6 +813,7 @@ func (d *Daemon) initialize(withMacaroonService bool) error {
 		staticLoopInManager:  staticLoopInManager,
 		openChannelManager:   openChannelManager,
 		assetClient:          d.assetClient,
+		recoveryService:      recoveryService,
 		stopDaemon:           d.Stop,
 	}
 

loopd/swapclient_server.go

@@ -29,6 +29,7 @@ import (
 	"github.com/lightninglabs/loop/liquidity"
 	"github.com/lightninglabs/loop/loopdb"
 	"github.com/lightninglabs/loop/looprpc"
+	"github.com/lightninglabs/loop/recovery"
 	"github.com/lightninglabs/loop/staticaddr/address"
 	"github.com/lightninglabs/loop/staticaddr/deposit"
 	"github.com/lightninglabs/loop/staticaddr/loopin"
@@ -101,6 +102,7 @@ type swapClientServer struct {
 	staticLoopInManager  *loopin.Manager
 	openChannelManager   *openchannel.Manager
 	assetClient          *assets.TapdClient
+	recoveryService      *recovery.Service
 	swaps                map[lntypes.Hash]loop.SwapInfo
 	subscribers          map[int]chan<- any
 	statusChan           chan loop.SwapInfo
@@ -1277,6 +1279,32 @@ func (s *swapClientServer) FetchL402Token(ctx context.Context,
 	return &looprpc.FetchL402TokenResponse{}, nil
 }
 
+// Recover restores the local paid L402 token material and static-address state
+// from an encrypted backup file.
+func (s *swapClientServer) Recover(ctx context.Context,
+	req *looprpc.RecoverRequest) (*looprpc.RecoverResponse, error) {
+
+	if s.recoveryService == nil {
+		return nil, status.Error(
+			codes.Unavailable, "recovery service not configured",
+		)
+	}
+
+	result, err := s.recoveryService.Restore(ctx, req.GetBackupFile())
+	if err != nil {
+		return nil, err
+	}
+
+	return &looprpc.RecoverResponse{
+		BackupFile:                 result.BackupFile,
+		RestoredL402:               result.RestoredL402,
+		RestoredStaticAddress:      result.RestoredStaticAddress,
+		StaticAddress:              result.StaticAddress,
+		NumDepositsFound:           uint32(result.NumDepositsFound),
+		DepositReconciliationError: result.DepositReconciliationError,
+	}, nil
+}
+
 // GetInfo returns basic information about the loop daemon and details to swaps
 // from the swap store.
 func (s *swapClientServer) GetInfo(ctx context.Context,
@@ -1646,6 +1674,17 @@ func (s *swapClientServer) NewStaticAddress(ctx context.Context,
 		return nil, err
 	}
 
+	if s.recoveryService != nil {
+		backupFile, backupErr := s.recoveryService.WriteBackup(ctx)
+		if backupErr != nil {
+			warnf("Unable to write recovery backup after static "+
+				"address request: %v", backupErr)
+		} else if backupFile != "" {
+			infof("Wrote encrypted recovery backup to %s after "+
+				"static address request", backupFile)
+		}
+	}
+
 	return &looprpc.NewStaticAddressResponse{
 		Address: staticAddress.String(),
 		Expiry:  uint32(expiry),