docs: update loop.md

Author: hieblmi

README.md

@@ -64,6 +64,23 @@ To execute a Loop In:
 loop in <amt_in_satoshis>
 ```
 
+### Static Address Recovery
+Loop now keeps one encrypted immutable recovery backup per paid L402
+generation in the active network data directory. Each backup contains the raw
+paid `l402.token` plus the legacy static-address parameters needed to recreate
+the current address locally.
+
+Existing static-address users get this backup backfilled on the next startup
+with the upgraded client. Fresh installs materialize the initial paid-L402 and
+legacy static-address generation during startup so the first backup can be
+written immediately.
+
+The follow-up multi-address work is expected to keep this one-backup-per-L402
+model and extend it with deterministic root metadata for synthetic-xpub /
+BIP328-style address derivation and scanning. 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)

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 uses the most recent immutable L402 backup file path
+
+.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 will use the most recent immutable network-specific L402 backup file.
+
+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 uses the most recent immutable L402 backup file path | 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:
 

staticaddr/deposit/manager.go

@@ -171,6 +171,20 @@ func (m *Manager) recoverDeposits(ctx context.Context) error {
 
 	log.Infof("Recovering static address parameters and deposits...")
 
+	// Deposits that are still in the plain Deposited state must remain
+	// unspent across a restart. Other active states may have already spent
+	// the deposit and rely on their owning managers to finish recovery.
+	utxos, err := m.cfg.AddressManager.ListUnspent(ctx, 0, 0)
+	if err != nil {
+		return fmt.Errorf("unable to list unspent deposits for "+
+			"recovery: %w", err)
+	}
+
+	unspentOutpoints := make(map[wire.OutPoint]struct{}, len(utxos))
+	for _, utxo := range utxos {
+		unspentOutpoints[utxo.OutPoint] = struct{}{}
+	}
+
 	// Recover deposits.
 	deposits, err := m.cfg.Store.AllDeposits(ctx)
 	if err != nil {
@@ -187,6 +201,15 @@ func (m *Manager) recoverDeposits(ctx context.Context) error {
 			continue
 		}
 
+		if d.GetState() == Deposited {
+			if _, ok := unspentOutpoints[d.OutPoint]; !ok {
+				log.Warnf("Skipping recovery of spent deposited "+
+					"outpoint %v", d.OutPoint)
+
+				continue
+			}
+		}
+
 		log.Debugf("Recovering deposit %x", d.ID)
 
 		// Create a state machine for a given deposit.

staticaddr/deposit/manager_test.go

@@ -304,6 +304,66 @@ func TestManager(t *testing.T) {
 	}
 }
 
+func TestRecoverDepositsSkipsSpentDeposited(t *testing.T) {
+	ctx := context.Background()
+
+	id, err := GetRandomDepositID()
+	require.NoError(t, err)
+
+	storedDeposit := &Deposit{
+		ID: id,
+		OutPoint: wire.OutPoint{
+			Hash:  chainhash.Hash{1},
+			Index: 1,
+		},
+		state:              Deposited,
+		Value:              btcutil.Amount(100000),
+		ConfirmationHeight: 42,
+	}
+
+	testContext := newManagerTestContextWithStoredDeposits(
+		t, []*Deposit{storedDeposit}, nil,
+	)
+
+	err = testContext.manager.recoverDeposits(ctx)
+	require.NoError(t, err)
+	require.Empty(t, testContext.manager.activeDeposits)
+
+	deposits, err := testContext.manager.GetActiveDepositsInState(Deposited)
+	require.NoError(t, err)
+	require.Empty(t, deposits)
+}
+
+func TestRecoverDepositsKeepsSpentWithdrawing(t *testing.T) {
+	ctx := context.Background()
+
+	id, err := GetRandomDepositID()
+	require.NoError(t, err)
+
+	storedDeposit := &Deposit{
+		ID: id,
+		OutPoint: wire.OutPoint{
+			Hash:  chainhash.Hash{2},
+			Index: 2,
+		},
+		state:              Withdrawing,
+		Value:              btcutil.Amount(100000),
+		ConfirmationHeight: 42,
+	}
+
+	testContext := newManagerTestContextWithStoredDeposits(
+		t, []*Deposit{storedDeposit}, nil,
+	)
+
+	err = testContext.manager.recoverDeposits(ctx)
+	require.NoError(t, err)
+
+	deposits, err := testContext.manager.GetActiveDepositsInState(Withdrawing)
+	require.NoError(t, err)
+	require.Len(t, deposits, 1)
+	require.Equal(t, storedDeposit.OutPoint, deposits[0].OutPoint)
+}
+
 // ManagerTestContext is a helper struct that contains all the necessary
 // components to test the reservation manager.
 type ManagerTestContext struct {
@@ -320,19 +380,9 @@ type ManagerTestContext struct {
 
 // newManagerTestContext creates a new test context for the reservation manager.
 func newManagerTestContext(t *testing.T) *ManagerTestContext {
-	mockLnd := test.NewMockLnd()
-	lndContext := test.NewContext(t, mockLnd)
-
-	mockStaticAddressClient := new(mockStaticAddressClient)
-	mockAddressManager := new(mockAddressManager)
-	mockStore := new(mockStore)
-	mockChainNotifier := new(MockChainNotifier)
-	confChan := make(chan *chainntnfs.TxConfirmation)
-	confErrChan := make(chan error)
-	blockChan := make(chan int32)
-	blockErrChan := make(chan error)
-
 	ID, err := GetRandomDepositID()
+	require.NoError(t, err)
+
 	utxo := &lnwallet.Utxo{
 		AddressType:   lnwallet.TaprootPubkey,
 		Value:         btcutil.Amount(100000),
@@ -343,7 +393,7 @@ func newManagerTestContext(t *testing.T) *ManagerTestContext {
 			Index: 0xffffffff,
 		},
 	}
-	require.NoError(t, err)
+
 	storedDeposits := []*Deposit{
 		{
 			ID:                   ID,
@@ -355,6 +405,26 @@ func newManagerTestContext(t *testing.T) *ManagerTestContext {
 		},
 	}
 
+	return newManagerTestContextWithStoredDeposits(
+		t, storedDeposits, []*lnwallet.Utxo{utxo},
+	)
+}
+
+func newManagerTestContextWithStoredDeposits(t *testing.T,
+	storedDeposits []*Deposit, utxos []*lnwallet.Utxo) *ManagerTestContext {
+
+	mockLnd := test.NewMockLnd()
+	lndContext := test.NewContext(t, mockLnd)
+
+	mockStaticAddressClient := new(mockStaticAddressClient)
+	mockAddressManager := new(mockAddressManager)
+	mockStore := new(mockStore)
+	mockChainNotifier := new(MockChainNotifier)
+	confChan := make(chan *chainntnfs.TxConfirmation)
+	confErrChan := make(chan error)
+	blockChan := make(chan int32)
+	blockErrChan := make(chan error)
+
 	mockStore.On(
 		"AllDeposits", mock.Anything,
 	).Return(storedDeposits, nil)
@@ -371,7 +441,7 @@ func newManagerTestContext(t *testing.T) *ManagerTestContext {
 
 	mockAddressManager.On(
 		"ListUnspent", mock.Anything, mock.Anything, mock.Anything,
-	).Return([]*lnwallet.Utxo{utxo}, nil)
+	).Return(utxos, nil)
 
 	// Define the expected return values for the mocks.
 	mockChainNotifier.On(