loop: add manual static deposit recovery

Add recoverdeposit CLI/RPC support for verifying one static-address output on-chain, matching it to a derived static address, restoring the address/import, and directly creating or reactivating the deposit row.

Author: hieblmi

cmd/loop/main.go

@@ -89,6 +89,7 @@ var (
 		listSwapsCommand, swapInfoCommand, getLiquidityParamsCommand,
 		setLiquidityRuleCommand, suggestSwapCommand, setParamsCommand,
 		getInfoCommand, abandonSwapCommand, recoverCommand,
+		recoverDepositCommand,
 		reservationsCommands,
 		instantOutCommand, listInstantOutsCommand, stopCommand,
 		printManCommand, printMarkdownCommand,

cmd/loop/recover.go

@@ -25,6 +25,37 @@ var recoverCommand = &cli.Command{
 	Action: runRecover,
 }
 
+var recoverDepositCommand = &cli.Command{
+	Name:  "recoverdeposit",
+	Usage: "recover one static address deposit from on-chain data",
+	Description: "Verifies the provided transaction output on-chain, " +
+		"restores the matching static address, stores the deposit, and " +
+		"starts normal deposit tracking.",
+	Flags: []cli.Flag{
+		&cli.StringFlag{
+			Name:     "txid",
+			Usage:    "transaction ID containing the deposit output",
+			Required: true,
+		},
+		&cli.UintFlag{
+			Name:     "vout",
+			Usage:    "deposit output index",
+			Required: true,
+		},
+		&cli.IntFlag{
+			Name:     "height_hint",
+			Usage:    "block height hint for the deposit transaction",
+			Required: true,
+		},
+		&cli.StringFlag{
+			Name:     "pkscript_hex",
+			Usage:    "expected static address P2TR pkScript in hex",
+			Required: true,
+		},
+	},
+	Action: runRecoverDeposit,
+}
+
 func runRecover(ctx context.Context, cmd *cli.Command) error {
 	if cmd.NArg() > 0 {
 		return showCommandHelp(ctx, cmd)
@@ -48,3 +79,32 @@ func runRecover(ctx context.Context, cmd *cli.Command) error {
 	printRespJSON(resp)
 	return nil
 }
+
+// runRecoverDeposit calls the daemon to manually recover one static-address
+// deposit from caller-supplied on-chain coordinates.
+func runRecoverDeposit(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.RecoverDeposit(
+		ctx, &looprpc.RecoverDepositRequest{
+			Txid:        cmd.String("txid"),
+			Vout:        uint32(cmd.Uint("vout")),
+			HeightHint:  int32(cmd.Int("height_hint")),
+			PkscriptHex: cmd.String("pkscript_hex"),
+		},
+	)
+	if err != nil {
+		return err
+	}
+
+	printRespJSON(resp)
+	return nil
+}

docs/loop.1

@@ -413,6 +413,25 @@ restore static address and L402 state from a local backup file
 .PP
 \fB--help, -h\fP: show help
 
+.SH recoverdeposit
+.PP
+recover one static address deposit from on-chain data
+
+.PP
+\fB--height_hint\fP="": block height hint for the deposit transaction (default: 0)
+
+.PP
+\fB--help, -h\fP: show help
+
+.PP
+\fB--pkscript_hex\fP="": expected static address P2TR pkScript in hex
+
+.PP
+\fB--txid\fP="": transaction ID containing the deposit output
+
+.PP
+\fB--vout\fP="": deposit output index (default: 0)
+
 .SH reservations, r
 .PP
 manage reservations
@@ -699,4 +718,3 @@ Open a channel to a an existing peer.
 
 .PP
 \fB--zero_conf\fP: (optional) whether a zero-conf channel open should be attempted.
-

docs/loop.md

@@ -437,6 +437,28 @@ The following flags are supported:
 | `--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`    |
 
+### `recoverdeposit` command
+
+recover one static address deposit from on-chain data.
+
+Verifies the provided transaction output on-chain, restores the matching static address, stores the deposit, and starts normal deposit tracking.
+
+Usage:
+
+```bash
+$ loop [GLOBAL FLAGS] recoverdeposit [COMMAND FLAGS] [ARGUMENTS...]
+```
+
+The following flags are supported:
+
+| Name                 | Description                                                            | Type   | Default value |
+|----------------------|------------------------------------------------------------------------|--------|:-------------:|
+| `--txid="…"`         | transaction ID containing the deposit output                           | string |
+| `--vout="…"`         | deposit output index                                                   | uint   |      `0`      |
+| `--height_hint="…"`  | block height hint for the deposit transaction                          | int    |      `0`      |
+| `--pkscript_hex="…"` | expected static address P2TR pkScript in hex                           | string |
+| `--help` (`-h`)      | show help                                                              | bool   |    `false`    |
+
 ### `reservations` command (aliases: `r`)
 
 manage reservations.
@@ -768,4 +790,3 @@ The following flags are supported:
 | `--fundmax`                             | if set, the wallet will attempt to commit the maximum possible local amount to the channel. This must not be set at the same time as local_amt                                                                                                                                                                        | bool   |    `false`    |
 | `--utxo="…"`                            | a utxo specified as outpoint(tx:idx) which will be used to fund a channel. This flag can be repeatedly used to fund a channel with a selection of utxos. The selected funds can either be entirely spent by specifying the fundmax flag or partially by selecting a fraction of the sum of the outpoints in local_amt | string |     `[]`      |
 | `--help` (`-h`)                         | show help                                                                                                                                                                                                                                                                                                             | bool   |    `false`    |
-

loopd/swapclient_server.go

@@ -1297,6 +1297,43 @@ func (s *swapClientServer) Recover(ctx context.Context,
 	}, nil
 }
 
+// RecoverDeposit verifies and restores one static-address deposit from
+// caller-supplied on-chain coordinates.
+func (s *swapClientServer) RecoverDeposit(ctx context.Context,
+	req *looprpc.RecoverDepositRequest) (*looprpc.RecoverDepositResponse,
+	error) {
+
+	if s.recoveryService == nil {
+		return nil, status.Error(
+			codes.Unavailable, "recovery service not configured",
+		)
+	}
+
+	result, err := s.recoveryService.RecoverDeposit(
+		ctx, &recovery.RecoverDepositRequest{
+			TxID:        req.GetTxid(),
+			VOut:        req.GetVout(),
+			HeightHint:  req.GetHeightHint(),
+			PkScriptHex: req.GetPkscriptHex(),
+		},
+	)
+	if err != nil {
+		return nil, err
+	}
+
+	return &looprpc.RecoverDepositResponse{
+		Outpoint:           result.OutPoint,
+		Value:              int64(result.Value),
+		ConfirmationHeight: result.ConfirmationHeight,
+		ClientKeyFamily:    result.ClientKeyFamily,
+		ClientKeyIndex:     result.ClientKeyIndex,
+		StaticAddress:      result.StaticAddress,
+		RecoveredAddress:   result.RecoveredAddress,
+		RecoveredDeposit:   result.RecoveredDeposit,
+		DepositId:          result.DepositID,
+	}, nil
+}
+
 // GetInfo returns basic information about the loop daemon and details to swaps
 // from the swap store.
 func (s *swapClientServer) GetInfo(ctx context.Context,

loopd/swapclient_server_staticaddr_test.go

@@ -34,6 +34,14 @@ func (s *staticAddrDepositStore) UpdateDeposit(context.Context,
 	return nil
 }
 
+// UpdateRecoveredDeposit satisfies deposit.Store for static-address server
+// tests that do not exercise manual recovery persistence.
+func (s *staticAddrDepositStore) UpdateRecoveredDeposit(context.Context,
+	*deposit.Deposit) error {
+
+	return nil
+}
+
 func (s *staticAddrDepositStore) GetDeposit(context.Context,
 	deposit.ID) (*deposit.Deposit, error) {
 

loopd/swapclient_server_test.go

@@ -1019,6 +1019,14 @@ func (s *mockDepositStore) UpdateDeposit(_ context.Context,
 	return nil
 }
 
+// UpdateRecoveredDeposit satisfies deposit.Store for server tests that only
+// need outpoint lookups.
+func (s *mockDepositStore) UpdateRecoveredDeposit(_ context.Context,
+	_ *deposit.Deposit) error {
+
+	return nil
+}
+
 func (s *mockDepositStore) GetDeposit(_ context.Context,
 	_ deposit.ID) (*deposit.Deposit, error) {
 

loopdb/sqlc/querier.go

@@ -32,6 +32,18 @@ SET
 WHERE
     deposits.deposit_id = $1;
 
+-- name: UpdateRecoveredDeposit :exec
+UPDATE deposits
+SET
+    tx_hash = $2,
+    out_index = $3,
+    amount = $4,
+    confirmation_height = $5,
+    timeout_sweep_pk_script = $6,
+    static_address_id = $7
+WHERE
+    deposits.deposit_id = $1;
+
 -- name: InsertDepositUpdate :exec
 INSERT INTO deposit_updates (
     deposit_id,