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

@@ -97,7 +97,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"
 	"github.com/lightningnetwork/lnd"
@@ -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{},
@@ -846,8 +849,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 " +

cmd/loop/testdata/sessions/static-loop-in/01_loop-static-new.json

@@ -13,13 +13,36 @@
     "clock_start_unix": 1769407086
   },
   "events": [
+    {
+      "time_ms": 1,
+      "kind": "grpc",
+      "data": {
+        "method": "/looprpc.SwapClient/GetStaticAddressSummary",
+        "event": "request",
+        "message_type": "looprpc.StaticAddressSummaryRequest",
+        "payload": {}
+      }
+    },
+    {
+      "time_ms": 1,
+      "kind": "grpc",
+      "data": {
+        "method": "/looprpc.SwapClient/GetStaticAddressSummary",
+        "event": "error",
+        "error": "rpc error: code = Unknown desc = no static address parameters found",
+        "status": {
+          "code": 2,
+          "message": "no static address parameters found"
+        }
+      }
+    },
     {
       "time_ms": 1,
       "kind": "stdout",
       "data": {
         "lines": [
           "\n",
-          "WARNING: Be aware that loosing 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 expires and your loop client sweeps the funds back to your lnd wallet. The deposit expiry could be months in the future.\n",
+          "WARNING: 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 expires and your loop client sweeps the funds back to your lnd wallet. The deposit expiry could be months in the future.\n",
           "\n",
           "CONTINUE WITH NEW ADDRESS? (y/n): "
         ]

cmd/loop/testdata/sessions/static-loop-in/04_loop-static.json

@@ -24,7 +24,7 @@
           "   loop static [command [command options]]\n",
           "\n",
           "COMMANDS:\n",
-          "   new, n           Create a new static loop in address.\n",
+          "   new, n           Return the static loop in address.\n",
           "   listunspent, l   List unspent static address outputs.\n",
           "   listdeposits     Displays static address deposits. A filter can be applied to only show deposits in a specific state.\n",
           "   listwithdrawals  Display a summary of past withdrawals.\n",

docs/loop.1

@@ -396,6 +396,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
@@ -449,7 +459,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

@@ -419,6 +419,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.
@@ -530,9 +549,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

@@ -191,7 +191,7 @@ 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.47.0 // indirect
+	golang.org/x/crypto v0.47.0
 	golang.org/x/exp v0.0.0-20250811191247-51f88131bc50 // indirect
 	golang.org/x/mod v0.31.0 // indirect
 	golang.org/x/net v0.49.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"
@@ -618,13 +619,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,
@@ -726,6 +730,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
@@ -794,6 +838,7 @@ func (d *Daemon) initialize(withMacaroonService bool) error {
 		staticLoopInManager:  staticLoopInManager,
 		openChannelManager:   openChannelManager,
 		assetClient:          d.assetClient,
+		recoveryService:      recoveryService,
 		stopDaemon:           d.Stop,
 	}