Wallet rotation safety (integration preview): eager forfeit + multi-wallet sweeps + signer-key-per-leaf

README.md

@@ -81,12 +81,13 @@ The `arkd` server can be configured using environment variables and the admin se
 | `ARKD_REDIS_NUM_OF_RETRIES`         | Maximum number of retries for Redis write operations in case of conflicts       | -                              |
 | `ARKD_ESPLORA_URL`                  | Esplora API URL                                                                 | `https://blockstream.info/api` |
 | `ARKD_WALLET_ADDR`                  | The arkd wallet address to connect to in the form `host:port`                   | -                              |
+| `ARKD_WALLET_FALLBACK_ADDRS`        | Additional arkd-wallet addresses (other LPs), comma-separated `host:port` list   | -                              |
 | `ARKD_SIGNER_ADDR`                  | The signer address to connect to in the form `host:port`                        | value of `ARKD_WALLET_ADDR`    |
 | `ARKD_NO_MACAROONS`                 | Disable macaroon authentication                                                 | `false`                        |
 | `ARKD_NO_TLS`                       | Disable TLS                                                                     | `true`                         |
-| `ARKD_UNLOCKER_TYPE`                | Wallet unlocker type (env, file) to enable auto-unlock                          | -                              |
+| `ARKD_UNLOCKER_TYPE`                | Macaroon (admin auth) unlocker type (env, file) to enable auto-unlock           | -                              |
 | `ARKD_UNLOCKER_FILE_PATH`           | Path to unlocker file                                                           | -                              |
-| `ARKD_UNLOCKER_PASSWORD`            | Wallet unlocker password                                                        | -                              |
+| `ARKD_UNLOCKER_PASSWORD`            | Macaroon (admin auth) unlocker password                                         | -                              |
 | `ARKD_SCHEDULER_TYPE`              | Scheduler type (gocron, block)                                                 | `gocron`                       |
 | `ARKD_TLS_EXTRA_IP`                | Extra IP addresses for TLS (comma-separated)                                   | -                              |
 | `ARKD_TLS_EXTRA_DOMAIN`            | Extra domains for TLS (comma-separated)                                         | -                              |
@@ -180,6 +181,16 @@ To connect `arkd` to `arkd-wallet` use this environment variable:
 export ARKD_WALLET_ADDR=localhost:6060
 ```
 
+### Configuring multiple LP wallets
+
+`arkd` can be backed by a primary `arkd-wallet` plus additional wallets belonging to other liquidity providers. List the additional wallets with `ARKD_WALLET_FALLBACK_ADDRS`, a comma-separated list of `host:port` addresses:
+
+```sh
+export ARKD_WALLET_FALLBACK_ADDRS=localhost:6061,localhost:6062
+```
+
+Every wallet, primary and fallback, must be initialized and unlocked out of band (see [Setup arkd](#setup-arkd)) and must be on the same network as the primary; `arkd` validates this at startup and refuses to start otherwise. The primary wallet remains the sole source of the forfeit address, connector address, scanning and signing. The additional wallets are used only as sweep fallbacks: when a batch cannot be signed by the primary wallet (for example a batch created before this wallet became the primary), `arkd` tries each fallback wallet in turn until one can sign it. The swept funds always go to the primary wallet's address, whichever wallet signs.
+
 ### Connect to signer
 
 By default, `arkd` makes use of the provided `arkd-wallet` also as signer, but you can customize its url either via environment variable or via API.
@@ -195,26 +206,31 @@ export ARKD_SIGNER_ADDR=localhost:7071
 
 ### Setup arkd
 
+`arkd` does not manage the wallet lifecycle. Each `arkd-wallet` must be initialized and unlocked out of band before `arkd` is started: if the wallet is not initialized and unlocked, `arkd` refuses to start. This is what lets a single `arkd` be backed by more than one `arkd-wallet`.
+
 1. Start the wallet:
    ```sh
    arkd-wallet
    ```
 
-2. Start arkd:
+2. Initialize and unlock the wallet. `arkd` does not manage the wallet lifecycle, so this is done out of band against the `arkd-wallet`:
    ```sh
-   arkd
+   # Create a new wallet and unlock it (prints the seed, back it up)
+   arkd-wallet create --password <password>
    ```
 
-3. Create a new wallet:
+   Or restore from mnemonic:
    ```sh
-   arkd wallet create --password <password>
+   arkd-wallet create --mnemonic "your twelve word mnemonic phrase here" --password <password>
    ```
+   By default these target `http://localhost:6060`; use `--url` to reach a wallet on another host. This wallet password is independent of the macaroon-service password used in step 5. After a wallet restart, unlock it again with `arkd-wallet unlock --password <password>`.
 
-   Or restore from mnemonic:
+3. Start arkd:
    ```sh
-   arkd wallet create --mnemonic "your twelve word mnemonic phrase here" --password <password>
+   arkd
    ```
-4. Only if you didn't configure either the wallet as signer, or a custom signer, you must load the signer before unlocking the wallet, or `arkd` will fail to start:
+
+4. Only if you didn't configure either the wallet as signer, or a custom signer, you must load the signer, or `arkd` will be unable to start the ark service:
    ```sh
    # If you configured a custom signer
    arkd signer load --signer-url localhost:7071
@@ -223,7 +239,7 @@ export ARKD_SIGNER_ADDR=localhost:7071
    ```
    Remember, if you use this command, you must use it at every restart unless you export the required environment variable(s).
 
-5. Unlock the wallet:
+5. If macaroon authentication is enabled and you did not configure an auto-unlocker, unlock the macaroon (admin auth) service so `arkd` can serve authenticated admin requests:
    ```sh
    arkd wallet unlock --password <password>
    ```

api-spec/openapi/swagger/ark/v1/admin.openapi.json

@@ -2145,6 +2145,19 @@
               "null"
             ],
             "format": "int64"
+          },
+          "walletAddr": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "Primary and fallback arkd-wallet connection addresses. Seeded from env on\nfirst boot; changes take effect on the next restart."
+          },
+          "walletFallbackAddrs": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
           }
         }
       },

api-spec/protobuf/ark/v1/admin.proto

@@ -447,6 +447,8 @@ message Settings {
   optional bool build_version_header_required = 23;
   optional string updated_at = 24;
   optional bool digest_header_required = 25;
+  optional string wallet_addr = 26;
+  repeated string wallet_fallback_addrs = 27;
 }
 
 message GetSettingsRequest {}

cmd/arkd-forfeit-backfill/main.go

@@ -0,0 +1,54 @@
+// Command arkd-forfeit-backfill signs the operator's half of forfeit transactions
+// that were persisted before arkd started signing forfeit txs at collection time.
+//
+// It connects to the same database and signer as arkd (via the standard arkd
+// configuration / environment), so the arkd-wallet signer must be running and
+// unlocked. It scans every unswept forfeited vtxo, signs the operator's half of
+// its forfeit tx when missing, and persists the result. It is safe to run
+// repeatedly: forfeit txs that already carry the operator signature are skipped.
+package main
+
+import (
+	"context"
+	"os"
+
+	"github.com/arkade-os/arkd/internal/backfill"
+	"github.com/arkade-os/arkd/internal/config"
+	log "github.com/sirupsen/logrus"
+)
+
+func main() {
+	cfg, err := config.LoadConfig()
+	if err != nil {
+		log.Fatalf("invalid config: %s", err)
+	}
+	log.SetLevel(log.Level(cfg.LogLevel))
+
+	repo, err := cfg.RepoManager()
+	if err != nil {
+		log.Fatalf("failed to init repositories: %s", err)
+	}
+	defer repo.Close()
+
+	signer, err := cfg.SignerService()
+	if err != nil {
+		log.Fatalf("failed to init signer: %s", err)
+	}
+
+	log.Info("starting forfeit-tx backfill...")
+	res, err := backfill.Run(context.Background(), repo.Vtxos(), repo.Rounds(), signer)
+	if err != nil {
+		log.Fatalf("forfeit-tx backfill failed: %s", err)
+	}
+
+	log.Infof(
+		"forfeit-tx backfill done: scanned=%d signed=%d already_signed=%d failed=%d",
+		res.Scanned, res.Signed, res.AlreadySigned, res.Failed,
+	)
+
+	// Non-zero exit when some forfeits could not be signed/persisted, so the
+	// operator (or a wrapping script) notices and re-runs after fixing the cause.
+	if res.Failed > 0 {
+		os.Exit(1)
+	}
+}