Consensys-Incorporated · MqllR · Aug 6, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,10 @@
 # Changelog
 
+## Next release
+### Features Added
+- Bulk loading keys from Azure Key Vault is significantly faster. Secrets and keys are now fetched concurrently, up to a configurable limit, while the vault is still being listed, instead of one 25-item page at a time. New options: `--azure-bulk-load-max-concurrency` (default 20) and `--azure-bulk-load-timeout` (default 900 seconds). Retries for throttled or transient failures are left to the Azure SDK's own default retry policy.
+
+---
 ## 26.7.0
 ### Features Added
 - Support for Hashicorp Vault Kubernetes authentication [PR 1195](https://github.com/Consensys/web3signer/pull/1195)

diff --git a/commandline/build.gradle b/commandline/build.gradle
@@ -16,6 +16,7 @@ dependencies {
 
   implementation project(":common")
   implementation project(":core")
+  implementation project(":keystorage")
   implementation project(":slashing-protection")
   implementation project(":signing")
   implementation 'info.picocli:picocli'

diff --git a/...ine/src/main/java/tech/pegasys/web3signer/commandline/PicoCliAzureKeyVaultParameters.java b/...ine/src/main/java/tech/pegasys/web3signer/commandline/PicoCliAzureKeyVaultParameters.java
@@ -12,9 +12,11 @@
  */
 package tech.pegasys.web3signer.commandline;
 
+import tech.pegasys.web3signer.keystorage.azure.BulkLoadOptions;
 import tech.pegasys.web3signer.signing.config.AzureAuthenticationMode;
 import tech.pegasys.web3signer.signing.config.AzureKeyVaultParameters;
 
+import java.time.Duration;
 import java.util.LinkedHashMap;
 import java.util.Map;
 
@@ -71,6 +73,22 @@ public class PicoCliAzureKeyVaultParameters implements AzureKeyVaultParameters {
       paramLabel = "<AZURE_RESPONSE_TIMEOUT>")
   private long timeout = 60;
 
+  @Option(
+      names = {"--azure-bulk-load-max-concurrency"},
+      description =
+          "Maximum number of concurrent requests to Azure Key Vault during bulk key loading "
+              + "(Default: ${DEFAULT-VALUE})",
+      paramLabel = "<MAX_CONCURRENCY>")
+  private int maxConcurrency = BulkLoadOptions.DEFAULT_MAX_CONCURRENCY;
+
+  @Option(
+      names = {"--azure-bulk-load-timeout"},
+      description =
+          "Overall time budget for bulk loading keys from Azure Key Vault (in seconds). Keys not "
+              + "loaded within it are reported as errors (Default: ${DEFAULT-VALUE})",
+      paramLabel = "<AZURE_BULK_LOAD_TIMEOUT>")
+  private long bulkLoadTimeout = BulkLoadOptions.DEFAULT_DEADLINE.toSeconds();
+
   @CommandLine.Option(
       names = {"--azure-tags"},
       mapFallbackValue = "",
@@ -119,4 +137,9 @@ public long getTimeout() {
   public Map<String, String> getTags() {
     return tags;
   }
+
+  @Override
+  public BulkLoadOptions getBulkLoadOptions() {
+    return new BulkLoadOptions(maxConcurrency, Duration.ofSeconds(bulkLoadTimeout));
+  }
 }
diff --git a/core/src/main/java/tech/pegasys/web3signer/core/Eth1Runner.java b/core/src/main/java/tech/pegasys/web3signer/core/Eth1Runner.java
@@ -183,8 +183,10 @@ private MappedResults<ArtifactSigner> bulkLoadSigners(
 
   private MappedResults<ArtifactSigner> bulkLoadAzureKeys(
       AzureKeyVaultFactory azureKeyVaultFactory, AzureKeyVaultSignerFactory azureSignerFactory) {
-    LOG.info("Bulk loading keys from Azure key vault ... ");
     final AzureKeyVaultParameters azureKeyVaultConfig = eth1Config.getAzureKeyVaultConfig();
+    LOG.info(
+        "Bulk loading keys from Azure key vault (max concurrency: {}) ... ",
+        azureKeyVaultConfig.getBulkLoadOptions().maxConcurrency());
     final AzureKeyVault azureKeyVault =
         azureKeyVaultFactory.createAzureKeyVault(
             azureKeyVaultConfig.getClientId(),

diff --git a/core/src/main/java/tech/pegasys/web3signer/core/Eth2Runner.java b/core/src/main/java/tech/pegasys/web3signer/core/Eth2Runner.java
@@ -220,7 +220,9 @@ private MappedResults<ArtifactSigner> bulkLoadSigners(
       final AzureKeyVaultFactory azureKeyVaultFactory) {
     MappedResults<ArtifactSigner> results = MappedResults.newSetInstance();
     if (azureKeyVaultParameters.isAzureKeyVaultEnabled()) {
-      LOG.info("Bulk loading keys from Azure key vault ... ");
+      LOG.info(
+          "Bulk loading keys from Azure key vault (max concurrency: {}) ... ",
+          azureKeyVaultParameters.getBulkLoadOptions().maxConcurrency());
       /*
        Note: Azure supports 25K bytes per secret. https://learn.microsoft.com/en-us/azure/key-vault/secrets/about-secrets
        Each raw bls private key in hex format is approximately 100 bytes. We should store about 200 or fewer
@@ -373,6 +375,7 @@ final MappedResults<ArtifactSigner> loadAzureSigners(
             return null;
           }
         },
-        azureKeyVaultParameters.getTags());
+        azureKeyVaultParameters.getTags(),
+        azureKeyVaultParameters.getBulkLoadOptions());
   }
 }
diff --git a/keystorage/src/main/java/tech/pegasys/web3signer/keystorage/azure/AzureKeyVault.java b/keystorage/src/main/java/tech/pegasys/web3signer/keystorage/azure/AzureKeyVault.java
@@ -24,12 +24,11 @@
 import java.util.Map;
 import java.util.Optional;
 import java.util.Set;
-import java.util.concurrent.ConcurrentHashMap;
 import java.util.concurrent.ExecutorService;
-import java.util.concurrent.atomic.AtomicInteger;
 import java.util.function.BiFunction;
 import java.util.function.Function;
 import java.util.stream.Collectors;
+import java.util.stream.Stream;
 
 import com.azure.core.credential.AccessToken;
 import com.azure.core.credential.TokenCredential;
@@ -54,17 +53,15 @@
 import com.azure.security.keyvault.secrets.models.SecretProperties;
 import com.google.common.annotations.VisibleForTesting;
 import io.vertx.core.json.JsonObject;
-import org.apache.logging.log4j.LogManager;
-import org.apache.logging.log4j.Logger;
 import org.apache.tuweni.bytes.Bytes;
 
 public class AzureKeyVault {
 
-  private static final Logger LOG = LogManager.getLogger();
   private final TokenCredential tokenCredential;
   private final SecretClient secretClient;
   private final KeyClient keyClient;
   private static final List<String> SCOPE = List.of("https://vault.azure.net/.default");
+
   private final TokenRequestContext tokenRequestContext =
       new TokenRequestContext().setScopes(SCOPE);
 
@@ -182,45 +179,28 @@ public static String constructAzureKeyVaultUrl(final String keyVaultName) {
    *
    * @param mapper The mapper function to transform secret values to type R.
    * @param tags Map of tags. Only secrets which contains all the tags entries are processed.
+   * @param options Concurrency and retry parameters for the load.
    * @return Mapped results containing the converted secrets and error count.
    * @param <R> The result type of mapper function.
    */
   public <R> MappedResults<R> mapSecrets(
-      final BiFunction<String, String, R> mapper, final Map<String, String> tags) {
-    final Set<R> result = ConcurrentHashMap.newKeySet();
-    final AtomicInteger errorCount = new AtomicInteger(0);
-    try {
-      final PagedIterable<SecretProperties> secretsPagedIterable =
-          secretClient.listPropertiesOfSecrets();
-
-      secretsPagedIterable
-          .streamByPage()
-          .forEach(
-              keyPage ->
-                  keyPage.getValue().parallelStream()
-                      .filter(secretProperties -> secretPropertiesPredicate(tags, secretProperties))
-                      .forEach(
-                          sp -> {
-                            try {
-                              final KeyVaultSecret secret = secretClient.getSecret(sp.getName());
-                              final MappedResults<R> multiResult =
-                                  SecretValueMapperUtil.mapSecretValue(
-                                      mapper, sp.getName(), secret.getValue());
-                              result.addAll(multiResult.getValues());
-                              errorCount.addAndGet(multiResult.getErrorCount());
-                            } catch (final Exception e) {
-                              LOG.warn(
-                                  "Failed to map secret '{}' to requested object type.",
-                                  sp.getName());
-                              errorCount.incrementAndGet();
-                            }
-                          }));
-
-    } catch (final Exception e) {
-      LOG.error("Unexpected error during Azure map-secrets", e);
-      errorCount.incrementAndGet();
-    }
-    return MappedResults.newInstance(result, errorCount.intValue());
+      final BiFunction<String, String, R> mapper,
+      final Map<String, String> tags,
+      final BulkLoadOptions options) {
+    // the listing is consumed lazily, so secrets are fetched while later pages are still listed
+    final Stream<SecretProperties> secrets =
+        secretClient.listPropertiesOfSecrets().stream()
+            .filter(sp -> secretPropertiesPredicate(tags, sp));
+
+    return new ConcurrentBulkLoader(options)
+        .load(
+            "Azure secrets bulk load",
+            secrets,
+            SecretProperties::getName,
+            sp -> {
+              final KeyVaultSecret secret = secretClient.getSecret(sp.getName());
+              return SecretValueMapperUtil.mapSecretValue(mapper, sp.getName(), secret.getValue());
+            });
   }
 
   /**
@@ -229,39 +209,24 @@ public <R> MappedResults<R> mapSecrets(
    *
    * @param mapper Mapper function to transform Azure KeyProperties to type R
    * @param tags Map of tags. Only keys which contains all the tags entries are processed.
+   * @param options Concurrency and retry parameters for the load.
    * @return Mapped results containing the converted keys and error count.
    * @param <R> The result type of mapper function.
    */
   public <R> MappedResults<R> mapKeyProperties(
-      final Function<KeyProperties, R> mapper, final Map<String, String> tags) {
-    final Set<R> result = ConcurrentHashMap.newKeySet();
-    final AtomicInteger errorCount = new AtomicInteger(0);
-    try {
-      keyClient
-          .listPropertiesOfKeys()
-          .streamByPage()
-          .forEach(
-              keyPage ->
-                  keyPage.getValue().parallelStream()
-                      .filter(keyProperties -> keyPropertiesPredicate(tags, keyProperties))
-                      .forEach(
-                          kp -> {
-                            try {
-                              final R value = mapper.apply(kp);
-                              result.add(value);
-                            } catch (final Exception e) {
-                              LOG.warn(
-                                  "Failed to map keyProperties '{}' to requested object type.",
-                                  kp.getName());
-                              errorCount.incrementAndGet();
-                            }
-                          }));
-    } catch (final Exception e) {
-      LOG.error("Unexpected error during Azure mapKeyProperties", e);
-      errorCount.incrementAndGet();
-    }
-
-    return MappedResults.newInstance(result, errorCount.intValue());
+      final Function<KeyProperties, R> mapper,
+      final Map<String, String> tags,
+      final BulkLoadOptions options) {
+    // the listing is consumed lazily, so keys are mapped while later pages are still listed
+    final Stream<KeyProperties> keys =
+        keyClient.listPropertiesOfKeys().stream().filter(kp -> keyPropertiesPredicate(tags, kp));
+
+    return new ConcurrentBulkLoader(options)
+        .load(
+            "Azure keys bulk load",
+            keys,
+            KeyProperties::getName,
+            kp -> MappedResults.newInstance(Set.of(mapper.apply(kp)), 0));
   }
 
   /**

diff --git a/keystorage/src/main/java/tech/pegasys/web3signer/keystorage/azure/BulkLoadOptions.java b/keystorage/src/main/java/tech/pegasys/web3signer/keystorage/azure/BulkLoadOptions.java
@@ -0,0 +1,41 @@
+/*
+ * Copyright 2026 ConsenSys AG.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
+ * an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations under the License.
+ */
+package tech.pegasys.web3signer.keystorage.azure;
+
+import java.time.Duration;
+
+import com.google.common.base.Preconditions;
+
+/**
+ * Tuning parameters for a bulk load performed by {@link ConcurrentBulkLoader}.
+ *
+ * @param maxConcurrency upper bound on concurrent requests.
+ * @param deadline overall time budget for the load. Items not loaded within it are reported as
+ *     errors rather than silently dropped.
+ */
+public record BulkLoadOptions(int maxConcurrency, Duration deadline) {
+
+  public static final int DEFAULT_MAX_CONCURRENCY = 20;
+  public static final Duration DEFAULT_DEADLINE = Duration.ofMinutes(15);
+
+  /** Options applied when a caller does not configure bulk loading. */
+  public static final BulkLoadOptions DEFAULT =
+      new BulkLoadOptions(DEFAULT_MAX_CONCURRENCY, DEFAULT_DEADLINE);
+
+  /** Validates the parameters. */
+  public BulkLoadOptions {
+    Preconditions.checkArgument(maxConcurrency > 0, "maxConcurrency must be positive");
+    Preconditions.checkArgument(
+        !deadline.isNegative() && !deadline.isZero(), "deadline must be positive");
+  }
+}