aere-network/aere-node
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
bc8dc80946
aere-node/patches/0003-aere-pq-anchor.patch

43933 lines
2.0 MiB
Raw Blame History

From 65a97c099634691fed1c2ee619b74b5cf0254739 Mon Sep 17 00:00:00 2001
From: Aere Network <node@aere.network>
Date: Thu, 10 Sep 2026 21:47:55 +0300
Subject: [PATCH] Aere Network: post-quantum certificate anchor for QBFT
Regenerated 2026-09-10 from the production tree (overlay applied) over the same file set.
diff --git a/app/src/main/java/org/hyperledger/besu/cli/BesuCommand.java b/app/src/main/java/org/hyperledger/besu/cli/BesuCommand.java
index 2767db2eb..df19c1dd2 100644
--- a/app/src/main/java/org/hyperledger/besu/cli/BesuCommand.java
+++ b/app/src/main/java/org/hyperledger/besu/cli/BesuCommand.java
@@ -11,6 +11,12 @@
* specific language governing permissions and limitations under the License.
*
* SPDX-License-Identifier: Apache-2.0
+ *
+ * Modifications Copyright contributors to the Aere Network.
+ *
+ * This file was modified by contributors to the Aere Network, as required by section 4(b) of the
+ * Apache License 2.0. The copyright header above is the upstream one and is left exactly as it was
+ * found, as section 4(c) requires. The change itself is in patches/0003-aere-pq-anchor.patch.
*/
package org.hyperledger.besu.cli;
@@ -41,6 +47,7 @@ import org.hyperledger.besu.cli.config.ProfilesCompletionCandidates;
import org.hyperledger.besu.cli.custom.JsonRPCAllowlistHostsProperty;
import org.hyperledger.besu.cli.error.BesuExecutionExceptionHandler;
import org.hyperledger.besu.cli.error.BesuParameterExceptionHandler;
+import org.hyperledger.besu.cli.options.AerePqEmergencyOptions;
import org.hyperledger.besu.cli.options.ApiConfigurationOptions;
import org.hyperledger.besu.cli.options.BalConfigurationOptions;
import org.hyperledger.besu.cli.options.ChainPruningOptions;
@@ -299,6 +306,13 @@ public class BesuCommand implements DefaultCommandValues, Runnable {
private final ChainPruningOptions unstableChainPruningOptions = ChainPruningOptions.create();
private final QBFTOptions unstableQbftOptions = QBFTOptions.create();
+ /**
+ * AERE OPTIUNI-URGENTA (2026-08-02): the three post-quantum emergency controls, so that standing
+ * the anchor down is a RESTART and not a rebuild. See {@link AerePqEmergencyOptions}.
+ */
+ private final AerePqEmergencyOptions unstableAerePqEmergencyOptions =
+ AerePqEmergencyOptions.create();
+
// stable CLI options
final DataStorageOptions dataStorageOptions = DataStorageOptions.create();
private final EthstatsOptions ethstatsOptions = EthstatsOptions.create();
@@ -950,6 +964,13 @@ public class BesuCommand implements DefaultCommandValues, Runnable {
logger.info("Starting Besu");
+ // AERE OPTIUNI-URGENTA (2026-08-02): apply the post-quantum emergency controls FIRST, before
+ // anything that reads them. FalconSealSupport runs its guards in its constructor and
+ // PqAnchorConfig is resolved while the protocol schedule is assembled, both of which happen
+ // inside buildController() further down. This is also the earliest point at which logging is
+ // configured, so the banner lands where an operator will see it.
+ unstableAerePqEmergencyOptions.applyAndAnnounce();
+
// set merge config on the basis of genesis config
setMergeConfigOptions();
@@ -1243,6 +1264,9 @@ public class BesuCommand implements DefaultCommandValues, Runnable {
.put("IPC Options", unstableIpcOptions)
.put("Chain Data Pruning Options", unstableChainPruningOptions)
.put("QBFT Options", unstableQbftOptions)
+ // AERE OPTIUNI-URGENTA: registered here so `besu --Xhelp` LISTS them. An emergency
+ // control nobody can find at three in the morning is not a control.
+ .put("AERE post-quantum emergency controls", unstableAerePqEmergencyOptions)
.build();
UnstableOptionsSubCommand.createUnstableOptions(commandLine, unstableOptions);
diff --git a/app/src/main/java/org/hyperledger/besu/cli/options/AerePqEmergencyOptions.java b/app/src/main/java/org/hyperledger/besu/cli/options/AerePqEmergencyOptions.java
new file mode 100755
index 000000000..509c81f73
--- /dev/null
+++ b/app/src/main/java/org/hyperledger/besu/cli/options/AerePqEmergencyOptions.java
@@ -0,0 +1,244 @@
+/*
+ * Copyright contributors to Besu / AERE Network.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.cli.options;
+
+import org.hyperledger.besu.consensus.common.bft.FalconSealSupport;
+import org.hyperledger.besu.consensus.common.bft.PqAnchorConfig;
+
+import java.util.ArrayList;
+import java.util.List;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import picocli.CommandLine;
+
+/**
+ * AERE OPTIUNI-URGENTA (2026-08-02): the three emergency controls for the post-quantum certificate
+ * anchor, as COMMAND-LINE OPTIONS.
+ *
+ * <p><b>The requirement, in one sentence: there has to be a way back that does not need a build.</b>
+ * If the anchor misbehaves on the live chain at three in the morning, the person on the other end of
+ * the page has to be able to stand it down with a RESTART. Until this class existed the controls
+ * were real but reachable only as system properties and environment variables, which in practice
+ * means editing a systemd unit or a wrapper script on seven machines under time pressure, in a file
+ * whose syntax nobody remembers, with no {@code --help} to check against. Two of these options were
+ * already named in the javadoc of {@code PqAnchorConfig} as though they existed. They did not.
+ *
+ * <p><b>The three controls, and why exactly these three.</b>
+ *
+ * <ul>
+ * <li>{@code --Xaere-pq-anchor-disarm} switches both anchor rules off on this node. This is the
+ * blunt instrument, and it is the one to reach for when the anchor itself is rejecting
+ * headers the fleet agrees are good.
+ * <li>{@code --Xaere-pq-anchor-min-seals-max} caps the seal threshold K. It can only ever LOWER
+ * it: the effective threshold is {@code min(scheduled, ceiling)}. A control that could raise K
+ * would be a way to halt a chain, not a way to restart one, so it is not offered. This is the
+ * one to reach for when the chain has stalled because proposers cannot gather K seals - too
+ * many validators down, a key rotation half-done - and the rest of the scheme is fine.
+ * <li>{@code --Xaere-pq-registry-mismatch-allow} lets a node START and KEEP RUNNING with a Falcon
+ * registry that does not satisfy what genesis requires. This is the way back from the A8
+ * guard, which is a CONFIGURATION guard: one wrong byte in a registry file pushed to the fleet
+ * stops every node it reached, for a reason that has nothing to do with whether the blocks are
+ * valid.
+ * </ul>
+ *
+ * <p><b>Every one of them shouts.</b> A quiet way out is worse than no way out, because it will be
+ * set once in an emergency and found six months later on a fleet everybody believed was enforcing
+ * something. So each control that is IN FORCE costs one complete ERROR line at EVERY height, for as
+ * long as the node runs: see {@code PqEmergencyShoutRule} and {@code
+ * FalconSealSupport.shoutRegistryOverrideUnsafe}. Nothing is emitted when nothing is overridden, so
+ * a clean log is a measurable statement and not an absence of instrumentation.
+ *
+ * <p><b>How they take effect, and why through the properties.</b> Each option writes the SAME system
+ * property the control has always read, before anything reads it. That is deliberate: it leaves
+ * exactly one place where each decision is made, so the command line cannot mean something subtly
+ * different from the environment variable, and the code that was measured under A8 and under the
+ * anchor work is the code still doing the deciding. Precedence is command line, then system
+ * property, then environment variable; which source won is written into the log so an operator never
+ * has to guess whether the flag took.
+ *
+ * <p><b>Deliberately LOCAL, not on-chain.</b> A halted chain cannot deliver a height-scheduled
+ * configuration change. The only control that works when the chain is ALREADY STOPPED is one that
+ * lives in the node's own start-up and takes effect on restart, and restarting a quorum of nodes is
+ * the right price for a change of this weight.
+ */
+public class AerePqEmergencyOptions {
+
+ private static final Logger LOG = LoggerFactory.getLogger(AerePqEmergencyOptions.class);
+
+ /** The stable log code for the startup banner listing every override in force. */
+ public static final String BANNER_CODE = "AERE-PQC-EMG-BANNER-01";
+
+ /** Default constructor. */
+ private AerePqEmergencyOptions() {}
+
+ /**
+ * Create a new instance.
+ *
+ * @return a new instance
+ */
+ public static AerePqEmergencyOptions create() {
+ return new AerePqEmergencyOptions();
+ }
+
+ @CommandLine.Option(
+ names = {"--Xaere-pq-anchor-disarm"},
+ description =
+ "AERE EMERGENCY. Switch the post-quantum certificate anchor rules OFF on this node. Takes "
+ + "effect on restart, needs no rebuild, and makes this node log one ERROR line per "
+ + "block for as long as it is set. Recovery setting only. (default: ${DEFAULT-VALUE})",
+ arity = "0..1",
+ fallbackValue = "true",
+ paramLabel = "<true|false>",
+ hidden = true)
+ private Boolean anchorDisarm = null;
+
+ @CommandLine.Option(
+ names = {"--Xaere-pq-anchor-min-seals-max"},
+ description =
+ "AERE EMERGENCY. Cap the post-quantum seal threshold K at this value. It can only LOWER "
+ + "the scheduled threshold, never raise it. Use when the chain has stalled because "
+ + "proposers cannot gather K seals. Logs one ERROR line per block while it is "
+ + "actually lowering something. (default: ${DEFAULT-VALUE})",
+ paramLabel = "<integer>",
+ hidden = true)
+ private Integer minSealsMax = null;
+
+ @CommandLine.Option(
+ names = {"--Xaere-pq-registry-mismatch-allow"},
+ description =
+ "AERE EMERGENCY. Start and keep running even though this node's Falcon registry does not "
+ + "satisfy the binding genesis requires. The node then does NOT verify post-quantum "
+ + "certificates and says so at every height. Recovery setting only. (default: "
+ + "${DEFAULT-VALUE})",
+ arity = "0..1",
+ fallbackValue = "true",
+ paramLabel = "<true|false>",
+ hidden = true)
+ private Boolean registryMismatchAllow = null;
+
+ /**
+ * Apply whatever was given on the command line onto the system properties the controls read, and
+ * announce the resulting state.
+ *
+ * <p>Call this ONCE, early in startup and before the controller is built, because {@code
+ * PqAnchorConfig.fromSystemConfiguration()} and the {@code FalconSealSupport} constructor both
+ * read these properties while the protocol schedule is being assembled.
+ *
+ * <p>An out-of-range ceiling REFUSES TO START rather than being ignored. An emergency control that
+ * silently declines to do what the operator typed is the worst possible behaviour for a control
+ * used under pressure: the operator would believe the chain had been given a way out and would go
+ * looking somewhere else for why it had not moved.
+ *
+ * @throws IllegalArgumentException when an option value is out of range
+ */
+ public void applyAndAnnounce() {
+ final List<String> inForce = new ArrayList<>();
+
+ if (minSealsMax != null && minSealsMax < 0) {
+ throw new IllegalArgumentException(
+ "--Xaere-pq-anchor-min-seals-max must not be negative (got "
+ + minSealsMax
+ + "). Use 0 to require no post-quantum seals at all.");
+ }
+
+ if (anchorDisarm != null) {
+ System.setProperty(PqAnchorConfig.PROPERTY_DISABLE, anchorDisarm.toString());
+ }
+ if (minSealsMax != null) {
+ System.setProperty(PqAnchorConfig.PROPERTY_MIN_SEALS_CEILING, minSealsMax.toString());
+ }
+ if (registryMismatchAllow != null) {
+ System.setProperty(
+ FalconSealSupport.PROPERTY_REGISTRY_MISMATCH_ALLOW, registryMismatchAllow.toString());
+ }
+
+ // Read back from the properties, NOT from the fields. What is announced has to be what the
+ // controls will actually see, including the case where the operator set the environment
+ // variable and nothing on the command line.
+ if (Boolean.parseBoolean(
+ effective(PqAnchorConfig.PROPERTY_DISABLE, "AERE_PQ_ANCHOR_DISABLE"))) {
+ inForce.add(
+ "ANCHOR DISARMED (both certificate-anchor rules off) via "
+ + origin(anchorDisarm, PqAnchorConfig.PROPERTY_DISABLE, "AERE_PQ_ANCHOR_DISABLE"));
+ }
+ final String ceiling =
+ effective(PqAnchorConfig.PROPERTY_MIN_SEALS_CEILING, "AERE_PQ_ANCHOR_MIN_SEALS_MAX");
+ if (ceiling != null) {
+ inForce.add(
+ "SEAL THRESHOLD CAPPED at K<="
+ + ceiling
+ + " (lowering only, never raising) via "
+ + origin(
+ minSealsMax,
+ PqAnchorConfig.PROPERTY_MIN_SEALS_CEILING,
+ "AERE_PQ_ANCHOR_MIN_SEALS_MAX"));
+ }
+ if (Boolean.parseBoolean(
+ effective(
+ FalconSealSupport.PROPERTY_REGISTRY_MISMATCH_ALLOW,
+ FalconSealSupport.ENV_REGISTRY_MISMATCH_ALLOW))) {
+ inForce.add(
+ "REGISTRY BINDING BYPASSED (this node may run without verifying post-quantum "
+ + "certificates) via "
+ + origin(
+ registryMismatchAllow,
+ FalconSealSupport.PROPERTY_REGISTRY_MISMATCH_ALLOW,
+ FalconSealSupport.ENV_REGISTRY_MISMATCH_ALLOW));
+ }
+
+ if (inForce.isEmpty()) {
+ // Say NOTHING. The silence is a measurement: a node with no AERE-PQC-EMG line in its log is
+ // running with no emergency control in force, and that has to be checkable by grep.
+ return;
+ }
+
+ LOG.error(
+ "AERE PQC EMERGENCY [{}]: this node is starting with {} POST-QUANTUM SAFETY CONTROL(S) "
+ + "OVERRIDDEN: {}. These are RECOVERY settings. They reduce what this node checks, they "
+ + "are local to this node and bound to nothing, and a fleet running on them is not "
+ + "running the scheme it is documented as running. Each one in force writes a line at "
+ + "every block, on purpose. Remove them and restart as soon as the cause is fixed.",
+ BANNER_CODE,
+ inForce.size(),
+ String.join(" | ", inForce));
+ }
+
+ /** The value a control will actually see: system property first, then environment variable. */
+ private static String effective(final String property, final String environmentVariable) {
+ final String fromProperty = System.getProperty(property);
+ if (fromProperty != null && !fromProperty.isBlank()) {
+ return fromProperty.trim();
+ }
+ final String fromEnvironment = System.getenv(environmentVariable);
+ if (fromEnvironment != null && !fromEnvironment.isBlank()) {
+ return fromEnvironment.trim();
+ }
+ return null;
+ }
+
+ /** Where the value in force came from, so nobody has to guess whether the flag took. */
+ private static String origin(
+ final Object fromCommandLine, final String property, final String environmentVariable) {
+ if (fromCommandLine != null) {
+ return "the COMMAND LINE";
+ }
+ final String fromProperty = System.getProperty(property);
+ if (fromProperty != null && !fromProperty.isBlank()) {
+ return "system property " + property;
+ }
+ return "environment variable " + environmentVariable;
+ }
+}
diff --git a/app/src/main/java/org/hyperledger/besu/controller/QbftBesuControllerBuilder.java b/app/src/main/java/org/hyperledger/besu/controller/QbftBesuControllerBuilder.java
index 7fbf58d0b..281add4c9 100644
--- a/app/src/main/java/org/hyperledger/besu/controller/QbftBesuControllerBuilder.java
+++ b/app/src/main/java/org/hyperledger/besu/controller/QbftBesuControllerBuilder.java
@@ -11,6 +11,12 @@
* specific language governing permissions and limitations under the License.
*
* SPDX-License-Identifier: Apache-2.0
+ *
+ * Modifications Copyright contributors to the Aere Network.
+ *
+ * This file was modified by contributors to the Aere Network, as required by section 4(b) of the
+ * Apache License 2.0. The copyright header above is the upstream one and is left exactly as it was
+ * found, as section 4(c) requires. The change itself is in patches/0003-aere-pq-anchor.patch.
*/
package org.hyperledger.besu.controller;
@@ -18,6 +24,7 @@ import static com.google.common.base.Preconditions.checkNotNull;
import org.hyperledger.besu.config.BftConfigOptions;
import org.hyperledger.besu.config.BftFork;
+import org.hyperledger.besu.config.JsonGenesisConfigOptions;
import org.hyperledger.besu.config.QbftConfigOptions;
import org.hyperledger.besu.config.QbftFork;
import org.hyperledger.besu.consensus.common.BftValidatorOverrides;
@@ -33,7 +40,15 @@ import org.hyperledger.besu.consensus.common.bft.BftRoundExpiryTimeCalculator;
import org.hyperledger.besu.consensus.common.bft.BlockTimer;
import org.hyperledger.besu.consensus.common.bft.EthSynchronizerUpdater;
import org.hyperledger.besu.consensus.common.bft.EventMultiplexer;
+import org.hyperledger.besu.consensus.common.bft.FalconSealSupport;
+import org.hyperledger.besu.consensus.common.bft.HybridSealSupport;
import org.hyperledger.besu.consensus.common.bft.MessageTracker;
+import org.hyperledger.besu.consensus.common.bft.PqAnchorConfig;
+import org.hyperledger.besu.consensus.common.bft.PqAnchorSyncModeGuard;
+import org.hyperledger.besu.consensus.common.bft.PqAnchorThresholdGuard;
+import org.hyperledger.besu.consensus.common.bft.PqRegistryHash;
+import org.hyperledger.besu.consensus.common.bft.PqSealCache;
+import org.hyperledger.besu.consensus.common.bft.PqSignerRegistry;
import org.hyperledger.besu.consensus.common.bft.RoundTimer;
import org.hyperledger.besu.consensus.common.bft.UniqueMessageMulticaster;
import org.hyperledger.besu.consensus.common.bft.blockcreation.BftMiningCoordinator;
@@ -197,6 +212,283 @@ public class QbftBesuControllerBuilder extends BesuControllerBuilder {
final SyncState syncState,
final EthProtocolManager ethProtocolManager) {
final MutableBlockchain blockchain = protocolContext.getBlockchain();
+
+ // AERE GARDA-ACTIVARE (2026-08-01): the CHAIN-RELATIVE half of the Falcon seal-attachment guard.
+ //
+ // FalconSealSupport is constructed eagerly while the protocol schedule is built, which is early
+ // enough to validate the configuration against ITSELF but too early to see a chain. That left a
+ // measured hole: attachmentArmed() only ever required blockNumber >= attachBlock, so a validator
+ // restarted with an activation height the chain had ALREADY PASSED started with no complaint and
+ // armed on its first commit, emitting Falcon-carrying Commits into a fleet that had not armed.
+ //
+ // This is the first point in startup where a chain head exists, and it is still before the
+ // network and the QBFT state machine are started, so an abort here is a clean refusal to start
+ // rather than a mid-flight halt. The predicate answers "does the header at this height carry at
+ // least one Falcon seal", which is the on-chain proof that the fleet legitimately armed and is
+ // what lets a crashed validator restart into a live activation instead of being locked out.
+ FalconSealSupport.instance()
+ .verifyAttachHeightAgainstChainHeadOrAbort(
+ blockchain.getChainHeadBlockNumber(),
+ n ->
+ blockchain
+ .getBlockHeader(n)
+ .map(h -> !qbftExtraDataCodec.decode(h).getFalconSeals().isEmpty())
+ .orElse(false),
+ dataDirectory);
+
+ // D-334 (2026-09-03): the HYBRID configuration (scheme schedule, registry, SLH-DSA key) is
+ // loaded HERE, at startup, and not on first use. Measured on mainnet 2800: a registry the
+ // container user could not read passed every configuration gate (the file existed) and blew up
+ // inside the QBFT state machine at every anchor parent on three armed validators; with a fourth
+ // node restarting the chain stood 125 s. A defect in this configuration must refuse to START,
+ // exactly like the Falcon key above; QbftRound.hybridExtrasOrEmpty is the second net.
+ HybridSealSupport.instance();
+
+ // AERE GARDA-CHEIE-MASINA (2026-08-07): the Falcon key loaded must be THIS machine's own.
+ //
+ // Measured on seven test nodes with a single variable changed: node 0 was handed index 1's key.
+ // It started cleanly, logged index 1 -- the very same line the node that REALLY is index 1
+ // writes -- and the chain crossed the K=3 step without a pause, with zero rejected blocks and
+ // zero divergence, because the seals VERIFY. What was lost in silence: index 0 disappeared from
+ // the signer set and index 1 was counted twice.
+ //
+ // This is the first point in startup where the node knows its own validator address, and it is
+ // still before the network and the QBFT state machine, so a refusal here is a clean refusal to
+ // start. The guard is INERT for as long as there is no aere.falcon.key and no address-bound
+ // registry, so on 2800 as it stands today it cannot fire.
+ FalconSealSupport.instance()
+ .verifyLocalKeyBelongsToThisNodeOrAbort(Util.publicKeyToAddress(nodeKey.getPublicKey()));
+
+ // AERE BLOCAJ-REPORNIRE (2026-08-05): activate the late anchor FROM THE CHAIN HEAD STATE, at
+ // startup, and not only when a block is imported.
+ //
+ // WHY, and this is a measured chain death, not a supposition. The full activation rehearsal, on
+ // a seven-node test network, found a CIRCULAR DEADLOCK nobody had been looking for:
+ // activateLateAnchor() was called ONLY from FalconSealValidationRule, that is only while
+ // validating an IMPORTED block. After a simultaneous restart of the whole fleet no block is
+ // imported, because nobody proposes. So lateActivated stays false, attachmentArmed() answers
+ // false, no seal is attached, no certificate reaches K, and nobody can propose. Seals come
+ // from Commits, Commits come from proposals, and proposals need seals.
+ // The node's exact message, verbatim from the run: "refusing to propose ... holds 0 valid
+ // eligible Falcon seal(s) ... threshold is 3", over "Attachment stays OFF (fail-safe)".
+ // With K=0 the chain heals itself. With K>0 it NEVER heals.
+ //
+ // A simultaneous restart of the whole fleet is not an exotic scenario: it is a power cut, a
+ // scheduled
+ // kernel update, or any procedure that starts the fleet all at once.
+ //
+ // The repair invents nothing and weakens no check: it does here, once, exactly what the import
+ // path already did, reading the same slot 0 of the same contract, out of the chain head state.
+ // activateLateAnchor stays idempotent and fail-closed: on a hash mismatch the registry stays
+ // EMPTY and the path is terminally failed, exactly as before. If the head state cannot be read,
+ // nothing changes and the import path remains the second chance.
+ //
+ // Deliberately placed before the registry guard and before the QBFT machine starts, so that a
+ // refusal here is still a clean refusal to start.
+ if (FalconSealSupport.instance().anchorAddress() != null) {
+ try {
+ final BlockHeader aereCap = blockchain.getChainHeadHeader();
+ protocolContext
+ .getWorldStateArchive()
+ .get(aereCap.getStateRoot(), aereCap.getHash())
+ .ifPresent(
+ ws -> {
+ final var cont = ws.get(Address.fromHexString(FalconSealSupport.instance().anchorAddress()));
+ if (cont == null) {
+ return;
+ }
+ final var slot0 = cont.getStorageValue(org.apache.tuweni.units.bigints.UInt256.ZERO);
+ if (slot0 == null || slot0.isZero()) {
+ return;
+ }
+ final boolean armat =
+ FalconSealSupport.instance()
+ .activateLateAnchor(slot0.toBytes().toUnprefixedHexString());
+ LOG.info(
+ "AERE PQC: anchor activation at STARTUP from the chain head state {}: {}. "
+ + "Without it, a simultaneous fleet restart with K>0 deadlocks the chain "
+ + "for good (measured on a seven-node test network, 2026-08-05).",
+ aereCap.getNumber(),
+ armat ? "SUCCEEDED" : "failed, the import path remains the second chance");
+ });
+ } catch (final Exception e) {
+ LOG.warn(
+ "AERE PQC: the anchor activation at startup could not be done ({}); the import path "
+ + "remains the second chance, but after a fleet restart with K>0 that path never "
+ + "opens again.",
+ e.toString());
+ }
+
+ // AERE-D358 (2026-09-10, measured on validator 8 of chain 2800): the "import path" named above
+ // is FalconSealValidationRule, and on 2800 that rule is RETIRED from the anchor block
+ // (PqAnchorConfig.legacyFalconRuleRetirementBlock), so it never runs. The startup attempt
+ // above is therefore the ONLY attempt, and it is silent when the head world state is not yet
+ // readable at that instant: after a plain container restart at 15:41Z the manifest loaded as
+ // PENDING, no STARTUP line was logged at all, and the node stayed PENDING for 55 minutes -
+ // refusing every peer Commit and Prepare as "NO post-quantum seal", emitting nothing, timing
+ // out its proposer slot every rotation, and slowing the whole chain from 0.56 to 1.07 s/block.
+ // A second restart activated at once, which is exactly what a race looks like.
+ //
+ // The repair: while the late anchor is PENDING, retry the same read (same contract, same
+ // slot 0, same activateLateAnchor) on every block added to the chain, and stop retrying once
+ // it is activated or terminally failed. It invents nothing and weakens no check.
+ if (FalconSealSupport.instance().anchorAddress() != null
+ && FalconSealSupport.instance().lateAnchorPending()) {
+ final java.util.concurrent.atomic.AtomicLong aereD358Retries =
+ new java.util.concurrent.atomic.AtomicLong();
+ blockchain.observeBlockAdded(
+ event -> {
+ final FalconSealSupport pqc = FalconSealSupport.instance();
+ if (!pqc.lateAnchorPending()) {
+ return;
+ }
+ try {
+ final BlockHeader h = event.getBlock().getHeader();
+ protocolContext
+ .getWorldStateArchive()
+ .get(h.getStateRoot(), h.getHash())
+ .ifPresent(
+ ws -> {
+ final var cont =
+ ws.get(Address.fromHexString(pqc.anchorAddress()));
+ if (cont == null) {
+ return;
+ }
+ final var slot0 =
+ cont.getStorageValue(
+ org.apache.tuweni.units.bigints.UInt256.ZERO);
+ if (slot0 == null || slot0.isZero()) {
+ return;
+ }
+ final long n = aereD358Retries.incrementAndGet();
+ final boolean armat =
+ pqc.activateLateAnchor(slot0.toBytes().toUnprefixedHexString());
+ if (armat || n == 1 || n % 100 == 0) {
+ LOG.info(
+ "AERE-D358: late-anchor activation retried at block {} (attempt {}): {}",
+ h.getNumber(),
+ n,
+ armat
+ ? "SUCCEEDED"
+ : "still pending (contract present, hash mismatch or refused)");
+ }
+ });
+ } catch (final Exception e) {
+ LOG.debug("AERE-D358: retry could not read the head state ({})", e.toString());
+ }
+ });
+ LOG.info(
+ "AERE-D358: late anchor is PENDING after the startup attempt; activation will be "
+ + "retried on every imported block until it succeeds or terminally fails.");
+ }
+ }
+
+ // AERE A8 (2026-08-01): bind the Falcon registry to consensus.
+ //
+ // Deliberately placed immediately after the attachment guard and before BftExecutors, for the
+ // same reason: a chain head exists here, and the network and the QBFT state machine have not
+ // been started, so a refusal is a clean refusal to start.
+ //
+ // Deliberately placed BEFORE the attachment guard would ever let a seal be emitted: a node whose
+ // registry disagrees with its peers must not reach the point of signing or verifying anything.
+ // The two guards answer different questions - "is the activation height sane relative to this
+ // chain" and "is this the registry this chain requires" - and both have to be true.
+ //
+ // AERE A8 (2026-08-02): the SCHEDULE comes from the genesis configuration BESU BOOTED WITH, not
+ // from a genesis file re-opened by path from a system property. Re-reading a file would have
+ // reproduced the defect one level up: the enforced binding would again depend on a local file a
+ // node can be pointed at wrongly, and a node reading a stale copy would enforce a stale
+ // schedule, or none, in silence. Read from GenesisConfigOptions there is no second file: the
+ // value enforced comes out of the same object that produced this node's genesis hash, so a node
+ // that disagrees about the schedule already disagrees about the chain.
+ //
+ // MEASURED, and it is the input that decides the hash: the live chain 2800 genesis carries
+ // config.chainId = 2800, so getChainId() is PRESENT and the 0L fallback below is not the value
+ // in play. That had been recorded as unmeasured, and any registry hash pinned into genesis has
+ // to be computed under the same chain id the guard will use.
+ final PqRegistryHash.Schedule pqRegistrySchedule =
+ PqRegistryHash.parseSchedule(
+ aereGenesisConfigNode("pqRegistryHash"), "booted genesis config.pqRegistryHash");
+ FalconSealSupport.instance()
+ .verifyRegistryBindingOrAbort(
+ blockchain.getChainHeadBlockNumber(),
+ genesisConfigOptions
+ .getChainId()
+ .map(java.math.BigInteger::longValue)
+ .orElse(0L),
+ pqRegistrySchedule);
+
+ // AERE SINCRONIZARE (2026-08-02): the anchor is only a defence if it applies to the history this
+ // node ACCEPTS, and not only to the blocks it is offered as proposals. Outside FULL sync the
+ // header import path never instantiates a header validator at all, so both anchor rules would be
+ // skipped for the entire span between checkpoint and pivot. Refuse to start rather than run a
+ // node that believes it is protected and is not.
+ //
+ // Placed with the other two startup guards and for the same reason: a chain head exists here, the
+ // network is not up and the QBFT state machine has not been created, so this is a clean refusal
+ // to start. Inert when aere.pq.anchorBlock is unset, which is chain 2800 as it stands today.
+ // AERE GARDA-PRAG (2026-08-02): read the anchor configuration ONCE, here, and hand the SAME
+ // object to every guard that needs it. Two calls to fromSystemConfiguration would print the
+ // ARMED banner twice and, worse, would give two guards two independent chances to disagree
+ // about what is actually configured on this node.
+ final PqAnchorConfig aereAnchorConfig = PqAnchorConfig.fromSystemConfiguration();
+
+ PqAnchorSyncModeGuard.verifySyncModeOrAbort(
+ syncConfig == null || syncConfig.getSyncMode() == null
+ ? null
+ : syncConfig.getSyncMode().name(),
+ aereAnchorConfig);
+
+ // AERE PERSISTENTA-SIGILII (2026-08-05): THE SECOND HALF of the chain death on a whole-fleet
+ // restart. The first half is repaired above (BLOCAJ-REPORNIRE): the registry now arms at startup
+ // from the chain head state, and all seven nodes reported SUCCEEDED. The chain died anyway, the
+ // refusal only changing shape: "registry address-bound=TRUE ... Heard 0 seal(s)", frozen 150 s
+ // on the first restart and 298 s on the second.
+ //
+ // WHY. Falcon seals over M(head) travel ONLY on the Commit messages of the head block. Those
+ // messages are never repeated after a restart, and they exist nowhere else: the head block
+ // carries in element 6 the certificate over its PARENT, not over itself. So every node started
+ // with zero seals, nobody reached K, nobody could propose, and so nobody sent another Commit.
+ // The same circular deadlock, one level down.
+ //
+ // WHY THIS IS NOT A8 IN NEW CLOTHES, and this is the whole security argument: the seal is
+ // SELF-VERIFYING. Every seal read from the file is cryptographically verified again against the
+ // anchored registry, over an M rebuilt from the head header this very process has just loaded,
+ // exactly as the producer does at selection time. A forged file cannot inject a seal without
+ // forging a Falcon-512 signature; all it can obtain is the empty cache an absent file already
+ // gives. A8 was a REGISTRY of keys trusted because it sat in a file.
+ //
+ // Deliberately here: the registry is already armed by the block above (otherwise no seal could
+ // resolve and the restore would have gone quiet for nothing), the chain head exists, and the
+ // network and the QBFT machine have not started. Inert when the anchor is not armed, so chain
+ // 2800 as it stands today sees nothing.
+ if (aereAnchorConfig.everActive()) {
+ PqSealCache.instance().enablePersistence(dataDirectory, aereAnchorConfig.chainId());
+ try {
+ final BlockHeader aereCapSigilii = blockchain.getChainHeadHeader();
+ final int aereSigiliiRestaurate =
+ PqSealCache.instance()
+ .restoreFromDisk(
+ aereCapSigilii.getNumber(),
+ aereCapSigilii.getHash(),
+ PqSignerRegistry.falconSealSupport());
+ LOG.info(
+ "AERE PERSISTENTA-SIGILII: {} VERIFIED seal(s) restored for chain head {} ({}). The "
+ + "threshold demanded at the next height is K={}. Zero means this node cannot "
+ + "propose until it hears a Commit, which after a fleet restart with K>0 never "
+ + "happens again on its own.",
+ aereSigiliiRestaurate,
+ aereCapSigilii.getNumber(),
+ aereCapSigilii.getHash(),
+ aereAnchorConfig.minSealsAt(aereCapSigilii.getNumber() + 1L));
+ } catch (final Exception e) {
+ LOG.warn(
+ "AERE PERSISTENTA-SIGILII: restoring the chain head seals could not be done ({}); the "
+ + "node starts with an empty cache, exactly as before this repair.",
+ e.toString());
+ }
+ }
+
final BftExecutors bftExecutors =
BftExecutors.create(metricsSystem, BftExecutors.ConsensusType.QBFT);
final QbftBlockCodec blockEncoder = new QbftBlockCodecAdaptor(qbftExtraDataCodec);
@@ -226,6 +518,22 @@ public class QbftBesuControllerBuilder extends BesuControllerBuilder {
validatorProvider =
protocolContext.getConsensusContext(BftContext.class).getValidatorProvider();
}
+
+ // AERE GARDA-PRAG (2026-08-02): refuse to start on a seal threshold that STOPS the chain.
+ //
+ // Measured before this line was written: nothing anywhere refused a threshold value. Searched
+ // the whole fork tree for any occurrence of minSeals near quorum, throw, refuse, abort or
+ // Illegal, and there were ZERO. PqAnchorConfig rejects a negative K and a step scheduled below
+ // the activation height, and nothing else; the only other check, PqAnchorProducer's
+ // warnIfActivationHeightCanRefuse, writes one LOG.error and returns. So a value at or above the
+ // QBFT quorum was a configuration a node accepted in silence and then halted on.
+ //
+ // Placed here rather than beside the other three startup guards because this is the FIRST point
+ // at which the validator set is resolved, and the bound is a function of its size. It is still
+ // before the network exists (ValidatorPeers is built below) and before the QBFT state machine is
+ // created, so a refusal here is a clean refusal to start rather than a mid-flight halt.
+ PqAnchorThresholdGuard.verifyThresholdAgainstQuorumOrAbort(
+ aereAnchorConfig, validatorProvider.getValidatorsAtHead().size());
final QbftValidatorProvider qbftValidatorProvider =
new QbftValidatorProviderAdaptor(validatorProvider);
@@ -447,6 +755,42 @@ public class QbftBesuControllerBuilder extends BesuControllerBuilder {
return new BftValidatorOverrides(result);
}
+ /**
+ * AERE A8: read a genesis {@code config.*} value that Besu itself does not model, out of the
+ * genesis configuration THIS NODE BOOTED WITH.
+ *
+ * <p>Besu's {@code GenesisConfigOptions.asMap()} cannot be used for this: it is an allow-list of
+ * the keys Besu knows about, so a key of ours is simply absent from it and the guard would read
+ * "no schedule" on a genesis that plainly carries one. That failure would be silent and would
+ * disarm the binding on exactly the fleet that had configured it, which is worse than not having
+ * written it.
+ *
+ * <p>MEASURED, and it is why the lookup is done twice: Besu normalises every genesis config key
+ * to lower case in {@code GenesisReader} via {@code JsonUtil.normalizeKeys}, so {@code
+ * pqRegistryHash} as written by an operator arrives here as {@code pqregistryhash}. Looking up
+ * only the camel-case spelling would find nothing on a real genesis file. Both spellings are
+ * tried so the guard cannot be switched off by a rebase that changes the normalisation.
+ *
+ * <p>Returns null when the key is absent, which {@code PqRegistryHash.parseSchedule} turns into
+ * the empty schedule, i.e. nothing is enforced and the existing chain is untouched.
+ */
+ private com.fasterxml.jackson.databind.JsonNode aereGenesisConfigNode(final String key) {
+ if (!(genesisConfigOptions instanceof JsonGenesisConfigOptions)) {
+ LOG.warn(
+ "AERE PQC A8: the genesis configuration is a {}, not the JSON-backed implementation, so "
+ + "config.{} cannot be read and the Falcon registry binding is NOT ENFORCED on this "
+ + "node. A binding everybody believes is on and is not is worse than no binding.",
+ genesisConfigOptions.getClass().getName(),
+ key);
+ return null;
+ }
+ final JsonGenesisConfigOptions json = (JsonGenesisConfigOptions) genesisConfigOptions;
+ final com.fasterxml.jackson.databind.JsonNode exact = json.aereRawConfigValue(key);
+ return exact != null
+ ? exact
+ : json.aereRawConfigValue(key.toLowerCase(java.util.Locale.ROOT));
+ }
+
private static MinedBlockObserver blockLogger(
final TransactionPool transactionPool, final Address localAddress) {
return block ->
diff --git a/app/src/test/java/org/hyperledger/besu/cli/options/AerePqEmergencyOptionsTest.java b/app/src/test/java/org/hyperledger/besu/cli/options/AerePqEmergencyOptionsTest.java
new file mode 100755
index 000000000..b77a549b2
--- /dev/null
+++ b/app/src/test/java/org/hyperledger/besu/cli/options/AerePqEmergencyOptionsTest.java
@@ -0,0 +1,136 @@
+/*
+ * Copyright contributors to Besu / AERE Network.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.cli.options;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+import org.hyperledger.besu.consensus.common.bft.FalconSealSupport;
+import org.hyperledger.besu.consensus.common.bft.PqAnchorConfig;
+
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import picocli.CommandLine;
+
+/**
+ * AERE OPTIUNI-URGENTA: the command line really reaches the controls.
+ *
+ * <p>These options exist for exactly one reason - that standing the post-quantum anchor down must be
+ * a RESTART and never a rebuild - so the thing worth asserting is the hand-off: a flag typed on the
+ * command line ends up in the same system property the control has always read, and it wins over a
+ * property already set, so an operator who types the flag does not have to know what a wrapper
+ * script did earlier.
+ */
+class AerePqEmergencyOptionsTest {
+
+ private static final String[] PROPERTIES = {
+ PqAnchorConfig.PROPERTY_DISABLE,
+ PqAnchorConfig.PROPERTY_MIN_SEALS_CEILING,
+ FalconSealSupport.PROPERTY_REGISTRY_MISMATCH_ALLOW
+ };
+
+ @BeforeEach
+ @AfterEach
+ void clearProperties() {
+ for (final String property : PROPERTIES) {
+ System.clearProperty(property);
+ }
+ }
+
+ private AerePqEmergencyOptions parse(final String... args) {
+ final AerePqEmergencyOptions options = AerePqEmergencyOptions.create();
+ new CommandLine(options).parseArgs(args);
+ return options;
+ }
+
+ @Test
+ void nothingOnTheCommandLineTouchesNothing() {
+ parse().applyAndAnnounce();
+ for (final String property : PROPERTIES) {
+ assertThat(System.getProperty(property)).isNull();
+ }
+ }
+
+ @Test
+ void bareDisarmFlagArmsTheDisarm() {
+ parse("--Xaere-pq-anchor-disarm").applyAndAnnounce();
+ assertThat(System.getProperty(PqAnchorConfig.PROPERTY_DISABLE)).isEqualTo("true");
+ }
+
+ @Test
+ void disarmCanBeSpelledOutAndCanBeSpelledFalse() {
+ parse("--Xaere-pq-anchor-disarm=false").applyAndAnnounce();
+ assertThat(System.getProperty(PqAnchorConfig.PROPERTY_DISABLE)).isEqualTo("false");
+ }
+
+ @Test
+ void theCommandLineBeatsAPropertySetEarlier() {
+ // The case this protects: a wrapper script or a unit file left the disarm on, and the operator
+ // now wants it off. Typing the flag has to be enough.
+ System.setProperty(PqAnchorConfig.PROPERTY_DISABLE, "true");
+ parse("--Xaere-pq-anchor-disarm=false").applyAndAnnounce();
+ assertThat(System.getProperty(PqAnchorConfig.PROPERTY_DISABLE)).isEqualTo("false");
+ }
+
+ @Test
+ void ceilingReachesTheProperty() {
+ parse("--Xaere-pq-anchor-min-seals-max=2").applyAndAnnounce();
+ assertThat(System.getProperty(PqAnchorConfig.PROPERTY_MIN_SEALS_CEILING)).isEqualTo("2");
+ }
+
+ @Test
+ void aCeilingOfZeroIsAReadableValueAndNotAnAbsentOne() {
+ parse("--Xaere-pq-anchor-min-seals-max=0").applyAndAnnounce();
+ assertThat(System.getProperty(PqAnchorConfig.PROPERTY_MIN_SEALS_CEILING)).isEqualTo("0");
+ }
+
+ @Test
+ void aNegativeCeilingRefusesToStartRatherThanBeingIgnored() {
+ assertThatThrownBy(() -> parse("--Xaere-pq-anchor-min-seals-max=-1").applyAndAnnounce())
+ .isInstanceOf(IllegalArgumentException.class)
+ .hasMessageContaining("must not be negative");
+ assertThat(System.getProperty(PqAnchorConfig.PROPERTY_MIN_SEALS_CEILING)).isNull();
+ }
+
+ @Test
+ void registryBypassReachesTheProperty() {
+ parse("--Xaere-pq-registry-mismatch-allow").applyAndAnnounce();
+ assertThat(System.getProperty(FalconSealSupport.PROPERTY_REGISTRY_MISMATCH_ALLOW))
+ .isEqualTo("true");
+ }
+
+ @Test
+ void allThreeCanBeGivenTogether() {
+ parse(
+ "--Xaere-pq-anchor-disarm",
+ "--Xaere-pq-anchor-min-seals-max=0",
+ "--Xaere-pq-registry-mismatch-allow")
+ .applyAndAnnounce();
+ assertThat(System.getProperty(PqAnchorConfig.PROPERTY_DISABLE)).isEqualTo("true");
+ assertThat(System.getProperty(PqAnchorConfig.PROPERTY_MIN_SEALS_CEILING)).isEqualTo("0");
+ assertThat(System.getProperty(FalconSealSupport.PROPERTY_REGISTRY_MISMATCH_ALLOW))
+ .isEqualTo("true");
+ }
+
+ @Test
+ void whatTheCommandLineWritesIsWhatPqAnchorConfigThenReads() {
+ // The hand-off end to end, through the real reader rather than a re-implementation of it.
+ parse("--Xaere-pq-anchor-disarm", "--Xaere-pq-anchor-min-seals-max=1").applyAndAnnounce();
+ final PqAnchorConfig read = PqAnchorConfig.fromSystemConfiguration();
+ assertThat(read.disabled()).isTrue();
+ assertThat(read.minSealsCeiling()).hasValue(1);
+ }
+}
diff --git a/config/src/main/java/org/hyperledger/besu/config/JsonGenesisConfigOptions.java b/config/src/main/java/org/hyperledger/besu/config/JsonGenesisConfigOptions.java
index eeaa4ac3e..79581600f 100644
--- a/config/src/main/java/org/hyperledger/besu/config/JsonGenesisConfigOptions.java
+++ b/config/src/main/java/org/hyperledger/besu/config/JsonGenesisConfigOptions.java
@@ -11,6 +11,12 @@
* specific language governing permissions and limitations under the License.
*
* SPDX-License-Identifier: Apache-2.0
+ *
+ * Modifications Copyright contributors to the Aere Network.
+ *
+ * This file was modified by contributors to the Aere Network, as required by section 4(b) of the
+ * Apache License 2.0. The copyright header above is the upstream one and is left exactly as it was
+ * found, as section 4(c) requires. The change itself is in patches/0003-aere-pq-anchor.patch.
*/
package org.hyperledger.besu.config;
@@ -639,4 +645,20 @@ public class JsonGenesisConfigOptions implements GenesisConfigOptions {
public int hashCode() {
return Objects.hash(configRoot, configOverrides);
}
+
+ /**
+ * AERE A8: the raw genesis {@code config.*} value for a key Besu does not model, or null.
+ *
+ * <p>WHY THIS EXISTS. {@link #asMap()} is an allow-list of the keys Besu knows, so a key of ours
+ * is absent from it, and a guard reading it would conclude "no schedule" on a genesis that
+ * plainly carries one. Silently disarming a binding on exactly the fleet that configured it is
+ * worse than never having written the binding. This accessor is additive and read-only: it
+ * changes no Besu behaviour and returns the node exactly as the genesis reader normalised it.
+ *
+ * @param key the config key, as normalised by the genesis reader (lower case)
+ * @return the value node, or null when absent
+ */
+ public com.fasterxml.jackson.databind.JsonNode aereRawConfigValue(final String key) {
+ return configRoot.get(key);
+ }
}
diff --git a/consensus/common/build.gradle b/consensus/common/build.gradle
index 499c974f1..a6f5276f2 100644
--- a/consensus/common/build.gradle
+++ b/consensus/common/build.gradle
@@ -11,6 +11,12 @@
* specific language governing permissions and limitations under the License.
*
* SPDX-License-Identifier: Apache-2.0
+ *
+ * Modifications Copyright contributors to the Aere Network.
+ *
+ * This file was modified by contributors to the Aere Network, as required by section 4(b) of the
+ * Apache License 2.0. The copyright header above is the upstream one and is left exactly as it was
+ * found, as section 4(c) requires. The change itself is in patches/0003-aere-pq-anchor.patch.
*/
apply plugin: 'java-library'
@@ -47,6 +53,7 @@ dependencies {
implementation 'com.fasterxml.jackson.core:jackson-databind'
implementation 'com.google.guava:guava'
+ implementation 'org.bouncycastle:bcprov-jdk18on'
implementation 'io.consensys.tuweni:tuweni-bytes'
testImplementation project(':config')
diff --git a/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/AereAnchorProposalDelay.java b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/AereAnchorProposalDelay.java
new file mode 100755
index 000000000..84eeb15a4
--- /dev/null
+++ b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/AereAnchorProposalDelay.java
@@ -0,0 +1,152 @@
+/*
+ * Copyright contributors to Aere Network.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.common.bft;
+
+import org.hyperledger.besu.consensus.common.bft.blockcreation.PqAnchorProducer;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+/**
+ * D-337 (2026-09-04): how long the proposer waits, ONLY at an anchor height, before its proposal
+ * timer fires.
+ *
+ * <p>WHY THIS EXISTS, measured on chain 2800. At an anchor height the proposer must carry K valid
+ * seals of EVERY scheme in the schedule, and the SLH-DSA seals arrive with the commits of the
+ * parent. With the hybrid certificate live, the proposal timer fires about half a second after the
+ * parent and the sixth SLH-DSA seal is not there yet, so the producer refuses (it will not write a
+ * certificate it cannot fill), round 0 expires, and the anchor costs the whole four-second
+ * round-change timeout: eleven of twelve anchors measured on 2026-09-04, parent-to-anchor 5.6 s
+ * instead of 0.8 s. Making the signature four times faster fixed the PARENT (3.3 s to 1 s) and did
+ * not fix this, because the race is against the proposal timer, not against the CPU.
+ *
+ * <p>WHAT IT IS NOT. This is local timing, not consensus. A node that does not set it proposes
+ * exactly as before; a proposal that arrives later is valid under the same rules (QBFT only
+ * requires the timestamp to be at least a block period after the parent). So it can be set node by
+ * node, with no activation height and no fleet agreement, and a wrong value costs liveness at
+ * anchors, never a fork.
+ *
+ * <p>Unset or zero means today's behaviour, exactly. The value is read once, validated at node
+ * start (from {@link BlockTimer}'s constructor), and refused if it is negative or above five
+ * seconds: a delay longer than the round-change timeout would trade one stall for another.
+ */
+public final class AereAnchorProposalDelay {
+ private static final Logger LOG = LoggerFactory.getLogger(AereAnchorProposalDelay.class);
+
+ /** System property carrying the delay in milliseconds. */
+ public static final String PROPERTY = "aere.pq.anchorProposalDelayMs";
+
+ /** Environment variable carrying the delay in milliseconds. */
+ public static final String ENV = "AERE_PQ_ANCHOR_PROPOSAL_DELAY_MS";
+
+ /** The largest delay that can be configured; above this a stall is traded for a stall. */
+ public static final long MAX_MILLIS = 5000L;
+
+ private static volatile Long cached;
+
+ private AereAnchorProposalDelay() {}
+
+ /**
+ * The configured delay in milliseconds, read once and memoised.
+ *
+ * @return the delay, zero when unset
+ * @throws IllegalArgumentException if the value is not a number in [0, {@link #MAX_MILLIS}]
+ */
+ public static long configuredMillis() {
+ Long local = cached;
+ if (local == null) {
+ synchronized (AereAnchorProposalDelay.class) {
+ local = cached;
+ if (local == null) {
+ local = parse(readRaw());
+ if (local > 0) {
+ LOG.info(
+ "AERE PQ-ANCHOR: proposals at anchor heights wait an extra {} ms for the seals of"
+ + " the parent (D-337). This is local timing, not consensus.",
+ local);
+ }
+ cached = local;
+ }
+ }
+ }
+ return local;
+ }
+
+ /**
+ * The delay to add to the proposal timer for a given height: the configured value at an anchor
+ * height, zero everywhere else.
+ *
+ * @param blockNumber the height whose proposal timer is being started
+ * @return milliseconds to add
+ */
+ public static long millisFor(final long blockNumber) {
+ final long delay = configuredMillis();
+ if (delay <= 0) {
+ return 0L;
+ }
+ try {
+ return PqAnchorProducer.config().anchorAppliesAt(blockNumber) ? delay : 0L;
+ } catch (final RuntimeException e) {
+ // The anchor configuration is read at start and refuses there; if it somehow cannot be read
+ // here, the honest answer is "no extra delay", never an exception into the block timer.
+ LOG.warn("AERE PQ-ANCHOR: cannot tell whether {} is an anchor height: {}", blockNumber, e.getMessage());
+ return 0L;
+ }
+ }
+
+ /**
+ * Parse and validate a raw value.
+ *
+ * @param raw the text, possibly null or blank
+ * @return the delay in milliseconds
+ */
+ static long parse(final String raw) {
+ if (raw == null || raw.isBlank()) {
+ return 0L;
+ }
+ final long value;
+ try {
+ value = Long.parseLong(raw.trim());
+ } catch (final NumberFormatException e) {
+ throw new IllegalArgumentException(
+ "AERE-PQC-ANCHOR-CONF-05: " + PROPERTY + "='" + raw + "' is not a number of milliseconds");
+ }
+ if (value < 0 || value > MAX_MILLIS) {
+ throw new IllegalArgumentException(
+ "AERE-PQC-ANCHOR-CONF-05: "
+ + PROPERTY
+ + "="
+ + value
+ + " is outside [0, "
+ + MAX_MILLIS
+ + "] ms. A delay longer than the round-change timeout trades one stall for another.");
+ }
+ return value;
+ }
+
+ private static String readRaw() {
+ final String property = System.getProperty(PROPERTY);
+ return property != null ? property : System.getenv(ENV);
+ }
+
+ /**
+ * Drop the memoised value. For tests only.
+ */
+ static void forgetForTesting() {
+ synchronized (AereAnchorProposalDelay.class) {
+ cached = null;
+ }
+ }
+}
diff --git a/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/BftBlockInterface.java b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/BftBlockInterface.java
index b7a886c29..77af53d68 100644
--- a/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/BftBlockInterface.java
+++ b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/BftBlockInterface.java
@@ -11,6 +11,12 @@
* specific language governing permissions and limitations under the License.
*
* SPDX-License-Identifier: Apache-2.0
+ *
+ * Modifications Copyright contributors to the Aere Network.
+ *
+ * This file was modified by contributors to the Aere Network, as required by section 4(b) of the
+ * Apache License 2.0. The copyright header above is the upstream one and is left exactly as it was
+ * found, as section 4(c) requires. The change itself is in patches/0003-aere-pq-anchor.patch.
*/
package org.hyperledger.besu.consensus.common.bft;
@@ -79,6 +85,19 @@ public class BftBlockInterface implements BlockInterface {
/**
* Replace round in block.
*
+ * <p>AERE ANCHOR V2, MEASURED DEFECT, FIXED HERE. This method used the five argument {@link
+ * BftExtraData} constructor, which defaults the Falcon seal collection to EMPTY, so every round
+ * replacement silently DELETED element 6. That is harmless while element 6 only carries a
+ * log-only attestation, and fatal under V2: the round change path
+ * ({@code QbftRound.startRoundWith} to {@code replaceRoundAndProposerForProposalBlock}) re-uses a
+ * prepared block, and it would have re-proposed it with vanityData still carrying the digest D of
+ * a certificate that had just been stripped out. The digest rule would then reject every single
+ * re-proposed block, on a chain where rounds above zero do occur (measured 1 in 307).
+ *
+ * <p>Carrying the seals across is safe for every existing user of this method, because the Falcon
+ * list is excluded from BOTH hash pre-images: neither the committed-seal hash nor the on-chain
+ * block hash changes. IBFT, which shares this class, always has an empty list here.
+ *
* @param block the block
* @param round the round
* @param blockHeaderFunctions the block header functions
@@ -93,7 +112,12 @@ public class BftBlockInterface implements BlockInterface {
prevExtraData.getSeals(),
prevExtraData.getVote(),
round,
- prevExtraData.getValidators());
+ prevExtraData.getValidators(),
+ prevExtraData.getFalconSeals(),
+ // AERE ANCHOR V2 (2026-09-03, D-328): the scheme-tagged certificate rides along too. Without
+ // this line every v2 header lost its certificate at the round substitution and the fleet
+ // refused its own first v2 anchor (testnet 28001, block 168032, 3 hours stalled).
+ prevExtraData.getHybridSeals());
final BlockHeaderBuilder headerBuilder = BlockHeaderBuilder.fromHeader(block.getHeader());
headerBuilder
diff --git a/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/BftExtraData.java b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/BftExtraData.java
index a24c33a93..c444a1514 100644
--- a/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/BftExtraData.java
+++ b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/BftExtraData.java
@@ -11,6 +11,12 @@
* specific language governing permissions and limitations under the License.
*
* SPDX-License-Identifier: Apache-2.0
+ *
+ * Modifications Copyright contributors to the Aere Network.
+ *
+ * This file was modified by contributors to the Aere Network, as required by section 4(b) of the
+ * Apache License 2.0. The copyright header above is the upstream one and is left exactly as it was
+ * found, as section 4(c) requires. The change itself is in patches/0003-aere-pq-anchor.patch.
*/
package org.hyperledger.besu.consensus.common.bft;
@@ -21,6 +27,8 @@ import org.hyperledger.besu.datatypes.Address;
import org.hyperledger.besu.ethereum.core.ParsedExtraData;
import java.util.Collection;
+import java.util.Collections;
+import java.util.List;
import java.util.Optional;
import org.apache.tuweni.bytes.Bytes;
@@ -34,7 +42,17 @@ public class BftExtraData implements ParsedExtraData {
private final int round;
/**
- * Instantiates a new Bft extra data.
+ * Parallel, ADDITIVE post-quantum (Falcon-512) seals. These sit alongside the decisive ECDSA
+ * {@link #seals} and are excluded from every signed pre-image, so they never disturb the ECDSA
+ * committed seals or the block/header hash.
+ */
+ private final Collection<FalconSeal> falconSeals;
+ /** AERE ANCHOR V2: the scheme-tagged certificate; empty on every header below the v2 height. */
+ private final List<SchemeSeal> hybridSeals;
+
+ /**
+ * Instantiates a new Bft extra data (no Falcon seals). Retained for callers, notably the IBFT
+ * codec, that never carry a parallel post-quantum seal.
*
* @param vanityData the vanity data
* @param seals the seals
@@ -48,14 +66,59 @@ public class BftExtraData implements ParsedExtraData {
final Optional<Vote> vote,
final int round,
final Collection<Address> validators) {
+ this(vanityData, seals, vote, round, validators, Collections.emptyList());
+ }
+
+ /**
+ * Instantiates a new Bft extra data with a parallel Falcon-512 seal list.
+ *
+ * @param vanityData the vanity data
+ * @param seals the ECDSA committed seals (decisive)
+ * @param vote the vote
+ * @param round the round
+ * @param validators the validators
+ * @param falconSeals the parallel post-quantum Falcon seals (additive, log-only)
+ */
+ public BftExtraData(
+ final Bytes vanityData,
+ final Collection<SECPSignature> seals,
+ final Optional<Vote> vote,
+ final int round,
+ final Collection<Address> validators,
+ final Collection<FalconSeal> falconSeals) {
+ this(vanityData, seals, vote, round, validators, falconSeals, Collections.emptyList());
+ }
+
+ /**
+ * Full constructor.
+ *
+ * @param hybridSeals the scheme-tagged (v2) certificate, or empty; a header carries the v1 Falcon
+ * list OR the v2 certificate, never both
+ */
+ public BftExtraData(
+ final Bytes vanityData,
+ final Collection<SECPSignature> seals,
+ final Optional<Vote> vote,
+ final int round,
+ final Collection<Address> validators,
+ final Collection<FalconSeal> falconSeals,
+ final List<SchemeSeal> hybridSeals) {
checkNotNull(vanityData);
+ checkNotNull(hybridSeals);
+ if (!hybridSeals.isEmpty() && falconSeals != null && !falconSeals.isEmpty()) {
+ throw new IllegalArgumentException(
+ "AERE ANCHOR V2: a header carries the v1 Falcon list OR the v2 certificate, not both");
+ }
+ this.hybridSeals = List.copyOf(hybridSeals);
checkNotNull(seals);
checkNotNull(validators);
+ checkNotNull(falconSeals);
this.vanityData = vanityData;
this.seals = seals;
this.validators = validators;
this.vote = vote;
this.round = round;
+ this.falconSeals = falconSeals;
}
/**
@@ -103,6 +166,24 @@ public class BftExtraData implements ParsedExtraData {
return round;
}
+ /**
+ * Gets the parallel post-quantum Falcon seals.
+ *
+ * @return the Falcon seals (possibly empty, never null)
+ */
+ public Collection<FalconSeal> getFalconSeals() {
+ return falconSeals;
+ }
+
+ /**
+ * The scheme-tagged (v2) certificate.
+ *
+ * @return the v2 seals, canonical order; empty below the v2 height
+ */
+ public List<SchemeSeal> getHybridSeals() {
+ return hybridSeals;
+ }
+
@Override
public String toString() {
return "BftExtraData{"
@@ -116,6 +197,10 @@ public class BftExtraData implements ParsedExtraData {
+ vote
+ ", round="
+ round
+ + ", falconSeals="
+ + falconSeals
+ + ", hybridSeals="
+ + hybridSeals
+ '}';
}
}
diff --git a/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/BlockTimer.java b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/BlockTimer.java
index 80f6815c8..73493403c 100644
--- a/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/BlockTimer.java
+++ b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/BlockTimer.java
@@ -11,6 +11,12 @@
* specific language governing permissions and limitations under the License.
*
* SPDX-License-Identifier: Apache-2.0
+ *
+ * Modifications Copyright contributors to the Aere Network.
+ *
+ * This file was modified by contributors to the Aere Network, as required by section 4(b) of the
+ * Apache License 2.0. The copyright header above is the upstream one and is left exactly as it was
+ * found, as section 4(c) requires. The change itself is in patches/0003-aere-pq-anchor.patch.
*/
package org.hyperledger.besu.consensus.common.bft;
@@ -53,6 +59,12 @@ public class BlockTimer {
final ForksSchedule<? extends BftConfigOptions> forksSchedule,
final BftExecutors bftExecutors,
final Clock clock) {
+ // Load the anchor proposal-delay configuration HERE, at construction, so a malformed value
+ // refuses START-UP rather than surfacing on its first use inside the consensus state machine.
+ // Measured 2026-09-03 on mainnet: a lazily-loaded consensus setting turned an unreadable file
+ // into 125 seconds of halted chain, while every configuration gate stayed green because the
+ // files existed.
+ AereAnchorProposalDelay.configuredMillis();
this.queue = queue;
this.forksSchedule = forksSchedule;
this.bftExecutors = bftExecutors;
@@ -123,7 +135,13 @@ public class BlockTimer {
final int emptyBlockPeriodSeconds = currentForkOptions.getEmptyBlockPeriodSeconds();
setBlockTimes(currentBlockPeriodSeconds, emptyBlockPeriodSeconds);
- startTimer(round, expiryTime);
+ // AERE D-337 (2026-09-04): at an anchor height the proposer needs K seals of every scheme, and
+ // those ride on the commits of the parent. Measured on chain 2800, the timer fires before the
+ // sixth SLH-DSA seal arrives, the producer refuses to write a certificate it cannot fill, and
+ // the anchor pays the whole round-change timeout. The extra wait applies ONLY at anchor heights
+ // and is zero unless configured; see AereAnchorProposalDelay for why this is local timing and
+ // not consensus.
+ startTimer(round, expiryTime + AereAnchorProposalDelay.millisFor(round.getSequenceNumber()));
}
/**
diff --git a/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/FalconSeal.java b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/FalconSeal.java
new file mode 100755
index 000000000..9f290a1aa
--- /dev/null
+++ b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/FalconSeal.java
@@ -0,0 +1,88 @@
+/*
+ * Copyright contributors to Besu / AERE Network.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.common.bft;
+
+import java.util.Objects;
+
+import org.apache.tuweni.bytes.Bytes;
+
+/**
+ * A parallel post-quantum (Falcon-512) seal attached to a BFT block header, ALONGSIDE (never
+ * replacing) the decisive ECDSA committed seals.
+ *
+ * <p>Because Falcon signatures are not public-key-recoverable, each seal carries an explicit {@code
+ * validatorIndex} so a verifier can look up the signer's Falcon public key in the validator to
+ * Falcon-pubkey registry. This is an additive, log-only attestation for the hybrid PQC demo; ECDSA
+ * committed seals remain the liveness-critical seal that decides block acceptance.
+ */
+public class FalconSeal {
+ private final int validatorIndex;
+ private final Bytes signature;
+
+ /**
+ * Instantiates a new Falcon seal.
+ *
+ * @param validatorIndex the index of the signing validator in the Falcon registry
+ * @param signature the Falcon-512 signature over the block commit hash
+ */
+ public FalconSeal(final int validatorIndex, final Bytes signature) {
+ this.validatorIndex = validatorIndex;
+ this.signature = signature;
+ }
+
+ /**
+ * Gets the validator index.
+ *
+ * @return the validator index used to look up the Falcon public key
+ */
+ public int getValidatorIndex() {
+ return validatorIndex;
+ }
+
+ /**
+ * Gets the Falcon signature bytes.
+ *
+ * @return the Falcon-512 signature
+ */
+ public Bytes getSignature() {
+ return signature;
+ }
+
+ @Override
+ public boolean equals(final Object o) {
+ if (this == o) {
+ return true;
+ }
+ if (o == null || getClass() != o.getClass()) {
+ return false;
+ }
+ final FalconSeal that = (FalconSeal) o;
+ return validatorIndex == that.validatorIndex && Objects.equals(signature, that.signature);
+ }
+
+ @Override
+ public int hashCode() {
+ return Objects.hash(validatorIndex, signature);
+ }
+
+ @Override
+ public String toString() {
+ return "FalconSeal{validatorIndex="
+ + validatorIndex
+ + ", sigLen="
+ + (signature == null ? 0 : signature.size())
+ + '}';
+ }
+}
diff --git a/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/FalconSealScheme.java b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/FalconSealScheme.java
new file mode 100755
index 000000000..0f0090cb3
--- /dev/null
+++ b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/FalconSealScheme.java
@@ -0,0 +1,104 @@
+/* AERE crypto-agility: Falcon-512 behind the SealScheme seam. The registry form is the raw
+ * Falcon h vector, 896 bytes, exactly what the signer registry stores today (measured on the
+ * proof-network registry files, registru-PROBA-v2-*.properties: 896 per entry). The 897-byte
+ * form pk(897) = 0x09 || h belongs to the 0x0AE1 PRECOMPILE input format, one header byte above
+ * this layer; confusing the two costs a red test, which is exactly how this comment was earned. */
+package org.hyperledger.besu.consensus.common.bft;
+
+import java.security.SecureRandom;
+import java.util.Optional;
+
+import org.bouncycastle.pqc.crypto.falcon.FalconKeyGenerationParameters;
+import org.bouncycastle.pqc.crypto.falcon.FalconKeyPairGenerator;
+import org.bouncycastle.pqc.crypto.falcon.FalconParameters;
+import org.bouncycastle.pqc.crypto.falcon.FalconPrivateKeyParameters;
+import org.bouncycastle.pqc.crypto.falcon.FalconPublicKeyParameters;
+import org.bouncycastle.pqc.crypto.falcon.FalconSigner;
+import org.bouncycastle.crypto.AsymmetricCipherKeyPair;
+
+/** Falcon-512 as a pluggable seal scheme. */
+public final class FalconSealScheme implements SealScheme {
+
+ /** Registry form: the raw public h vector for Falcon-512 (no precompile header byte). */
+ public static final int PUBLIC_KEY_LENGTH = 896;
+
+ private record Pub(FalconPublicKeyParameters params) implements PublicHandle {}
+
+ private record Priv(FalconPrivateKeyParameters params) implements PrivateHandle {}
+
+ @Override
+ public String id() {
+ return "falcon-512";
+ }
+
+ @Override
+ public byte wireId() {
+ return 0x01;
+ }
+
+ @Override
+ public int publicKeyLength() {
+ return PUBLIC_KEY_LENGTH;
+ }
+
+ @Override
+ public Optional<PublicHandle> parsePublicKey(final byte[] registryForm) {
+ if (registryForm == null || registryForm.length != PUBLIC_KEY_LENGTH) {
+ return Optional.empty();
+ }
+ try {
+ return Optional.of(new Pub(new FalconPublicKeyParameters(FalconParameters.falcon_512, registryForm)));
+ } catch (final RuntimeException e) {
+ return Optional.empty();
+ }
+ }
+
+ @Override
+ public Optional<byte[]> sign(final PrivateHandle key, final byte[] message) {
+ if (!(key instanceof Priv p) || message == null) {
+ return Optional.empty();
+ }
+ try {
+ final FalconSigner signer = new FalconSigner();
+ signer.init(true, p.params());
+ return Optional.of(signer.generateSignature(message));
+ } catch (final RuntimeException e) {
+ return Optional.empty();
+ }
+ }
+
+ @Override
+ public boolean verify(final PublicHandle key, final byte[] message, final byte[] signature) {
+ if (!(key instanceof Pub p) || message == null || signature == null) {
+ return false;
+ }
+ try {
+ final FalconSigner verifier = new FalconSigner();
+ verifier.init(false, p.params());
+ return verifier.verifySignature(message, signature);
+ } catch (final RuntimeException e) {
+ return false;
+ }
+ }
+
+ /** Transition bridge for the live signing path: FalconSealSupport loads the node's private
+ * key as BC {@link FalconPrivateKeyParameters} long before this layer existed. Routing its
+ * signing through the scheme without re-plumbing key loading needs this one adapter. The BC
+ * type appears ONLY here, in the class whose whole job is to speak Falcon. */
+ public Optional<byte[]> signWithParams(final FalconPrivateKeyParameters key, final byte[] message) {
+ if (key == null || message == null) {
+ return Optional.empty();
+ }
+ return sign(new Priv(key), message);
+ }
+
+ @Override
+ public GeneratedPair generate(final SecureRandom random) {
+ final FalconKeyPairGenerator gen = new FalconKeyPairGenerator();
+ gen.init(new FalconKeyGenerationParameters(random, FalconParameters.falcon_512));
+ final AsymmetricCipherKeyPair pair = gen.generateKeyPair();
+ final FalconPublicKeyParameters pub = (FalconPublicKeyParameters) pair.getPublic();
+ final FalconPrivateKeyParameters priv = (FalconPrivateKeyParameters) pair.getPrivate();
+ return new GeneratedPair(new Pub(pub), new Priv(priv), pub.getH());
+ }
+}
diff --git a/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/FalconSealSupport.java b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/FalconSealSupport.java
new file mode 100755
index 000000000..7049b8414
--- /dev/null
+++ b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/FalconSealSupport.java
@@ -0,0 +1,4130 @@
+/*
+ * Copyright contributors to Besu.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.common.bft;
+
+import java.io.FileInputStream;
+import java.io.InputStream;
+import java.io.OutputStream;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.nio.file.Paths;
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.HashMap;
+import java.util.Iterator;
+import java.util.LinkedHashSet;
+import java.util.List;
+import java.util.Locale;
+import java.util.Map;
+import java.util.Optional;
+import java.util.OptionalInt;
+import java.util.Properties;
+import java.util.Set;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.atomic.AtomicBoolean;
+import java.util.concurrent.atomic.AtomicLong;
+import java.util.function.LongPredicate;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import org.apache.tuweni.bytes.Bytes;
+import org.apache.tuweni.bytes.Bytes32;
+import org.bouncycastle.crypto.digests.KeccakDigest;
+import org.bouncycastle.pqc.crypto.falcon.FalconParameters;
+import org.bouncycastle.pqc.crypto.falcon.FalconPrivateKeyParameters;
+import org.bouncycastle.pqc.crypto.falcon.FalconPublicKeyParameters;
+import org.bouncycastle.pqc.crypto.falcon.FalconSigner;
+import org.hyperledger.besu.datatypes.Address;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+/**
+ * BFT-local, PARALLEL Falcon-512 signer + verifier + registry for the Falcon consensus SEAL: a
+ * post-quantum signature carried ALONGSIDE the classical seals.
+ *
+ * <p>NAMING, and this is not pedantry. This line used to read "for the hybrid post-quantum
+ * consensus seal". AERE DOES NOT HAVE POST-QUANTUM CONSENSUS and must never be described as having
+ * it: proposer selection and finality are classical secp256k1 ECDSA QBFT, and the post-quantum
+ * layer is signature, precompile and account level. Our own audit scope dossier
+ * ({@code audit-package-pq-consensus/scope/AUDIT-SCOPE-DOSSIER-2026-07-12.md}, section 3) tells
+ * reviewers to FLAG that phrase wherever it appears in code comments. It appeared here.
+ *
+ * <p>This deliberately does NOT ride the shared secp256k1 {@code NodeKey} / {@code SecurityModule}
+ * singleton (that interface returns ECDSA R,S and is used chain-wide for transactions and devp2p).
+ * The Falcon key here is a second, consensus-only key.
+ *
+ * <p>AERE audit fix (AUD-CONSENSUS-1 / AUD-CONSENSUS-2, 2026-07-18): the registry now binds each
+ * Falcon-512 public key to a validator ADDRESS, not merely to an index. This is what makes the
+ * "eligible signer" set {@code currentValidators INTERSECT registry} well defined, so the blocking
+ * rule can compute BOTH the Falcon quorum AND the counted-seal set over the SAME set of validator
+ * addresses (see {@code FalconSealValidationRule}). Without the address binding the registry is only
+ * a bag of indexed keys with no tie to the live validator set, which is exactly the decoupling that
+ * let a routine add-validator vote raise the ECDSA-sized quorum above the fixed key count and halt a
+ * post-fork chain, and let a removed validator's key keep counting.
+ *
+ * <p>Configuration (system property takes precedence over environment variable):
+ *
+ * <ul>
+ * <li>{@code aere.falcon.key} / {@code AERE_FALCON_KEY}: path to this node's Falcon private key
+ * .properties file with keys {@code index, f, g, F, pk} (hex, low-level BouncyCastle Falcon
+ * components). This is a per-node local SECRET and never appears in any registry.
+ * <li>{@code aere.falcon.genesis} / {@code AERE_FALCON_GENESIS}: path to the chain's genesis file
+ * carrying a GENESIS-ANCHORED validator-to-Falcon-pubkey manifest. Tamper-evident and
+ * immutable from genesis. Highest precedence.
+ * <li>{@code aere.falcon.manifest} / {@code AERE_FALCON_MANIFEST} together with {@code
+ * aere.falcon.anchor.address} / {@code AERE_FALCON_ANCHOR_ADDRESS}: the STAGE-2
+ * LATE-ANCHOR (contract-anchored) registry source for chains that launched WITHOUT a genesis
+ * manifest (i.e. an already-live chain). The manifest file carries the full
+ * index-to-{addr,pk} JSON object; the anchor contract's storage slot 0 must hold
+ * {@code keccak256(canonical manifest)}. The registry stays EMPTY (pending) until consensus
+ * code observes the anchor contract in the chain's world state and calls {@link
+ * #activateLateAnchor}; activation is fail-closed on any hash mismatch. This removes the
+ * re-genesis requirement for activating the hybrid PQC certificate on an existing chain.
+ * <li>{@code aere.falcon.registry} / {@code AERE_FALCON_REGISTRY}: (LEGACY, mutable-file
+ * fallback) path to the validator to Falcon-pubkey registry .properties file. Lowest
+ * precedence; retained for backward compatibility and the upstream unit tests. This legacy
+ * source carries pubkeys ONLY (no validator address), so a registry loaded from it is NOT
+ * address-bound and is NOT eligible to arm blocking (see {@link #addressBound()}).
+ * <li>{@code aere.falcon.forkBlock} / {@code AERE_FALCON_FORKBLOCK}: block number at and after
+ * which the Falcon quorum certificate is BLOCKING. Unset means never blocking (log-only).
+ * </ul>
+ *
+ * <p>Every method is defensive: any load, parse, sign or verify failure is swallowed and logged, so
+ * a Falcon fault never THROWS on the consensus path.
+ *
+ * <p>THAT IS NO LONGER THE SAME THING AS "IT CANNOT HALT THE CHAIN", and the sentence that used to
+ * claim so has been removed rather than softened. Not throwing only means the failure is returned
+ * as a verdict, and two consumers now turn that verdict into a REJECT: {@code
+ * FalconSealValidationRule} once {@code aere.falcon.forkBlock} is reached with an active registry,
+ * and {@code PqAnchorSealsRule} (V2 R2) at and above {@code pqAnchorBlock}, which refuses a header
+ * whenever {@link #addressForIndex} returns null or {@link #verify} returns false. A node whose
+ * registry file fails to load therefore rejects every header carrying a certificate, i.e. it halts
+ * itself, and two nodes with DIFFERENT registry files disagree about which headers are valid. That
+ * is defect A8 and it is why the registry has to be bound to genesis by {@code pqRegistryHash}
+ * before any of this is armed. While both of those gates are unset - which is the state of chain
+ * 2800 today - the subsystem is log-only and the old sentence holds; it is not a property of this
+ * file, it is a property of the configuration.
+ */
+public final class FalconSealSupport {
+
+ private static final Logger LOG = LoggerFactory.getLogger(FalconSealSupport.class);
+
+ private static volatile FalconSealSupport instance;
+
+ /**
+ * System anchor address whose storage slot 0 holds keccak256 of the canonical Falcon manifest.
+ * Because genesis {@code alloc} storage is committed into the genesis stateRoot (and hence the
+ * genesis block hash), the manifest hash is bound to the chain identity itself: two nodes that
+ * agree on the chain necessarily agree on the manifest hash, and it is independently queryable
+ * via {@code eth_getStorageAt(0x..0fa1, 0x0)}. 40-hex, lower-case, no 0x prefix.
+ */
+ private static final String ANCHOR_ADDRESS = "0000000000000000000000000000000000000fa1";
+
+ /** Storage slot (0) at the anchor address holding the manifest hash. 64-hex, no 0x prefix. */
+ private static final String ANCHOR_SLOT =
+ "0000000000000000000000000000000000000000000000000000000000000000";
+
+ /** How many seals this node emitted on its own PREPAREs. See {@link #preparesSealed()}. */
+ private final java.util.concurrent.atomic.AtomicLong preparesSealed =
+ new java.util.concurrent.atomic.AtomicLong();
+
+ /** How many seals this node emitted on its own PROPOSALs since startup. */
+ private final java.util.concurrent.atomic.AtomicLong proposalsSealed =
+ new java.util.concurrent.atomic.AtomicLong();
+
+ /** How many seals this node emitted on its own ROUND-CHANGEs since startup. */
+ private final java.util.concurrent.atomic.AtomicLong roundChangesSealed =
+ new java.util.concurrent.atomic.AtomicLong();
+
+ private final boolean signingEnabled;
+ private final int localIndex;
+ private final FalconPrivateKeyParameters localPrivateKey;
+ private final Map<Integer, FalconPublicKeyParameters> registry;
+
+ /**
+ * Validator ADDRESS bound to each registry index (AUD-CONSENSUS-1 fix). Populated in lockstep
+ * with {@link #registry} from an address-bound manifest; empty for the legacy pubkey-only source.
+ * This is the map that makes {@code currentValidators INTERSECT registry} computable.
+ */
+ private final Map<Integer, Address> indexToAddress;
+
+ private final boolean genesisAnchored;
+
+ /**
+ * AERE A8: the registry file this node ACTUALLY used, and which of the three sources it came from.
+ * Recorded so the consensus-binding guard can re-read exactly that file and hash it, rather than
+ * hashing something adjacent to it. Null when no registry is configured at all.
+ */
+ private final String registrySourcePath;
+
+ private final PqRegistryHash.SourceKind registrySourceKind;
+
+ /** Outcome of the A8 registry-binding guard; NOT_CHECKED equivalent is null until it has run. */
+ private volatile PqRegistryHash.GateState registryBindingState;
+
+ /**
+ * AERE A8 (per-block half): the schedule the startup guard actually enforced, the registry object
+ * it hashed, and the chain id it hashed under. Held so that {@link #registryBindingSatisfiedAt}
+ * can answer the SAME question on the per-block consensus path without re-reading a file 61
+ * million times a year, and without a second, drifting copy of the decision.
+ *
+ * <p>Null until the guard has run. Null means the per-block rule is INERT, which is the only safe
+ * default: a node whose controller never called the guard (a non-QBFT path, or a unit test) must
+ * not start rejecting headers because of a binding nobody configured.
+ */
+ private volatile PqRegistryHash.Schedule registryBindingSchedule;
+
+ private volatile PqRegistryHash.Registry registryBindingLoaded;
+
+ /**
+ * D-081: every registry this node holds, bound to the schedule entry each one satisfies.
+ *
+ * <p>{@link #registryBindingLoaded} above is the registry for the HEAD, and it is what the node
+ * signs with. It is kept because every diagnostic message names it. This field is the whole
+ * scheduled history, and it is what the per-block binding question and height-resolved
+ * verification are answered from. With no history configured the set holds exactly the one
+ * registry above, so both answers are bit-for-bit what they were before D-081.
+ */
+ private volatile PqRegistryHash.RegistrySet registryBindingSet;
+
+ /** D-081: per (schedule entry, index) Falcon public keys, built on demand from the set. */
+ private final Map<String, FalconPublicKeyParameters> historicalKeys = new ConcurrentHashMap<>();
+
+ private volatile long registryBindingChainId;
+
+ /** Highest height at which the per-block binding rule has already shouted, to bound the log. */
+ private final java.util.concurrent.atomic.AtomicLong registryBindingLastShout =
+ new java.util.concurrent.atomic.AtomicLong(-1L);
+
+ /**
+ * AERE OPTIUNI-URGENTA (2026-08-02): the operator has EXPLICITLY asked this node to run even
+ * though its Falcon registry does not satisfy the binding genesis requires.
+ *
+ * <p>WHY THIS EXISTS AT ALL. The A8 guard is a CONFIGURATION guard: it refuses to start a node
+ * whose registry file is not the one the chain names. That refusal is correct and it is
+ * fail-closed, and it also means a single bad registry file pushed to the fleet takes the fleet
+ * down and the only documented way back was to rebuild or to hand-edit a service unit at whatever
+ * hour it happened. This flag is the way back. It is read ONCE, in the constructor, from {@value
+ * #PROPERTY_REGISTRY_MISMATCH_ALLOW} or its environment form, which is where the command-line
+ * option {@code --Xaere-pq-registry-mismatch-allow} writes.
+ *
+ * <p>WHY IT IS NOT A QUIET ONE. A silent bypass is worse than no bypass, because a fleet can run
+ * for months on it and nobody finds out until the property it was supposed to guarantee is needed.
+ * So: a full-width banner at startup, and one complete ERROR line at EVERY height at which the
+ * bypass actually carries weight, for as long as the node runs.
+ */
+ private final boolean registryMismatchAllow;
+
+ /**
+ * True once the bypass has ACTUALLY suppressed a refusal, at startup or on the block path. Distinct
+ * from {@link #registryMismatchAllow}, which only says the operator armed it: a node whose registry
+ * is fine must not announce that it is running unverified.
+ */
+ private volatile boolean registryOverrideEngaged;
+
+ /** Highest height at which the unsafe-override announcement has already been made. */
+ private final java.util.concurrent.atomic.AtomicLong registryOverrideLastShout =
+ new java.util.concurrent.atomic.AtomicLong(-1L);
+
+ private volatile String manifestHash;
+
+ // ---- STAGE-2 LATE-ANCHOR (contract-anchored) state ----
+ /** Parsed-but-not-yet-activated manifest pubkeys (validator index -> Falcon-512 pubkey). */
+ private final Map<Integer, FalconPublicKeyParameters> pendingLate;
+ /** Parsed-but-not-yet-activated validator addresses (validator index -> address). */
+ private final Map<Integer, Address> pendingLateAddresses;
+ /** keccak256(canonical pending manifest), 64-hex no 0x; null when no late manifest configured. */
+ private final String pendingLateHash;
+ /** The on-chain anchor CONTRACT address (0x-hex) whose slot 0 must equal pendingLateHash. */
+ private final String anchorContractAddress;
+
+ private volatile boolean lateActivated;
+ private volatile boolean lateFailed;
+
+ // ---- AERE FIX-OPRIRE-CONSENS: SEAL-ATTACHMENT GATE ----
+ //
+ // The halting bug this state exists to prevent: seal ATTACHMENT used to be gated on nothing but
+ // key presence. The moment an operator dropped a Falcon key onto one validator and restarted it,
+ // that node began emitting Falcon-carrying Commit messages. Every peer still running the stock
+ // binary decodes Commit with a STRICT rlpInput.leaveList(), threw MalformedRLPInputException, and
+ // DISCARDED the entire Commit - including the decisive ECDSA seal it carried. A rolling
+ // key-by-key restart therefore walks the fleet straight through a state where the stock nodes
+ // cannot see enough ECDSA commit seals to reach quorum.
+ //
+ // The gate makes that order impossible: attachment is OFF until an explicitly configured
+ // ACTIVATION HEIGHT is reached AND the anchored registry covers every current validator. Both are
+ // fleet-wide facts, identical on every node, so all nodes flip together at the same block. Key
+ // presence alone now does nothing at all.
+
+ /** Minimum gap required between the attachment height and the blocking fork height. */
+ private static final long DEFAULT_MIN_ATTACH_LEAD = 256L;
+
+ /**
+ * Minimum validator-set size for which BLOCKING Falcon quorum may be armed. At N=7 the Falcon
+ * quorum (5 of 7) equals the ECDSA quorum, so the Falcon layer has ZERO extra fault margin: a
+ * single keyed validator whose Falcon key is faulty or whose process is down becomes a new
+ * liveness dependency and stops the chain. N&gt;=9 restores a one-fault Falcon margin.
+ */
+ private static final int MIN_BLOCKING_VALIDATORS = 9;
+
+ // ---- AERE ARMING GUARD (2026-08-01): the CHAIN-RELATIVE half of the attachment guard ----
+ //
+ // The constructor-time guards below can only check the configuration against ITSELF. They have no
+ // chain, so they cannot answer the one question that matters most: is the configured attachment
+ // height still AHEAD of us? Measured hole (run P1-PAST-ATTACH-RESTART): a fleet configured exactly
+ // per the documented activation order, with aere.falcon.attachBlock UNSET everywhere, emitted
+ // nothing for 60 s. One validator was then restarted with aere.falcon.attachBlock=5 while the
+ // chain head was 19. It started with no complaint and ARMED at block 21, and each of the four
+ // stock peers immediately began discarding its Commit messages. A procedure is not a guard.
+ //
+ // Two things must be true for the fleet to flip together at one block:
+ // (i) the height has not already gone by; and
+ // (ii) every node is already PARTICIPATING in consensus before that height arrives, otherwise a
+ // node that is still starting up arms at the first block it commits, which is a different
+ // block from the rest of the fleet. Measured on the scratch fleet: 45.2 s elapse between
+ // the startup config guard and the first commit this node takes part in.
+ // The margin below is what makes (ii) true, which is why it is a margin and not a mere > head.
+
+ /**
+ * Default number of blocks by which {@code aere.falcon.attachBlock} must LEAD this node's local
+ * chain head at startup. Sized from the measured startup-to-first-commit window (45.2 s, i.e. ~46
+ * blocks on the 1 s scratch fleet) with a wide safety factor, so that a node which is still
+ * opening its database, syncing and joining the network cannot have the activation height arrive
+ * underneath it. Chains with a sub-second block period must RAISE this: see
+ * GARDA-ACTIVARE-2026-08-01.md for the sizing formula.
+ */
+ private static final long DEFAULT_MIN_ATTACH_FUTURE_MARGIN = 1024L;
+
+ /**
+ * How many blocks back from the chain head the startup guard looks for positive proof that the
+ * fleet has ALREADY armed at the configured height (a header carrying at least one Falcon seal).
+ * Once the fleet arms, every subsequent block carries seals, so the evidence is at the head; the
+ * lookback only absorbs a short tail.
+ */
+ private static final int ACTIVATION_EVIDENCE_LOOKBACK = 128;
+
+ /**
+ * File written inside the node's data directory when the startup guard ADMITS an attachment height
+ * that was safely in the future. Its only job is to tell a later restart "this node was already
+ * admitted with this exact activation height, on this exact registry", so that a crash during an
+ * activation window is not turned into a permanent refusal to start.
+ */
+ private static final String ADMISSION_RECEIPT_FILE = "aere-falcon-activation.receipt";
+
+ /**
+ * D-081: the registries this node holds for SCHEDULED HEIGHTS IT IS NO LONGER AT, as a
+ * comma-separated list of files. Env: {@code AERE_FALCON_REGISTRY_HISTORY}.
+ *
+ * <p>WHY A SECOND PROPERTY AND NOT A LIST IN THE FIRST. {@code aere.falcon.registry} names the
+ * registry this node SIGNS with, and there can only ever be one of those. This names the ones it
+ * must still be able to VERIFY against, and there is one per rotation the chain has ever done.
+ * Keeping them apart means a rotation adds a file to this list and changes the first property, and
+ * neither operation can be confused with the other.
+ *
+ * <p>The list is never pruned. Cosmos ADR-016 may bound its rotation history by the unbonding
+ * period; chain 2800 has no unbonding period and a node syncing from genesis verifies every block
+ * ever produced, so every registry ever scheduled has to stay here forever.
+ */
+ public static final String PROPERTY_REGISTRY_HISTORY = "aere.falcon.registry.history";
+
+ /**
+ * AERE OPTIUNI-URGENTA: system property behind the command-line option {@code
+ * --Xaere-pq-registry-mismatch-allow}. Env: {@code AERE_PQ_REGISTRY_MISMATCH_ALLOW}. Setting it
+ * lets this node start and keep running with a Falcon registry that does NOT satisfy the binding
+ * genesis requires, at the price of one full ERROR line at every height where that matters.
+ */
+ public static final String PROPERTY_REGISTRY_MISMATCH_ALLOW = "aere.pq.registry.mismatchAllow";
+
+ /** Environment-variable form of {@link #PROPERTY_REGISTRY_MISMATCH_ALLOW}. */
+ public static final String ENV_REGISTRY_MISMATCH_ALLOW = "AERE_PQ_REGISTRY_MISMATCH_ALLOW";
+
+ /**
+ * AERE D-079: the DECLARED height at or after which the on-chain late-anchor registry contract is
+ * expected to be observable. Mandatory whenever a blocking fork height is armed over a late-anchor
+ * registry that is still pending; see {@link #validateAnchorObservationHeightOrAbort}.
+ */
+ public static final String PROPERTY_ANCHOR_OBSERVE_BLOCK = "aere.falcon.anchor.block";
+
+ /** Environment-variable form of {@link #PROPERTY_ANCHOR_OBSERVE_BLOCK}. */
+ public static final String ENV_ANCHOR_OBSERVE_BLOCK = "AERE_FALCON_ANCHOR_BLOCK";
+
+ /** Activation height for seal ATTACHMENT; Long.MAX_VALUE means NEVER attach. */
+ private final long attachBlock;
+
+ /**
+ * AERE D-079: the BLOCKING height, resolved and validated exactly ONCE, at construction, and
+ * owned thereafter. Long.MAX_VALUE means never blocking.
+ *
+ * <p>It used to be a property read on every call to {@link #forkBlock()}, with a
+ * NumberFormatException swallowed into "never blocking, log-only" plus one WARN line. The startup
+ * guard added for AUD-CONSENSUS-3 validated the property but did not TAKE it, so the one value the
+ * whole PQC layer is gated on could still turn itself off after the guard had passed, at any call,
+ * on any input the guard never saw. A value that is checked at the boundary and re-parsed at every
+ * use is not checked. It is parsed here, once, or the node does not start.
+ */
+ private final long forkBlock;
+
+ /**
+ * AERE D-079: the height at and after which the on-chain LATE-ANCHOR registry contract is expected
+ * to be observable, as DECLARED by the operator. Long.MAX_VALUE when undeclared.
+ *
+ * <p>This value does not activate anything. It exists because without it the ordering that the
+ * whole late-anchor activation depends on cannot be stated, and therefore cannot be checked: the
+ * registry becomes usable at a height that only the chain knows, while blocking arms at a height
+ * only the configuration knows. Declaring it is what lets the two be compared before the node
+ * joins the network.
+ */
+ private final long anchorObserveBlock;
+
+ /**
+ * AERE D-079: first height at which this node validated a header at or after the blocking height
+ * while the anchored registry was NOT active, or -1 if that has never happened.
+ *
+ * <p>This is the residual the configuration guard cannot close: an operator may declare the
+ * observation height correctly and the anchor transaction may still fail to land. The header rule
+ * deliberately stays LOG-ONLY there rather than halt the chain (see AUD-CONSENSUS-4), which is the
+ * right trade and is also exactly how the condition used to disappear: log-only, one line, nothing
+ * a command could ever read. Now it leaves a mark.
+ */
+ private final AtomicLong blockingArmedWithoutRegistrySince = new AtomicLong(-1L);
+
+ /** Outcome of the chain-relative startup guard; NOT_CHECKED until it has run. */
+ private volatile ChainRelativeGateState chainRelativeState = ChainRelativeGateState.NOT_CHECKED;
+
+ /** Height at which activation evidence was found on chain, or -1. */
+ private volatile long armedEvidenceHeight = -1L;
+
+ /** Latest validator set observed from the header-validation path, or null if never observed. */
+ private volatile Set<Address> observedValidators;
+
+ /** Height at which {@link #observedValidators} was captured. */
+ private volatile long observedValidatorsHeight = -1L;
+
+ /** One-shot latches so the gate diagnostics do not spam one line per block. */
+ private final AtomicBoolean loggedAttachmentOff = new AtomicBoolean(false);
+
+ private final AtomicBoolean loggedAttachmentOn = new AtomicBoolean(false);
+
+ private final AtomicBoolean loggedCoverageBlocked = new AtomicBoolean(false);
+
+ /**
+ * D2 HARDENING (b): the once-only latch for the refusal to resolve keys at an armed height with no
+ * height-to-registry binding. One line per block at a 523 ms period is a hazard, not a diagnostic.
+ */
+ private final AtomicBoolean loggedUnboundArmedHeight = new AtomicBoolean(false);
+
+ /**
+ * AERE D-078 (2026-08-02): the last coverage situation this node reported, as "N/R", so the
+ * coverage line is emitted exactly when the situation CHANGES and not once per block. Null means
+ * nothing has been reported yet.
+ */
+ private volatile String lastCoverageSignature;
+
+ private FalconSealSupport() {
+ int idx = -1;
+ FalconPrivateKeyParameters priv = null;
+ final Map<Integer, FalconPublicKeyParameters> reg = new ConcurrentHashMap<>();
+ final Map<Integer, Address> regAddr = new ConcurrentHashMap<>();
+ String mHash = null;
+ boolean anchored = false;
+ Map<Integer, FalconPublicKeyParameters> late = null;
+ Map<Integer, Address> lateAddr = null;
+ String lateHash = null;
+ String anchorAddr = null;
+
+ // Registry source resolution order:
+ // 1) GENESIS-ANCHORED manifest (aere.falcon.genesis) - tamper-evident, immutable, preferred.
+ // 2) LATE-ANCHOR manifest + contract (aere.falcon.manifest + aere.falcon.anchor.address) -
+ // Stage-2 activation path for an ALREADY-LIVE chain: pending until the anchor contract is
+ // observed on-chain and the manifest hash matches (fail-closed).
+ // 3) LEGACY shared .properties file (aere.falcon.registry) - backward-compatible fallback.
+ final String genesisPath = resolve("aere.falcon.genesis", "AERE_FALCON_GENESIS");
+ final String manifestPath = resolve("aere.falcon.manifest", "AERE_FALCON_MANIFEST");
+ final String anchorProp = resolve("aere.falcon.anchor.address", "AERE_FALCON_ANCHOR_ADDRESS");
+ final String registryPath = resolve("aere.falcon.registry", "AERE_FALCON_REGISTRY");
+ if (genesisPath != null) {
+ mHash = loadGenesisAnchoredRegistry(genesisPath, reg, regAddr);
+ anchored = mHash != null;
+ } else if (manifestPath != null && anchorProp != null) {
+ final Map<Integer, FalconPublicKeyParameters> pend = new HashMap<>();
+ final Map<Integer, Address> pendAddr = new HashMap<>();
+ lateHash = loadPendingLateManifest(manifestPath, pend, pendAddr);
+ if (lateHash != null) {
+ late = pend;
+ lateAddr = pendAddr;
+ anchorAddr = anchorProp.trim();
+ LOG.info(
+ "AERE PQC: LATE-ANCHOR manifest loaded from {} ({} entries, address-bound={}), "
+ + "keccak256(manifest)=0x{}; registry PENDING until the on-chain anchor contract "
+ + "{} (slot 0) is observed to match. Fail-closed on mismatch.",
+ manifestPath,
+ pend.size(),
+ !pendAddr.isEmpty() && pendAddr.size() == pend.size(),
+ lateHash,
+ anchorAddr);
+ } else {
+ LOG.error(
+ "AERE PQC: failed to load LATE-ANCHOR manifest from {}; registry EMPTY (fail-closed).",
+ manifestPath);
+ }
+ } else if (registryPath != null) {
+ // AERE A8 REPAIR (2026-08-02): the properties source the design prescribed was measured to
+ // HALT EVERY NODE at the activation height. Not by being mutable, and not by disagreeing with
+ // a hash: by carrying public keys and NO ADDRESSES. addressForIndex() then returns null for
+ // every index, and the V2 seals rule (R2) refuses every header that carries a certificate.
+ // Measured on three observers with the data directory wiped, on the SAME honest chain:
+ // genesis-anchored address-bound registry reached head 374 with R1=0 R2=0, while this source
+ // stopped at head 19 with R2=4 rejections, indistinguishable from having no registry at all.
+ //
+ // The repair is in two halves and both are needed. FIRST, this loader now reads the optional
+ // "<i>.addr=0x<20 bytes>" row, exactly the shape PqRegistryHash.loadPropertiesRegistry
+ // already accepts, so the prescribed source CAN be address-bound and CAN carry the fleet past
+ // activation. SECOND, armingReadinessDiagnostic() below no longer merely logs when an
+ // activation is configured over a registry that is still pubkey-only: it refuses to start.
+ // A loud refusal at startup and a silent fleet-wide halt at the activation height are not the
+ // same event, and only one of them is survivable.
+ try (InputStream in = new FileInputStream(registryPath)) {
+ final Properties p = new Properties();
+ p.load(in);
+ final Map<Integer, Address> propAddr = new java.util.TreeMap<>();
+ for (final String name : p.stringPropertyNames()) {
+ if ("count".equals(name)) {
+ continue;
+ }
+ try {
+ final String key = name.trim();
+ if (key.endsWith(".addr")) {
+ final int i = Integer.parseInt(key.substring(0, key.length() - ".addr".length()));
+ final byte[] a = Bytes.fromHexStringLenient(p.getProperty(name).trim()).toArray();
+ if (a.length != 20) {
+ throw new IllegalArgumentException(
+ "address is " + a.length + " bytes, expected exactly 20");
+ }
+ // Built through the canonical hex of the VALIDATED 20 bytes, not from the raw string
+ // and not through Address.wrap: the lenient hex parser above accepts shapes the
+ // strict one does not, so re-rendering the checked bytes is the only spelling that
+ // cannot disagree with the length check that just passed.
+ propAddr.put(i, Address.fromHexString(Bytes.wrap(a).toHexString()));
+ } else {
+ final int i = Integer.parseInt(key);
+ final byte[] h = Bytes.fromHexStringLenient(p.getProperty(name).trim()).toArray();
+ reg.put(i, new FalconPublicKeyParameters(FalconParameters.falcon_512, h));
+ }
+ } catch (final RuntimeException e) {
+ LOG.warn("Skipping malformed Falcon registry entry '{}': {}", name, e.toString());
+ }
+ }
+ // Address binding is ALL-OR-NOTHING. A half-bound registry is worse than an unbound one:
+ // some indices would resolve and some would not, so the fleet would reject a header that
+ // one operator can verify and another cannot, which is defect A8 wearing a different hat.
+ final boolean fullyBound = !reg.isEmpty() && propAddr.keySet().equals(reg.keySet());
+ if (fullyBound) {
+ regAddr.putAll(propAddr);
+ } else if (!propAddr.isEmpty()) {
+ LOG.error(
+ "AERE PQC A8: LEGACY registry file {} carries {} '<i>.addr' rows for {} keys. A "
+ + "PARTIALLY address-bound registry is refused as a binding source (all-or-"
+ + "nothing): some indices would resolve to a validator address and some would "
+ + "not, so two nodes would disagree about which headers are valid. Treating this "
+ + "registry as pubkey-only.",
+ registryPath,
+ propAddr.size(),
+ reg.size());
+ }
+ LOG.info(
+ "AERE PQC: loaded Falcon validator registry ({} entries, address-bound={}) from LEGACY "
+ + "file {} (mutable; superseded by aere.falcon.genesis / aere.falcon.manifest). "
+ + "{}",
+ reg.size(),
+ fullyBound,
+ registryPath,
+ fullyBound
+ ? "Address-bound, so the eligible-signer intersection is computable and this "
+ + "registry CAN carry the fleet past an activation height; it is still bound to "
+ + "consensus only if config.pqRegistryHash names its hash."
+ : "PUBKEY-ONLY, so addressForIndex() returns null for every index and EVERY header "
+ + "carrying a certificate would be rejected at the activation height. NOT "
+ + "eligible to arm blocking.");
+ } catch (final Exception e) {
+ LOG.warn(
+ "AERE PQC: failed to load Falcon registry from {}: {}", registryPath, e.toString());
+ }
+ } else {
+ LOG.info(
+ "AERE PQC: no Falcon registry configured (aere.falcon.genesis/aere.falcon.manifest/"
+ + "aere.falcon.registry); hybrid seal verification will be a no-op.");
+ }
+
+ // Load this node's Falcon private key (only present on validators that should sign).
+ final String keyPath = resolve("aere.falcon.key", "AERE_FALCON_KEY");
+ if (keyPath != null) {
+ try (InputStream in = new FileInputStream(keyPath)) {
+ final Properties p = new Properties();
+ p.load(in);
+ idx = Integer.parseInt(p.getProperty("index").trim());
+ final byte[] f = Bytes.fromHexStringLenient(p.getProperty("f").trim()).toArray();
+ final byte[] g = Bytes.fromHexStringLenient(p.getProperty("g").trim()).toArray();
+ final byte[] bigF = Bytes.fromHexStringLenient(p.getProperty("F").trim()).toArray();
+ final byte[] pk = Bytes.fromHexStringLenient(p.getProperty("pk").trim()).toArray();
+ priv = new FalconPrivateKeyParameters(FalconParameters.falcon_512, f, g, bigF, pk);
+ LOG.info(
+ "AERE PQC: loaded local Falcon signing key for validator index {} from {}",
+ idx,
+ keyPath);
+ } catch (final Exception e) {
+ LOG.warn("AERE PQC: failed to load Falcon signing key from {}: {}", keyPath, e.toString());
+ idx = -1;
+ priv = null;
+ }
+ }
+
+ this.registry = reg;
+ this.indexToAddress = regAddr;
+ this.localIndex = idx;
+ this.localPrivateKey = priv;
+ this.signingEnabled = priv != null && idx >= 0;
+ this.manifestHash = mHash;
+ this.genesisAnchored = anchored;
+ this.pendingLate = late;
+ this.pendingLateAddresses = lateAddr;
+ this.pendingLateHash = lateHash;
+ this.anchorContractAddress = anchorAddr;
+
+ // AERE A8: remember WHICH file the registry came from, so the consensus-binding guard hashes
+ // the file this node is really running on and not a different one that happens to be nearby.
+ if (genesisPath != null) {
+ this.registrySourcePath = genesisPath;
+ this.registrySourceKind = PqRegistryHash.SourceKind.GENESIS_MANIFEST;
+ } else if (manifestPath != null && anchorProp != null) {
+ this.registrySourcePath = manifestPath;
+ this.registrySourceKind = PqRegistryHash.SourceKind.MANIFEST_JSON;
+ } else if (registryPath != null) {
+ this.registrySourcePath = registryPath;
+ this.registrySourceKind = PqRegistryHash.SourceKind.LEGACY_PROPERTIES;
+ } else {
+ this.registrySourcePath = null;
+ this.registrySourceKind = PqRegistryHash.SourceKind.NONE;
+ }
+
+ // AERE OPTIUNI-URGENTA (2026-08-02): read the registry bypass ONCE, here, so that every later
+ // decision reads one immutable field rather than re-resolving a property that could have been
+ // changed underneath it. Announced immediately, whether or not it ends up carrying weight,
+ // because "somebody armed the bypass on this node" is itself something an operator must be able
+ // to see in the first screen of the log.
+ this.registryMismatchAllow =
+ Boolean.parseBoolean(
+ resolve(PROPERTY_REGISTRY_MISMATCH_ALLOW, ENV_REGISTRY_MISMATCH_ALLOW));
+ if (this.registryMismatchAllow) {
+ LOG.warn(
+ "AERE PQC EMERGENCY [AERE-PQC-EMG-REGALLOW-01]: the Falcon registry binding bypass is "
+ + "ARMED on this node ({}). If the registry this node holds does NOT satisfy what "
+ + "genesis requires, this node will START ANYWAY and will keep importing headers "
+ + "whose certificates it cannot correctly verify, and it will say so at every height "
+ + "where that is true. This is a RECOVERY setting. It is not a configuration to leave "
+ + "in place: remove it as soon as the correct registry is installed.",
+ PROPERTY_REGISTRY_MISMATCH_ALLOW);
+ }
+
+ // AERE audit fix (AUD-CONSENSUS-3): fail-closed on a MALFORMED fork-block config at startup,
+ // before anything else. A present-but-unparseable aere.falcon.forkBlock must not silently
+ // degrade to never-blocking (log-only); it aborts node init here (config time, NOT the per-block
+ // consensus path).
+ // AERE D-079: the result is TAKEN, not merely checked. Nothing re-reads the property afterwards.
+ this.forkBlock = validateForkBlockConfigOrAbort();
+
+ // AERE FIX-OPRIRE-CONSENS (b): resolve and validate the ATTACHMENT gate. Every inconsistent
+ // combination aborts here, at config time, before the node joins the network - never as a
+ // surprise mid-chain.
+ this.attachBlock = validateAndResolveAttachBlockOrAbort(this.forkBlock);
+
+ // AERE D-079: the ORDER between the blocking height and the height at which the registry that
+ // backs it can become active. Aborts here, at config time, for the same reason as everything
+ // above it: after the node has joined, the same error is a silent degradation to log-only.
+ this.anchorObserveBlock =
+ validateAnchorObservationHeightOrAbort(this.forkBlock, this.attachBlock);
+
+ // AERE audit fix (AUD-CONSENSUS-1): fail-closed ARMING diagnostic at config/startup time.
+ // If a fork block is configured (blocking is intended) but the manifest that WILL back it is
+ // not address-bound, the eligible-signer intersection cannot be formed and every post-fork
+ // block will fail closed. Surface that LOUDLY here, at arm/config time, rather than as a silent
+ // block-production halt later. (Late-anchor: the pending manifest is checked; the live registry
+ // is still empty until activation, which is expected.)
+ armingReadinessDiagnostic();
+
+ // AERE D-146 (2026-08-06): the SECOND arming question, and the one AERE-PQC-REG-ARM-01 cannot
+ // answer. Address-bound says every index has SOME address next to it. It does not say that the
+ // validator at that address ever held the Falcon key filed under it. Measured on the real
+ // verification path on 2026-08-06: a registry with two rows' public keys swapped - no duplicate
+ // key, no duplicate address, so no uniqueness check would have seen it - produced an ACCEPTED
+ // header, and one key placed at two indices satisfied a threshold of two on its own.
+ requireRegistryBindingProofsOrAbort();
+
+ // AERE D-078 (2026-08-03): the arm-time comparison the repair above NAMED and did not make.
+ // armingReadinessDiagnostic() answers "is the manifest address-bound"; it never asks whether the
+ // threshold the fleet is about to arm is one the fleet can be guaranteed to MEET.
+ validateThresholdReachabilityOrAbort();
+ }
+
+ /**
+ * AERE audit fix (AUD-CONSENSUS-3): distinguish an UNSET fork block from a MALFORMED configured
+ * one. {@link #forkBlock()} on the per-block path deliberately never throws (it falls back to
+ * {@link Long#MAX_VALUE}); on its own that means a typo'd fork block fails OPEN to never-blocking,
+ * asymmetric with the manifest / anchor loaders that all fail CLOSED. This startup guard closes
+ * that gap: if the property/env IS present but does not parse as a NON-NEGATIVE block number, we
+ * ABORT node init (fail-closed). This runs at construction (node init), not during block
+ * validation, so it never throws on the consensus path. An UNSET value keeps the safe
+ * never-blocking log-only default.
+ *
+ * <p>AERE D-079 (2026-08-03): it now RETURNS the validated height and the constructor keeps it in
+ * a final field. Validating a value and then re-reading its source on every use leaves the
+ * original defect intact one level down, which is exactly where it was found.
+ *
+ * @return the validated blocking height, or {@link Long#MAX_VALUE} when unset
+ */
+ private long validateForkBlockConfigOrAbort() {
+ final String v = resolve("aere.falcon.forkBlock", "AERE_FALCON_FORKBLOCK");
+ if (v == null) {
+ return Long.MAX_VALUE; // unset: safe never-blocking default, nothing to validate
+ }
+ final long parsed;
+ try {
+ parsed = Long.parseLong(v.trim());
+ } catch (final NumberFormatException e) {
+ throw new ActivationConfigException(
+ ActivationConfigException.Kind.SYNTAX,
+ "AERE-PQC-CFG-SYNTAX-03",
+ "AERE PQC: aere.falcon.forkBlock is set to a MALFORMED value '"
+ + v
+ + "' (not an integer block number). Refusing to start (fail-closed): a malformed fork "
+ + "block must not silently degrade to never-blocking / log-only. Set a valid "
+ + "non-negative block number, or UNSET the property to run the additive log-only "
+ + "baseline.");
+ }
+ if (parsed < 0) {
+ throw new ActivationConfigException(
+ ActivationConfigException.Kind.SYNTAX,
+ "AERE-PQC-CFG-SYNTAX-04",
+ "AERE PQC: aere.falcon.forkBlock '"
+ + v
+ + "' is negative. Refusing to start (fail-closed): set a valid non-negative block "
+ + "number, or UNSET the property to run the additive log-only baseline.");
+ }
+ return parsed;
+ }
+
+ /**
+ * AERE D-079: the ordering guard between the BLOCKING height and the height at which the registry
+ * that backs it can first be active.
+ *
+ * <p>THE HOLE THIS CLOSES, in the words of the code that documented it and did nothing about it.
+ * {@code FalconSealValidationRule} says: "If forkBlock is armed at or before the late-anchor
+ * observation height, the registry is not yet active when the fork block is validated". Its answer
+ * is to stay LOG-ONLY, which is the correct answer for a header rule - blocking over an empty
+ * registry provides zero safety and only a halt. But it means the misconfiguration has no
+ * consequence a node can be stopped by and no consequence a command can read: the operator asked
+ * for a post-quantum quorum, the node said yes, and the quorum is never enforced.
+ *
+ * <p>The check cannot be made against the chain, because the height at which an anchor contract
+ * lands is not knowable at config time. It is therefore made against a DECLARED height, {@code
+ * aere.falcon.anchor.block}, in the same spirit as EIP-7910's {@code eth_config}: state the fork
+ * parameters explicitly so they can be compared, instead of inferring them and finding out at the
+ * boundary. Declaring the height is mandatory whenever blocking is armed over a registry that is
+ * still pending, because a value nobody stated is a value nobody can check.
+ *
+ * <p>Only two rules are needed, and the second one implies what the finding is named after:
+ *
+ * <ol>
+ * <li>a blocking height over a PENDING late anchor with no declared observation height aborts;
+ * <li>{@code attachBlock < anchorObserveBlock} aborts. Because {@code forkBlock - attachBlock >=
+ * minAttachLead} is already enforced above, this makes {@code forkBlock > anchorObserveBlock
+ * + minAttachLead} a THEOREM rather than a third rule that could drift out of step with the
+ * other two.
+ * </ol>
+ *
+ * <p>Genesis-anchored and legacy-file registries are exempt on purpose: both are active from block
+ * 0, so there is no observation height to compare against and demanding one would break the
+ * deployment path that {@link #armingReadinessDiagnostic()} names as the remedy.
+ *
+ * @param fork the validated blocking height
+ * @param attach the validated attachment height
+ * @return the declared observation height, or {@link Long#MAX_VALUE} when undeclared
+ */
+ private long validateAnchorObservationHeightOrAbort(final long fork, final long attach) {
+ final String raw = resolve(PROPERTY_ANCHOR_OBSERVE_BLOCK, ENV_ANCHOR_OBSERVE_BLOCK);
+ final long observe;
+ if (raw == null) {
+ observe = Long.MAX_VALUE;
+ } else {
+ final long parsed;
+ try {
+ parsed = Long.parseLong(raw.trim());
+ } catch (final NumberFormatException e) {
+ throw new ActivationConfigException(
+ ActivationConfigException.Kind.SYNTAX,
+ "AERE-PQC-CFG-SYNTAX-09",
+ "AERE PQC: "
+ + PROPERTY_ANCHOR_OBSERVE_BLOCK
+ + " is set to a MALFORMED value '"
+ + raw
+ + "' (not an integer block number). Refusing to start (fail-closed): every "
+ + "aere.falcon.* height fails closed on a syntax error, uniformly, because a "
+ + "half-fail-closed property set is worse than either extreme - nobody can predict "
+ + "which half they are in.");
+ }
+ if (parsed < 0) {
+ throw new ActivationConfigException(
+ ActivationConfigException.Kind.SYNTAX,
+ "AERE-PQC-CFG-SYNTAX-10",
+ "AERE PQC: "
+ + PROPERTY_ANCHOR_OBSERVE_BLOCK
+ + " '"
+ + raw
+ + "' is negative. Refusing to start (fail-closed).");
+ }
+ observe = parsed;
+ }
+
+ // Nothing blocking is configured, or the registry is already active at block 0. In both cases
+ // there is no ordering to violate.
+ if (fork == Long.MAX_VALUE || genesisAnchored || anchorContractAddress == null) {
+ return observe;
+ }
+
+ if (raw == null) {
+ throw new ActivationConfigException(
+ ActivationConfigException.Kind.UNSAFE,
+ "AERE-PQC-CFG-UNSAFE-06",
+ "AERE PQC: aere.falcon.forkBlock is set to "
+ + fork
+ + " (Falcon quorum BLOCKING) over a LATE-ANCHOR registry that is still PENDING (anchor "
+ + "contract "
+ + anchorContractAddress
+ + "), and "
+ + PROPERTY_ANCHOR_OBSERVE_BLOCK
+ + " is UNDECLARED. Refusing to start (fail-closed). WHY THIS IS REFUSED RATHER THAN "
+ + "WARNED: if the anchor is observed at or after the blocking height, the registry is "
+ + "empty when the fork block is validated, and the header rule then stays LOG-ONLY "
+ + "forever - correctly, because blocking over an empty registry would only halt the "
+ + "chain. The result is a node that was told to enforce a post-quantum quorum, "
+ + "reported no error, and enforces nothing. Nothing on the node can detect that, "
+ + "because the height the registry becomes usable at is known only to the chain and "
+ + "the height blocking arms at is known only to this configuration. Declare "
+ + PROPERTY_ANCHOR_OBSERVE_BLOCK
+ + " as the height at or after which the anchor contract is expected to be observable, "
+ + "and set aere.falcon.attachBlock at or after it.");
+ }
+
+ if (attach < observe) {
+ throw new ActivationConfigException(
+ ActivationConfigException.Kind.UNSAFE,
+ "AERE-PQC-CFG-UNSAFE-07",
+ "AERE PQC: aere.falcon.attachBlock ("
+ + attach
+ + ") is BEFORE "
+ + PROPERTY_ANCHOR_OBSERVE_BLOCK
+ + " ("
+ + observe
+ + "), with aere.falcon.forkBlock="
+ + fork
+ + ". Refusing to start (fail-closed): until the anchor is observed the registry is "
+ + "empty, so no node can emit a Falcon seal, so the LOG-ONLY soak window between "
+ + "attachment and blocking observes nothing and proves nothing. Order the three "
+ + "heights "
+ + PROPERTY_ANCHOR_OBSERVE_BLOCK
+ + " <= aere.falcon.attachBlock, and aere.falcon.forkBlock at least "
+ + minAttachLead()
+ + " blocks after aere.falcon.attachBlock; that ordering is also the only thing that "
+ + "keeps the blocking height strictly AFTER the observation height, which is the "
+ + "configuration this guard exists to refuse.");
+ }
+
+ LOG.info(
+ "AERE PQC: activation ORDER accepted: {}={} <= attachBlock={}, forkBlock={} (lead {} >= "
+ + "{}). Blocking arms {} block(s) after the earliest height at which the anchored "
+ + "registry can be active.",
+ PROPERTY_ANCHOR_OBSERVE_BLOCK,
+ observe,
+ attach,
+ fork,
+ fork - attach,
+ minAttachLead(),
+ fork - observe);
+ return observe;
+ }
+
+ /**
+ * AERE FIX-OPRIRE-CONSENS (b): resolve and validate the seal-ATTACHMENT height. Runs at
+ * construction (node init), never on the consensus path. Every inconsistent combination ABORTS
+ * here, so a fleet can never be started into a configuration that halts it later.
+ *
+ * <p>Rules enforced:
+ *
+ * <ol>
+ * <li>a present but MALFORMED or negative attachBlock aborts (no silent degrade);
+ * <li>configuring BLOCKING ({@code aere.falcon.forkBlock}) without an attachBlock aborts: seals
+ * would never be emitted, so every post-fork block would fail closed and the chain would
+ * stop;
+ * <li>{@code attachBlock > forkBlock} aborts: blocking would arm before any seal exists;
+ * <li>{@code forkBlock - attachBlock} below the minimum lead aborts: the fleet needs a
+ * log-only window in which seals are demonstrably flowing and verifying before the quorum
+ * becomes decisive;
+ * <li>arming BLOCKING with a validator set smaller than {@link #MIN_BLOCKING_VALIDATORS}
+ * aborts, because at N&lt;9 the Falcon quorum has no fault margin over the ECDSA quorum
+ * (see the N=7 zero-margin finding). Isolated test networks opt out explicitly with
+ * {@code aere.falcon.testnetAllowSmallFleet=true}, which logs an ERROR every start.
+ * </ol>
+ *
+ * @param fork the already-validated blocking height (AERE D-079: passed in rather than re-parsed
+ * from the property, so this method and {@link #forkBlock()} cannot disagree about it)
+ * @return the resolved attachment height, or {@link Long#MAX_VALUE} when unset
+ */
+ private long validateAndResolveAttachBlockOrAbort(final long fork) {
+ final String rawAttach = resolve("aere.falcon.attachBlock", "AERE_FALCON_ATTACHBLOCK");
+
+ if (rawAttach == null) {
+ if (fork == Long.MAX_VALUE && signingEnabled) {
+ // The rolling-restart case: an operator dropped a Falcon key on this node and restarted it.
+ // Say plainly, at startup, that this does NOT arm anything.
+ LOG.warn(
+ "AERE PQC: this node HOLDS a Falcon signing key (index {}) but seal ATTACHMENT is NOT "
+ + "configured (aere.falcon.attachBlock unset), so NO Falcon-carrying Commit will be "
+ + "emitted. This is the safe default: emitting one while any peer still runs a "
+ + "binary with a strict Commit decoder would make that peer DISCARD the whole "
+ + "Commit, ECDSA seal included.",
+ localIndex);
+ }
+ if (fork != Long.MAX_VALUE) {
+ throw new ActivationConfigException(
+ ActivationConfigException.Kind.UNSAFE,
+ "AERE-PQC-CFG-UNSAFE-01",
+ "AERE PQC: aere.falcon.forkBlock is set to "
+ + fork
+ + " (Falcon quorum BLOCKING) but aere.falcon.attachBlock is UNSET. Refusing to "
+ + "start (fail-closed): with attachment off, no node ever emits a Falcon seal, so "
+ + "every block at or after the fork block would be rejected for want of a quorum "
+ + "certificate and the chain would STOP. Set aere.falcon.attachBlock to a height at "
+ + "least "
+ + minAttachLead()
+ + " blocks BEFORE the fork block, and only after the whole fleet runs a binary that "
+ + "can parse a Falcon-carrying Commit.");
+ }
+ return Long.MAX_VALUE;
+ }
+
+ final long attach;
+ try {
+ attach = Long.parseLong(rawAttach.trim());
+ } catch (final NumberFormatException e) {
+ throw new ActivationConfigException(
+ ActivationConfigException.Kind.SYNTAX,
+ "AERE-PQC-CFG-SYNTAX-01",
+ "AERE PQC: aere.falcon.attachBlock is set to a MALFORMED value '"
+ + rawAttach
+ + "' (not an integer block number). Refusing to start (fail-closed).");
+ }
+ if (attach < 0) {
+ throw new ActivationConfigException(
+ ActivationConfigException.Kind.SYNTAX,
+ "AERE-PQC-CFG-SYNTAX-02",
+ "AERE PQC: aere.falcon.attachBlock '" + rawAttach + "' is negative. Refusing to start.");
+ }
+
+ if (fork != Long.MAX_VALUE) {
+ if (attach > fork) {
+ throw new ActivationConfigException(
+ ActivationConfigException.Kind.UNSAFE,
+ "AERE-PQC-CFG-UNSAFE-02",
+ "AERE PQC: aere.falcon.attachBlock ("
+ + attach
+ + ") is AFTER aere.falcon.forkBlock ("
+ + fork
+ + "). Refusing to start (fail-closed): the Falcon quorum would become blocking "
+ + "before any Falcon seal is ever attached, rejecting every block.");
+ }
+ final long lead = fork - attach;
+ if (lead < minAttachLead()) {
+ throw new ActivationConfigException(
+ ActivationConfigException.Kind.UNSAFE,
+ "AERE-PQC-CFG-UNSAFE-03",
+ "AERE PQC: only "
+ + lead
+ + " block(s) between aere.falcon.attachBlock ("
+ + attach
+ + ") and aere.falcon.forkBlock ("
+ + fork
+ + "); the minimum lead is "
+ + minAttachLead()
+ + ". Refusing to start (fail-closed): the fleet needs a LOG-ONLY window in which "
+ + "seals are observably flowing and verifying before the quorum becomes decisive.");
+ }
+ final int fleet = expectedFleetSize();
+ final boolean smallFleetAllowed =
+ Boolean.parseBoolean(
+ String.valueOf(
+ resolve("aere.falcon.testnetAllowSmallFleet", "AERE_FALCON_TESTNET_SMALL_FLEET")));
+ if (fleet < MIN_BLOCKING_VALIDATORS && !smallFleetAllowed) {
+ throw new ActivationConfigException(
+ ActivationConfigException.Kind.UNSAFE,
+ "AERE-PQC-CFG-UNSAFE-04",
+ "AERE PQC: BLOCKING Falcon quorum is configured (forkBlock="
+ + fork
+ + ") for a fleet of "
+ + fleet
+ + " validator(s), below the minimum of "
+ + MIN_BLOCKING_VALIDATORS
+ + ". Refusing to start (fail-closed): at N<"
+ + MIN_BLOCKING_VALIDATORS
+ + " the Falcon quorum equals the ECDSA quorum, so the Falcon layer carries ZERO "
+ + "extra fault margin and any single keyed validator that is down or holds a faulty "
+ + "Falcon key becomes a new liveness dependency that stops the chain. Grow the "
+ + "validator set to at least "
+ + MIN_BLOCKING_VALIDATORS
+ + " first. Isolated test networks may set aere.falcon.testnetAllowSmallFleet=true.");
+ }
+ if (fleet < MIN_BLOCKING_VALIDATORS) {
+ LOG.error(
+ "AERE PQC: aere.falcon.testnetAllowSmallFleet=true - BLOCKING armed on a fleet of {} "
+ + "(< {}). ZERO Falcon fault margin. This setting MUST NOT be used on mainnet.",
+ fleet,
+ MIN_BLOCKING_VALIDATORS);
+ }
+ }
+
+ LOG.info(
+ "AERE PQC: seal-ATTACHMENT gate configured: attachBlock={}, forkBlock={}, minLead={}. "
+ + "Holding a Falcon key does NOT by itself emit a Falcon-carrying Commit.",
+ attach,
+ fork == Long.MAX_VALUE ? "unset" : Long.toString(fork),
+ minAttachLead());
+ return attach;
+ }
+
+ /**
+ * Minimum number of blocks between the attachment height and the blocking fork height.
+ *
+ * <p>AERE ARMING GUARD: this used to swallow a malformed value and silently return the default.
+ * That is the same silent-degrade defect the attachBlock guard exists to prevent, one level down:
+ * an operator who typed the margin wrong would believe a long soak window was enforced when the
+ * default was. Every {@code aere.falcon.*} value now fails closed on a syntax error, uniformly. A
+ * half-fail-closed property set is worse than either extreme, because nobody can predict which
+ * half they are in.
+ */
+ private long minAttachLead() {
+ final String v = resolve("aere.falcon.minAttachLead", "AERE_FALCON_MIN_ATTACH_LEAD");
+ if (v == null) {
+ return DEFAULT_MIN_ATTACH_LEAD;
+ }
+ final long parsed;
+ try {
+ parsed = Long.parseLong(v.trim());
+ } catch (final NumberFormatException e) {
+ throw new ActivationConfigException(
+ ActivationConfigException.Kind.SYNTAX,
+ "AERE-PQC-CFG-SYNTAX-07",
+ "AERE PQC: aere.falcon.minAttachLead is set to a MALFORMED value '"
+ + v
+ + "' (not an integer number of blocks). Refusing to start: a soak-window length that "
+ + "silently reverted to its default would leave the operator believing a longer soak "
+ + "is enforced than actually is.");
+ }
+ if (parsed < 0) {
+ throw new ActivationConfigException(
+ ActivationConfigException.Kind.SYNTAX,
+ "AERE-PQC-CFG-SYNTAX-07",
+ "AERE PQC: aere.falcon.minAttachLead '" + v + "' is negative. Refusing to start.");
+ }
+ return parsed;
+ }
+
+ /**
+ * Best available estimate of the validator-set size at config time, used only for the N&gt;=9
+ * blocking guard. The registry (or the pending late manifest) is address-bound one entry per
+ * validator, so its size is the fleet the operator intends to arm.
+ */
+ private int expectedFleetSize() {
+ final String v = resolve("aere.falcon.validatorCount", "AERE_FALCON_VALIDATOR_COUNT");
+ if (v != null) {
+ try {
+ return Integer.parseInt(v.trim());
+ } catch (final NumberFormatException e) {
+ throw new ActivationConfigException(
+ ActivationConfigException.Kind.SYNTAX,
+ "AERE-PQC-CFG-SYNTAX-08",
+ "AERE PQC: aere.falcon.validatorCount is set to a MALFORMED value '"
+ + v
+ + "' (not an integer). Refusing to start: falling through to the registry-derived "
+ + "size would silently apply the N>=9 blocking guard to a fleet size the operator "
+ + "did not state.");
+ }
+ }
+ if (!registry.isEmpty()) {
+ return registry.size();
+ }
+ return pendingLate == null ? 0 : pendingLate.size();
+ }
+
+ // ---- AERE ARMING GUARD (2026-08-01): CHAIN-RELATIVE STARTUP GUARD ----
+
+ /** Outcome of the chain-relative attachment-height guard. Exposed for tests and diagnostics. */
+ public enum ChainRelativeGateState {
+ /** The guard has not run yet. */
+ NOT_CHECKED,
+ /** No attachment height is configured, so there is nothing to check. */
+ NOT_APPLICABLE,
+ /** The attachment height leads the local chain head by at least the required margin. */
+ FUTURE,
+ /** The height has passed and the chain itself proves the fleet armed at it. */
+ RESUMED_ACTIVATED,
+ /** This node was previously admitted with this exact height while it was still in the future. */
+ RESUMED_ADMITTED,
+ /** An operator named this exact height in an explicit acknowledgement property. */
+ OPERATOR_ACKNOWLEDGED
+ }
+
+ /**
+ * Thrown to ABORT node startup on a Falcon activation configuration that must not be allowed to
+ * run. The {@link Kind} separates the two cases an operator has to treat differently.
+ *
+ * <p>A {@link Kind#SYNTAX} failure is a value this code could not parse at all. It can never be
+ * correct anywhere, it is local to this node, and the fix is to correct the string on this node
+ * and restart. A {@link Kind#UNSAFE} failure is a value that parsed perfectly and describes a
+ * configuration that would damage the fleet. It is usually NOT local: the same value is probably
+ * on the other validators too, and "fixing" it on this node alone can be exactly the wrong move.
+ * Keeping the two apart is the difference between a one-node typo and a fleet-wide decision.
+ */
+ public static final class ActivationConfigException extends IllegalStateException {
+
+ private static final long serialVersionUID = 1L;
+
+ /** Whether the value could not be parsed, or parsed and is dangerous. */
+ public enum Kind {
+ /** The configured value is not parseable. A typo. Local to this node. */
+ SYNTAX,
+ /** The configured value parses but the resulting activation would be unsafe. */
+ UNSAFE
+ }
+
+ private final Kind kind;
+ private final String code;
+
+ ActivationConfigException(final Kind kind, final String code, final String message) {
+ super("[" + code + "] " + message);
+ this.kind = kind;
+ this.code = code;
+ }
+
+ /**
+ * The failure class.
+ *
+ * @return SYNTAX for an unparseable value, UNSAFE for a dangerous one
+ */
+ public Kind kind() {
+ return kind;
+ }
+
+ /**
+ * The stable machine-readable code, e.g. {@code AERE-PQC-CFG-UNSAFE-05}.
+ *
+ * @return the code
+ */
+ public String code() {
+ return code;
+ }
+ }
+
+ /**
+ * CHAIN-RELATIVE half of the seal-attachment guard: refuse to start when {@code
+ * aere.falcon.attachBlock} is not comfortably AHEAD of this node's chain head, unless there is
+ * positive evidence that this is a legitimate resumption rather than a misconfiguration.
+ *
+ * <p>Call this exactly once during node startup, from the first point at which a chain head
+ * exists and BEFORE the network and the consensus state machine are started, so that a refusal is
+ * a clean refusal to start rather than a mid-flight abort.
+ *
+ * <p>The hole this closes, measured: {@link #attachmentArmed(long)} only ever required {@code
+ * blockNumber >= attachBlock}. Nothing required {@code attachBlock} to be in the future, so a
+ * single validator restarted with an already-passed height began emitting Falcon-carrying Commit
+ * messages on its first commit, into a fleet that was otherwise correctly configured.
+ *
+ * <p>The failure mode this guard introduces, and how it is handled: a node that CRASHES and
+ * restarts after the attachment height has legitimately passed must still be able to come back. A
+ * guard that refuses that restart is itself a halt risk, and on the scratch fleet losing one of
+ * seven validators stalled the chain for 61 s. Three independent pieces of evidence therefore
+ * distinguish "this height was configured in the past, which is a misconfiguration" from "this
+ * height passed normally while we were running, which is expected":
+ *
+ * <ol>
+ * <li>ON-CHAIN, strongest and fleet-wide: a header at or after the attachment height carries a
+ * Falcon seal. The fleet demonstrably armed. Nothing local is trusted for this.
+ * <li>LOCAL ADMISSION RECEIPT: this node was already admitted, by this same guard, with this
+ * exact height and this exact registry, at a time when the height was safely in the future.
+ * This is what rescues a crash in the window BEFORE the height arrives, where no on-chain
+ * evidence can exist yet.
+ * <li>EXPLICIT OPERATOR ACKNOWLEDGEMENT naming the exact height. The escape hatch for a node
+ * restored from a backup that predates the activation and lost its receipt.
+ * </ol>
+ *
+ * @param chainHeadNumber this node's local chain head at startup
+ * @param headerCarriesFalconSeal true iff the header at that height carries >= 1 Falcon seal; may
+ * be null, in which case on-chain evidence is treated as unavailable (fail-closed)
+ * @param dataDirectory the node data directory in which the admission receipt lives; may be null
+ * @throws ActivationConfigException with {@link ActivationConfigException.Kind#UNSAFE} when the
+ * configured height is not safely ahead and no evidence of a legitimate activation exists
+ */
+ public void verifyAttachHeightAgainstChainHeadOrAbort(
+ final long chainHeadNumber,
+ final LongPredicate headerCarriesFalconSeal,
+ final Path dataDirectory) {
+
+ if (attachBlock == Long.MAX_VALUE) {
+ chainRelativeState = ChainRelativeGateState.NOT_APPLICABLE;
+ LOG.info(
+ "AERE PQC: chain-relative attachment guard NOT APPLICABLE - aere.falcon.attachBlock is "
+ + "unset, so seal attachment is OFF at every height (safe default).");
+ return;
+ }
+
+ final long margin = minAttachFutureMargin();
+ final long head = Math.max(0L, chainHeadNumber);
+ final long lead = attachBlock - head;
+
+ if (lead >= margin) {
+ chainRelativeState = ChainRelativeGateState.FUTURE;
+ LOG.info(
+ "AERE PQC: attachment-height guard PASSED - aere.falcon.attachBlock={} leads this node's "
+ + "chain head {} by {} block(s); required margin aere.falcon.minAttachFutureMargin={}."
+ + " Recording an admission receipt so that a crash-restart inside the activation "
+ + "window is not refused.",
+ attachBlock,
+ head,
+ lead,
+ margin);
+ writeAdmissionReceipt(dataDirectory, head);
+ return;
+ }
+
+ // The height is at, behind, or uncomfortably close to the head. Refuse UNLESS something
+ // positively proves this is a resumption. Absence of evidence is treated as evidence of
+ // misconfiguration: that direction is the fail-closed one.
+
+ final long evidenceFloor = Math.max(attachBlock, head - ACTIVATION_EVIDENCE_LOOKBACK + 1);
+ if (fleetAlreadyArmed(head, evidenceFloor, headerCarriesFalconSeal)) {
+ chainRelativeState = ChainRelativeGateState.RESUMED_ACTIVATED;
+ LOG.warn(
+ "AERE PQC: attachment height {} is already PASSED at this node's chain head {} (lead={}, "
+ + "margin={}), but block {} carries a Falcon seal, so the fleet demonstrably ARMED at "
+ + "this height and this is a legitimate RESTART, not a misconfiguration. Starting "
+ + "normally; this node will attach seals immediately, which is what its peers already "
+ + "do.",
+ attachBlock,
+ head,
+ lead,
+ margin,
+ armedEvidenceHeight);
+ writeAdmissionReceipt(dataDirectory, head);
+ return;
+ }
+
+ if (admissionReceiptMatches(dataDirectory)) {
+ chainRelativeState = ChainRelativeGateState.RESUMED_ADMITTED;
+ LOG.warn(
+ "AERE PQC: attachment height {} is not {} block(s) ahead of this node's chain head {} "
+ + "(lead={}), and no block at or after {} carries a Falcon seal yet, BUT this node "
+ + "holds an admission receipt for exactly this height and registry, i.e. this same "
+ + "guard already accepted this configuration while the height was safely in the "
+ + "future. This is a RESTART inside the activation window, not a misconfiguration. "
+ + "Starting normally.",
+ attachBlock,
+ margin,
+ head,
+ lead,
+ evidenceFloor);
+ return;
+ }
+
+ if (operatorAcknowledgedPastAttachBlock()) {
+ chainRelativeState = ChainRelativeGateState.OPERATOR_ACKNOWLEDGED;
+ LOG.error(
+ "AERE PQC: OPERATOR OVERRIDE - aere.falcon.attachBlockAcknowledgePast={} matches "
+ + "aere.falcon.attachBlock, so the chain-relative guard is being bypassed even though "
+ + "the height is not {} block(s) ahead of the chain head {} (lead={}) and no on-chain "
+ + "activation evidence was found. This node WILL attach Falcon seals as soon as it "
+ + "commits. Use this ONLY to restore a validator into an activation that has genuinely "
+ + "already happened. REMOVE the property after the node is back.",
+ attachBlock,
+ margin,
+ head,
+ lead);
+ writeAdmissionReceipt(dataDirectory, head);
+ return;
+ }
+
+ throw new ActivationConfigException(
+ ActivationConfigException.Kind.UNSAFE,
+ "AERE-PQC-CFG-UNSAFE-05",
+ "AERE PQC: aere.falcon.attachBlock="
+ + attachBlock
+ + " is NOT safely ahead of this node's chain head "
+ + head
+ + " (lead="
+ + lead
+ + " block(s); required aere.falcon.minAttachFutureMargin="
+ + margin
+ + "). Refusing to start (fail-closed). An attachment height that this chain has already "
+ + "passed - or that will pass while this node is still starting up and not yet taking "
+ + "part in consensus - makes THIS node begin emitting Falcon-carrying Commit messages at "
+ + "a block the rest of the fleet did not arm at. Every peer whose Commit decoder is "
+ + "strict then discards the whole Commit, decisive ECDSA seal included, and the "
+ + "committing set silently shrinks. No evidence of a legitimate activation was found: no "
+ + "header in ["
+ + evidenceFloor
+ + ","
+ + head
+ + "] carries a Falcon seal, and this node holds no admission receipt for attachBlock="
+ + attachBlock
+ + ". REMEDY: if the fleet HAS legitimately activated at this height and this node lost "
+ + "its data directory, restart once with "
+ + "-Daere.falcon.attachBlockAcknowledgePast="
+ + attachBlock
+ + " (the value must equal aere.falcon.attachBlock exactly). Otherwise set "
+ + "aere.falcon.attachBlock to a height at least "
+ + margin
+ + " blocks ahead of the fleet's head, ON EVERY VALIDATOR, and restart the fleet.");
+ }
+
+ /**
+ * Look for on-chain proof that the fleet has already armed: a header at or after the attachment
+ * height carrying at least one Falcon seal. Fails CLOSED - an unreadable or undecodable header is
+ * not evidence.
+ */
+ private boolean fleetAlreadyArmed(
+ final long head, final long evidenceFloor, final LongPredicate headerCarriesFalconSeal) {
+ if (headerCarriesFalconSeal == null || attachBlock > head) {
+ return false;
+ }
+ for (long n = head; n >= evidenceFloor && n >= 0; n--) {
+ try {
+ if (headerCarriesFalconSeal.test(n)) {
+ armedEvidenceHeight = n;
+ return true;
+ }
+ } catch (final RuntimeException e) {
+ LOG.warn(
+ "AERE PQC: could not inspect header {} for Falcon seals ({}); treating on-chain "
+ + "activation evidence as UNAVAILABLE (fail-closed).",
+ n,
+ e.toString());
+ return false;
+ }
+ }
+ return false;
+ }
+
+ /**
+ * Identity of the registry this node is configured against, so an admission receipt written for
+ * one chain or one manifest can never admit a different one.
+ */
+ private String registryIdentity() {
+ if (manifestHash != null) {
+ return manifestHash;
+ }
+ if (pendingLateHash != null) {
+ return pendingLateHash;
+ }
+ return "none";
+ }
+
+ /** Path of the admission receipt inside the node data directory, or null if unavailable. */
+ private Path admissionReceiptPath(final Path dataDirectory) {
+ return dataDirectory == null ? null : dataDirectory.resolve(ADMISSION_RECEIPT_FILE);
+ }
+
+ /**
+ * Record that this guard ADMITTED this attachment height. Deliberately best-effort: a data
+ * directory that cannot be written must not stop a validator from starting. It is logged at ERROR
+ * because the consequence is real - without the receipt, a crash-restart before the activation
+ * height would be refused and would need the acknowledgement property.
+ */
+ private void writeAdmissionReceipt(final Path dataDirectory, final long head) {
+ final Path p = admissionReceiptPath(dataDirectory);
+ if (p == null) {
+ return;
+ }
+ final Properties props = new Properties();
+ props.setProperty("attachBlock", Long.toString(attachBlock));
+ props.setProperty("registryIdentity", registryIdentity());
+ props.setProperty("admittedAtChainHead", Long.toString(head));
+ props.setProperty("admittedAtEpochMillis", Long.toString(System.currentTimeMillis()));
+ try {
+ Files.createDirectories(p.getParent());
+ try (OutputStream out = Files.newOutputStream(p)) {
+ props.store(
+ out,
+ "AERE PQC activation admission receipt. Written by the chain-relative attachment guard "
+ + "when it accepted this attachment height. Presence of this file lets a later "
+ + "restart tell a legitimate resumption from a past-height misconfiguration. It "
+ + "contains no key material.");
+ }
+ } catch (final Exception e) {
+ LOG.error(
+ "AERE PQC: could NOT write the activation admission receipt to {} ({}). Startup "
+ + "continues, but if this node restarts before block {} it will have no local proof "
+ + "that this activation height was already accepted, and the chain-relative guard "
+ + "will refuse to start it until either the fleet has visibly armed on chain or "
+ + "-Daere.falcon.attachBlockAcknowledgePast={} is set.",
+ p,
+ e.toString(),
+ attachBlock,
+ attachBlock);
+ }
+ }
+
+ /** True iff a receipt exists recording an earlier admission of this exact height and registry. */
+ private boolean admissionReceiptMatches(final Path dataDirectory) {
+ final Path p = admissionReceiptPath(dataDirectory);
+ if (p == null || !Files.isRegularFile(p)) {
+ return false;
+ }
+ try (InputStream in = Files.newInputStream(p)) {
+ final Properties props = new Properties();
+ props.load(in);
+ final String a = props.getProperty("attachBlock");
+ final String id = props.getProperty("registryIdentity");
+ final boolean match =
+ a != null
+ && id != null
+ && Long.parseLong(a.trim()) == attachBlock
+ && id.trim().equals(registryIdentity());
+ if (!match) {
+ LOG.warn(
+ "AERE PQC: an activation admission receipt exists at {} but does NOT match the current "
+ + "configuration (receipt attachBlock={}, registryIdentity={}; configured "
+ + "attachBlock={}, registryIdentity={}). It is being IGNORED, which is the "
+ + "fail-closed direction: a receipt for a different activation must never admit "
+ + "this one.",
+ p,
+ a,
+ id,
+ attachBlock,
+ registryIdentity());
+ }
+ return match;
+ } catch (final Exception e) {
+ LOG.warn(
+ "AERE PQC: could not read the activation admission receipt at {} ({}); treating it as "
+ + "ABSENT (fail-closed).",
+ p,
+ e.toString());
+ return false;
+ }
+ }
+
+ /**
+ * The explicit operator escape hatch. The acknowledgement must NAME the exact attachment height,
+ * so it cannot be a blanket "true" that survives across activations and quietly disarms this
+ * guard forever. An acknowledgement naming a DIFFERENT height is itself an abort: it means the
+ * operator is acknowledging an activation this node is not configured for.
+ */
+ private boolean operatorAcknowledgedPastAttachBlock() {
+ final String v =
+ resolve("aere.falcon.attachBlockAcknowledgePast", "AERE_FALCON_ATTACHBLOCK_ACK_PAST");
+ if (v == null) {
+ return false;
+ }
+ final long ack;
+ try {
+ ack = Long.parseLong(v.trim());
+ } catch (final NumberFormatException e) {
+ throw new ActivationConfigException(
+ ActivationConfigException.Kind.SYNTAX,
+ "AERE-PQC-CFG-SYNTAX-05",
+ "AERE PQC: aere.falcon.attachBlockAcknowledgePast is set to a MALFORMED value '"
+ + v
+ + "' (not an integer block number). Refusing to start. This property is not a "
+ + "boolean: it must repeat the exact aere.falcon.attachBlock value being acknowledged "
+ + "("
+ + attachBlock
+ + ").");
+ }
+ if (ack != attachBlock) {
+ throw new ActivationConfigException(
+ ActivationConfigException.Kind.UNSAFE,
+ "AERE-PQC-CFG-UNSAFE-06",
+ "AERE PQC: aere.falcon.attachBlockAcknowledgePast="
+ + ack
+ + " does not match aere.falcon.attachBlock="
+ + attachBlock
+ + ". Refusing to start (fail-closed): an acknowledgement that names a different "
+ + "height is a stale acknowledgement left over from an earlier activation, and it "
+ + "must never silently authorise the current one.");
+ }
+ return true;
+ }
+
+ /**
+ * Highest legal value for {@code aere.falcon.attachInterval}.
+ *
+ * <p>This is NOT a taste limit, it is {@link #ACTIVATION_EVIDENCE_LOOKBACK}. A validator that
+ * loses its data directory and restarts past an attachment height proves the fleet is already
+ * armed by finding a header carrying at least one seal within the last {@value
+ * #ACTIVATION_EVIDENCE_LOOKBACK} blocks; with a wider interval that window can contain no
+ * seal-bearing header at all, the evidence search comes up empty, and the node refuses to start
+ * with AERE-PQC-CFG-UNSAFE-05. The failure would arrive days later, on an unrelated restart, on
+ * whichever node happened to lose its disk. Refusing the interval at configuration time is the
+ * only place the operator can still see the connection.
+ */
+ private static final int MAX_ATTACH_INTERVAL = ACTIVATION_EVIDENCE_LOOKBACK;
+
+ /**
+ * Write the Falcon certificate only on every Nth block, counted from {@code
+ * aere.falcon.attachBlock}. Configurable via {@code aere.falcon.attachInterval} / {@code
+ * AERE_FALCON_ATTACHINTERVAL}.
+ *
+ * <p>WHY THIS EXISTS, measured on chain 2800 on 2026-08-08. Attachment was armed on all seven
+ * validators and the header went from 525 to 3844 bytes, five Falcon seals on EVERY block, about
+ * 200 GB per node per year against 12 GB of free disk on the tightest host. The anchor producer
+ * already has both an interval and a seal cap, but the assembler reached when the anchor is NOT
+ * armed has neither, and that assembler is the one that runs before the activation height. So the
+ * cheap-by-design path was unreachable precisely during the window it was needed.
+ *
+ * <p>Unset means EVERY block, which is exactly today's behaviour. A node that writes fewer
+ * certificates than its neighbours is a behaviour change on a live chain and has to be asked for,
+ * never delivered as a default.
+ *
+ * <p>There is no consensus coupling here and that is deliberate: below the anchor activation
+ * height no rule reads element 6 to refuse anything, so two nodes with different intervals still
+ * agree on exactly which headers are valid. That stops being true at the activation height, where
+ * PqAnchorDigestRule binds the certificate to the vanity digest, and from there the anchor's own
+ * interval governs.
+ *
+ * @return the interval in blocks, or empty for every block
+ */
+ public OptionalInt attachInterval() {
+ final String v = resolve("aere.falcon.attachInterval", "AERE_FALCON_ATTACHINTERVAL");
+ if (v == null) {
+ return OptionalInt.empty();
+ }
+ final int parsed;
+ try {
+ parsed = Integer.parseInt(v.trim());
+ } catch (final NumberFormatException e) {
+ throw new ActivationConfigException(
+ ActivationConfigException.Kind.SYNTAX,
+ "AERE-PQC-CFG-SYNTAX-09",
+ "AERE PQC: aere.falcon.attachInterval is set to a MALFORMED value '"
+ + v
+ + "' (not an integer number of blocks). Refusing to start: an interval that silently "
+ + "reverted to 'every block' would leave the operator believing a disk control is in "
+ + "force when it is not, and the disk would fill anyway.");
+ }
+ if (parsed < 1 || parsed > MAX_ATTACH_INTERVAL) {
+ throw new ActivationConfigException(
+ ActivationConfigException.Kind.UNSAFE,
+ "AERE-PQC-CFG-UNSAFE-09",
+ "AERE PQC: aere.falcon.attachInterval "
+ + parsed
+ + " is outside the legal range 1.."
+ + MAX_ATTACH_INTERVAL
+ + ". Refusing to start. The upper bound is the "
+ + ACTIVATION_EVIDENCE_LOOKBACK
+ + "-block window in which a restarting validator looks for proof that the fleet is "
+ + "already armed; a wider interval can leave that window with no seal-bearing header, "
+ + "and the node would then refuse to start with AERE-PQC-CFG-UNSAFE-05 days later, "
+ + "on whichever node happened to lose its data directory.");
+ }
+ return OptionalInt.of(parsed);
+ }
+
+ /**
+ * Largest number of seals this node writes into a certificate on the pre-activation assembly
+ * path. Configurable via {@code aere.falcon.attachMaxSeals} / {@code
+ * AERE_FALCON_ATTACHMAXSEALS}; unset means no cap, which is today's behaviour.
+ *
+ * <p>This is the twin of {@code aere.pq.anchor.maxSeals}, which caps the anchor producer. K is a
+ * FLOOR, not a ceiling: nodes attach as many seals as reach them in time, not as many as any
+ * threshold asks for. Measured on 2026-08-08, five seals per block arrived with seven validators
+ * attaching.
+ *
+ * <p>Unlike the anchor cap there is no minimum tied to a K schedule, because below the activation
+ * height no rule counts these seals. The only floor is 1: a certificate of zero seals is not a
+ * cheaper certificate, it is an absent one, and the caller should unset attachment instead.
+ *
+ * @return the cap, or empty for no cap
+ */
+ public OptionalInt attachMaxSeals() {
+ final String v = resolve("aere.falcon.attachMaxSeals", "AERE_FALCON_ATTACHMAXSEALS");
+ if (v == null) {
+ return OptionalInt.empty();
+ }
+ final int parsed;
+ try {
+ parsed = Integer.parseInt(v.trim());
+ } catch (final NumberFormatException e) {
+ throw new ActivationConfigException(
+ ActivationConfigException.Kind.SYNTAX,
+ "AERE-PQC-CFG-SYNTAX-10",
+ "AERE PQC: aere.falcon.attachMaxSeals is set to a MALFORMED value '"
+ + v
+ + "' (not an integer). Refusing to start rather than silently carrying no cap.");
+ }
+ if (parsed < 1) {
+ throw new ActivationConfigException(
+ ActivationConfigException.Kind.UNSAFE,
+ "AERE-PQC-CFG-UNSAFE-10",
+ "AERE PQC: aere.falcon.attachMaxSeals "
+ + parsed
+ + " is below 1. Refusing to start: a cap of zero produces an absent certificate, not "
+ + "a cheaper one. To stop writing certificates, unset aere.falcon.attachBlock.");
+ }
+ return OptionalInt.of(parsed);
+ }
+
+ /**
+ * Whether the pre-activation assembler should write a certificate into THIS block's header.
+ *
+ * <p>Counted from {@code attachBlock} so that every node in the fleet picks the same heights
+ * without any agreement protocol: the two inputs are a configured constant and the block number.
+ * Nodes with different intervals disagree about which blocks carry a certificate, and that is
+ * harmless below the activation height for the reason given on {@link #attachInterval()}.
+ *
+ * @param blockNumber the height being sealed
+ * @return true if a certificate should be written at this height
+ */
+ public boolean attachesCertificateAt(final long blockNumber) {
+ return attachmentArmed(blockNumber) && isAttachHeight(blockNumber, attachBlock, attachInterval());
+ }
+
+ /**
+ * The height arithmetic of {@link #attachesCertificateAt}, with no dependency on instance state.
+ *
+ * <p>Kept separate and package-private so it can be measured on its own. The surrounding gate
+ * needs a fully constructed node with a loaded registry, a signing key and an armed attachment
+ * height, which is a great deal of scaffolding around one modulo; a proof that has to build all
+ * of that in order to ask "is 12,900,100 an attachment height" ends up measuring the scaffolding.
+ *
+ * @param blockNumber the height being sealed
+ * @param from the configured attachment height
+ * @param every the configured interval, or empty for every block
+ * @return true if a certificate belongs at this height
+ */
+ static boolean isAttachHeight(final long blockNumber, final long from, final OptionalInt every) {
+ if (blockNumber < from) {
+ return false;
+ }
+ if (every.isEmpty()) {
+ return true;
+ }
+ return (blockNumber - from) % every.getAsInt() == 0;
+ }
+
+ /**
+ * Minimum number of blocks by which the attachment height must lead this node's chain head at
+ * startup. Configurable via {@code aere.falcon.minAttachFutureMargin} /
+ * {@code AERE_FALCON_MIN_ATTACH_FUTURE_MARGIN}; a malformed or negative value aborts startup
+ * rather than silently reverting to the default, so an operator can never believe a margin is in
+ * force when it is not.
+ *
+ * @return the required margin in blocks
+ */
+ public long minAttachFutureMargin() {
+ final String v =
+ resolve("aere.falcon.minAttachFutureMargin", "AERE_FALCON_MIN_ATTACH_FUTURE_MARGIN");
+ if (v == null) {
+ return DEFAULT_MIN_ATTACH_FUTURE_MARGIN;
+ }
+ final long parsed;
+ try {
+ parsed = Long.parseLong(v.trim());
+ } catch (final NumberFormatException e) {
+ throw new ActivationConfigException(
+ ActivationConfigException.Kind.SYNTAX,
+ "AERE-PQC-CFG-SYNTAX-06",
+ "AERE PQC: aere.falcon.minAttachFutureMargin is set to a MALFORMED value '"
+ + v
+ + "' (not an integer number of blocks). Refusing to start: a safety margin that "
+ + "silently reverted to its default would leave the operator believing a margin is in "
+ + "force when it is not.");
+ }
+ if (parsed < 0) {
+ throw new ActivationConfigException(
+ ActivationConfigException.Kind.SYNTAX,
+ "AERE-PQC-CFG-SYNTAX-06",
+ "AERE PQC: aere.falcon.minAttachFutureMargin '"
+ + v
+ + "' is negative. Refusing to start.");
+ }
+ return parsed;
+ }
+
+ /**
+ * Outcome of the chain-relative startup guard.
+ *
+ * @return the gate state, NOT_CHECKED until the guard has run
+ */
+ public ChainRelativeGateState chainRelativeState() {
+ return chainRelativeState;
+ }
+
+ // ---- AERE A8 (2026-08-01): BIND THE REGISTRY TO CONSENSUS ----
+
+ /**
+ * A8 GUARD: refuse to start when the Falcon registry this node loaded is not the one the chain
+ * requires at this height.
+ *
+ * <p>THE DEFECT, read out of the constructor above and not guessed at. The registry that answers
+ * "which Falcon public key is validator index i" can come from {@code aere.falcon.registry}, a
+ * plain local properties file with no binding to anything. Two nodes handed two different files
+ * disagree about who index i is, so one and the same certificate verifies on one node and fails on
+ * the other. That splits the network with no attacker in it. The two anchored sources do check a
+ * hash, but their fail-closed action is to leave the registry EMPTY and log; the process still
+ * STARTS, so a node can run for days as a validator that can verify nothing and report itself
+ * healthy while doing it.
+ *
+ * <p>WHAT THIS GUARD DOES. It re-reads the registry file this node actually used, computes its
+ * canonical hash, and compares it against {@code config.pqRegistryHash} in genesis, which is a
+ * height-indexed schedule. Below the first scheduled height nothing is enforced, so the roughly
+ * 11.8 million blocks already on chain 2800 are untouched. At and above it, a mismatch throws and
+ * the node does not start; the refusal names the hash expected, the hash found, the file, the
+ * source kind and a fingerprint per registry row.
+ *
+ * <p>Call this from the same place as {@link #verifyAttachHeightAgainstChainHeadOrAbort}: after a
+ * chain head exists and before the network and the QBFT state machine are started, so a refusal is
+ * a clean refusal to start rather than a mid-flight abort.
+ *
+ * <p>The genesis file is located from {@code aere.pq.genesis} / {@code AERE_PQ_GENESIS}, falling
+ * back to {@code aere.falcon.genesis} / {@code AERE_FALCON_GENESIS}. When neither is set there is
+ * no schedule to read, nothing is enforced, and that fact is logged at WARN rather than passed
+ * over: a binding everybody believes is on and is not is worse than no binding at all.
+ *
+ * @param chainHeadNumber this node's local chain head at startup
+ * @param chainId the chain id, which is part of the canonical pre-image
+ * @return the gate state
+ * @throws PqRegistryHash.RegistryConfigException when a binding is active and is not satisfied
+ */
+ public PqRegistryHash.GateState verifyRegistryBindingOrAbort(
+ final long chainHeadNumber, final long chainId) {
+
+ final String genesisForSchedule =
+ resolve("aere.pq.genesis", "AERE_PQ_GENESIS") != null
+ ? resolve("aere.pq.genesis", "AERE_PQ_GENESIS")
+ : resolve("aere.falcon.genesis", "AERE_FALCON_GENESIS");
+
+ final PqRegistryHash.Schedule schedule;
+ if (genesisForSchedule == null) {
+ LOG.warn(
+ "AERE PQC A8: no genesis file is reachable to read config.pqRegistryHash from (neither "
+ + "aere.pq.genesis nor aere.falcon.genesis is set), so the Falcon registry on this "
+ + "node is NOT bound to consensus. The registry in use is {} ({}). Two nodes holding "
+ + "different registry files would disagree about which public key validator index i "
+ + "has, and the same certificate would verify on one and fail on the other.",
+ registrySourcePath == null ? "(none)" : registrySourcePath,
+ registrySourceKind);
+ schedule = PqRegistryHash.emptySchedule();
+ } else {
+ schedule = PqRegistryHash.loadScheduleFromGenesis(Paths.get(genesisForSchedule));
+ }
+
+ return verifyRegistryBindingOrAbort(chainHeadNumber, chainId, schedule);
+ }
+
+ /**
+ * AERE A8, the form the caller should actually use: verify the registry binding against a
+ * schedule that came from the genesis configuration BESU ITSELF PARSED AND BOOTED WITH.
+ *
+ * <p>WHY THIS OVERLOAD EXISTS, and it is not tidiness. The single-argument form above reads
+ * {@code config.pqRegistryHash} out of a genesis FILE whose path comes from a system property.
+ * That is a local file named by local configuration, which is the exact shape of the defect this
+ * guard was written to close. A node pointed at a stale copy of genesis would enforce a stale
+ * binding, or none, and would say nothing. Handing the schedule down from {@code
+ * GenesisConfigOptions} removes the second file entirely: the value enforced is read out of the
+ * same genesis object that produced this node's genesis hash, so a node that disagrees about the
+ * schedule already disagrees about the chain and is not on it.
+ *
+ * @param chainHeadNumber this node's local chain head at startup
+ * @param chainId the chain id, which is part of the canonical pre-image
+ * @param schedule the schedule parsed from the booted genesis configuration
+ * @return the gate state
+ * @throws PqRegistryHash.RegistryConfigException when a binding is active and is not satisfied
+ */
+ public PqRegistryHash.GateState verifyRegistryBindingOrAbort(
+ final long chainHeadNumber, final long chainId, final PqRegistryHash.Schedule schedule) {
+
+ PqRegistryHash.Registry loaded = null;
+ if (registrySourcePath != null) {
+ loaded = PqRegistryHash.loadAuto(Paths.get(registrySourcePath));
+ }
+
+ // D-081: build the height-resolved set BEFORE anything is published, from the registry this
+ // node signs with plus every registry named in the history list. With no history configured the
+ // set holds exactly the one registry and every answer below is what it was before D-081.
+ //
+ // AERE D-A (2026-08-06). THIS BLOCK USED TO SIT 41 LINES LOWER, AND THAT WAS THE DEFECT. The
+ // startup guard below was handed the single primary registry and threw
+ // AERE-PQC-REG-MISMATCH-01 before this code ever ran, so a node holding exactly the right files
+ // - the post-rotation registry as its own, the pre-rotation one as history - refused to start
+ // with a correct configuration. Re-confirmed 2026-08-06 with head at 2554. Consequence: after
+ // the first rotation, no node could be restarted without hand intervention.
+ //
+ // MOVING IT UP ADDS NO WORK ON AN UNCONFIGURED NODE: resolve() returns null, and
+ // parseRegistryPaths(null) returns an empty list, so nothing is opened that was not opened
+ // before. On chain 2800 the schedule is empty, buildSet's loop has zero iterations, and this
+ // whole block costs one map lookup.
+ final List<PqRegistryHash.Registry> held = new ArrayList<>();
+ held.add(loaded);
+ final String history = resolve(PROPERTY_REGISTRY_HISTORY, "AERE_FALCON_REGISTRY_HISTORY");
+ for (final java.nio.file.Path p : PqRegistryHash.parseRegistryPaths(history)) {
+ held.add(PqRegistryHash.loadAuto(p));
+ }
+ final PqRegistryHash.RegistrySet set = PqRegistryHash.buildSet(schedule, held, chainId);
+
+ PqRegistryHash.GateState state;
+ try {
+ state = PqRegistryHash.verifyOrAbort(schedule, set, chainHeadNumber, chainId);
+ requireAnchorHeightIsASignedHeightOrAbort(schedule, set);
+ } catch (final PqRegistryHash.RegistryConfigException e) {
+ // AERE OPTIUNI-URGENTA (2026-08-02): THE WAY BACK, and the only one that does not need a
+ // build. Without it, a registry file that is wrong in one byte takes down every node it was
+ // pushed to, and the documented recovery was to edit a unit file or rebuild. With it, the
+ // recovery is a restart with one flag - and the node spends the whole time it runs saying, at
+ // every height, that it is running unverified.
+ //
+ // NOT bypassed here, deliberately: AERE-PQC-REG-ARM-01, the refusal to arm over a registry
+ // with no validator addresses. That refusal is not a configuration mismatch, it is a
+ // guarantee that the fleet is about to halt at the activation height, and starting anyway
+ // would only move the halt a few blocks later. The way out of THAT one is to disarm the
+ // anchor, which is a different option and is why there are three and not one.
+ if (!registryMismatchAllow) {
+ throw e;
+ }
+ registryOverrideEngaged = true;
+ LOG.error(
+ "AERE PQC EMERGENCY [AERE-PQC-REG-UNSAFE-01]: STARTING ANYWAY WITH AN UNVERIFIED FALCON "
+ + "REGISTRY. The A8 registry-binding guard REFUSED this node ({}), and {} is set, so "
+ + "the refusal has been overridden BY EXPLICIT OPERATOR REQUEST. What that means, "
+ + "stated plainly: from the first height at which genesis requires a registry hash, "
+ + "this node cannot correctly decide whether a header's Falcon certificate is valid, "
+ + "and it will import those headers anyway. It is NOT a validating node for the "
+ + "post-quantum layer while this is set. WHAT TO DO: install the registry whose hash "
+ + "genesis names and restart WITHOUT this option. The refusal that was overridden "
+ + "follows in full.\n{}",
+ e.code(),
+ PROPERTY_REGISTRY_MISMATCH_ALLOW,
+ e.getMessage());
+ state = PqRegistryHash.GateState.OVERRIDDEN_UNSAFE;
+ }
+ if (schedule.enforced() && !set.coversWholeSchedule()) {
+ // NOT a refusal here, and the reason is measured, not aesthetic. This method is also the
+ // path a node takes when it is being started BELOW the first scheduled height, where nothing
+ // is enforced yet and an operator legitimately holds only one file. The per-block rule
+ // refuses at exactly the heights that are uncovered, which is the narrowest fail-closed
+ // action that still names the problem. What must never happen is silence.
+ LOG.error(
+ "AERE PQC D-081: this node holds {} registry file(s) and the chain's pqRegistryHash "
+ + "schedule has {} entr(ies), of which the heights {} are covered by NOTHING this "
+ + "node holds. Every header at or after such a height will be REFUSED, and a node "
+ + "syncing from genesis will stop there. Name the missing registry file(s) in {} "
+ + "(comma-separated). The list is never pruned: one file per rotation the chain has "
+ + "ever performed, kept forever, because a node acquiring history has to verify every "
+ + "block that was ever produced.",
+ set.count(),
+ schedule.entries().size(),
+ set.uncoveredEntryBlocks(),
+ PROPERTY_REGISTRY_HISTORY);
+ }
+ this.registryBindingState = state;
+ // Publish the inputs the per-block half needs. Order matters: the schedule is written LAST, and
+ // registryBindingSatisfiedAt() reads it FIRST and returns true when it is null, so a rule that
+ // runs while this is being assembled sees "inert" and never sees a half-built gate.
+ this.registryBindingLoaded = loaded;
+ this.registryBindingSet = set;
+ this.historicalKeys.clear();
+ this.registryBindingChainId = chainId;
+ this.registryBindingSchedule = schedule;
+ return state;
+ }
+
+ /**
+ * AERE D-B (2026-08-06), THE LOCAL HALF. The height this node ARMS at must be a height the fleet
+ * actually signed a registry for.
+ *
+ * <p>WHY THIS CANNOT BE THE SAME KIND OF GUARD AS THE ONE ABOVE, and the difference is the whole
+ * honest limitation of D-B. {@code aere.pq.anchorBlock} is a SYSTEM PROPERTY, set per node through
+ * {@code BESU_OPTS}. It is in no genesis. Nothing in the document the validators hold
+ * byte-identically constrains it. So the agreement of the nodes on an arming height CANNOT BE
+ * ENFORCED by any code that runs on one node - it can only be DETECTED locally, and that is what
+ * this does. Enforcement would require the height to move into genesis, which is a change to the
+ * chain's configuration and not to this class. That is written here as a limitation, not as a
+ * to-do, because a reader must not mistake this for a consensus rule.
+ *
+ * <p>WHAT IT COMPARES. The arming height A against the {@code block} values of
+ * {@code config.pqRegistryHash}. A registry row's possession proof and validator claim both sign
+ * the bind height; the schedule entry that puts a registry in force names the same number (that is
+ * {@code AERE-PQC-REG-BIND-08}, enforced above). If A is not one of those heights, the moment at
+ * which certificates begin to carry weight is a number no validator ever put a signature on.
+ * Measured 2026-08-06 on a network of seven with A moved from 40 to 70: seven of seven started,
+ * head reached 95, agreement 7 of 7, zero refusals.
+ *
+ * <p>WHY IT CANNOT FIRE ON CHAIN 2800 OR ON ANY NODE RUNNING TODAY. Three independent gates, any
+ * one of which returns first: the anchor is not armed ({@code aere.pq.anchorBlock} unset, so
+ * {@code anchorArmedFrom()} is {@link Long#MAX_VALUE}); {@code config.pqRegistryHash} is in no
+ * genesis this fleet runs, so the schedule is not enforced; and the held registry is v1, carrying
+ * no signatures over any height at all.
+ *
+ * @param schedule the schedule parsed from the booted genesis
+ * @param set the registries this node holds
+ * @throws PqRegistryHash.RegistryConfigException with {@code AERE-PQC-REG-BIND-09}
+ */
+ private void requireAnchorHeightIsASignedHeightOrAbort(
+ final PqRegistryHash.Schedule schedule, final PqRegistryHash.RegistrySet set) {
+ final long armedFrom = anchorArmedFrom();
+ if (armedFrom == Long.MAX_VALUE || !schedule.enforced()) {
+ return;
+ }
+ final PqRegistryHash.Registry primary = set.primary();
+ if (primary == null || !primary.proofBound()) {
+ // Nothing here signed a height. A v1 registry on an armed node is already refused, louder and
+ // for a better reason, by AERE-PQC-REG-ARM-02 in the constructor; this must not take that
+ // message over.
+ return;
+ }
+ for (final PqRegistryHash.ScheduleEntry e : schedule.entries()) {
+ if (e.block() == armedFrom) {
+ return;
+ }
+ }
+ final StringBuilder heights = new StringBuilder();
+ for (final PqRegistryHash.ScheduleEntry e : schedule.entries()) {
+ if (heights.length() > 0) {
+ heights.append(", ");
+ }
+ heights.append(e.block());
+ }
+ throw new PqRegistryHash.RegistryConfigException(
+ "AERE-PQC-REG-BIND-09",
+ "AERE PQC D-B: REFUSING TO START - this node arms at a height no validator signed for.\n"
+ + " FIELD: aere.pq.anchorBlock (system property, per node, read through "
+ + "PqAnchorConfig) versus the 'block' values of config.pqRegistryHash in genesis ("
+ + schedule.source()
+ + ").\n"
+ + " READ: aere.pq.anchorBlock = "
+ + armedFrom
+ + "\n"
+ + " config.pqRegistryHash heights = ["
+ + heights
+ + "]\n"
+ + " EXPECTED: the arming height is ONE of those heights. Every row of the registry "
+ + "carries a Falcon possession proof and an ECDSA claim by that validator's own "
+ + "consensus key, and both signatures cover a single bind height. From the arming "
+ + "height a header's Falcon certificate carries consensus weight; if that height is not "
+ + "one the fleet signed, the day the chain starts enforcing post-quantum seals is a "
+ + "number one operator typed.\n"
+ + " WHY NOTHING ELSE CATCHES IT: aere.pq.anchorBlock is not in genesis. It is not in "
+ + "the document every node holds identically, so no node can hold another node to "
+ + "it. This refusal is DETECTION on this node only. Two nodes with different "
+ + "aere.pq.anchorBlock still do not disagree about a header until the lower of the two "
+ + "heights, and this guard cannot see the other node's value.\n"
+ + " WHAT TO DO: EITHER set aere.pq.anchorBlock to one of the heights above, on every "
+ + "node and in the same change - a node armed alone validates differently from "
+ + "the rest. OR, if the activation day genuinely moved, re-run the key ceremony for the "
+ + "new height, put the re-signed registry's NEW hash in config.pqRegistryHash at that "
+ + "height, and roll it to the whole fleet. Moving the day is 14 signatures. It is "
+ + "supposed to be.\n"
+ + " CHECK THE WHOLE FLEET BEFORE RESTARTING ANYTHING: this property is per node and "
+ + "is in no genesis, so two nodes can disagree about it silently. Compare it across "
+ + "every validator and treat a split state as a fault, not as a detail.");
+ }
+
+ /**
+ * AERE A8, the PER-BLOCK half: does the registry this node is running on satisfy the binding the
+ * chain requires AT THIS HEIGHT? Never throws.
+ *
+ * <p>WHY A STARTUP GUARD IS NOT ENOUGH, measured as a gap and not assumed. The startup guard
+ * answers the question once, against the chain head that existed at startup. A node that is
+ * already running when a ROTATION height in the schedule passes underneath it is never asked
+ * again: it keeps validating with a registry the chain has moved off, and it keeps reporting
+ * itself healthy while doing it. That is the same failure mode A8 was opened for, arriving by a
+ * different door. With a schedule of one entry the two guards are equivalent; with two or more,
+ * only this one covers the interval after the second entry.
+ *
+ * <p>WHAT IT DOES ON MISMATCH. It returns false, and the header rule that calls it refuses the
+ * header. That is deliberate and it is fail-closed: a node whose registry no longer matches what
+ * the chain requires cannot verify the certificates in the headers it is being offered, so
+ * importing them would mean asserting a check it did not perform. It stops instead, loudly, at
+ * the first header past the rotation. It does NOT touch proposer selection or finality.
+ *
+ * @param blockNumber the height of the header being validated
+ * @return true when no binding is active at that height, or the registry satisfies it
+ */
+ public boolean registryBindingSatisfiedAt(final long blockNumber) {
+ final PqRegistryHash.Schedule schedule = this.registryBindingSchedule;
+ if (schedule == null) {
+ return true; // guard never ran on this node: inert, exactly as before this change
+ }
+ final Optional<PqRegistryHash.ScheduleEntry> required =
+ PqRegistryHash.requiredHashAt(schedule, blockNumber);
+ if (required.isEmpty()) {
+ return true; // below the first scheduled height: the 11.8 million existing blocks are untouched
+ }
+ final PqRegistryHash.Registry loaded = this.registryBindingLoaded;
+ // D-081: ask the whole scheduled history, not only the entry in force at the head. Before this
+ // change a node held one registry, so one rotation left NO configuration that satisfied both
+ // the pre-rotation interval and the head, and the chain became permanently unjoinable.
+ final boolean ok =
+ PqRegistryHash.matchesAt(
+ schedule, this.registryBindingSet, blockNumber, this.registryBindingChainId);
+ if (!ok) {
+ // AERE OPTIUNI-URGENTA: the per-block half of the bypass. It has to consult the ARMED flag
+ // and not only the ENGAGED one, because the case this rule exists for is precisely the one
+ // the startup guard never saw: a rotation height passing underneath a node that started
+ // clean. In that case nothing was overridden at startup and there is nothing engaged yet.
+ if (registryMismatchAllow) {
+ registryOverrideEngaged = true;
+ shoutRegistryOverrideUnsafe(blockNumber, required.get(), loaded);
+ return true;
+ }
+ shoutRegistryBindingMismatch(blockNumber, required.get(), loaded);
+ }
+ return ok;
+ }
+
+ /**
+ * AERE OPTIUNI-URGENTA: is this node ACTUALLY running on a suppressed registry refusal?
+ *
+ * @return true once the bypass has suppressed a real refusal, at startup or on the block path
+ */
+ public boolean registryOverrideEngaged() {
+ return registryOverrideEngaged;
+ }
+
+ /**
+ * AERE OPTIUNI-URGENTA: has an operator armed the registry bypass on this node?
+ *
+ * @return true iff the bypass property or environment variable is set
+ */
+ public boolean registryMismatchAllowArmed() {
+ return registryMismatchAllow;
+ }
+
+ /**
+ * One complete ERROR line per height, for as long as the bypass carries weight. Bounded to one per
+ * height for the same reason the refusal is: at a 0.5 s block period an unbounded line would bury
+ * the first and most useful occurrence. Bounded per height is NOT bounded once: the mission for
+ * this option was that the node shouts at EVERY block, and one line per height is what "every
+ * block" means on a path that is asked about a height more than once.
+ */
+ private void shoutRegistryOverrideUnsafe(
+ final long blockNumber,
+ final PqRegistryHash.ScheduleEntry required,
+ final PqRegistryHash.Registry loaded) {
+ if (registryOverrideLastShout.getAndSet(blockNumber) == blockNumber) {
+ return;
+ }
+ LOG.error(
+ "AERE PQC EMERGENCY [AERE-PQC-REG-UNSAFE-02]: height {} ACCEPTED UNVERIFIED. This chain "
+ + "requires registry hash {} from height {}, the registry this node holds hashes to {}, "
+ + "and the header was imported anyway because {} is set. This node is NOT checking the "
+ + "post-quantum certificates in the headers it accepts. Registry in use: {} ({}, {} "
+ + "entries, address-bound={}). WHAT TO DO: install the registry whose hash is {} and "
+ + "restart WITHOUT the bypass. THIS LINE REPEATS AT EVERY HEIGHT, BY DESIGN.",
+ blockNumber,
+ required.hash(),
+ required.block(),
+ // A8: this used to print hashV1 next to `required.hash()`, which is computed with hashFor.
+ // Two numbers set side by side to be compared, but computed differently: for a registry
+ // that carries proofs the two can NEVER match, and the message sends the operator hunting
+ // for the defect where it is not. Measured on a fleet of seven on 2026-08-06.
+ loaded == null
+ ? "(no registry loaded)"
+ : PqRegistryHash.hashFor(loaded, registryBindingChainId),
+ PROPERTY_REGISTRY_MISMATCH_ALLOW,
+ loaded == null ? "(none)" : loaded.sourcePath(),
+ loaded == null ? "(none)" : loaded.kind(),
+ loaded == null ? 0 : loaded.count(),
+ loaded != null && loaded.addressBound(),
+ required.hash());
+ }
+
+ /**
+ * One loud, complete line per height, at most. Bounded because this sits on the header path and a
+ * mismatched node is offered a header roughly twice a second; an unbounded log would bury the
+ * first and most useful occurrence.
+ */
+ private void shoutRegistryBindingMismatch(
+ final long blockNumber,
+ final PqRegistryHash.ScheduleEntry required,
+ final PqRegistryHash.Registry loaded) {
+ if (registryBindingLastShout.getAndSet(blockNumber) == blockNumber) {
+ return;
+ }
+ LOG.error(
+ "AERE PQC A8 [AERE-PQC-REG-BLOCK-01]: REFUSING header at height {} (fail-closed). The "
+ + "chain requires registry hash {} from height {} (schedule source {}), and the "
+ + "registry this node is running has hash {}. Registry in use: {} ({}), {} entries, "
+ + "address-bound={}. WHY THIS FIRES NOW AND NOT AT STARTUP: this node started under an "
+ + "earlier entry of the same schedule and a ROTATION height has passed underneath it. "
+ + "The startup guard cannot see that; this rule can. WHAT TO DO: install the registry "
+ + "whose hash is {} and restart. Per-row fingerprints of the registry in use: {}",
+ blockNumber,
+ required.hash(),
+ required.block(),
+ this.registryBindingSchedule == null ? "(none)" : this.registryBindingSchedule.source(),
+ // A8, same reason as above: this is compared against required.hash(), which is computed
+ // with hashFor.
+ loaded == null ? "(no registry loaded)" : PqRegistryHash.hashFor(loaded, registryBindingChainId),
+ loaded == null ? "(none)" : loaded.sourcePath(),
+ loaded == null ? "(none)" : loaded.kind(),
+ loaded == null ? 0 : loaded.count(),
+ loaded != null && loaded.addressBound(),
+ required.hash(),
+ rowFingerprints(loaded));
+ }
+
+ private String rowFingerprints(final PqRegistryHash.Registry loaded) {
+ if (loaded == null) {
+ return "(none)";
+ }
+ final StringBuilder sb = new StringBuilder();
+ for (int i = 0; i < loaded.count(); i++) {
+ if (i > 0) {
+ sb.append(' ');
+ }
+ sb.append('[').append(i).append(']').append(PqRegistryHash.fingerprint(loaded, i));
+ }
+ return sb.toString();
+ }
+
+ /**
+ * Outcome of the A8 registry-binding guard.
+ *
+ * @return the gate state, or null when the guard has not run
+ */
+ public PqRegistryHash.GateState registryBindingState() {
+ return registryBindingState;
+ }
+
+ /**
+ * Parse a Falcon manifest JSON node ({@code count} plus {@code 0..N-1} entries) into {@code
+ * outPub} / {@code outAddr} and return the keccak256 of the canonical pre-image, or {@code null}
+ * on any failure.
+ *
+ * <p>Each entry is EITHER an address-bound object {@code {"addr": "0x..", "pk": "hex"}} (the
+ * audit-fixed form that binds the Falcon key to a validator address) OR a bare pubkey hex string
+ * (legacy, pubkey-only). A manifest must be uniformly one or the other; a mixed manifest is
+ * rejected (fail-closed). The canonical pre-image is the concatenation, in ascending
+ * validator-index order, of {@code addr(20) || pk} when address-bound, or {@code pk} when legacy.
+ */
+ private static String parseManifest(
+ final JsonNode cfg, final Map<Integer, byte[]> outPub, final Map<Integer, Address> outAddr) {
+ if (cfg == null || cfg.isMissingNode() || !cfg.has("count")) {
+ return null;
+ }
+ final int count = cfg.get("count").asInt();
+ if (count <= 0) {
+ return null;
+ }
+ Boolean addressBoundMode = null; // decided by the first entry, then enforced uniformly
+ for (int i = 0; i < count; i++) {
+ final JsonNode e = cfg.get(Integer.toString(i));
+ if (e == null) {
+ return null;
+ }
+ final boolean bound = e.isObject();
+ if (addressBoundMode == null) {
+ addressBoundMode = bound;
+ } else if (addressBoundMode != bound) {
+ return null; // mixed manifest -> fail-closed
+ }
+ if (bound) {
+ final JsonNode addrNode = e.get("addr");
+ final JsonNode pkNode = e.get("pk");
+ if (addrNode == null || !addrNode.isTextual() || pkNode == null || !pkNode.isTextual()) {
+ return null;
+ }
+ final Address addr;
+ try {
+ addr = Address.fromHexString(addrNode.asText().trim());
+ } catch (final RuntimeException ex) {
+ return null;
+ }
+ if (addr == null) {
+ return null;
+ }
+ outAddr.put(i, addr);
+ outPub.put(i, Bytes.fromHexStringLenient(pkNode.asText().trim()).toArray());
+ } else {
+ if (!e.isTextual()) {
+ return null;
+ }
+ outPub.put(i, Bytes.fromHexStringLenient(e.asText().trim()).toArray());
+ }
+ }
+ final KeccakDigest kd = new KeccakDigest(256);
+ for (int i = 0; i < count; i++) {
+ if (Boolean.TRUE.equals(addressBoundMode)) {
+ // Base Besu d2032017: Address extends BytesHolder (not a Tuweni Bytes), so obtain the raw
+ // 20 address bytes via getBytes().toArray(). Byte-identical to the intended pre-image
+ // (addr20 || pk). Reconciled during PQ-CONSENSUS-BUILDTEST-2026-07-18 (compiles clean).
+ final byte[] a = outAddr.get(i).getBytes().toArray();
+ kd.update(a, 0, a.length);
+ }
+ final byte[] h = outPub.get(i);
+ kd.update(h, 0, h.length);
+ }
+ final byte[] digest = new byte[32];
+ kd.doFinal(digest, 0);
+ return Bytes.wrap(digest).toUnprefixedHexString();
+ }
+
+ /**
+ * Load the STAGE-2 late-anchor manifest file (a bare JSON object {@code {"count": N, "0": {...},
+ * ...}}) into a PENDING pubkey + address map. The registry is NOT populated here; activation
+ * happens only via {@link #activateLateAnchor} once the on-chain anchor contract has been
+ * observed.
+ *
+ * @param manifestPath path to the manifest JSON file
+ * @param pend out-param pending pubkey map
+ * @param pendAddr out-param pending validator-address map
+ * @return keccak256(canonical manifest) 64-hex no 0x, or null on any failure
+ */
+ private static String loadPendingLateManifest(
+ final String manifestPath,
+ final Map<Integer, FalconPublicKeyParameters> pend,
+ final Map<Integer, Address> pendAddr) {
+ try {
+ final byte[] raw = Files.readAllBytes(Paths.get(manifestPath));
+ final JsonNode root = new ObjectMapper().readTree(raw);
+ final Map<Integer, byte[]> pub = new HashMap<>();
+ final Map<Integer, Address> addr = new HashMap<>();
+ final String computed = parseManifest(root, pub, addr);
+ if (computed == null) {
+ return null;
+ }
+ for (final Map.Entry<Integer, byte[]> e : pub.entrySet()) {
+ pend.put(
+ e.getKey(), new FalconPublicKeyParameters(FalconParameters.falcon_512, e.getValue()));
+ }
+ pendAddr.putAll(addr);
+ return computed;
+ } catch (final Exception e) {
+ LOG.error(
+ "AERE PQC: failed to parse late-anchor manifest {}: {} (fail-closed).",
+ manifestPath,
+ e.toString());
+ return null;
+ }
+ }
+
+ /**
+ * Load the validator-to-Falcon-pubkey registry from a GENESIS-ANCHORED manifest and verify it
+ * against the on-chain-committed manifest hash.
+ *
+ * <p>Fail-CLOSED: if the manifest is absent, malformed, or its keccak256 does not equal the
+ * on-chain anchor (i.e. a tampered pubkey or address), the registry is left EMPTY and {@code
+ * null} is returned. With an empty registry every Falcon seal fails to verify, so a post-fork
+ * BLOCKING chain rejects the block - a manifest tamper is therefore detected and cannot be
+ * silently accepted.
+ *
+ * @param genesisPath path to the genesis file
+ * @param reg out-param registry map to populate on success
+ * @param regAddr out-param validator-address map to populate on success
+ * @return the verified manifest hash (64-hex, no 0x) on success, or {@code null} on any failure
+ */
+ private static String loadGenesisAnchoredRegistry(
+ final String genesisPath,
+ final Map<Integer, FalconPublicKeyParameters> reg,
+ final Map<Integer, Address> regAddr) {
+ try {
+ final byte[] raw = Files.readAllBytes(Paths.get(genesisPath));
+ final JsonNode root = new ObjectMapper().readTree(raw);
+ final JsonNode cfg = root.path("config").path("aereFalconRegistry");
+ final Map<Integer, byte[]> pub = new HashMap<>();
+ final Map<Integer, Address> addr = new HashMap<>();
+ final String computed = parseManifest(cfg, pub, addr);
+ if (computed == null) {
+ LOG.error(
+ "AERE PQC: genesis {} has no valid config.aereFalconRegistry manifest; registry EMPTY "
+ + "(fail-closed).",
+ genesisPath);
+ return null;
+ }
+
+ final String anchored = readAnchoredHash(root);
+ if (anchored == null) {
+ LOG.error(
+ "AERE PQC: genesis {} has no on-chain anchored manifest hash at alloc 0x{} slot 0; "
+ + "registry EMPTY (fail-closed).",
+ genesisPath,
+ ANCHOR_ADDRESS);
+ return null;
+ }
+ if (!computed.equalsIgnoreCase(anchored)) {
+ LOG.error(
+ "AERE PQC: GENESIS MANIFEST TAMPER DETECTED - keccak256(manifest)=0x{} != "
+ + "genesis-anchored hash 0x{} (alloc 0x{} slot 0). Registry REJECTED / EMPTY "
+ + "(fail-closed); post-fork blocks will not verify.",
+ computed,
+ anchored,
+ ANCHOR_ADDRESS);
+ return null;
+ }
+
+ for (final Map.Entry<Integer, byte[]> e : pub.entrySet()) {
+ reg.put(
+ e.getKey(), new FalconPublicKeyParameters(FalconParameters.falcon_512, e.getValue()));
+ }
+ regAddr.putAll(addr);
+ LOG.info(
+ "AERE PQC: loaded GENESIS-ANCHORED Falcon registry ({} entries, address-bound={}) from "
+ + "{}; manifestHash=0x{} MATCHES on-chain anchor (alloc 0x{} slot 0, committed in the "
+ + "genesis stateRoot / block hash). Registry is immutable from genesis.",
+ reg.size(),
+ !regAddr.isEmpty() && regAddr.size() == reg.size(),
+ genesisPath,
+ computed,
+ ANCHOR_ADDRESS);
+ return computed;
+ } catch (final Exception e) {
+ LOG.error(
+ "AERE PQC: failed to load genesis-anchored Falcon registry from {}: {} "
+ + "(registry EMPTY, fail-closed).",
+ genesisPath,
+ e.toString());
+ return null;
+ }
+ }
+
+ /** Read the anchored manifest hash from genesis alloc[ANCHOR].storage[slot0]; null if absent. */
+ private static String readAnchoredHash(final JsonNode root) {
+ final JsonNode alloc = root.path("alloc");
+ if (alloc.isMissingNode()) {
+ return null;
+ }
+ final Iterator<Map.Entry<String, JsonNode>> it = alloc.fields();
+ while (it.hasNext()) {
+ final Map.Entry<String, JsonNode> en = it.next();
+ if (!norm(en.getKey(), 40).equals(ANCHOR_ADDRESS)) {
+ continue;
+ }
+ final JsonNode storage = en.getValue().path("storage");
+ if (storage.isMissingNode()) {
+ return null;
+ }
+ final Iterator<Map.Entry<String, JsonNode>> sit = storage.fields();
+ while (sit.hasNext()) {
+ final Map.Entry<String, JsonNode> entry = sit.next();
+ if (norm(entry.getKey(), 64).equals(ANCHOR_SLOT)) {
+ return norm(entry.getValue().asText(), 64);
+ }
+ }
+ }
+ return null;
+ }
+
+ /** Normalise a hex string: strip 0x, lower-case, left-pad with zeros to {@code width} chars. */
+ private static String norm(final String hex, final int width) {
+ String s = hex == null ? "" : hex.trim();
+ if (s.startsWith("0x") || s.startsWith("0X")) {
+ s = s.substring(2);
+ }
+ s = s.toLowerCase(Locale.ROOT);
+ final StringBuilder b = new StringBuilder();
+ for (int i = s.length(); i < width; i++) {
+ b.append('0');
+ }
+ b.append(s);
+ return b.toString();
+ }
+
+ /**
+ * Process-wide lazy singleton.
+ *
+ * @return the shared instance
+ */
+ public static FalconSealSupport instance() {
+ if (instance == null) {
+ synchronized (FalconSealSupport.class) {
+ if (instance == null) {
+ instance = new FalconSealSupport();
+ }
+ }
+ }
+ return instance;
+ }
+
+ /**
+ * D-177 (2026-08-28): every legacy {@code aere.falcon.*} switch now has a first-class
+ * algorithm-neutral twin, {@code aere.pq.sig.*} (env {@code AERE_PQ_SIG_*}). The protocol
+ * surface an operator touches must not name a primitive: the founder's next step is the
+ * Falcon+SPHINCS+ hybrid, and a second algorithm must not mean a second set of sixteen
+ * parallel switches. Precedence, and why it is shaped this way:
+ *
+ * <ul>
+ * <li>the NEUTRAL name wins when only it is set - new fleets never need the legacy name;
+ * <li>the LEGACY name still works alone - the live fleet keeps running untouched;
+ * <li>both set to the SAME value is fine - that is what a migration window looks like;
+ * <li>both set to DIFFERENT values REFUSES to start. A node that silently prefers one
+ * spelling turns a typo into a consensus divergence, and on 2026-08-09 a silent
+ * property rewrite already cost this fleet a live fork for two days.
+ * </ul>
+ */
+ static String resolve(final String sysProp, final String envVar) {
+ final String neutralProp =
+ sysProp.startsWith("aere.falcon.")
+ ? "aere.pq.sig." + sysProp.substring("aere.falcon.".length())
+ : null;
+ final String neutralEnv =
+ envVar.startsWith("AERE_FALCON_")
+ ? "AERE_PQ_SIG_" + envVar.substring("AERE_FALCON_".length())
+ : null;
+ final String neutral = firstNonBlank(
+ neutralProp == null ? null : System.getProperty(neutralProp),
+ neutralEnv == null ? null : System.getenv(neutralEnv));
+ final String legacy = firstNonBlank(System.getProperty(sysProp), System.getenv(envVar));
+ if (neutral != null && legacy != null && !neutral.trim().equals(legacy.trim())) {
+ throw new ActivationConfigException(
+ ActivationConfigException.Kind.SYNTAX,
+ "AERE-PQC-CFG-DUAL-NAME-01",
+ "AERE PQC: "
+ + neutralProp
+ + " and its legacy twin "
+ + sysProp
+ + " are BOTH set, to DIFFERENT values ('"
+ + neutral
+ + "' vs '"
+ + legacy
+ + "'). Refusing to start: a node that silently prefers one spelling turns a typo "
+ + "into a consensus divergence. Set exactly one, or both to the same value.");
+ }
+ return neutral != null ? neutral : legacy;
+ }
+
+ private static String firstNonBlank(final String a, final String b) {
+ if (a != null && !a.isBlank()) {
+ return a;
+ }
+ if (b != null && !b.isBlank()) {
+ return b;
+ }
+ return null;
+ }
+
+ // ---- STAGE-2 LATE-ANCHOR API ----
+
+ /**
+ * Whether a late-anchor manifest is configured, parsed, and still awaiting on-chain activation.
+ * Returns false once activated, terminally failed, or when late-anchor mode is not configured.
+ *
+ * @return true iff consensus code should keep looking for the on-chain anchor contract
+ */
+ public boolean lateAnchorPending() {
+ return anchorContractAddress != null && !lateActivated && !lateFailed;
+ }
+
+ /**
+ * The configured on-chain anchor contract address for the late-anchor registry source.
+ *
+ * @return the 0x-hex contract address, or null when late-anchor mode is not configured
+ */
+ public String anchorAddress() {
+ return anchorContractAddress;
+ }
+
+ /**
+ * Whether the registry has been activated from the late-anchor (contract-anchored) source.
+ *
+ * @return true iff late-anchor activation succeeded
+ */
+ public boolean lateAnchored() {
+ return lateActivated;
+ }
+
+ /**
+ * Whether the late anchor is TERMINALLY FAILED, i.e. an on-chain anchor was observed and its hash
+ * did NOT match the local manifest (tamper, or a wrong manifest shipped to this node).
+ *
+ * <p>AERE FIX-OPRIRE-CONSENS (c): this is the state the old code had no way to express. {@link
+ * #lateAnchorPending()} returns false both while a legitimate anchor has simply not landed yet AND
+ * after a tampered anchor was rejected, and the validation rule keyed BLOCKING off {@code
+ * genesisAnchored() || lateAnchored()} alone. A tampered anchor therefore silently degraded the
+ * whole PQC layer to LOG-ONLY: it failed OPEN. PENDING and terminally FAILED are now distinct, and
+ * the rule fails CLOSED on FAILED.
+ *
+ * @return true iff a manifest/anchor mismatch was detected and the registry is permanently empty
+ */
+ public boolean lateAnchorFailed() {
+ return lateFailed;
+ }
+
+ /**
+ * STAGE-2: activate the pending late-anchor registry against the manifest hash observed in the
+ * anchor contract's storage slot 0 in the chain's world state.
+ *
+ * <p>Idempotent and fail-closed: on a hash match the pending manifest becomes the live registry;
+ * on a mismatch the registry stays EMPTY and the late-anchor path is terminally failed (so a
+ * post-fork BLOCKING chain rejects blocks rather than accepting an unverified manifest).
+ *
+ * @param onChainHash the 32-byte hash read from the anchor contract's slot 0 (hex, 0x optional)
+ * @return true iff the registry is (now) activated from the late anchor
+ */
+ public synchronized boolean activateLateAnchor(final String onChainHash) {
+ if (lateActivated) {
+ return true;
+ }
+ if (lateFailed || anchorContractAddress == null || pendingLateHash == null) {
+ return false;
+ }
+ final String observed = norm(onChainHash, 64);
+ if (!pendingLateHash.equalsIgnoreCase(observed)) {
+ LOG.error(
+ "AERE PQC: LATE-ANCHOR MANIFEST TAMPER DETECTED - keccak256(local manifest)=0x{} != "
+ + "on-chain anchor 0x{} at contract {} slot 0. Registry REJECTED / EMPTY "
+ + "(fail-closed); post-fork blocks will not verify.",
+ pendingLateHash,
+ observed,
+ anchorContractAddress);
+ lateFailed = true;
+ return false;
+ }
+ registry.putAll(pendingLate);
+ if (pendingLateAddresses != null) {
+ indexToAddress.putAll(pendingLateAddresses);
+ }
+ manifestHash = pendingLateHash;
+ lateActivated = true;
+ LOG.info(
+ "AERE PQC: LATE-ANCHOR ACTIVATED - Falcon registry ({} entries, address-bound={}) is now "
+ + "live; keccak256(manifest)=0x{} MATCHES the on-chain anchor at contract {} slot 0 "
+ + "(readable via eth_getStorageAt). Hybrid PQC certificate can now be verified on an "
+ + "already-live chain with NO re-genesis.",
+ registry.size(),
+ addressBound(),
+ pendingLateHash,
+ anchorContractAddress);
+ return true;
+ }
+
+ /**
+ * Whether this node holds a Falcon signing key and should attach a parallel seal.
+ *
+ * @return true if signing is enabled
+ */
+ public boolean signingEnabled() {
+ return signingEnabled;
+ }
+
+ /**
+ * This node's validator index in the Falcon registry.
+ *
+ * @return the local validator index, or -1 if signing is disabled
+ */
+ public int localIndex() {
+ return localIndex;
+ }
+
+ /**
+ * Number of validators in the Falcon registry.
+ *
+ * @return the registry size
+ */
+ public int registrySize() {
+ return registry.size();
+ }
+
+ // ---- AERE audit fix (AUD-CONSENSUS-1 / -2): address binding + eligible-signer set ----
+
+ /**
+ * Whether the active registry binds every one of its Falcon keys to a validator ADDRESS. Only an
+ * address-bound registry can produce a well-defined {@code currentValidators INTERSECT registry}
+ * eligible-signer set, so ONLY an address-bound registry may arm blocking. The legacy pubkey-only
+ * {@code aere.falcon.registry} file and an empty (pending / unconfigured) registry both return
+ * false, so a post-fork block over such a registry fails closed.
+ *
+ * @return true iff the registry is non-empty and every registry index has a bound validator
+ * address
+ */
+ public boolean addressBound() {
+ return !registry.isEmpty() && indexToAddress.size() == registry.size();
+ }
+
+ /**
+ * The validator ADDRESS bound to a registry index, or {@code null} if the index is unregistered
+ * or the registry is not address-bound.
+ *
+ * @param validatorIndex the registry index carried by a Falcon seal
+ * @return the bound validator address, or null
+ */
+ public Address addressForIndex(final int validatorIndex) {
+ return indexToAddress.get(validatorIndex);
+ }
+
+ /**
+ * AERE 2026-08-07. Refuses to start when the Falcon key this node loaded belongs to a DIFFERENT
+ * validator, i.e. when the registry binds the key's index to an address that is not this node's.
+ *
+ * <p>WHY THIS EXISTS, and it is a measurement not a worry. Seven test nodes, one variable changed:
+ * node 0 was handed index 1's key file. It started clean and logged {@code loaded local Falcon
+ * signing key for validator index 1} - the very same line the node that really is index 1 logs.
+ * Zero refusals, zero mismatch lines. The chain then crossed the K=3 threshold height without a
+ * pause, to height 86, with zero rejected blocks on the healthy nodes and zero divergence, because
+ * the seals VERIFY: it is genuinely index 1's key. What was silently lost is that index 0
+ * disappeared from the signer set and index 1 was duplicated. The N=7, K=3, f=2 margin is computed
+ * over SEVEN DISTINCT signers; you have six and nothing tells you.
+ *
+ * <p>Nothing else catches it. Not startup, not the log, not the block rhythm, not rejections, not
+ * the divergence detector - every node agrees, because the certificate is valid. Until today the
+ * only guard was a PROCEDURE step run by hand on each target, and a procedure step can be skipped.
+ * The runbook claimed it "shows up as R2 rejections at the anchor height"; measured, it does not.
+ *
+ * <p>WHY IT IS SAFE TO REFUSE HERE. Same argument as the other startup guards: this runs before
+ * the network and the QBFT state machine start, so it is a clean refusal to start rather than a
+ * mid-flight halt. It is INERT unless a Falcon key is configured AND the registry is address-bound,
+ * so on chain 2800 as it stands today - no {@code aere.falcon.key} anywhere - it cannot fire.
+ *
+ * <p>A null bound address is NOT treated as a failure: that means a pubkey-only registry, which is
+ * already refused elsewhere for the paths that matter, and turning it into a second refusal here
+ * would move the operator's attention to the wrong place.
+ *
+ * @param thisNodeAddress this node's own validator address, derived from its node key
+ */
+ public void verifyLocalKeyBelongsToThisNodeOrAbort(final Address thisNodeAddress) {
+ if (localIndex < 0 || localPrivateKey == null) {
+ return; // no local Falcon key: nothing to bind
+ }
+ if (thisNodeAddress == null) {
+ LOG.warn(
+ "AERE PQC KEY-ADDR: this node holds Falcon key index {} but its own validator address "
+ + "could not be derived, so the key-to-machine binding was NOT checked. This is the "
+ + "one failure mode that stays invisible afterwards.",
+ localIndex);
+ return;
+ }
+ final Address bound = indexToAddress.get(localIndex);
+ if (bound == null) {
+ LOG.warn(
+ "AERE PQC KEY-ADDR: this node holds Falcon key index {} and the registry binds NO address "
+ + "to that index (pubkey-only registry), so the key-to-machine binding cannot be "
+ + "checked. A key placed on the wrong machine would not be detectable here.",
+ localIndex);
+ return;
+ }
+ if (bound.equals(thisNodeAddress)) {
+ LOG.info(
+ "AERE PQC KEY-ADDR: local Falcon key index {} is bound by the registry to {}, which is "
+ + "this node's own validator address. Key and machine agree.",
+ localIndex,
+ bound);
+ return;
+ }
+ throw new ActivationConfigException(
+ ActivationConfigException.Kind.UNSAFE,
+ "AERE-PQC-KEY-ADDR-01",
+ "AERE PQC: REFUSING TO START (fail-closed). The local Falcon key index does not map to "
+ + "this node.\n"
+ + " READ: aere.falcon.key carries index "
+ + localIndex
+ + ", and the registry binds that index to validator "
+ + bound
+ + ".\n"
+ + " BUT: this node's own validator address is "
+ + thisNodeAddress
+ + ".\n"
+ + " MEANING: this machine was handed ANOTHER validator's Falcon key. If it started, it "
+ + "would sign as "
+ + bound
+ + ", so that index would be produced by two machines while this node's own index would "
+ + "never appear in any certificate. The quorum would be silently one signer short: the "
+ + "N/K/f margin is computed over DISTINCT signers.\n"
+ + " WHY YOU WOULD NOT HAVE NOTICED: measured 2026-08-07 on seven nodes, this exact "
+ + "mistake produces a chain that crosses the threshold height with no pause, no rejected "
+ + "blocks, no divergence and no error line anywhere.\n"
+ + " FIX: put the key whose index the registry binds to "
+ + thisNodeAddress
+ + " on this machine, and run the on-target check "
+ + "(VerificaPotrivireaCheilor) before starting.");
+ }
+
+ /**
+ * D2 HARDENING (a). THIS NODE's own signing identity, which is the one place in the stack that
+ * legitimately has no height.
+ *
+ * <p>WHY IT IS A SEPARATE METHOD AND NOT {@code addressForIndex(localIndex())}. The adversarial
+ * review of 2026-08-02 (D2) found the verification path asking the registry questions with no
+ * height. Deleting the height-less pair from {@link PqSignerRegistry} left exactly one honest
+ * caller behind: {@code QbftBlockCreatorAdaptor} asking "am I, right now, an eligible signer",
+ * before signing with the single private key this process holds. There is no historical question
+ * in that, and inventing a height for it would be a lie dressed as rigour. Giving it its own name
+ * means the two uses can no longer be confused by a future reader, which is how D2 arrived in the
+ * first place.
+ *
+ * @return this node's registry-bound address, or null when it holds no key or the registry is not
+ * address-bound
+ */
+ public Address localSigningAddress() {
+ return indexToAddress.get(localIndex);
+ }
+
+ /**
+ * D2 HARDENING (b). The height at and above which this node is ARMED, i.e. from which a header's
+ * Falcon certificate carries consensus weight.
+ *
+ * <p>WHY THE HEIGHT-RESOLVED LOOKUPS NEED IT. Before this, {@code keyAt} and {@code
+ * addressForIndexAt} fell back to the HEAD registry whenever no {@code config.pqRegistryHash}
+ * entry was in force - and {@code pqRegistryHash} is in no genesis this fleet runs (measured
+ * 2026-08-05: {@code grep -rn pqRegistryHash --include=*.json deploy/ monitoring/} returns
+ * nothing). So the whole D-081 machinery was inert and the answer above the arming height was
+ * still "verify this year-old header against today's keys", which IS D2/T2, unrepaired. Falling
+ * back is correct BELOW the arming height, where no certificate is being judged; at and above it,
+ * the honest answer to "which keys were in force here" is a refusal, not a guess.
+ *
+ * <p>Read through {@link PqAnchorProducer#config()} so the value is the same one the producer and
+ * the R1/R2 rules use, memoised there. Never throws: a broken anchor configuration already fails
+ * closed at construction, and this method must not be the thing that turns a diagnostic into an
+ * exception on the per-block path.
+ *
+ * <p>INERT ON CHAIN 2800 AS IT STANDS. {@code aere.pq.anchorBlock} is unset on the live fleet, so
+ * {@code everActive()} is false, this returns {@link Long#MAX_VALUE}, no height is at or above it,
+ * and every answer below is byte-for-byte what it was before. This code cannot stop a validator
+ * that is running today.
+ *
+ * @return the arming height, or {@link Long#MAX_VALUE} when the anchor is not configured
+ */
+ private long anchorArmedFrom() {
+ try {
+ final PqAnchorConfig cfg =
+ org.hyperledger.besu.consensus.common.bft.blockcreation.PqAnchorProducer.config();
+ return cfg.everActive() ? cfg.anchorBlock() : Long.MAX_VALUE;
+ } catch (final RuntimeException e) {
+ // An unreadable anchor configuration is already a refusal to start elsewhere. Here, the
+ // conservative answer is "armed from nowhere", because claiming armed would refuse headers on
+ // a node whose only fault is a diagnostic that threw.
+ return Long.MAX_VALUE;
+ }
+ }
+
+ /**
+ * The set of validator addresses that have a Falcon key in the registry. This is the "signer
+ * registry" side of the eligible-signer intersection {@code currentValidators INTERSECT
+ * registry}.
+ *
+ * @return an immutable snapshot of the registered validator addresses (possibly empty)
+ */
+ public Set<Address> registeredValidatorAddresses() {
+ return Set.copyOf(indexToAddress.values());
+ }
+
+ /**
+ * Whether the registry covers the given (current) validator set, i.e. every current validator has
+ * a Falcon key in the registry. This is the ARMING INVARIANT (AUD-CONSENSUS-1): blocking should be
+ * armed only when coverage is complete, so the eligible-signer set equals the full validator set
+ * and the Falcon quorum matches the ECDSA quorum. When coverage is incomplete the blocking rule
+ * stays LIVE on the intersection (it never silently halts) but warns that the margin is reduced
+ * and a registry re-anchor is required.
+ *
+ * @param validators the current QBFT validator set
+ * @return true iff the registry is address-bound and contains every current validator
+ */
+ public boolean registryCoversValidators(final Collection<Address> validators) {
+ if (!addressBound()) {
+ return false;
+ }
+ final Set<Address> registered = registeredValidatorAddresses();
+ return registered.containsAll(validators);
+ }
+
+ /**
+ * Whether the registry was resolved from a verified GENESIS-ANCHORED manifest (as opposed to the
+ * late-anchor path, the legacy mutable file, or no registry at all).
+ *
+ * @return true iff the registry is genesis-anchored and its hash matched the on-chain anchor
+ */
+ public boolean genesisAnchored() {
+ return genesisAnchored;
+ }
+
+ /**
+ * The verified keccak256 of the canonical anchored manifest (genesis-anchored or late-anchored),
+ * or {@code null} when no anchored registry is active.
+ *
+ * @return the manifest hash as 64-hex (no 0x prefix), or null
+ */
+ public String registryManifestHash() {
+ return manifestHash;
+ }
+
+ /**
+ * The block number at and after which the LEGACY per-block Falcon rule
+ * ({@link org.hyperledger.besu.consensus.qbft.headervalidationrules.FalconSealValidationRule})
+ * becomes blocking. Configured via {@code aere.falcon.forkBlock} / {@code AERE_FALCON_FORKBLOCK};
+ * defaults to {@link Long#MAX_VALUE} (never blocking, pure log-only) so an unconfigured node
+ * behaves exactly like the additive baseline.
+ *
+ * <p><b>ON CHAIN 2800 THIS ARMS A RULE THAT IS ALREADY RETIRED, so setting it changes nothing
+ * (finding D-235, corrected 2026-08-19).</b> The legacy rule stands down at
+ * {@code PqAnchorConfig.legacyFalconRuleRetirementBlock()} = the anchor block, 13,014,000, and
+ * this property is set to 14,050,000 - above it. Until 2026-08-19 our own public texts said a
+ * per-block 2f+1 Falcon quorum had been blocking since that height; the claim was withdrawn the
+ * same day. What is defensible: at every 32nd height a certificate of at least K valid Falcon-512
+ * seals sits under the block hash, and without it that block does not finalize.
+ *
+ * <p>AERE D-079 (2026-08-03): this used to re-read the property on every call and swallow a
+ * NumberFormatException into {@link Long#MAX_VALUE} with a WARN line. That is the finding, in one
+ * method: the single value the entire post-quantum enforcement layer is gated on could silently
+ * become "never blocking", and the only trace was a log line nothing reads. The value is now
+ * resolved once, in the constructor, by {@link #validateForkBlockConfigOrAbort()}, which ABORTS on
+ * anything it cannot parse. There is no longer any input to this method and therefore no longer
+ * any way for it to fail open.
+ *
+ * @return the fork block, or {@link Long#MAX_VALUE} if unconfigured
+ */
+ public long forkBlock() {
+ return forkBlock;
+ }
+
+ /**
+ * AERE D-079: the DECLARED height at or after which the on-chain late-anchor registry contract is
+ * expected to be observable, or {@link Long#MAX_VALUE} when undeclared.
+ *
+ * @return the declared anchor observation height
+ */
+ public long anchorObserveBlock() {
+ return anchorObserveBlock;
+ }
+
+ /**
+ * AERE D-079: the first height at which this node validated a header at or after the blocking
+ * height while the anchored registry was NOT active, or -1 if that has never happened.
+ *
+ * <p>The configuration guard refuses the misconfiguration that CAUSES this. It cannot refuse the
+ * accident: a correctly declared observation height whose anchor transaction never lands. From
+ * that height on, the node runs log-only while its operator believes the Falcon quorum is
+ * enforced. This counter is the difference between that situation being visible and it being a
+ * warning in a file.
+ *
+ * @return the first such height, or -1
+ */
+ public long blockingArmedWithoutRegistrySince() {
+ return blockingArmedWithoutRegistrySince.get();
+ }
+
+ /**
+ * Record that the blocking height has been reached with no active anchored registry. Never throws;
+ * called from the header-validation path.
+ *
+ * @param blockNumber the height at which the condition was observed
+ * @return true iff this is the FIRST height at which it was observed, so the caller can log once
+ * instead of once per block (a per-block line at a sub-second block period is a disk hazard,
+ * measured on this fleet in a different form on 2026-08-02)
+ */
+ public boolean noteBlockingArmedWithoutActiveRegistry(final long blockNumber) {
+ final boolean first = blockingArmedWithoutRegistrySince.compareAndSet(-1L, blockNumber);
+ if (first) {
+ LOG.error(
+ "AERE PQC [AERE-PQC-ARM-INERT-01]: block {} is at or after the Falcon BLOCKING height {} "
+ + "and the anchored registry is NOT active, so the Falcon quorum is NOT being "
+ + "enforced and will not be until the anchor lands. Declared observation height was "
+ + "{}. This node is running the additive LOG-ONLY baseline while configured to "
+ + "enforce a post-quantum quorum. Deploy or re-observe the anchor contract {}.",
+ blockNumber,
+ forkBlock,
+ anchorObserveBlock == Long.MAX_VALUE ? "undeclared" : Long.toString(anchorObserveBlock),
+ anchorContractAddress == null ? "(none configured)" : anchorContractAddress);
+ }
+ return first;
+ }
+
+ /**
+ * AERE audit fix (AUD-CONSENSUS-1) fail-closed ARMING diagnostic, emitted once at construction.
+ * If a fork block is configured (blocking is intended) but the manifest that will back it is not
+ * address-bound, the {@code currentValidators INTERSECT registry} eligible-signer set cannot be
+ * formed and post-fork blocks will fail closed. We log this LOUDLY here (arm/config time) rather
+ * than let it surface as a silent block-production halt later. We deliberately do NOT throw: this
+ * class must never throw on the consensus path, so the guarantee is loud-diagnostic-plus-fail-
+ * closed-reject (in the rule), not process abort.
+ */
+ private void armingReadinessDiagnostic() {
+ final long fork = forkBlock();
+ if (fork == Long.MAX_VALUE) {
+ return; // blocking not configured; nothing to arm
+ }
+ final boolean pendingAddressBound =
+ pendingLate != null
+ && pendingLateAddresses != null
+ && !pendingLate.isEmpty()
+ && pendingLateAddresses.size() == pendingLate.size();
+ if (addressBound() || (anchorContractAddress != null && pendingAddressBound)) {
+ LOG.info(
+ "AERE PQC: blocking configured (forkBlock={}); backing manifest is ADDRESS-BOUND, so the "
+ + "eligible-signer set (currentValidators INTERSECT registry) is well defined.",
+ fork);
+ return;
+ }
+ // AERE A8 REPAIR (2026-08-02). This used to be LOG.error and nothing else, and the comment
+ // above still says "diagnostic only". That was measured to be the wrong trade. A node that
+ // starts here does not stay harmless: it joins the fleet, reaches the activation height, and
+ // from that height rejects every header that carries a certificate. Measured on three
+ // observers: head 19 with R2=4 rejections, against head 374 with R1=0 R2=0 for the
+ // address-bound source on the same honest chain. A whole fleet configured this way stops, and
+ // stops in the shape of a consensus failure rather than a configuration error, which is the
+ // most expensive shape a configuration error can take.
+ //
+ // So it now REFUSES TO START. The reasons this is safe to do HERE, and only here: this is the
+ // constructor, i.e. config time, on the same path as validateForkBlockConfigOrAbort() and
+ // validateAndResolveAttachBlockOrAbort(), which already abort; the network is not up; the QBFT
+ // state machine has not been created; and no header has been offered to anybody. The promise
+ // that this class never throws is a promise about the PER-BLOCK path, and it is kept: nothing
+ // below this constructor throws.
+ //
+ // The refusal is inert on chain 2800 as it stands today, because forkBlock is unset there, so
+ // this code cannot stop a live validator that is running now.
+ throw new ActivationConfigException(
+ ActivationConfigException.Kind.UNSAFE,
+ "AERE-PQC-REG-ARM-01",
+ "AERE PQC A8: REFUSING TO START (fail-closed). Falcon blocking is "
+ + "configured at forkBlock="
+ + fork
+ + " but the active Falcon registry is NOT ADDRESS-BOUND"
+ + " (registrySize="
+ + registry.size()
+ + ", indexToAddress="
+ + indexToAddress.size()
+ + ", source="
+ + (registrySourcePath == null ? "(none)" : registrySourcePath)
+ + " ["
+ + registrySourceKind
+ + "], late-anchor pending="
+ + (anchorContractAddress != null)
+ + "). WHAT THIS MEANS: addressForIndex() returns null for every index, so the "
+ + "eligible-signer set (currentValidators INTERSECT registry) is empty and EVERY block "
+ + "at or above the activation height would be rejected by the seals rule. Measured, "
+ + "this is not a degradation, it is a fleet-wide halt: three observers replaying the "
+ + "same honest chain reached head 374 with an address-bound registry and stopped at "
+ + "head 19 with this one. WHAT TO DO: re-anchor the registry in an ADDRESS-BOUND form "
+ + "- a genesis manifest at config.aereFalconRegistry with {\"addr\",\"pk\"} entries, or "
+ + "a properties file carrying a '<i>.addr=0x<20 bytes>' row for every index - and set "
+ + "config.pqRegistryHash to its hash, before configuring aere.falcon.forkBlock. To "
+ + "start this node unchanged for diagnosis, unset aere.falcon.forkBlock; the node is "
+ + "then log-only and cannot halt anything.");
+ }
+
+ /**
+ * AERE D-146 (2026-08-06). REFUSE TO START when this node is ARMED and the registry it will be
+ * held to carries no binding proofs.
+ *
+ * <p>WHAT IT ADDS OVER {@code AERE-PQC-REG-ARM-01}. That guard asks whether the registry is
+ * ADDRESS-BOUND, i.e. whether index {@code i} has an address at all. This one asks the question
+ * that decides who a seal is CREDITED to: does row {@code i} carry a Falcon possession proof over
+ * its own {@code (chainId, bindHeight, count, i, address, publicKey)} pre-image, and an ECDSA
+ * claim over the same bytes signed by that validator's own consensus key. Without both, whoever
+ * writes the registry file decides attribution, and the threshold itself becomes fiction: two
+ * indices carrying the same key satisfy K=2 with a single private key.
+ *
+ * <p>WHY UNIQUENESS IS NOT ENOUGH, and this is measured rather than argued. Swapping the public
+ * keys of two rows leaves four distinct keys and four distinct addresses, so every uniqueness
+ * check passes and the forged header is ACCEPTED. Uniqueness repairs the THRESHOLD. Only a
+ * signature by the validator repairs ATTRIBUTION.
+ *
+ * <p>WHEN IT FIRES. Only when this node is armed: {@code aere.falcon.forkBlock} is configured, or
+ * the certificate anchor is active per {@link #anchorArmedFrom()}. Both are unset on chain 2800 as
+ * it stands, so this refusal is INERT on the live fleet exactly as AERE-PQC-REG-ARM-01 is, and it
+ * cannot stop a validator that is running today. That inertness is not asserted here, it is
+ * measured by {@code PqInertBinaryTest}, which drives a node with no {@code aere.pq.*}
+ * and no {@code aere.falcon.forkBlock} property at all through this constructor.
+ *
+ * <p>WHAT IT DOES NOT JUDGE. A node armed with NO registry file at all returns without a word.
+ * D-146 is about a row that credits a seal to the wrong validator, and a registry with no rows
+ * credits nobody; that condition belongs to AERE-PQC-REG-ARM-01 and AERE-PQC-CFG-UNSAFE-08, which
+ * own it and name the numbers. See the comment at the return itself for what was measured when
+ * this guard tried to own it too.
+ *
+ * <p>WHY IT IS NOT BEHIND THE EMERGENCY BYPASS. {@code aere.falcon.registry.mismatch.allow}
+ * overrides the A8 hash gate, which answers "is this the file genesis named" - a question about
+ * configuration drift, recoverable by installing the right file. This one answers "can this
+ * registry be trusted to say who signed", and the anchor contract is IMMUTABLE once written: a
+ * fleet armed over unbound rows carries D-146 for the life of the chain. The way out of THIS one
+ * is the same as for AERE-PQC-REG-ARM-01 - do not arm, or disarm: unset {@code
+ * aere.falcon.forkBlock}, or set {@code aere.pq.anchor.disable=true}, which makes {@link
+ * #anchorArmedFrom()} return {@link Long#MAX_VALUE} and leaves {@code PqEmergencyShoutRule}
+ * shouting at every height.
+ *
+ * <p>WHY IT MAY THROW HERE. Same path, same reasoning and same precedent as
+ * AERE-PQC-REG-ARM-01 and AERE-PQC-CFG-UNSAFE-04 directly around it: this is the constructor, the
+ * network is not up, the QBFT state machine does not exist and no header has been offered to
+ * anybody. The promise that this class never throws is a promise about the PER-BLOCK path, and it
+ * is kept.
+ *
+ * <p>NOT MEASURED, and written rather than hidden: when the anchor configuration itself cannot be
+ * read, {@link #anchorArmedFrom()} answers {@link Long#MAX_VALUE} and this guard therefore does
+ * not fire. That case is owned by the anchor loader, which refuses to start on its own account
+ * (AERE-PQC-ANCHOR-CONF-01); that the refusal always reaches the operator BEFORE this constructor
+ * runs has not been measured here.
+ *
+ * @throws PqRegistryHash.RegistryConfigException with code {@code AERE-PQC-REG-ARM-02} when this
+ * node is armed over a registry with no binding proofs
+ */
+ private void requireRegistryBindingProofsOrAbort() {
+ if (forkBlock() == Long.MAX_VALUE && anchorArmedFrom() == Long.MAX_VALUE) {
+ return; // nothing armed on this node; inert, exactly as on chain 2800 today
+ }
+ if (registrySourcePath == null) {
+ // AN ARMED NODE WITH NO REGISTRY AT ALL IS NOT A D-146 DEFECT, and this return is the
+ // difference between a guard and a blanket. D-146 is mis-ATTRIBUTION: a row that credits a
+ // seal to a validator who never held the key on it. That requires ROWS. With no registry
+ // there are no rows, indexToAddress is empty, the eligible-signer set is empty, and nobody
+ // can be credited with anything - there is nothing for a forged binding to say.
+ //
+ // The "armed over nothing" condition is real and it is already owned, twice, by guards that
+ // say more than this one could: AERE-PQC-REG-ARM-01 immediately above (when
+ // aere.falcon.forkBlock is set) and AERE-PQC-CFG-UNSAFE-08 immediately below, which refuses
+ // a positive threshold that the anchored key count cannot guarantee and names the two
+ // numbers. MEASURED 2026-08-06: refusing here instead took over both of those messages -
+ // PqForkThresholdReachabilityTest#aPositiveThresholdWithNoAnchoredKeysMustRefuseToStart got
+ // AERE-PQC-REG-ARM-02 where it must get AERE-PQC-CFG-UNSAFE-08 - and additionally refused
+ // the K=0 warm-up regime, which is the regime the fleet is meant to arm INTO. A guard that
+ // breaks the intended activation procedure is not fail-closed, it is just closed.
+ //
+ // KNOWN AND NOT CLOSED HERE: aere.falcon.testnetAllowSmallFleet waives
+ // AERE-PQC-CFG-UNSAFE-08, so on a fleet that sets it, armed + no registry + K>0 still
+ // starts. That is an explicitly named isolated-network waiver and it is deliberately not
+ // re-litigated by this guard.
+ return;
+ }
+ // Deliberately re-read from the source file rather than from the parsed maps: the proofs are
+ // per-ROW and the in-memory index-to-key / index-to-address maps have already thrown them away.
+ // A guard that judged the maps would be judging what survived the loader, not what was written.
+ PqRegistryHash.requireBindingsOrThrow(PqRegistryHash.loadAuto(Paths.get(registrySourcePath)));
+ }
+
+ /**
+ * AERE D-078 (2026-08-03). REFUSE TO START when the armed Falcon threshold K is above the number of
+ * anchored-key holders this fleet is GUARANTEED to have among a block's ECDSA committers.
+ *
+ * <p>WHY THIS EXISTS. The 2026-08-02 repair correctly removed the fleet-wide coverage question from
+ * the per-commit attachment gate, because answering it with "stop attaching" is what stopped the
+ * chain. In its place the javadoc of {@link #attachmentArmed} promised that the same protection was
+ * still there, one level up: "an arm-time decision, and it is made at arm time by
+ * armingReadinessDiagnostic() and by the operator". Measured on 2026-08-03: {@code
+ * armingReadinessDiagnostic()} tests ADDRESS-BOUNDNESS and nothing else. It does not read the fleet
+ * size, the keyed count, or K. The protection named there did not exist. This method is it.
+ *
+ * <p>WHAT IT COMPARES. K is the highest threshold the staged schedule ever reaches, because that is
+ * the one the chain will eventually be held to; the guarantee is {@link #worstCaseKeyedSigners}
+ * over the DECLARED fleet size and the anchored key count. Both numbers are known at config time,
+ * on every node, without a chain and without a vote. The emergency ceiling is deliberately ignored:
+ * it can only LOWER K later, and a guard must not be satisfied by a lever an operator may not pull.
+ *
+ * <p>WHY IT MAY THROW HERE. Same reasoning, same path and same precedent as AERE-PQC-CFG-UNSAFE-04
+ * and the A8 refusal directly above: this is the constructor, the network is not up, the QBFT state
+ * machine does not exist, and no header has been offered to anyone. The promise that this class
+ * never throws is a promise about the PER-BLOCK path, and it is kept.
+ *
+ * <p>WHY IT IS NOT A RUNTIME CHECK. A per-block version of this comparison would be exactly the
+ * defect of D-078 rebuilt: a fleet-wide fact, false on every node at the same height after an
+ * ordinary vote, answered with a halting action. The runtime half stays a REPORT, in {@link
+ * #reportRegistryCoverage}, and decides nothing.
+ *
+ * <p>INERT ON CHAIN 2800 as it stands: {@code aere.pq.anchorBlock} is unset there, so there is no
+ * threshold and no comparison. This code cannot stop a validator that is running now.
+ */
+ private void validateThresholdReachabilityOrAbort() {
+ final PqAnchorConfig anchor;
+ try {
+ anchor = PqAnchorConfig.fromSystemConfiguration();
+ } catch (final RuntimeException e) {
+ // The anchor loader already fails closed on its own account and logs why. A guard must not be
+ // the thing that turns an anchor-config fault into an unexplained startup failure here.
+ LOG.warn(
+ "AERE PQC: threshold-reachability guard SKIPPED - the anchor configuration could not be "
+ + "read ({}). This is NOT a statement that the threshold is reachable.",
+ e.toString());
+ return;
+ }
+ if (!anchor.everActive()) {
+ return;
+ }
+ int k = 0;
+ for (final Integer step : anchor.minSealsSchedule().values()) {
+ if (step != null && step > k) {
+ k = step;
+ }
+ }
+ if (k <= 0) {
+ return;
+ }
+
+ final int keyed = anchoredKeyCount();
+ final int fleet = Math.max(expectedFleetSize(), keyed);
+ final int guaranteed = worstCaseKeyedSigners(fleet, keyed);
+ final int deficit = thresholdDeficit(fleet, keyed, k);
+ if (deficit == 0) {
+ LOG.info(
+ "AERE PQC: Falcon threshold K={} is REACHABLE - a fleet of {} with {} anchored key "
+ + "holder(s) guarantees {} keyed signer(s) among a block's committers.",
+ k,
+ fleet,
+ keyed,
+ guaranteed);
+ return;
+ }
+
+ final boolean waived =
+ Boolean.parseBoolean(
+ String.valueOf(
+ resolve("aere.falcon.testnetAllowSmallFleet", "AERE_FALCON_TESTNET_SMALL_FLEET")));
+ if (waived) {
+ LOG.error(
+ "AERE PQC: aere.falcon.testnetAllowSmallFleet=true - arming Falcon threshold K={} on a "
+ + "fleet of {} with only {} anchored key holder(s), which guarantees {}. A proposer "
+ + "can legitimately fail to assemble a certificate. This setting MUST NOT be used on "
+ + "mainnet.",
+ k,
+ fleet,
+ keyed,
+ guaranteed);
+ return;
+ }
+
+ throw new ActivationConfigException(
+ ActivationConfigException.Kind.UNSAFE,
+ "AERE-PQC-CFG-UNSAFE-08",
+ "AERE PQC D-078: REFUSING TO START (fail-closed). The Falcon anchor is armed at height "
+ + anchor.anchorBlock()
+ + " with a staged threshold that reaches K="
+ + k
+ + ", but this fleet is guaranteed to produce only "
+ + guaranteed
+ + " Falcon seal(s) per block: "
+ + fleet
+ + " validator(s), of which "
+ + keyed
+ + " hold an anchored Falcon key, need ceil(2N/3)="
+ + BftHelpers.calculateRequiredValidatorQuorum(fleet)
+ + " ECDSA committers, and the unluckiest committer set takes every UNKEYED validator "
+ + "first. Short by "
+ + deficit
+ + ". WHAT THIS MEANS: with every node honest and every node up, a proposer can fail to "
+ + "assemble a certificate, and it fails on every node at once because the validator set "
+ + "is consensus state - the chain stops in a state where the re-anchoring transaction "
+ + "that would repair it can no longer be carried by any block. That is D-078. WHAT TO "
+ + "DO: re-anchor the manifest so that every validator holds a key (this is what makes "
+ + "the standing 'grow to N>=9 before arming' order safe - the manifest has to grow WITH "
+ + "the set, not after it), or lower the "
+ + PqAnchorConfig.PROPERTY_MIN_SEALS
+ + " schedule to at most "
+ + guaranteed
+ + ", or declare the true fleet size in aere.falcon.validatorCount if it is wrong here. "
+ + "Isolated test networks may set aere.falcon.testnetAllowSmallFleet=true.");
+ }
+
+ /**
+ * AERE D-078: how many validators hold an anchored Falcon key, counting a late anchor that has not
+ * landed yet the same way {@link #expectedFleetSize()} does, so the two numbers being compared are
+ * read at the same moment from the same manifest.
+ *
+ * @return the anchored key count
+ */
+ private int anchoredKeyCount() {
+ if (!registry.isEmpty()) {
+ return registry.size();
+ }
+ return pendingLate == null ? 0 : pendingLate.size();
+ }
+
+ // ---- AERE FIX-OPRIRE-CONSENS (b): SEAL-ATTACHMENT GATE ----
+
+ /**
+ * The block number at and after which this node may ATTACH a Falcon seal to its Commit messages.
+ * Configured via {@code aere.falcon.attachBlock} / {@code AERE_FALCON_ATTACHBLOCK}; defaults to
+ * {@link Long#MAX_VALUE}, i.e. NEVER attach.
+ *
+ * <p>This is deliberately a separate, EARLIER height than {@link #forkBlock()}. The safe ordering
+ * is: every validator binary upgraded (keyless) -&gt; fleet confirmed on the new binary -&gt;
+ * attachment height reached, seals start flowing and are verified LOG-ONLY -&gt; only then the fork
+ * height, where the Falcon quorum becomes blocking.
+ *
+ * @return the attachment height, or {@link Long#MAX_VALUE} when attachment is not configured
+ */
+ public long attachBlock() {
+ return attachBlock;
+ }
+
+ /**
+ * Record the validator set seen by the header-validation path. This is the "does the anchored
+ * registry cover the WHOLE fleet" input to the attachment gate, captured from the one place that
+ * already has an authoritative validator set for a given height.
+ *
+ * @param blockNumber the height the set was read at
+ * @param validators the validator set at that height
+ */
+ public void observeValidators(final long blockNumber, final Collection<Address> validators) {
+ if (validators == null || validators.isEmpty() || blockNumber < observedValidatorsHeight) {
+ return;
+ }
+ this.observedValidators = new LinkedHashSet<>(validators);
+ this.observedValidatorsHeight = blockNumber;
+ }
+
+ /**
+ * AERE D-078: the height at which a validator set was last observed, or {@code -1} when none ever
+ * was. Diagnostic, and the only way a test can tell "the gate is being fed" from "the gate happens
+ * to say yes anyway", which is the difference the D-078 repair turns on.
+ *
+ * @return the observation height, or -1 if no validator set has been observed
+ */
+ public long observedValidatorsHeight() {
+ return observedValidators == null ? -1L : observedValidatorsHeight;
+ }
+
+ /**
+ * Whether this node may ATTACH a Falcon seal to a Commit for the given block. Never throws.
+ *
+ * <p>All three conditions are fleet-wide facts, so every correct node flips at the same block:
+ *
+ * <ol>
+ * <li>an ATTACHMENT HEIGHT is configured and reached;
+ * <li>the anchored Falcon registry is ACTIVE (genesis-anchored, or a late anchor already
+ * observed on-chain) and address-bound;
+ * <li>that registry binds THIS node's own Falcon index to a validator address.
+ * </ol>
+ *
+ * <p><b>AERE D-078 (2026-08-02): condition 3 used to be "that registry COVERS every validator in
+ * the last observed validator set", and that is the sentence that stopped the chain.</b> Coverage
+ * is a property of the validator set, which is consensus state, so an ordinary add-validator vote
+ * falsifies it on every node at the same height; the old answer to that was to switch attachment
+ * OFF, which is fleet-wide, which starves every proposer of seals, which stops the chain in a
+ * state where the repairing transaction can no longer be included. Measured in {@code
+ * PqForkValidatorSetChangeTest}. Condition 3 is now a LOCAL fact that no membership change can
+ * falsify; coverage is REPORTED by {@link #reportRegistryCoverage} with the margin number it
+ * costs, and decides nothing.
+ *
+ * <p>WHICH CONDITION PROVIDES WHICH PROTECTION (corrected 2026-08-01; the earlier claim here was
+ * wrong and is restated so nobody relies on protection that is not there):
+ *
+ * <ul>
+ * <li>CONDITION 1 is what makes a one-by-one KEY rollout harmless. {@code attachBlock} defaults
+ * to {@link Long#MAX_VALUE}, so a node holding a Falcon key attaches nothing until an
+ * operator names an activation height. That default, and nothing else, is why step 3 of the
+ * activation order (distribute keys, restart one at a time) cannot emit a single seal.
+ * <li>CONDITION 2 stops attachment when the registry backing it is absent or not address-bound,
+ * so a seal is never emitted against a registry that cannot be checked.
+ * <li>CONDITION 3 checks that the anchored registry binds THIS node's own index, so this node
+ * never emits a seal no verifier can attribute. It stops one node, never the fleet, and
+ * nothing outside this node's own configuration can change its answer. It does NOT and
+ * cannot check peer BINARY VERSION, and it is emphatically NOT what makes the halting order
+ * impossible. Until 2026-08-02 it asked the FLEET question instead - does the registry cover
+ * every observed validator - and switched attachment off when the answer was no; see the
+ * D-078 note on the method below for why that was a chain stop rather than a safeguard.
+ * <li>The CHAIN-RELATIVE guard, {@link #verifyAttachHeightAgainstChainHeadOrAbort}, is what
+ * closes that last gap. It refuses to START a node whose activation height is not safely
+ * ahead of the chain head, so the height cannot be one that the fleet has already walked
+ * past without arming.
+ * </ul>
+ *
+ * <p>None of these check peer binary version. That remains procedural: see step 2 of the
+ * activation order and the "what this fix does NOT do" section of FIX-OPRIRE-CONSENS.
+ *
+ * @param blockNumber the block whose commit is being sealed
+ * @return true iff attaching a Falcon seal is safe for the whole fleet
+ */
+ public boolean attachmentArmed(final long blockNumber) {
+ if (attachBlock == Long.MAX_VALUE) {
+ if (signingEnabled && loggedAttachmentOff.compareAndSet(false, true)) {
+ LOG.warn(
+ "AERE PQC: this node HOLDS a Falcon signing key (index {}) but seal ATTACHMENT is NOT "
+ + "configured (aere.falcon.attachBlock unset), so NO Falcon-carrying Commit will be "
+ + "emitted. This is the safe default: emitting one while any peer still runs a "
+ + "binary with a strict Commit decoder would make that peer DISCARD the whole "
+ + "Commit, ECDSA seal included. Set aere.falcon.attachBlock only after the ENTIRE "
+ + "validator fleet runs a binary that can parse a Falcon-carrying Commit.",
+ localIndex);
+ }
+ return false;
+ }
+ if (blockNumber < attachBlock) {
+ return false;
+ }
+ if (!(genesisAnchored || lateActivated) || !addressBound()) {
+ if (loggedCoverageBlocked.compareAndSet(false, true)) {
+ LOG.error(
+ "AERE PQC: attachment height {} reached at block {} but the anchored registry is NOT "
+ + "active/address-bound (genesisAnchored={}, lateAnchored={}, lateAnchorFailed={}). "
+ + "Attachment stays OFF (fail-safe for liveness).",
+ attachBlock,
+ blockNumber,
+ genesisAnchored,
+ lateActivated,
+ lateFailed);
+ }
+ return false;
+ }
+ // AERE D-078 (2026-08-02), CONDITION 3, REPLACED. What stands here now is a LOCAL fact: does the
+ // anchored registry bind MY OWN index to an address, so that every verifier can resolve my seal
+ // to a signer. It is a property of this node and the anchored manifest, and nothing that happens
+ // to the validator set can falsify it.
+ //
+ // WHAT USED TO STAND HERE AND WHY IT HAD TO GO. The old condition 3 asked a FLEET question -
+ // "does the anchored registry cover every validator I have observed" - and answered NO by
+ // switching seal attachment OFF. Both halves are wrong, and the second is the halt:
+ //
+ // * an ordinary add-validator vote admits a node that, by construction, is not in a manifest
+ // anchored before it existed. Coverage therefore goes false on EVERY node at the SAME
+ // height, because the validator set is consensus state. Every node stops attaching, so no
+ // proposer can gather K seals, so PqAnchorProducer refuses for every proposer in turn and
+ // the chain stops - and it stops in a state where the re-anchoring transaction that would
+ // repair it can no longer be carried by any block. That is D-078, measured in
+ // PqForkValidatorSetChangeTest.
+ // * the input it read is fed by observeValidators, whose only caller stands down at the anchor
+ // height. Above that height the answer was either FROZEN at a set from below it, or - on any
+ // node whose process started above it - never set at all, which the old code also answered
+ // with "stop signing". A node restart is an ordinary operation; it must not be able to
+ // silence this node's post-quantum seal for good.
+ //
+ // "I could not measure the fleet" and "the fleet is unsafe" are different states, and only one of
+ // them justifies the halting action. Coverage is now REPORTED, with the liveness margin it
+ // actually costs, and it decides nothing. What coverage genuinely protects - that blocking is
+ // not ARMED over a partial manifest - is an arm-time decision, not one taken once per commit by
+ // every node at once.
+ //
+ // CORRECTED 2026-08-03. This comment used to name armingReadinessDiagnostic() as the place that
+ // arm-time decision was made. It was not: that method tests ADDRESS-BOUNDNESS and nothing else,
+ // and it never reads the fleet size, the keyed count, or K. So for one day the compensating
+ // control for this repair was a sentence in a comment. It is now validateThresholdReachabilityOrAbort(),
+ // which refuses to start a node whose armed threshold is above what the fleet is guaranteed to
+ // produce (AERE-PQC-CFG-UNSAFE-08), and it is measured in PqForkThresholdReachabilityTest.
+ if (localIndex < 0 || indexToAddress.get(localIndex) == null) {
+ if (loggedCoverageBlocked.compareAndSet(false, true)) {
+ LOG.error(
+ "AERE PQC: attachment height {} reached at block {} but the anchored registry does not "
+ + "bind THIS node's Falcon index {} to a validator address ({} bound entries). A "
+ + "seal from an index no verifier can resolve is refused by the seals rule, so "
+ + "emitting one would only add bytes. Attachment stays OFF for this node alone; the "
+ + "rest of the fleet is unaffected. Re-anchor a manifest that contains this index.",
+ attachBlock,
+ blockNumber,
+ localIndex,
+ indexToAddress.size());
+ }
+ return false;
+ }
+ reportRegistryCoverage(blockNumber);
+ if (loggedAttachmentOn.compareAndSet(false, true)) {
+ LOG.info(
+ "AERE PQC: seal ATTACHMENT ARMED at block {} (attachBlock={}, anchored address-bound "
+ + "registry of {} entries binds this node's index {}). This node will now attach a "
+ + "Falcon seal to its Commit messages. Falcon quorum becomes BLOCKING at forkBlock={}.",
+ blockNumber,
+ attachBlock,
+ indexToAddress.size(),
+ localIndex,
+ forkBlock() == Long.MAX_VALUE ? "unset" : Long.toString(forkBlock()));
+ }
+ return true;
+ }
+
+ /**
+ * AERE D-078 (2026-08-02). REPORT what the anchored registry covers, and what that costs in
+ * liveness margin. This decides nothing: it is called after the attachment gate has already said
+ * yes, and its only effect is a log line.
+ *
+ * <p>It exists because removing coverage from the gate must not also remove the operator's ability
+ * to see coverage. What it prints is not "incomplete" but a NUMBER, {@link
+ * #worstCaseKeyedSigners}, because "the registry does not cover the set" is compatible with both a
+ * chain that is completely fine and a chain that is one proposer turn from stopping, and only the
+ * number tells them apart.
+ *
+ * <p>Emitted when the situation CHANGES, not once per block: the interesting event is the height
+ * where the validator set moved, and a line per block would bury it.
+ *
+ * @param blockNumber the height being sealed
+ */
+ private void reportRegistryCoverage(final long blockNumber) {
+ final Set<Address> validators = observedValidators;
+ if (validators == null) {
+ if (!"unobserved".equals(lastCoverageSignature)) {
+ lastCoverageSignature = "unobserved";
+ LOG.warn(
+ "AERE PQC: attaching Falcon seals at block {} without having observed a validator set, "
+ + "so registry COVERAGE is NOT MEASURED on this node. This is not a safety "
+ + "statement in either direction: attachment is gated on this node's own registry "
+ + "binding, which is satisfied. It is normal for a process that started above the "
+ + "anchor height. Coverage is reported as soon as a validator set is observed.",
+ blockNumber);
+ }
+ return;
+ }
+ final int n = validators.size();
+ final int keyed = (int) validators.stream().filter(registeredValidatorAddresses()::contains).count();
+ final String signature = n + "/" + keyed;
+ if (signature.equals(lastCoverageSignature)) {
+ return;
+ }
+ lastCoverageSignature = signature;
+ if (keyed == n) {
+ LOG.info(
+ "AERE PQC: anchored registry COVERS the validator set at block {} ({} of {} validators "
+ + "keyed). Falcon and ECDSA quorums coincide.",
+ blockNumber,
+ keyed,
+ n);
+ return;
+ }
+ LOG.warn(
+ "AERE PQC: the anchored registry does NOT cover the validator set at block {}: {} of {} "
+ + "validators hold an anchored Falcon key. Seal attachment CONTINUES - switching it off "
+ + "here is what stops a chain (D-078) - but the post-quantum margin has moved: in the "
+ + "worst case only {} keyed validator(s) are among the {} ECDSA committers of a block. "
+ + "Compare that with the Falcon threshold K in force: if it is above that number, a "
+ + "proposer can legitimately fail to assemble a certificate. RE-ANCHOR the manifest for "
+ + "the full validator set, or lower K, before relying on the post-quantum seal.",
+ blockNumber,
+ keyed,
+ n,
+ worstCaseKeyedSigners(n, keyed),
+ BftHelpers.calculateRequiredValidatorQuorum(n));
+ }
+
+ /**
+ * AERE D-078. The number of anchored-key holders a block's ECDSA committer set is GUARANTEED to
+ * contain, in the worst case, when {@code validators} validators are in the set and {@code keyed}
+ * of them hold an anchored Falcon key.
+ *
+ * <p>A block needs {@code ceil(2N/3)} ECDSA committed seals. An adversarial (or merely unlucky)
+ * choice of committers takes every unkeyed validator first, so the guaranteed keyed count is
+ * {@code quorum - (N - keyed)}, floored at zero. A Falcon threshold K above this number is a
+ * threshold the chain is not guaranteed to be able to meet, which is exactly the shape of D-078:
+ * at N=7 with all 7 keyed and K=5 the margin is exactly zero, one added unkeyed validator holds it
+ * at zero, and a second takes it negative.
+ *
+ * @param validators the size of the current validator set
+ * @param keyed how many of them hold an anchored Falcon key
+ * @return the guaranteed number of keyed signers among a block's committers, never negative
+ */
+ public static int worstCaseKeyedSigners(final int validators, final int keyed) {
+ if (validators <= 0 || keyed <= 0) {
+ return 0;
+ }
+ final int quorum = BftHelpers.calculateRequiredValidatorQuorum(validators);
+ return Math.max(0, quorum - (validators - Math.min(keyed, validators)));
+ }
+
+ /**
+ * AERE D-078 (2026-08-03). By how much a Falcon threshold {@code k} exceeds what the fleet is
+ * GUARANTEED to be able to produce. Zero means reachable; any positive number is a threshold a
+ * proposer can legitimately fail to meet with every node honest and every node up.
+ *
+ * <p>Zero is REACHABLE, not comfortable: at N=7 fully keyed with K=5 the deficit is 0 and the
+ * margin is also 0, which is why {@link #MIN_BLOCKING_VALIDATORS} exists as a separate rule. The
+ * two say different things and neither implies the other.
+ *
+ * @param validators the size of the validator set
+ * @param keyed how many of them hold an anchored Falcon key
+ * @param k the Falcon threshold in force
+ * @return {@code k} minus the guaranteed keyed signer count, floored at zero
+ */
+ public static int thresholdDeficit(final int validators, final int keyed, final int k) {
+ if (k <= 0) {
+ return 0;
+ }
+ return Math.max(0, k - worstCaseKeyedSigners(validators, keyed));
+ }
+
+ /**
+ * Falcon-sign a commit hash with this node's Falcon key, producing a parallel seal. Never throws.
+ *
+ * <p>AERE FIX-OPRIRE-CONSENS (b): the block number is MANDATORY and the attachment gate is
+ * checked here, at the single point where a seal can be produced. There is deliberately no
+ * height-less overload, so no call site can attach a seal without passing the gate.
+ *
+ * @param blockNumber the number of the block whose commit is being sealed
+ * @param commitHash the same 32-byte commit hash the ECDSA committed seal signs
+ * @return the Falcon seal, or empty if signing is disabled, gated off, or failed
+ */
+ public Optional<FalconSeal> sign(final long blockNumber, final Bytes32 commitHash) {
+ if (!signingEnabled) {
+ return Optional.empty();
+ }
+ if (!attachmentArmed(blockNumber)) {
+ return Optional.empty();
+ }
+ // AERE AGILITY step 4 (2026-08-24): signing goes through the scheme layer. The same
+ // FalconSigner underneath, but the path is now the one the hybrid will use too; the 751
+ // baseline tests prove the equivalence.
+ final java.util.Optional<byte[]> sig =
+ ((FalconSealScheme) SealSchemes.FALCON_512).signWithParams(localPrivateKey, commitHash.toArray());
+ if (sig.isEmpty()) {
+ LOG.warn("AERE PQC: Falcon signing failed (ECDSA seal unaffected)");
+ return Optional.empty();
+ }
+ return Optional.of(new FalconSeal(localIndex, Bytes.wrap(sig.get())));
+ }
+
+ /**
+ * Property naming the first height at which this node ATTACHES a post-quantum seal to its own
+ * PREPARE messages. Absent = never, which is the configuration of every node today.
+ *
+ * <p>SEPARATE from {@code aere.falcon.attachBlock}, and the separation is mandatory: if PREPARE
+ * emission started together with commit emission, rolling the binary onto the fleet would become
+ * a flag day. This way the binary can sit on every node for months before any of them emits
+ * anything new.
+ */
+ public static final String PREPARE_ATTACH_PROPERTY = "aere.pq.preparePq.attachBlock";
+
+ /** Environment fallback for {@link #PREPARE_ATTACH_PROPERTY}. */
+ public static final String PREPARE_ATTACH_ENV = "AERE_PQ_PREPAREPQ_ATTACHBLOCK";
+
+ /**
+ * The configured PREPARE attachment height, read fresh on every call.
+ *
+ * <p>Absent = {@link Long#MAX_VALUE}, i.e. never. A value that is PRESENT but unreadable REFUSES
+ * loudly instead of disarming: the lesson paid for by the anchor loader is that a mistyped
+ * character must never boot the node DISARMED, because then nobody finds out.
+ *
+ * @return the height, or Long.MAX_VALUE when unset
+ */
+ public static long prepareAttachBlock() {
+ final String raw = resolve(PREPARE_ATTACH_PROPERTY, PREPARE_ATTACH_ENV);
+ if (raw == null || raw.isBlank()) {
+ return Long.MAX_VALUE;
+ }
+ try {
+ final long v = Long.parseLong(raw.trim());
+ if (v < 0) {
+ throw new NumberFormatException("negative");
+ }
+ return v;
+ } catch (final NumberFormatException e) {
+ throw new ActivationConfigException(
+ ActivationConfigException.Kind.SYNTAX,
+ "AERE-PQC-PREPARE-CONF-01",
+ "AERE PQ PREPARE: "
+ + PREPARE_ATTACH_PROPERTY
+ + " is set to '"
+ + raw
+ + "', which is not a non-negative block height. A node must REFUSE to start rather "
+ + "than silently run with PREPARE attachment disarmed: a disarmed node looks exactly "
+ + "like a correctly configured one until the day it matters.");
+ }
+ }
+
+ /**
+ * Sign this node's own PREPARE, when the PREPARE attachment gate is open at this height.
+ *
+ * <p>It requires THREE things, and each closes one way of being wrong:
+ *
+ * <ul>
+ * <li>{@code signingEnabled}: the node holds a key. Without one nothing is emitted, and the
+ * ECDSA path is not touched in any way.
+ * <li>{@link #attachmentArmed(long)}: the same registry-coverage conditions as commit, AND the
+ * fact that the fleet already emits seals on commit. A PREPARE seal on a fleet that does not
+ * emit on commit would be something new in a network that has not yet seen anything new.
+ * <li>its own height, above.
+ * </ul>
+ *
+ * <p>NEVER THROWS except for the strict configuration case above: a signing failure is a log line
+ * and an empty value, exactly as at commit, because the ECDSA path must not be disturbed.
+ *
+ * @param blockNumber the height being prepared
+ * @param message the domain-separated PREPARE message (see PqAnchor.prepareMessage)
+ * @return the seal, or empty when any gate is shut
+ */
+ public Optional<FalconSeal> signPrepare(final long blockNumber, final Bytes32 message) {
+ if (!signingEnabled) {
+ return Optional.empty();
+ }
+ if (!attachmentArmed(blockNumber)) {
+ return Optional.empty();
+ }
+ if (blockNumber < prepareAttachBlock()) {
+ return Optional.empty();
+ }
+ final java.util.Optional<byte[]> sig =
+ ((FalconSealScheme) SealSchemes.FALCON_512).signWithParams(localPrivateKey, message.toArray());
+ if (sig.isEmpty()) {
+ LOG.warn("AERE PQ PREPARE: Falcon signing failed (ECDSA path unaffected)");
+ return Optional.empty();
+ }
+ final long n = preparesSealed.incrementAndGet();
+ // LOG VOLUME IS A DECISION, not an oversight. One line per PREPARE would be two lines per
+ // second per node, which is exactly the kind of log that gets trained away (see D-153, where a
+ // permanent ERROR made an entire log worthless). The first emission is worth a line, because it
+ // is the moment the node starts doing something new; after that, one line every 500, so a
+ // testnet still has a number to count.
+ if (n == 1L) {
+ LOG.info(
+ "AERE PQ PREPARE: this node EMITTED its first post-quantum seal on a PREPARE, at "
+ + "height {} (gate {}={}). From here on its PREPAREs carry a seal.",
+ blockNumber,
+ PREPARE_ATTACH_PROPERTY,
+ prepareAttachBlock());
+ } else if (n % 500L == 0L) {
+ LOG.info("AERE PQ PREPARE: {} seals emitted on PREPAREs since startup.", n);
+ }
+ return Optional.of(new FalconSeal(localIndex, Bytes.wrap(sig.get())));
+ }
+
+ /**
+ * How many seals this node has emitted on PREPAREs since startup.
+ *
+ * <p>It exists so that the COVERAGE step can be measured: without a number, arming enforcement
+ * would be a bet. Read from the log on a testnet, and from this value in tests.
+ *
+ * @return the count
+ */
+ public long preparesSealed() {
+ return preparesSealed.get();
+ }
+
+ /**
+ * Property naming the first height at which this node ATTACHES a post-quantum seal to its own
+ * PROPOSAL messages. Absent = never, which is the configuration of every node today.
+ *
+ * <p>SEPARATE from both the commit and the PREPARE gates, same reason: three layers that arm on
+ * three independent decisions must not share a switch, or the day one is turned on becomes a flag
+ * day for the others.
+ */
+ public static final String PROPOSAL_ATTACH_PROPERTY = "aere.pq.proposalPq.attachBlock";
+
+ /** Environment fallback for {@link #PROPOSAL_ATTACH_PROPERTY}. */
+ public static final String PROPOSAL_ATTACH_ENV = "AERE_PQ_PROPOSALPQ_ATTACHBLOCK";
+
+ /**
+ * The configured PROPOSAL attachment height, read fresh on every call.
+ *
+ * <p>Absent = {@link Long#MAX_VALUE}, i.e. never. A value that is PRESENT but unreadable REFUSES
+ * loudly instead of disarming - the anchor loader's lesson, once per gate, every gate.
+ *
+ * @return the height, or Long.MAX_VALUE when unset
+ */
+ public static long proposalAttachBlock() {
+ final String raw = resolve(PROPOSAL_ATTACH_PROPERTY, PROPOSAL_ATTACH_ENV);
+ if (raw == null || raw.isBlank()) {
+ return Long.MAX_VALUE;
+ }
+ try {
+ final long v = Long.parseLong(raw.trim());
+ if (v < 0) {
+ throw new NumberFormatException("negative");
+ }
+ return v;
+ } catch (final NumberFormatException e) {
+ throw new ActivationConfigException(
+ ActivationConfigException.Kind.SYNTAX,
+ "AERE-PQC-PROPOSAL-CONF-01",
+ "AERE PQ PROPOSAL: "
+ + PROPOSAL_ATTACH_PROPERTY
+ + " is set to '"
+ + raw
+ + "', which is not a non-negative block height. A node must REFUSE to start rather "
+ + "than silently run with PROPOSAL attachment disarmed: a disarmed node looks exactly "
+ + "like a correctly configured one until the day it matters.");
+ }
+ }
+
+ /**
+ * Sign this node's own PROPOSAL, when the PROPOSAL attachment gate is open at this height.
+ *
+ * <p>Same three requirements as {@link #signPrepare}, for the same three reasons: a key, the
+ * commit-layer coverage conditions, and its own height. NEVER throws except for the strict
+ * configuration case: a signing failure is a log line and an empty value, because the ECDSA path
+ * must not be disturbed.
+ *
+ * @param blockNumber the height being proposed
+ * @param message the domain-separated PROPOSAL message (see PqAnchor.proposalMessage)
+ * @return the seal, or empty when any gate is shut
+ */
+ public Optional<FalconSeal> signProposal(final long blockNumber, final Bytes32 message) {
+ if (!signingEnabled) {
+ return Optional.empty();
+ }
+ if (!attachmentArmed(blockNumber)) {
+ return Optional.empty();
+ }
+ if (blockNumber < proposalAttachBlock()) {
+ return Optional.empty();
+ }
+ final java.util.Optional<byte[]> sig =
+ ((FalconSealScheme) SealSchemes.FALCON_512).signWithParams(localPrivateKey, message.toArray());
+ if (sig.isEmpty()) {
+ LOG.warn("AERE PQ PROPOSAL: Falcon signing failed (ECDSA path unaffected)");
+ return Optional.empty();
+ }
+ final long n = proposalsSealed.incrementAndGet();
+ // Same log-volume decision as at PREPARE: a proposal is at most one per round per proposer, so
+ // this is quieter by nature, but the counter still steps so a testnet has a number to count.
+ if (n == 1L) {
+ LOG.info(
+ "AERE PQ PROPOSAL: this node EMITTED its first post-quantum seal on a PROPOSAL, at "
+ + "height {} (gate {}={}). From here on its proposals carry a seal.",
+ blockNumber,
+ PROPOSAL_ATTACH_PROPERTY,
+ proposalAttachBlock());
+ } else if (n % 500L == 0L) {
+ LOG.info("AERE PQ PROPOSAL: {} seals emitted on PROPOSALs since startup.", n);
+ }
+ return Optional.of(new FalconSeal(localIndex, Bytes.wrap(sig.get())));
+ }
+
+ /**
+ * How many seals this node has emitted on its own PROPOSALs since startup. Exists so the
+ * coverage step can be measured, exactly as at PREPARE.
+ *
+ * @return the count
+ */
+ public long proposalsSealed() {
+ return proposalsSealed.get();
+ }
+
+ /**
+ * The property that opens the ROUND-CHANGE attachment gate: from this height on, this node's own
+ * round-changes carry a Falcon seal. Emission only - enforcement is {@code
+ * aere.pq.roundChangePq.forkBlock}, deliberately separate so the fleet can emit long before any
+ * node refuses, exactly as at PREPARE and PROPOSAL.
+ */
+ public static final String ROUNDCHANGE_ATTACH_PROPERTY = "aere.pq.roundChangePq.attachBlock";
+
+ /** Environment fallback for {@link #ROUNDCHANGE_ATTACH_PROPERTY}. */
+ public static final String ROUNDCHANGE_ATTACH_ENV = "AERE_PQ_ROUNDCHANGEPQ_ATTACHBLOCK";
+
+ /**
+ * The configured ROUND-CHANGE attachment height, read fresh on every call.
+ *
+ * <p>Absent = {@link Long#MAX_VALUE}, i.e. never. A value that is PRESENT but unreadable REFUSES
+ * loudly instead of disarming - the anchor loader's lesson, once per gate, every gate.
+ *
+ * @return the height, or Long.MAX_VALUE when unset
+ */
+ public static long roundChangeAttachBlock() {
+ final String raw = resolve(ROUNDCHANGE_ATTACH_PROPERTY, ROUNDCHANGE_ATTACH_ENV);
+ if (raw == null || raw.isBlank()) {
+ return Long.MAX_VALUE;
+ }
+ try {
+ final long v = Long.parseLong(raw.trim());
+ if (v < 0) {
+ throw new NumberFormatException("negative");
+ }
+ return v;
+ } catch (final NumberFormatException e) {
+ throw new ActivationConfigException(
+ ActivationConfigException.Kind.SYNTAX,
+ "AERE-PQC-ROUNDCHANGE-CONF-01",
+ "AERE PQ ROUNDCHANGE: "
+ + ROUNDCHANGE_ATTACH_PROPERTY
+ + " is set to '"
+ + raw
+ + "', which is not a non-negative block height. A node must REFUSE to start rather "
+ + "than silently run with ROUND-CHANGE attachment disarmed: a disarmed node looks "
+ + "exactly like a correctly configured one until the day it matters.");
+ }
+ }
+
+ /**
+ * Sign this node's own ROUND-CHANGE, when the ROUND-CHANGE attachment gate is open at this
+ * height.
+ *
+ * <p>Same three requirements as {@link #signPrepare} and {@link #signProposal}, for the same
+ * three reasons: a key, the commit-layer coverage conditions, and its own height. NEVER throws
+ * except for the strict configuration case: a signing failure is a log line and an empty value,
+ * because the ECDSA path must not be disturbed.
+ *
+ * @param blockNumber the height the round-change targets
+ * @param message the domain-separated ROUND-CHANGE message (see PqAnchor.roundChangeMessage)
+ * @return the seal, or empty when any gate is shut
+ */
+ public Optional<FalconSeal> signRoundChange(final long blockNumber, final Bytes32 message) {
+ if (!signingEnabled) {
+ return Optional.empty();
+ }
+ if (!attachmentArmed(blockNumber)) {
+ return Optional.empty();
+ }
+ if (blockNumber < roundChangeAttachBlock()) {
+ return Optional.empty();
+ }
+ final java.util.Optional<byte[]> sig =
+ ((FalconSealScheme) SealSchemes.FALCON_512).signWithParams(localPrivateKey, message.toArray());
+ if (sig.isEmpty()) {
+ LOG.warn("AERE PQ ROUNDCHANGE: Falcon signing failed (ECDSA path unaffected)");
+ return Optional.empty();
+ }
+ final long n = roundChangesSealed.incrementAndGet();
+ // Round-changes only exist when rounds FAIL, so on a healthy chain this counter barely moves;
+ // it still steps so a testnet that forces round-changes has a number to count.
+ if (n == 1L) {
+ LOG.info(
+ "AERE PQ ROUNDCHANGE: this node EMITTED its first post-quantum seal on a ROUND-CHANGE, "
+ + "at height {} (gate {}={}). From here on its round-changes carry a seal.",
+ blockNumber,
+ ROUNDCHANGE_ATTACH_PROPERTY,
+ roundChangeAttachBlock());
+ } else if (n % 100L == 0L) {
+ LOG.info("AERE PQ ROUNDCHANGE: {} seals emitted on ROUND-CHANGEs since startup.", n);
+ }
+ return Optional.of(new FalconSeal(localIndex, Bytes.wrap(sig.get())));
+ }
+
+ /**
+ * How many seals this node has emitted on its own ROUND-CHANGEs since startup. Exists so the
+ * coverage step can be measured, exactly as at PREPARE and PROPOSAL.
+ *
+ * @return the count
+ */
+ public long roundChangesSealed() {
+ return roundChangesSealed.get();
+ }
+
+ /**
+ * Verify a Falcon seal against the registry public key for its validator index. Never throws.
+ *
+ * @param validatorIndex the signer index
+ * @param commitHash the commit hash that was signed
+ * @param signature the Falcon signature bytes
+ * @return true iff a registry public key exists for the index and the signature verifies
+ */
+ public boolean verify(final int validatorIndex, final Bytes commitHash, final Bytes signature) {
+ return verifyWithKey(registry.get(validatorIndex), validatorIndex, commitHash, signature);
+ }
+
+ /**
+ * D-081. The Falcon public key registered for an index AT A HEIGHT: the one carried by the
+ * registry the chain's schedule makes active there.
+ *
+ * <p>WHY A HEIGHT IS NEEDED AT ALL. A certificate inside a block at height h was produced under
+ * the key set the chain required at h. After a rotation the node's own head registry is a
+ * different key set, so checking an old block against it fails for a reason that has nothing to do
+ * with the block. Cosmos ADR-016 states the same requirement for the same reason and keeps a
+ * height-to-key mapping; the only difference here is that ours is never pruned, because this chain
+ * has no unbonding period and a node syncing from genesis verifies every block ever produced.
+ *
+ * <p>Returns the head registry's key when no binding is active at that height, which is every
+ * height below the schedule's first entry and every height on a chain with no schedule at all. So
+ * a node on chain 2800 as it stands today gets exactly what it got before D-081.
+ */
+ private FalconPublicKeyParameters keyAt(
+ final long blockNumber, final int validatorIndex, final boolean historic) {
+ final PqRegistryHash.Schedule schedule = this.registryBindingSchedule;
+ final PqRegistryHash.RegistrySet set = this.registryBindingSet;
+ if (schedule == null || set == null) {
+ return headRegistryKeyOrRefuse(
+ blockNumber, validatorIndex, "no schedule was ever loaded", historic);
+ }
+ final Optional<PqRegistryHash.ScheduleEntry> required =
+ PqRegistryHash.requiredHashAt(schedule, blockNumber);
+ if (required.isEmpty()) {
+ // D-228. The only historical question ever asked one block below the schedule's first entry
+ // is about the certificate carried by the block at blockNumber+1, whose governing registry
+ // is the one bound EXACTLY at blockNumber+1. Answer it from that entry's VERIFIED bound
+ // registry, never from the unverified head file. Exactly one block: at blockNumber+2 below
+ // the schedule nothing changes.
+ final Optional<PqRegistryHash.ScheduleEntry> nextEntry =
+ PqRegistryHash.requiredHashAt(schedule, blockNumber + 1);
+ if (nextEntry.isPresent() && nextEntry.get().block() == blockNumber + 1) {
+ final Optional<PqRegistryHash.Registry> boundNext =
+ PqRegistryHash.registryAt(schedule, set, blockNumber + 1);
+ if (boundNext.isPresent()) {
+ for (final PqRegistryHash.Entry e : boundNext.get().entries()) {
+ if (e.index() == validatorIndex) {
+ return new FalconPublicKeyParameters(FalconParameters.falcon_512, e.publicKey());
+ }
+ }
+ return null;
+ }
+ }
+ return headRegistryKeyOrRefuse(
+ blockNumber, validatorIndex, "the schedule binds no registry at this height", historic);
+ }
+ final String cacheKey = required.get().block() + ":" + validatorIndex;
+ final FalconPublicKeyParameters cached = historicalKeys.get(cacheKey);
+ if (cached != null) {
+ return cached;
+ }
+ final Optional<PqRegistryHash.Registry> active =
+ PqRegistryHash.registryAt(schedule, set, blockNumber);
+ if (active.isEmpty()) {
+ // The entry active here is covered by nothing this node holds. Fail closed: no key, so no
+ // seal verifies, and the per-block binding rule has already refused the header for the same
+ // reason. Silence here would be the node deciding a question it cannot answer.
+ return null;
+ }
+ for (final PqRegistryHash.Entry e : active.get().entries()) {
+ if (e.index() == validatorIndex) {
+ final FalconPublicKeyParameters pub =
+ new FalconPublicKeyParameters(FalconParameters.falcon_512, e.publicKey());
+ historicalKeys.put(cacheKey, pub);
+ return pub;
+ }
+ }
+ return null;
+ }
+
+ /**
+ * D-081. The validator ADDRESS bound to a registry index at a height.
+ *
+ * <p>D2 HARDENING (b-v2): PRIVATE, with the caller's motive as an argument. The two public
+ * doors are {@link #addressForIndexAtHistoric} and {@link #addressForIndexAtOwnHead}, each of
+ * which passes a constant. Nothing outside this file can choose the value, so the one shared
+ * resolution body cannot drift between the two paths and no caller can pick the wrong flag.
+ *
+ * @param blockNumber the height of the header being validated
+ * @param validatorIndex the registry index carried by a Falcon seal
+ * @param historic true when the subject is a header this node received, false when it is this
+ * node's own head or the block it is building
+ * @return the bound address, or null when the index is unregistered at that height or the
+ * registry active there is not address-bound
+ */
+ private Address addressAt(
+ final long blockNumber, final int validatorIndex, final boolean historic) {
+ final PqRegistryHash.Schedule schedule = this.registryBindingSchedule;
+ final PqRegistryHash.RegistrySet set = this.registryBindingSet;
+ if (schedule == null || set == null) {
+ return headRegistryAddressOrRefuse(
+ blockNumber, validatorIndex, "no schedule was ever loaded", historic);
+ }
+ if (PqRegistryHash.requiredHashAt(schedule, blockNumber).isEmpty()) {
+ // D-228. Same alignment as in keyAt: one block below the schedule's first entry the subject
+ // is the certificate of the block at blockNumber+1, governed by the registry bound EXACTLY
+ // there, so the answer comes from that entry's VERIFIED bound registry and mirrors what
+ // this method answers at blockNumber+1 itself.
+ final Optional<PqRegistryHash.ScheduleEntry> nextEntry =
+ PqRegistryHash.requiredHashAt(schedule, blockNumber + 1);
+ if (nextEntry.isPresent() && nextEntry.get().block() == blockNumber + 1) {
+ final Optional<PqRegistryHash.Registry> boundNext =
+ PqRegistryHash.registryAt(schedule, set, blockNumber + 1);
+ if (boundNext.isPresent()) {
+ if (!boundNext.get().addressBound()) {
+ return null;
+ }
+ for (final PqRegistryHash.Entry e : boundNext.get().entries()) {
+ if (e.index() == validatorIndex && e.address() != null) {
+ return Address.wrap(Bytes.wrap(e.address()));
+ }
+ }
+ return null;
+ }
+ }
+ return headRegistryAddressOrRefuse(
+ blockNumber, validatorIndex, "the schedule binds no registry at this height", historic);
+ }
+ final Optional<PqRegistryHash.Registry> active =
+ PqRegistryHash.registryAt(schedule, set, blockNumber);
+ if (active.isEmpty() || !active.get().addressBound()) {
+ return null;
+ }
+ for (final PqRegistryHash.Entry e : active.get().entries()) {
+ if (e.index() == validatorIndex && e.address() != null) {
+ return Address.wrap(Bytes.wrap(e.address()));
+ }
+ }
+ return null;
+ }
+
+ /**
+ * D-081 / D2 HARDENING (b-v2). THE HISTORY DOOR. Verify a Falcon seal carried by a header this
+ * node RECEIVED, against the key set the chain required at that height.
+ *
+ * <p>WHY THE MOTIVE IS IN THE NAME AND NOT IN THE HEIGHT, measured on 2026-08-06. The first shape
+ * of hardening (b) refused whenever no height binding existed at or above the arming height, and
+ * decided that from the block number alone. That stopped the two paths that work on THIS NODE'S
+ * OWN head: restoring seals from disk after a restart, and proposing. Six tests went red, five in
+ * {@code PqSealPersistenceTest} and one in {@code PqForkValidatorSetChangeTest}, and the D078
+ * message says the consequence outright - the node refuses to propose, so it stops producing
+ * blocks. In every one of the six the number presented to the guard was 1030 against an arming
+ * height of 1000, identical to what a real historical question would present in the same process
+ * in the same second. So the distinction moved into the question.
+ *
+ * <p>Reaching THIS method means the node is judging somebody else's claim about a height it did
+ * not build. "Which keys were in force here" then has an answer that is not this node's current
+ * registry, and answering from the head registry anyway is D2/T2 verbatim: a header produced under
+ * one key set checked against another, with success reported.
+ *
+ * @param blockNumber the height of the header carrying the seal
+ * @param validatorIndex the signer index
+ * @param commitHash the message that was signed
+ * @param signature the Falcon signature bytes
+ * @return true iff a key was bound for that index AT THAT HEIGHT and the signature verifies
+ */
+ public boolean verifyAtHistoric(
+ final long blockNumber,
+ final int validatorIndex,
+ final Bytes commitHash,
+ final Bytes signature) {
+ return verifyWithKey(
+ keyAt(blockNumber, validatorIndex, true), validatorIndex, commitHash, signature);
+ }
+
+ /**
+ * D2 HARDENING (b-v2). THE OWN-HEAD DOOR. Verify a Falcon seal over a block this node holds as its
+ * own head, or is building right now.
+ *
+ * <p>It does not refuse for a missing height binding, because at this node's own head the head
+ * registry IS the answer by construction. A wrong local acceptance cannot manufacture history: the
+ * certificate is re-checked by the other six validators through {@code PqAnchorSealsRule}, which
+ * goes through {@link #verifyAtHistoric} at the parent's height. The cost of a local mistake is
+ * one lost proposer round, not a branch.
+ *
+ * <p>What it still refuses: a height the schedule DOES cover with a registry this node does not
+ * hold. That is not a missing binding, it is a node running a registry the chain has moved off,
+ * and it fails closed on both doors - see the {@code registryAt} branch of {@link #keyAt}.
+ *
+ * @param blockNumber this node's own head, or the block it is sealing
+ * @param validatorIndex the signer index
+ * @param commitHash the message that was signed
+ * @param signature the Falcon signature bytes
+ * @return true iff a key exists for the index there and the signature verifies
+ */
+ public boolean verifyAtOwnHead(
+ final long blockNumber,
+ final int validatorIndex,
+ final Bytes commitHash,
+ final Bytes signature) {
+ return verifyWithKey(
+ keyAt(blockNumber, validatorIndex, false), validatorIndex, commitHash, signature);
+ }
+
+ /**
+ * D-081 / D2 HARDENING (b-v2). THE HISTORY DOOR, address half. See {@link #verifyAtHistoric}.
+ *
+ * @param blockNumber the height of the header being validated
+ * @param validatorIndex the registry index carried by a Falcon seal
+ * @return the bound address, or null when nothing binds that index at that height
+ */
+ public Address addressForIndexAtHistoric(final long blockNumber, final int validatorIndex) {
+ return addressAt(blockNumber, validatorIndex, true);
+ }
+
+ /**
+ * D2 HARDENING (b-v2). THE OWN-HEAD DOOR, address half. See {@link #verifyAtOwnHead}.
+ *
+ * @param blockNumber this node's own head, or the block it is building
+ * @param validatorIndex the registry index
+ * @return the bound address, or null
+ */
+ public Address addressForIndexAtOwnHead(final long blockNumber, final int validatorIndex) {
+ return addressAt(blockNumber, validatorIndex, false);
+ }
+
+ /**
+ * D2 HARDENING (b). The one decision the whole hardening turns on, isolated so that removing it is
+ * a one-line edit and the negative control can prove the D2 test goes red without it.
+ *
+ * <p>THE MEASURED DEFECT. Both height-resolved lookups used to answer a height they had no binding
+ * for by returning the HEAD registry - the key set in force right now. Below the arming height
+ * that is correct and costs nothing: no certificate is being judged there. At and above it, it is
+ * D2/T2 verbatim: "an armed node verifies a year-old header against the keys it holds today", so
+ * one rotation makes every block between the arming height and the rotation unverifiable, and the
+ * node reports success while doing it. Refusing is the only answer that does not assert a check
+ * that was not performed.
+ *
+ * <p>WHAT A REFUSAL COSTS AND WHY IT IS THE CHEAPER FAILURE. A null key makes every seal fail, so
+ * {@code PqAnchorSealsRule} refuses the header and the node stops at the first block at or above
+ * the arming height. It stops; it does not fork. A node that cannot say which keys were in force
+ * cannot forge a competing history either, and the repair is to configure {@code
+ * config.pqRegistryHash} plus {@code aere.falcon.registry.history} and restart. Compare the
+ * silence this replaces, where the same node imports the whole chain and calls it verified.
+ *
+ * <p>D2 HARDENING (b-v2), 2026-08-06. The condition gained ONE term, {@code historic}, and
+ * that term is the whole of the second repair. The first shape refused on height alone; the
+ * six tests it turned red were all asking about this node's OWN head at height 1030 with an
+ * arming height of 1000, which is the same pair of numbers a genuinely historical question
+ * presents. The block number cannot tell them apart. The caller can, and now says so.
+ *
+ * @param blockNumber the height being asked about
+ * @param validatorIndex the registry index
+ * @param why the reason no height binding was found, for the log
+ * @param historic true when the subject is a received header, false for this node's own head
+ * @return the head registry's key when not historic or below the arming height, else null
+ */
+ private FalconPublicKeyParameters headRegistryKeyOrRefuse(
+ final long blockNumber,
+ final int validatorIndex,
+ final String why,
+ final boolean historic) {
+ if (!historic || blockNumber < anchorArmedFrom()) {
+ return registry.get(validatorIndex);
+ }
+ shoutUnboundHeight(blockNumber, why);
+ return null;
+ }
+
+ /**
+ * D2 HARDENING (b). The address half of {@link #headRegistryKeyOrRefuse}, with the same rule and
+ * for the same reason: at and above the arming height an unbound height has no answer, and {@code
+ * PqAnchorSealsRule} refuses an index it cannot bind to an address rather than skipping it.
+ *
+ * <p>D2 HARDENING (b-v2): same one added term as {@link #headRegistryKeyOrRefuse}.
+ *
+ * @param blockNumber the height being asked about
+ * @param validatorIndex the registry index
+ * @param why the reason no height binding was found, for the log
+ * @param historic true when the subject is a received header, false for this node's own head
+ * @return the head registry's bound address when not historic or below the arming height, else
+ * null
+ */
+ private Address headRegistryAddressOrRefuse(
+ final long blockNumber,
+ final int validatorIndex,
+ final String why,
+ final boolean historic) {
+ if (!historic || blockNumber < anchorArmedFrom()) {
+ return addressForIndex(validatorIndex);
+ }
+ shoutUnboundHeight(blockNumber, why);
+ return null;
+ }
+
+ /**
+ * D2 HARDENING (b). Say it once per configuration change, not once per block: at a 523 ms block
+ * period a per-block ERROR is itself a hazard on this fleet, and the refusal is already visible as
+ * a stopped node.
+ *
+ * @param blockNumber the height that has no registry binding
+ * @param why the reason
+ */
+ private void shoutUnboundHeight(final long blockNumber, final String why) {
+ if (loggedUnboundArmedHeight.compareAndSet(false, true)) {
+ LOG.error(
+ "AERE PQC D2: REFUSING to resolve Falcon keys at height {} - this node is ARMED from {} "
+ + "and {}. Until 2026-08-06 this fell back to the registry in force at the HEAD, "
+ + "which is the D2/T2 defect: a header produced under one key set was checked against "
+ + "another, and one key rotation would have made every block above the arming height "
+ + "unverifiable while the node reported success. Every header at or above the arming "
+ + "height will now be REFUSED until the height-to-registry binding exists. WHAT TO DO: "
+ + "put config.pqRegistryHash in the genesis this node booted (first entry exactly at "
+ + "the arming height) and name every registry file the schedule covers in {}.",
+ blockNumber,
+ anchorArmedFrom(),
+ why,
+ PROPERTY_REGISTRY_HISTORY);
+ }
+ }
+
+ private boolean verifyWithKey(
+ final FalconPublicKeyParameters pub,
+ final int validatorIndex,
+ final Bytes commitHash,
+ final Bytes signature) {
+ if (pub == null || commitHash == null || signature == null) {
+ return false;
+ }
+ // AERE AGILITY step 4: verification goes through the scheme layer, on the registry form
+ // (raw h, 896 bytes). verifyRaw never throws; a false here is an invalid seal,
+ // exactly the old contract.
+ final boolean valid =
+ SealSchemes.FALCON_512.verifyRaw(pub.getH(), commitHash.toArray(), signature.toArray());
+ if (!valid) {
+ LOG.debug("AERE PQC: Falcon seal did not verify for index {}", validatorIndex);
+ }
+ return valid;
+ }
+}
diff --git a/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/HybridSealProducer.java b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/HybridSealProducer.java
new file mode 100755
index 000000000..591ede15e
--- /dev/null
+++ b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/HybridSealProducer.java
@@ -0,0 +1,140 @@
+/*
+ * AERE HYBRID, the PRODUCER half (2026-08-25). The counterpart of PqCommitEnforcement: that one
+ * decides what is accepted, this one decides what is EMITTED.
+ *
+ * WHY A SEPARATE CLASS FROM FalconSealSupport. Falcon has an old production path, with
+ * per-component loading, startup guards and a singleton; widening it would have meant touching
+ * the very class the live consensus hangs on, for a capability armed nowhere today.
+ * Falcon is not touched here at all: this class produces ONLY the seals of the other schemes,
+ * i.e. exactly the content of the extras slot in CommitPayload.
+ *
+ * THE EMISSION GATE IS WHY THIS CLASS IS ALLOWED TO EXIST. Adding extras changes the signed
+ * bytes, so an older node can no longer PARSE the message. What protects the fleet is not
+ * leniency at decode time, which cannot work, but the fact that nothing emits extras until the
+ * attach height, the same discipline as the Falcon gate. Unset means: never emit,
+ * EVER, and that is the default.
+ *
+ * HALF A CERTIFICATE IS NOT EMITTED. If the schedule requires a scheme this node has no key
+ * for, no maimed certificate is sent (every neighbour would refuse it at quorum anyway):
+ * nothing is sent, and the log SHOUTS. An operator must find out a key is missing
+ * BEFORE the height where enforcement bites, not on that very day.
+ */
+package org.hyperledger.besu.consensus.common.bft;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.Set;
+
+import org.apache.tuweni.bytes.Bytes;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+/** Produces the non-Falcon scheme seals a hybrid commit carries, gated on height. */
+public final class HybridSealProducer {
+
+ private static final Logger LOG = LoggerFactory.getLogger(HybridSealProducer.class);
+
+ /** The disarmed attachment height: no block ever reaches it, so nothing is ever emitted. */
+ public static final long NEVER = Long.MAX_VALUE;
+
+ private final long attachFromBlock;
+ private final PqSchemeSchedule schedule;
+ private final int validatorIndex;
+ private final Map<String, SealScheme.PrivateHandle> localKeys;
+ // one shout per missing scheme, not one per block: a permanent alarm is learned and ignored
+ private final Set<String> alreadyShouted = new java.util.HashSet<>();
+
+ /**
+ * @param attachFromBlock first height at which extras may be emitted; {@link #NEVER} to disarm
+ * @param schedule which schemes are required at which height; null disarms as well
+ * @param validatorIndex this node's index, written into every seal it produces
+ * @param localKeys the private handles this node holds, per scheme id
+ */
+ public HybridSealProducer(
+ final long attachFromBlock,
+ final PqSchemeSchedule schedule,
+ final int validatorIndex,
+ final Map<String, SealScheme.PrivateHandle> localKeys) {
+ this.attachFromBlock = schedule == null ? NEVER : attachFromBlock;
+ this.schedule = schedule;
+ this.validatorIndex = validatorIndex;
+ this.localKeys = localKeys == null ? Map.of() : Map.copyOf(localKeys);
+ }
+
+ /** A producer that never emits anything: the configuration of every node today. */
+ public static HybridSealProducer disarmed() {
+ return new HybridSealProducer(NEVER, null, -1, Map.of());
+ }
+
+ /**
+ * Whether extras may be emitted at this height at all.
+ *
+ * @param blockNumber the height
+ * @return true when the attachment gate is open
+ */
+ public boolean attachmentArmedAt(final long blockNumber) {
+ return schedule != null && blockNumber >= attachFromBlock;
+ }
+
+ /**
+ * The extra scheme seals for this block, or an empty list.
+ *
+ * <p>Never throws: a producer fault must never take down the ECDSA commit path. Every refusal
+ * is a logged reason plus an empty list, exactly the stance of the Falcon signer.
+ *
+ * @param blockNumber the height of the block being committed
+ * @param message the very bytes the Falcon seal of this commit signs
+ * @return the seals, or empty when the gate is shut, a key is missing, or signing failed
+ */
+ public List<SchemeSeal> sealsFor(final long blockNumber, final Bytes message) {
+ if (!attachmentArmedAt(blockNumber) || message == null) {
+ return List.of();
+ }
+ try {
+ final Set<String> required = schedule.schemesAt(blockNumber);
+ final List<SchemeSeal> produced = new ArrayList<>();
+ for (final String schemeId : required) {
+ if (SealSchemes.FALCON_512.id().equals(schemeId)) {
+ continue; // Falcon has its own slot and its own signer; never duplicated here
+ }
+ final Optional<SealScheme> scheme = SealSchemes.byId(schemeId);
+ if (scheme.isEmpty()) {
+ shoutOnce(schemeId, "the schedule names scheme '" + schemeId
+ + "' which this binary does not implement");
+ return List.of();
+ }
+ final SealScheme.PrivateHandle key = localKeys.get(schemeId);
+ if (key == null) {
+ shoutOnce(schemeId, "this node holds NO " + schemeId
+ + " signing key, so it cannot produce the certificate the schedule requires from"
+ + " height " + blockNumber + " onwards");
+ return List.of();
+ }
+ final Optional<byte[]> signature = scheme.get().sign(key, message.toArray());
+ if (signature.isEmpty()) {
+ shoutOnce(schemeId, "signing with the local " + schemeId + " key FAILED");
+ return List.of();
+ }
+ produced.add(
+ new SchemeSeal(scheme.get().wireId(), validatorIndex, Bytes.wrap(signature.get())));
+ }
+ // Canonical order, so two honest nodes signing the same block emit identical bytes and the
+ // certificate cannot become a source of gratuitous divergence.
+ produced.sort(PqAnchorV2.CANONICAL);
+ return List.copyOf(produced);
+ } catch (final RuntimeException e) {
+ LOG.warn("AERE HIBRID: producer fault at block {}, emitting nothing: {}",
+ blockNumber, e.getMessage());
+ return List.of();
+ }
+ }
+
+ private void shoutOnce(final String schemeId, final String what) {
+ if (alreadyShouted.add(schemeId)) {
+ LOG.error("AERE HIBRID: {} - NO hybrid certificate will be emitted by this node."
+ + " Fix this BEFORE the enforcement height, not on the day.", what);
+ }
+ }
+}
diff --git a/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/HybridSealSupport.java b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/HybridSealSupport.java
new file mode 100755
index 000000000..34f362d8d
--- /dev/null
+++ b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/HybridSealSupport.java
@@ -0,0 +1,295 @@
+/*
+ * AERE HYBRID, the PRODUCTION loader (2026-08-25). The only place that reads a node's hybrid
+ * configuration and turns it into the two already-proven pieces: HybridSealProducer
+ * (emission) and the schedule+registry pair for PqCommitEnforcement (enforcement).
+ *
+ * THE PROPERTIES (all via BESU_OPTS, like every AERE switch; all absent = today's node,
+ * byte for byte):
+ * aere.pq.schemeSchedule / AERE_PQ_SCHEME_SCHEDULE the schedule "H:scheme+scheme,..."
+ * aere.pq.hybridRegistry / AERE_PQ_HYBRID_REGISTRY path of the hybrid-1 registry
+ * aere.pq.hybrid.attachBlock / AERE_PQ_HYBRID_ATTACHBLOCK height from which extras are EMITTED
+ * aere.pq.hybrid.key.<scheme> / (no env; one path per scheme) the local private key {index, sk}
+ *
+ * EACH CONFIGURATION HALF REFUSES AT STARTUP, with a code and a name:
+ * CONF-03 schedule without registry or the reverse (inherited from enforcement; caught earlier here)
+ * CONF-04 attach armed without schedule+registry: you would emit what nobody can verify
+ * CONF-05 the local key does not bind: index outside the registry, scheme unknown to the
+ * schedule, index different from the local Falcon index, or the probe signature does
+ * not verify against the public key the registry holds (the loader's positive
+ * control: a key that fails its own probe must not boot a node that believes itself armed)
+ *
+ * A mistyped comma does NOT silently boot the node disarmed: the anchor loader's lesson.
+ */
+package org.hyperledger.besu.consensus.common.bft;
+
+import java.io.FileInputStream;
+import java.io.IOException;
+import java.io.InputStream;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Path;
+import java.util.HashMap;
+import java.util.Map;
+import java.util.Optional;
+import java.util.Properties;
+
+import org.apache.tuweni.bytes.Bytes;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+/** Loads a node's hybrid-seal configuration once and hands out the proven parts. */
+public final class HybridSealSupport {
+
+ private static final Logger LOG = LoggerFactory.getLogger(HybridSealSupport.class);
+
+ /** System property naming the scheme schedule. */
+ public static final String PROPERTY_SCHEDULE = "aere.pq.schemeSchedule";
+ /** Environment fallback for {@link #PROPERTY_SCHEDULE}. */
+ public static final String ENV_SCHEDULE = "AERE_PQ_SCHEME_SCHEDULE";
+ /** System property naming the hybrid registry file path. */
+ public static final String PROPERTY_REGISTRY = "aere.pq.hybridRegistry";
+ /** Environment fallback for {@link #PROPERTY_REGISTRY}. */
+ public static final String ENV_REGISTRY = "AERE_PQ_HYBRID_REGISTRY";
+ /** System property naming the emission gate height. */
+ public static final String PROPERTY_ATTACH_BLOCK = "aere.pq.hybrid.attachBlock";
+ /** Environment fallback for {@link #PROPERTY_ATTACH_BLOCK}. */
+ public static final String ENV_ATTACH_BLOCK = "AERE_PQ_HYBRID_ATTACHBLOCK";
+ /** Prefix of the per-scheme local private key path property. */
+ public static final String PROPERTY_KEY_PREFIX = "aere.pq.hybrid.key.";
+
+ /** How this class reaches names and files; swappable so the loader itself is provable. */
+ public interface ConfigReader {
+ /** Returns the raw system property.
+ *
+ * @param name the system property name
+ * @return the value, or null when absent */
+ String property(String name);
+ /** Returns the raw environment variable.
+ *
+ * @param name the environment variable name
+ * @return the value, or null when absent */
+ String environment(String name);
+ /** Returns the file's bytes.
+ *
+ * @param path the file path
+ * @return the bytes
+ * @throws IOException when unreadable */
+ byte[] file(String path) throws IOException;
+ }
+
+ private static final ConfigReader REAL =
+ new ConfigReader() {
+ @Override
+ public String property(final String name) {
+ return System.getProperty(name);
+ }
+
+ @Override
+ public String environment(final String name) {
+ return System.getenv(name);
+ }
+
+ @Override
+ public byte[] file(final String path) throws IOException {
+ try (InputStream in = new FileInputStream(path)) {
+ return in.readAllBytes();
+ }
+ }
+ };
+
+ private static volatile HybridSealSupport instance;
+
+ private final PqSchemeSchedule schedule; // null = not configured
+ private final HybridSignerRegistry registry; // paired with the schedule, never alone
+ private final HybridSealProducer producer; // never null; disarmed when there is nothing
+
+ private HybridSealSupport(
+ final PqSchemeSchedule schedule,
+ final HybridSignerRegistry registry,
+ final HybridSealProducer producer) {
+ this.schedule = schedule;
+ this.registry = registry;
+ this.producer = producer;
+ }
+
+ /** The process-wide instance, loaded from real configuration on first use. */
+ public static HybridSealSupport instance() {
+ HybridSealSupport s = instance;
+ if (s == null) {
+ synchronized (HybridSealSupport.class) {
+ s = instance;
+ if (s == null) {
+ s = load(REAL);
+ instance = s;
+ }
+ }
+ }
+ return s;
+ }
+
+ /** Drops the cached instance, for tests only. */
+ public static void resetForTesting() {
+ instance = null;
+ }
+
+ /**
+ * Load from a reader. Public so the loader's refusals are provable without global state.
+ *
+ * @param reader the configuration source
+ * @return the loaded support; fully disarmed when nothing is configured
+ */
+ public static HybridSealSupport load(final ConfigReader reader) {
+ final String rawSchedule = firstOf(reader, PROPERTY_SCHEDULE, ENV_SCHEDULE);
+ final String rawRegistry = firstOf(reader, PROPERTY_REGISTRY, ENV_REGISTRY);
+ final String rawAttach = firstOf(reader, PROPERTY_ATTACH_BLOCK, ENV_ATTACH_BLOCK);
+
+ if ((rawSchedule == null) != (rawRegistry == null)) {
+ throw new IllegalStateException(
+ "AERE-PQC-COMMIT-CONF-03: " + PROPERTY_SCHEDULE + " and " + PROPERTY_REGISTRY
+ + " are a PAIR; configure both or neither. Half a hybrid configuration must"
+ + " refuse at startup, never run half-armed in silence.");
+ }
+ if (rawSchedule == null) {
+ if (rawAttach != null) {
+ throw new IllegalStateException(
+ "AERE-PQC-HYBRID-CONF-04: " + PROPERTY_ATTACH_BLOCK + " is set but the schedule and"
+ + " registry are not: this node would EMIT seals nobody can verify.");
+ }
+ return new HybridSealSupport(null, null, HybridSealProducer.disarmed());
+ }
+
+ final PqSchemeSchedule schedule;
+ try {
+ schedule = PqSchemeSchedule.parse(rawSchedule);
+ } catch (final RuntimeException e) {
+ throw new IllegalStateException(
+ "AERE-PQC-HYBRID-CONF-04: unparseable " + PROPERTY_SCHEDULE + ": " + e.getMessage());
+ }
+ final HybridSignerRegistry registry;
+ try {
+ final Properties p = new Properties();
+ p.load(
+ new java.io.StringReader(
+ new String(reader.file(rawRegistry), StandardCharsets.UTF_8)));
+ registry = HybridSignerRegistry.fromProperties(p, rawRegistry);
+ } catch (final IOException e) {
+ throw new IllegalStateException(
+ "AERE-PQC-HYBRID-CONF-04: cannot read " + PROPERTY_REGISTRY + " '" + rawRegistry
+ + "': " + e.getMessage());
+ }
+
+ long attachFrom = HybridSealProducer.NEVER;
+ if (rawAttach != null) {
+ try {
+ attachFrom = Long.parseLong(rawAttach.trim());
+ if (attachFrom < 0) {
+ throw new NumberFormatException("negative");
+ }
+ } catch (final NumberFormatException e) {
+ throw new IllegalStateException(
+ "AERE-PQC-HYBRID-CONF-04: " + PROPERTY_ATTACH_BLOCK
+ + " is set but not a non-negative height: '" + rawAttach + "'");
+ }
+ }
+
+ // Local private keys, one file per non-Falcon scheme the schedule ever names.
+ final Map<String, SealScheme.PrivateHandle> keys = new HashMap<>();
+ Integer boundIndex = null;
+ for (final SealScheme scheme : SealSchemes.all()) {
+ if (scheme.id().equals(SealSchemes.FALCON_512.id())) {
+ continue; // Falcon-ul are incarcatorul lui, neatins
+ }
+ final String keyPath = reader.property(PROPERTY_KEY_PREFIX + scheme.id());
+ if (keyPath == null) {
+ continue;
+ }
+ final int index;
+ final SealScheme.PrivateHandle handle;
+ try {
+ final Properties kp = new Properties();
+ kp.load(
+ new java.io.StringReader(
+ new String(reader.file(keyPath), StandardCharsets.UTF_8)));
+ index = Integer.parseInt(kp.getProperty("index", "").trim());
+ final byte[] sk =
+ Bytes.fromHexStringLenient(kp.getProperty("sk", "").trim()).toArray();
+ handle =
+ scheme
+ .parsePrivateKey(sk)
+ .orElseThrow(
+ () -> new IllegalStateException("bytes do not parse as a private key"));
+ } catch (final IOException | RuntimeException e) {
+ throw new IllegalStateException(
+ "AERE-PQC-HYBRID-CONF-05: cannot load the local " + scheme.id() + " key from '"
+ + keyPath + "': " + e.getMessage());
+ }
+ // THE LOADER'S POSITIVE CONTROL: the private key must pass its own probe against the
+ // PUBLIC key the registry holds for this index. A key that fails it must not boot a
+ // node that believes itself armed.
+ final Optional<byte[]> pub = registry.publicKey(index, scheme.id());
+ if (pub.isEmpty()) {
+ throw new IllegalStateException(
+ "AERE-PQC-HYBRID-CONF-05: the registry holds no " + scheme.id() + " key for index "
+ + index + " (from '" + keyPath + "')");
+ }
+ final byte[] probe = ("AERE-HYBRID-KEY-PROBE:" + index).getBytes(StandardCharsets.UTF_8);
+ final Optional<byte[]> sig = scheme.sign(handle, probe);
+ if (sig.isEmpty() || !scheme.verifyRaw(pub.get(), probe, sig.get())) {
+ throw new IllegalStateException(
+ "AERE-PQC-HYBRID-CONF-05: the local " + scheme.id() + " key at index " + index
+ + " does NOT verify against the registry's public key. Wrong key, wrong index,"
+ + " or wrong registry; refusing to start half-armed.");
+ }
+ if (boundIndex != null && boundIndex != index) {
+ throw new IllegalStateException(
+ "AERE-PQC-HYBRID-CONF-05: local hybrid keys disagree on the validator index ("
+ + boundIndex + " vs " + index + "). One node, one identity.");
+ }
+ boundIndex = index;
+ keys.put(scheme.id(), handle);
+ LOG.info(
+ "AERE HIBRID: loaded local {} signing key for validator index {} (probe verified"
+ + " against the registry)",
+ scheme.id(),
+ index);
+ }
+
+ if (attachFrom != HybridSealProducer.NEVER && keys.isEmpty()) {
+ throw new IllegalStateException(
+ "AERE-PQC-HYBRID-CONF-04: emission is armed from " + attachFrom + " but this node"
+ + " holds no local hybrid key (" + PROPERTY_KEY_PREFIX + "<scheme> unset)."
+ + " It would promise a certificate it cannot produce.");
+ }
+
+ final HybridSealProducer producer =
+ keys.isEmpty()
+ ? HybridSealProducer.disarmed()
+ : new HybridSealProducer(attachFrom, schedule, boundIndex, keys);
+ return new HybridSealSupport(schedule, registry, producer);
+ }
+
+ private static String firstOf(final ConfigReader r, final String prop, final String env) {
+ final String p = r.property(prop);
+ return p != null ? p : r.environment(env);
+ }
+
+ /** Returns the schedule, when the hybrid pair is configured.
+ *
+ * @return the schedule, or empty */
+ public Optional<PqSchemeSchedule> schedule() {
+ return Optional.ofNullable(schedule);
+ }
+
+ /** Returns the registry, when the hybrid pair is configured.
+ *
+ * @return the registry, or empty */
+ public Optional<HybridSignerRegistry> registry() {
+ return Optional.ofNullable(registry);
+ }
+
+ /** Returns the producer; disarmed (never emits) when nothing is configured.
+ *
+ * @return the producer */
+ public HybridSealProducer producer() {
+ return producer;
+ }
+}
diff --git a/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/HybridSignerRegistry.java b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/HybridSignerRegistry.java
new file mode 100755
index 000000000..49563b7b1
--- /dev/null
+++ b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/HybridSignerRegistry.java
@@ -0,0 +1,307 @@
+/*
+ * AERE crypto-agility, step 3: the hybrid signer registry.
+ *
+ * WHY. The live registry format holds ONE Falcon key per validator index (896-byte h, plus the
+ * 20-byte address). The founder-approved hybrid (2026-08-07, option 3) needs a registry that can
+ * hold a key PER SCHEME per validator, so a certificate can carry Falcon and SLH-DSA seals from
+ * the same validator and each can be checked against its own key.
+ *
+ * FORMAT (properties):
+ * formatVersion=hybrid-1
+ * chainId=<decimal>
+ * count=<decimal>
+ * <i>.addr=<20-byte hex> mandatory for every index 0..count-1
+ * <i>.key.<schemeId>=<hex> at least one per index; schemeId from SealSchemes
+ *
+ * STRICTNESS, learned the expensive way (blocante_armare 2026-08-06: "a mistyped comma boots
+ * the node DISARMED"): every deviation REFUSES the whole registry loudly - unknown scheme suffix,
+ * wrong key length for its scheme, a hole in the index sequence, a count that disagrees, a
+ * missing address, duplicate keys. A registry that loads "partially" is a node that validates
+ * differently from its peers without knowing it.
+ *
+ * NO REAL KEYS. This class never generates anything. Real hybrid validator keys require the
+ * founder-approved ceremony; tests feed it throwaway pairs from SealScheme.generate.
+ */
+package org.hyperledger.besu.consensus.common.bft;
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.NavigableMap;
+import java.util.Properties;
+import java.util.TreeMap;
+
+import org.apache.tuweni.bytes.Bytes;
+import org.apache.tuweni.bytes.Bytes32;
+import org.hyperledger.besu.crypto.Hash;
+
+/** The scheme-aware validator key registry for the hybrid certificate. Immutable once loaded. */
+public final class HybridSignerRegistry {
+
+ /** The exact format marker this loader accepts. */
+ public static final String FORMAT_VERSION = "hybrid-1";
+
+ /** Canonical-hash domain. Distinct from AERE-PQ-REGISTRY-1/-2 (the Falcon-only registry hash
+ * family in PqRegistryHash), so a hybrid registry hash can never be mistaken for a v1/v2 one. */
+ public static final String HASH_DOMAIN = "AERE-PQ-HYBRID-REGISTRY-1";
+
+ private final long chainId;
+ // index -> (schemeId -> key bytes); TreeMap so iteration is canonical by index
+ private final NavigableMap<Integer, Map<String, byte[]>> keys;
+ private final Map<Integer, byte[]> addresses;
+
+ private HybridSignerRegistry(
+ final long chainId,
+ final NavigableMap<Integer, Map<String, byte[]>> keys,
+ final Map<Integer, byte[]> addresses) {
+ this.chainId = chainId;
+ this.keys = keys;
+ this.addresses = addresses;
+ }
+
+ /** Load from a properties file on disk. Refuses loudly, never partially. */
+ public static HybridSignerRegistry load(final Path file) throws IOException {
+ final Properties p = new Properties();
+ try (InputStream in = Files.newInputStream(file)) {
+ p.load(in);
+ }
+ return fromProperties(p, file.toString());
+ }
+
+ /** Load from already-parsed properties. {@code source} names the origin for error messages. */
+ public static HybridSignerRegistry fromProperties(final Properties p, final String source) {
+ final String format = p.getProperty("formatVersion");
+ if (!FORMAT_VERSION.equals(format)) {
+ throw new IllegalArgumentException(
+ "AERE PQ HIBRID: " + source + " declares formatVersion=" + format
+ + ", this loader accepts only " + FORMAT_VERSION);
+ }
+ final long chainId = parseLong(p.getProperty("chainId"), "chainId", source);
+ final int count = (int) parseLong(p.getProperty("count"), "count", source);
+ if (count <= 0 || count > 1024) {
+ throw new IllegalArgumentException(
+ "AERE PQ HIBRID: " + source + " has count=" + count + ", outside (0, 1024]");
+ }
+
+ final NavigableMap<Integer, Map<String, byte[]>> keys = new TreeMap<>();
+ final Map<Integer, byte[]> addresses = new HashMap<>();
+
+ for (final String name : p.stringPropertyNames()) {
+ if (name.equals("formatVersion") || name.equals("chainId") || name.equals("count")) {
+ continue;
+ }
+ final int dot = name.indexOf('.');
+ if (dot <= 0) {
+ throw new IllegalArgumentException(
+ "AERE PQ HIBRID: " + source + " carries unrecognised entry '" + name + "'");
+ }
+ final int index = parseIndex(name.substring(0, dot), name, source);
+ final String rest = name.substring(dot + 1);
+ final byte[] value = decodeHex(p.getProperty(name), name, source);
+
+ if (rest.equals("addr")) {
+ if (value.length != 20) {
+ throw new IllegalArgumentException(
+ "AERE PQ HIBRID: " + source + " entry '" + name + "' is " + value.length
+ + " bytes, an address must be exactly 20");
+ }
+ if (addresses.put(index, value) != null) {
+ throw new IllegalArgumentException(
+ "AERE PQ HIBRID: " + source + " repeats address for index " + index);
+ }
+ } else if (rest.startsWith("key.")) {
+ final String schemeId = rest.substring("key.".length());
+ final SealScheme scheme =
+ SealSchemes.byId(schemeId)
+ .orElseThrow(
+ () ->
+ new IllegalArgumentException(
+ "AERE PQ HIBRID: " + source + " entry '" + name
+ + "' names UNKNOWN scheme '" + schemeId
+ + "' - refusing the whole registry, an unknown scheme must be loud"));
+ if (value.length != scheme.publicKeyLength()) {
+ throw new IllegalArgumentException(
+ "AERE PQ HIBRID: " + source + " entry '" + name + "' is " + value.length
+ + " bytes, scheme " + schemeId + " keys are exactly "
+ + scheme.publicKeyLength());
+ }
+ if (scheme.parsePublicKey(value).isEmpty()) {
+ throw new IllegalArgumentException(
+ "AERE PQ HIBRID: " + source + " entry '" + name
+ + "' does not parse as a " + schemeId + " public key");
+ }
+ final Map<String, byte[]> perScheme = keys.computeIfAbsent(index, i -> new TreeMap<>());
+ if (perScheme.put(schemeId, value) != null) {
+ throw new IllegalArgumentException(
+ "AERE PQ HIBRID: " + source + " repeats key for index " + index
+ + " scheme " + schemeId);
+ }
+ } else {
+ throw new IllegalArgumentException(
+ "AERE PQ HIBRID: " + source + " carries unrecognised entry '" + name + "'");
+ }
+ }
+
+ // completeness: every index 0..count-1 present, with an address and at least one key
+ for (int i = 0; i < count; i++) {
+ if (!addresses.containsKey(i)) {
+ throw new IllegalArgumentException(
+ "AERE PQ HIBRID: " + source + " is missing " + i + ".addr (count says " + count + ")");
+ }
+ if (!keys.containsKey(i) || keys.get(i).isEmpty()) {
+ throw new IllegalArgumentException(
+ "AERE PQ HIBRID: " + source + " has no key at all for index " + i);
+ }
+ }
+ if (addresses.size() != count || keys.size() != count) {
+ throw new IllegalArgumentException(
+ "AERE PQ HIBRID: " + source + " carries entries beyond count=" + count
+ + " (addresses " + addresses.size() + ", key rows " + keys.size() + ")");
+ }
+
+ return new HybridSignerRegistry(chainId, keys, addresses);
+ }
+
+ /** The chain this registry binds to. */
+ public long chainId() {
+ return chainId;
+ }
+
+ /** How many validator indices the registry holds. */
+ public int size() {
+ return keys.size();
+ }
+
+ /** The key of {@code index} under {@code schemeId}, if that validator has one. */
+ public Optional<byte[]> publicKey(final int index, final String schemeId) {
+ final Map<String, byte[]> perScheme = keys.get(index);
+ if (perScheme == null) {
+ return Optional.empty();
+ }
+ final byte[] exact = perScheme.get(schemeId);
+ if (exact != null) {
+ return Optional.of(exact.clone());
+ }
+ // D-325 (2026-09-03): a registry written with an ALIAS of a scheme id ("slh-dsa-128s") answers a
+ // lookup by the canonical id ("slh-dsa-sha2-128s") and the other way round. Stored names are
+ // kept as written so the registry's canonical hash does not move under a file that did not.
+ final String wanted = canonicalId(schemeId);
+ for (final Map.Entry<String, byte[]> e : perScheme.entrySet()) {
+ if (canonicalId(e.getKey()).equals(wanted)) {
+ return Optional.of(e.getValue().clone());
+ }
+ }
+ return Optional.empty();
+ }
+
+ private static String canonicalId(final String schemeId) {
+ return SealSchemes.byId(schemeId).map(SealScheme::id).orElse(schemeId);
+ }
+
+ /** The 20-byte address bound to {@code index}, or empty. */
+ public Optional<byte[]> address(final int index) {
+ return Optional.ofNullable(addresses.get(index)).map(byte[]::clone);
+ }
+
+ /** How many indices hold a key under {@code schemeId}. The arming gate for a scheme asks this:
+ * arming a K-of-N threshold under a scheme with coverage below K would be a chain stop. */
+ public int coverage(final String schemeId) {
+ final String wanted = canonicalId(schemeId);
+ return (int)
+ keys.values().stream()
+ .filter(m -> m.keySet().stream().anyMatch(k -> canonicalId(k).equals(wanted)))
+ .count();
+ }
+
+ /** The canonical hash: domain || chainId || count || per index asc: index, addr, schemeCount,
+ * then per scheme in id order: idLen, idBytes, keyLen, key. Length-prefixed throughout, keccak
+ * over the whole, same discipline as PqRegistryHash. */
+ public Bytes32 canonicalHash() {
+ final java.io.ByteArrayOutputStream out = new java.io.ByteArrayOutputStream();
+ writeAll(out, HASH_DOMAIN.getBytes(StandardCharsets.US_ASCII));
+ writeAll(out, uint64be(chainId));
+ writeAll(out, uint32be(keys.size()));
+ for (final Map.Entry<Integer, Map<String, byte[]>> row : keys.entrySet()) {
+ writeAll(out, uint32be(row.getKey()));
+ writeAll(out, addresses.get(row.getKey()));
+ writeAll(out, uint32be(row.getValue().size()));
+ for (final Map.Entry<String, byte[]> k : row.getValue().entrySet()) {
+ final byte[] id = k.getKey().getBytes(StandardCharsets.US_ASCII);
+ writeAll(out, uint32be(id.length));
+ writeAll(out, id);
+ writeAll(out, uint32be(k.getValue().length));
+ writeAll(out, k.getValue());
+ }
+ }
+ return Hash.keccak256(Bytes.wrap(out.toByteArray()));
+ }
+
+ /** The schemes present for {@code index}, in canonical id order. */
+ public List<String> schemesOf(final int index) {
+ final Map<String, byte[]> perScheme = keys.get(index);
+ return perScheme == null ? List.of() : new ArrayList<>(perScheme.keySet());
+ }
+
+ // ------------------------------------------------------------------------------- helpers
+
+ private static long parseLong(final String raw, final String field, final String source) {
+ if (raw == null || raw.isBlank()) {
+ throw new IllegalArgumentException("AERE PQ HIBRID: " + source + " is missing " + field);
+ }
+ try {
+ return Long.parseLong(raw.trim());
+ } catch (final NumberFormatException e) {
+ throw new IllegalArgumentException(
+ "AERE PQ HIBRID: " + source + " field " + field + " is not a number: '" + raw + "'");
+ }
+ }
+
+ private static int parseIndex(final String raw, final String entry, final String source) {
+ try {
+ final int i = Integer.parseInt(raw);
+ if (i < 0) {
+ throw new NumberFormatException("negative");
+ }
+ return i;
+ } catch (final NumberFormatException e) {
+ throw new IllegalArgumentException(
+ "AERE PQ HIBRID: " + source + " entry '" + entry + "' has a bad index '" + raw + "'");
+ }
+ }
+
+ private static byte[] decodeHex(final String raw, final String entry, final String source) {
+ if (raw == null || raw.isBlank()) {
+ throw new IllegalArgumentException(
+ "AERE PQ HIBRID: " + source + " entry '" + entry + "' is empty");
+ }
+ try {
+ return Bytes.fromHexStringLenient(raw.trim()).toArray();
+ } catch (final RuntimeException e) {
+ throw new IllegalArgumentException(
+ "AERE PQ HIBRID: " + source + " entry '" + entry + "' is not hex: " + e.getMessage());
+ }
+ }
+
+ private static void writeAll(final java.io.ByteArrayOutputStream out, final byte[] b) {
+ out.write(b, 0, b.length);
+ }
+
+ private static byte[] uint32be(final long v) {
+ return new byte[] {(byte) (v >>> 24), (byte) (v >>> 16), (byte) (v >>> 8), (byte) v};
+ }
+
+ private static byte[] uint64be(final long v) {
+ final byte[] b = new byte[8];
+ for (int i = 0; i < 8; i++) {
+ b[i] = (byte) (v >>> (8 * (7 - i)));
+ }
+ return b;
+ }
+}
diff --git a/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/PqAnchor.java b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/PqAnchor.java
new file mode 100755
index 000000000..32c634ee8
--- /dev/null
+++ b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/PqAnchor.java
@@ -0,0 +1,547 @@
+/*
+ * Copyright contributors to Besu / AERE Network.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.common.bft;
+
+import org.hyperledger.besu.crypto.Hash;
+import org.hyperledger.besu.ethereum.rlp.BytesValueRLPOutput;
+import org.hyperledger.besu.ethereum.rlp.RLPOutput;
+
+import java.nio.charset.StandardCharsets;
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.Comparator;
+import java.util.List;
+
+import org.apache.tuweni.bytes.Bytes;
+import org.apache.tuweni.bytes.Bytes32;
+
+/**
+ * CERTIFICATE ANCHOR, schema V2: "IT IS CARRIED, NOT REFERENCED".
+ *
+ * <p>Canonical encoding, anchor digest D and signed message M for the AERE post-quantum certificate
+ * anchor. This class is a PURE function library: no singletons, no configuration, no I/O, no state.
+ * Everything it computes is a function of its arguments only, which is what makes {@code
+ * PqAnchorDigestRule} usable in LIGHT validation.
+ *
+ * <p><b>Why V2 exists.</b> Today the QBFT block hash covers no proof of any post-quantum seal: the
+ * Falcon seal list sits in {@code EncodingType.ALL} only, and both hash pre-images exclude it. You
+ * can strip the entire post-quantum attestation from a header and its block hash is unchanged. The
+ * earlier design (Option V) tried to fix that by putting the digest of the PARENT's certificate,
+ * read out of the PARENT's header, into the child's vanityData. That died on a measurement: over 200
+ * consecutive headers read simultaneously from two of our own RPC nodes, with the block hash
+ * identical 200/200, the seal ORDER differed on 68 headers and the seal SET differed on 11. The
+ * cause is structural, not a bug to patch: {@code RoundState} holds commits in a {@code
+ * LinkedHashMap} keyed on author, {@code values()} yields arrival order, and the assembler does not
+ * reorder. Every node writes what IT heard. Sorting fixes the order and does NOT fix the set, and no
+ * deterministic function of a local set can produce the same output from two different sets.
+ *
+ * <p><b>What V2 does instead.</b> The certificate over block N-1 is not read out of N-1's header.
+ * It is CARRIED in the extraData of block N, chosen by N's proposer and ratified by N's round, and
+ * N's vanityData carries its digest over all 32 bytes. The digest therefore depends only on what the
+ * PROPOSER WROTE, and those bytes reach every node identically inside the same proposal. A validator
+ * never compares the certificate with what it heard: it checks only the threshold, strictly
+ * increasing indices, index eligibility in the PARENT's validator set, and k Falcon verifications. A
+ * node that heard 7 accepts the proposer's certificate of 5.
+ *
+ * <p><b>The two pre-images.</b>
+ *
+ * <pre>
+ * D = keccak256( RLP[ "AERE-PQ-ANCHOR-1", chainId, parentNumber, parentHash, C ] )
+ * M = keccak256( RLP[ "AERE-PQ-COMMIT-1", chainId, blockNumber, blockHash ] )
+ * C = RLP[ [idx, sig], [idx, sig], ... ] indices STRICTLY INCREASING
+ * </pre>
+ *
+ * <p>D occupies all 32 bytes of vanityData: no magic, no version byte, no padding. The budget is 32
+ * bytes and cannot grow, because two LIVE length checks require exactly 32 (AereQbftFinalityVerifier
+ * .sol line 194 and the second client's decoder). Versioning is by ACTIVATION HEIGHT, not by an
+ * in-band version byte, because any format change needs a governance-decided height anyway.
+ *
+ * <p>M is deliberately NOT the ECDSA commit hash. The commit hash includes the ROUND, which is not
+ * in the block-hash pre-image, and rounds above zero do occur on this chain (measured 1 in 307).
+ * Defining M over the block HASH makes the message reconstructible by any node holding the parent
+ * header: no state, no round, no local memory.
+ *
+ * <p>The domain labels are what stops a Falcon signature produced for another subsystem (the
+ * AerePQCTxAccount rail, ML-KEM intents, any application message) from being reinterpreted as a
+ * consensus seal, and the chainId is what stops a certificate produced on the 442807 proving chain,
+ * which runs the SAME binaries and may run the same Falcon keys, from being material here.
+ *
+ * <p>CONSENSUS IS STILL CLASSICAL secp256k1 ECDSA. This class does not make consensus post-quantum
+ * and must never be described as doing so. The post-quantum layer is signature, precompile and
+ * account level.
+ */
+public final class PqAnchor {
+
+ /** Domain label for the anchor digest D. Exactly 16 ASCII bytes. */
+ public static final String ANCHOR_DOMAIN = "AERE-PQ-ANCHOR-1";
+
+ /** Domain label for the signed commit message M. Exactly 16 ASCII bytes. */
+ public static final String COMMIT_DOMAIN = "AERE-PQ-COMMIT-1";
+
+ /** The anchor domain label as raw bytes. */
+ public static final Bytes ANCHOR_DOMAIN_BYTES =
+ Bytes.wrap(ANCHOR_DOMAIN.getBytes(StandardCharsets.US_ASCII));
+
+ /** The commit domain label as raw bytes. */
+ public static final Bytes COMMIT_DOMAIN_BYTES =
+ Bytes.wrap(COMMIT_DOMAIN.getBytes(StandardCharsets.US_ASCII));
+
+ /**
+ * The PREPARE domain label. AERE PQ (2026-08-28).
+ *
+ * <p>SEPARATE FROM COMMIT, and the separation is a security requirement, not a matter of style.
+ * If a PREPARE seal signed the same bytes as a commit seal, an adversary could take a PREPARE
+ * seal given HONESTLY by a validator and paste it onto a forged COMMIT: the signature would
+ * verify, and the very rule meant to defend the commit would be bypassed. One changed string in
+ * the preimage makes the two signatures non-transferable.
+ */
+ public static final String PREPARE_DOMAIN = "AERE-PQ-PREPARE-1";
+
+ /** The prepare domain label as raw bytes. */
+ public static final Bytes PREPARE_DOMAIN_BYTES =
+ Bytes.wrap(PREPARE_DOMAIN.getBytes(StandardCharsets.US_ASCII));
+
+ /**
+ * The PROPOSAL domain label. AERE PQ (2026-08-30), the next hot-path step after PREPARE.
+ *
+ * <p>SEPARATE FROM BOTH PREPARE AND COMMIT, for the same non-transferability reason: a seal a
+ * proposer gives HONESTLY over its own proposal must not be usable as a vote. A proposal is an
+ * OFFER, not a vote - the design note of 2026-08-28 measures that "prepared" needs a full quorum
+ * of PREPAREs, proposer included - so its seal must never count as one. One changed string in the
+ * preimage is what enforces that at the cryptographic layer instead of by convention.
+ */
+ public static final String PROPOSAL_DOMAIN = "AERE-PQ-PROPOSAL-1";
+
+ /** The proposal domain label as raw bytes. */
+ public static final Bytes PROPOSAL_DOMAIN_BYTES =
+ Bytes.wrap(PROPOSAL_DOMAIN.getBytes(StandardCharsets.US_ASCII));
+
+ /**
+ * The ROUND-CHANGE domain label. AERE PQ (2026-08-31), the last hot-path message.
+ *
+ * <p>SEPARATE FROM ALL THREE OTHERS, for the same non-transferability reason. A ROUND-CHANGE is
+ * the message that STEERS rounds: a quorum of them opens a new round, and one that claims a
+ * prepared block decides WHICH block gets re-proposed. A seal given honestly over a vote or a
+ * proposal must not be pasteable onto a round-change, and a round-change seal must not count as
+ * either. One changed string in the preimage enforces that cryptographically.
+ */
+ public static final String ROUNDCHANGE_DOMAIN = "AERE-PQ-ROUNDCHANGE-1";
+
+ /** The round-change domain label as raw bytes. */
+ public static final Bytes ROUNDCHANGE_DOMAIN_BYTES =
+ Bytes.wrap(ROUNDCHANGE_DOMAIN.getBytes(StandardCharsets.US_ASCII));
+
+ /** Orders Falcon seals by their registry index, ascending. */
+ public static final Comparator<FalconSeal> BY_INDEX =
+ Comparator.comparingInt(FalconSeal::getValidatorIndex);
+
+ private PqAnchor() {}
+
+ /**
+ * Encode the certificate C in its canonical wire form. This is byte-for-byte the shape {@code
+ * QbftExtraDataCodec} already writes for the Falcon seal element, so the certificate that is
+ * hashed is the certificate that is carried: one logical object, one accepted byte string.
+ *
+ * @param output the RLP sink to write the certificate list into
+ * @param certificate the seals, in the order they are to be encoded
+ */
+ public static void writeCertificate(
+ final RLPOutput output, final Collection<FalconSeal> certificate) {
+ output.writeList(
+ certificate,
+ (seal, rlp) -> {
+ rlp.startList();
+ rlp.writeIntScalar(seal.getValidatorIndex());
+ rlp.writeBytes(seal.getSignature());
+ rlp.endList();
+ });
+ }
+
+ /**
+ * The canonical RLP encoding of the certificate C on its own. Used by tests and diagnostics; the
+ * digest path writes the certificate directly into the outer list rather than nesting an encoded
+ * blob.
+ *
+ * @param certificate the seals, in the order they are to be encoded
+ * @return the canonical RLP bytes of C
+ */
+ public static Bytes encodeCertificate(final Collection<FalconSeal> certificate) {
+ final BytesValueRLPOutput out = new BytesValueRLPOutput();
+ writeCertificate(out, certificate);
+ return out.encoded();
+ }
+
+ /**
+ * Compute the anchor digest D that block N's vanityData must carry, over the certificate block N
+ * carries for its PARENT.
+ *
+ * <p>The certificate is hashed IN THE ORDER GIVEN. It is deliberately not sorted here: sorting
+ * inside the digest would let a header with a reordered certificate still match D, which would
+ * make the digest rule (cheap, runs in light validation) disagree with the seals rule (expensive,
+ * runs only where state exists). Instead BOTH rules require {@link
+ * #hasStrictlyIncreasingIndices(Collection)}, so for every ACCEPTED header "the order given" and
+ * "sorted" are the same list, and reordering is rejected in light validation too. Producers call
+ * {@link #sortedByIndex(Collection)} before writing.
+ *
+ * @param chainId the chain id, in the pre-image so a certificate from another chain running the
+ * same binaries and possibly the same Falcon keys is not material here
+ * @param parentNumber the number of the parent block the certificate attests to
+ * @param parentHash the hash of the parent block the certificate attests to
+ * @param certificate the carried certificate C, possibly empty (at the activation height itself)
+ * @return the 32-byte anchor digest D
+ */
+ public static Bytes32 anchorDigest(
+ final long chainId,
+ final long parentNumber,
+ final Bytes parentHash,
+ final Collection<FalconSeal> certificate) {
+ if (parentNumber < 0) {
+ throw new IllegalArgumentException(
+ "AERE PQ ANCHOR: parentNumber must not be negative (got " + parentNumber + ")");
+ }
+ if (parentHash == null || parentHash.size() != 32) {
+ throw new IllegalArgumentException(
+ "AERE PQ ANCHOR: parentHash must be 32 bytes (got "
+ + (parentHash == null ? "null" : parentHash.size() + " bytes")
+ + ")");
+ }
+ final BytesValueRLPOutput out = new BytesValueRLPOutput();
+ out.startList();
+ out.writeBytes(ANCHOR_DOMAIN_BYTES);
+ out.writeLongScalar(chainId);
+ out.writeLongScalar(parentNumber);
+ out.writeBytes(parentHash);
+ writeCertificate(out, certificate);
+ out.endList();
+ return Hash.keccak256(out.encoded());
+ }
+
+ /**
+ * Compute the message M that a validator's Falcon key signs when it seals a block.
+ *
+ * <p>M is a function of the block HASH, never of the commit hash, so it can be recomputed from the
+ * header alone: no round number, no local state, no memory of the round that produced it.
+ *
+ * @param chainId the chain id
+ * @param blockNumber the number of the block being sealed
+ * @param blockHash the hash of the block being sealed
+ * @return the 32-byte message M that Falcon signs
+ */
+ public static Bytes32 commitMessage(
+ final long chainId, final long blockNumber, final Bytes blockHash) {
+ if (blockNumber < 0) {
+ throw new IllegalArgumentException(
+ "AERE PQ ANCHOR: blockNumber must not be negative (got " + blockNumber + ")");
+ }
+ if (blockHash == null || blockHash.size() != 32) {
+ throw new IllegalArgumentException(
+ "AERE PQ ANCHOR: blockHash must be 32 bytes (got "
+ + (blockHash == null ? "null" : blockHash.size() + " bytes")
+ + ")");
+ }
+ final BytesValueRLPOutput out = new BytesValueRLPOutput();
+ out.startList();
+ out.writeBytes(COMMIT_DOMAIN_BYTES);
+ out.writeLongScalar(chainId);
+ out.writeLongScalar(blockNumber);
+ out.writeBytes(blockHash);
+ out.endList();
+ return Hash.keccak256(out.encoded());
+ }
+
+ /**
+ * The message a PREPARE seal signs: M = keccak256(RLP[PREPARE_DOMAIN, chainId, blockNumber,
+ * round, digest]).
+ *
+ * <p>RUNDA E IN PREIMAGINE, spre deosebire de commit, si asta e al doilea lucru care nu se sare:
+ * doua PREPARE-uri ale aceluiasi bloc in runde diferite sunt doua afirmatii diferite, iar un
+ * a seal given in one round must not be movable into another. Without the round, a seal from a
+ * PREPARE of a failed round could be reused to justify another one.
+ *
+ * @param chainId the chain id
+ * @param blockNumber the height being prepared
+ * @param round the round number of the prepare
+ * @param digest the block digest the prepare speaks about
+ * @return the 32-byte message to sign
+ */
+ public static Bytes32 prepareMessage(
+ final long chainId, final long blockNumber, final int round, final Bytes digest) {
+ if (blockNumber < 0) {
+ throw new IllegalArgumentException(
+ "AERE PQ PREPARE: blockNumber must not be negative (got " + blockNumber + ")");
+ }
+ if (round < 0) {
+ throw new IllegalArgumentException(
+ "AERE PQ PREPARE: round must not be negative (got " + round + ")");
+ }
+ if (digest == null || digest.size() != 32) {
+ throw new IllegalArgumentException(
+ "AERE PQ PREPARE: digest must be 32 bytes (got "
+ + (digest == null ? "null" : digest.size() + " bytes")
+ + ")");
+ }
+ final BytesValueRLPOutput out = new BytesValueRLPOutput();
+ out.startList();
+ out.writeBytes(PREPARE_DOMAIN_BYTES);
+ out.writeLongScalar(chainId);
+ out.writeLongScalar(blockNumber);
+ out.writeLongScalar(round);
+ out.writeBytes(digest);
+ out.endList();
+ return Hash.keccak256(out.encoded());
+ }
+
+ /**
+ * The 32-byte message a proposer's post-quantum PROPOSAL seal signs.
+ *
+ * <p>Same shape as {@link #prepareMessage}, different domain, and the ROUND is in the preimage
+ * for the same reason: a proposal for the same block in a different round is a different
+ * assertion, and a seal from a failed round must not open another one.
+ *
+ * @param chainId the chain id
+ * @param blockNumber the height being proposed
+ * @param round the round number of the proposal
+ * @param digest the digest of the proposed block
+ * @return the 32-byte message to sign
+ */
+ public static Bytes32 proposalMessage(
+ final long chainId, final long blockNumber, final int round, final Bytes digest) {
+ if (blockNumber < 0) {
+ throw new IllegalArgumentException(
+ "AERE PQ PROPOSAL: blockNumber must not be negative (got " + blockNumber + ")");
+ }
+ if (round < 0) {
+ throw new IllegalArgumentException(
+ "AERE PQ PROPOSAL: round must not be negative (got " + round + ")");
+ }
+ if (digest == null || digest.size() != 32) {
+ throw new IllegalArgumentException(
+ "AERE PQ PROPOSAL: digest must be 32 bytes (got "
+ + (digest == null ? "null" : digest.size() + " bytes")
+ + ")");
+ }
+ final BytesValueRLPOutput out = new BytesValueRLPOutput();
+ out.startList();
+ out.writeBytes(PROPOSAL_DOMAIN_BYTES);
+ out.writeLongScalar(chainId);
+ out.writeLongScalar(blockNumber);
+ out.writeLongScalar(round);
+ out.writeBytes(digest);
+ out.endList();
+ return Hash.keccak256(out.encoded());
+ }
+
+ /**
+ * The 32-byte message a validator's post-quantum ROUND-CHANGE seal signs, for a round-change
+ * that carries NO prepared-round metadata.
+ *
+ * <p>The preimage writes an explicit presence flag of 0 and empty placeholders, so a bare
+ * round-change and one prepared at round 0 can never collide: the flag, not the emptiness of a
+ * field, is what says whether metadata exists.
+ *
+ * @param chainId the chain id
+ * @param blockNumber the height the round-change targets (its sequence number)
+ * @param targetRound the round the sender wants to move to
+ * @return the 32-byte message to sign
+ */
+ public static Bytes32 roundChangeMessage(
+ final long chainId, final long blockNumber, final int targetRound) {
+ return roundChangePreimage(chainId, blockNumber, targetRound, false, 0, Bytes.EMPTY);
+ }
+
+ /**
+ * The 32-byte message a validator's post-quantum ROUND-CHANGE seal signs, for a round-change
+ * that CLAIMS a prepared block.
+ *
+ * <p>The prepared metadata is IN the preimage on purpose: a round-change that claims a prepared
+ * block decides which block gets re-proposed, so a seal from a bare round-change pasted onto one
+ * with metadata (or onto one with different metadata) must not verify. Same shape as {@link
+ * #proposalMessage}, its own domain.
+ *
+ * @param chainId the chain id
+ * @param blockNumber the height the round-change targets (its sequence number)
+ * @param targetRound the round the sender wants to move to
+ * @param preparedRound the round the claimed prepared block was prepared in
+ * @param preparedDigest the 32-byte digest of the claimed prepared block
+ * @return the 32-byte message to sign
+ */
+ public static Bytes32 roundChangeMessage(
+ final long chainId,
+ final long blockNumber,
+ final int targetRound,
+ final int preparedRound,
+ final Bytes preparedDigest) {
+ if (preparedRound < 0) {
+ throw new IllegalArgumentException(
+ "AERE PQ ROUNDCHANGE: preparedRound must not be negative (got " + preparedRound + ")");
+ }
+ if (preparedDigest == null || preparedDigest.size() != 32) {
+ throw new IllegalArgumentException(
+ "AERE PQ ROUNDCHANGE: preparedDigest must be 32 bytes (got "
+ + (preparedDigest == null ? "null" : preparedDigest.size() + " bytes")
+ + ")");
+ }
+ return roundChangePreimage(chainId, blockNumber, targetRound, true, preparedRound, preparedDigest);
+ }
+
+ private static Bytes32 roundChangePreimage(
+ final long chainId,
+ final long blockNumber,
+ final int targetRound,
+ final boolean hasPrepared,
+ final int preparedRound,
+ final Bytes preparedDigest) {
+ if (blockNumber < 0) {
+ throw new IllegalArgumentException(
+ "AERE PQ ROUNDCHANGE: blockNumber must not be negative (got " + blockNumber + ")");
+ }
+ if (targetRound < 0) {
+ throw new IllegalArgumentException(
+ "AERE PQ ROUNDCHANGE: targetRound must not be negative (got " + targetRound + ")");
+ }
+ final BytesValueRLPOutput out = new BytesValueRLPOutput();
+ out.startList();
+ out.writeBytes(ROUNDCHANGE_DOMAIN_BYTES);
+ out.writeLongScalar(chainId);
+ out.writeLongScalar(blockNumber);
+ out.writeLongScalar(targetRound);
+ out.writeLongScalar(hasPrepared ? 1 : 0);
+ out.writeLongScalar(preparedRound);
+ out.writeBytes(preparedDigest);
+ out.endList();
+ return Hash.keccak256(out.encoded());
+ }
+
+ /**
+ * Whether the certificate's validator indices are STRICTLY increasing.
+ *
+ * <p>Strictly increasing does three jobs at once and all three are structural rather than
+ * defensive: it fixes ONE accepted order for a given set (closing seal reordering), it makes
+ * duplicate indices unrepresentable (closing the "inflate k by repeating a seal" attack in the
+ * grammar of the format rather than with a HashSet applied afterwards), and it rejects negative
+ * indices when combined with the non-negative check below.
+ *
+ * @param certificate the carried certificate
+ * @return true iff every index is non-negative and each is strictly greater than its predecessor
+ */
+ public static boolean hasStrictlyIncreasingIndices(final Collection<FalconSeal> certificate) {
+ long previous = Long.MIN_VALUE;
+ for (final FalconSeal seal : certificate) {
+ if (seal == null || seal.getSignature() == null) {
+ return false;
+ }
+ final int index = seal.getValidatorIndex();
+ if (index < 0 || index <= previous) {
+ return false;
+ }
+ previous = index;
+ }
+ return true;
+ }
+
+ /**
+ * First anchor height of the one historical window on chain 2800 whose certificates carry indices
+ * that are distinct but NOT sorted. Measured 2026-08-11 by decoding every anchor header in
+ * [13,266,800, 13,269,400] straight off the public endpoint: 82 anchor headers, 46 sorted, 36 not,
+ * none without a certificate. The 36 are CONTIGUOUS at the 32-block anchor spacing and nothing
+ * outside the window is affected, so the range below is the measured extent, not a guess.
+ *
+ * <p>DERIVED, not written a second time. The bounds themselves live in {@link PqAnchorLapse},
+ * which is the one place a historical window is named, because the SAME interruption that left
+ * these certificates unsorted also left their headers without an anchor digest, and a value that
+ * appears in two places diverges. This constant is kept because it is the name this class has
+ * always used for the first bound.
+ */
+ public static final long UNORDERED_WINDOW_FIRST = PqAnchorLapse.windows().get(0).firstBlock();
+
+ /** Last anchor height of that window. Its neighbours 13,267,792 and 13,268,976 are both sorted. */
+ public static final long UNORDERED_WINDOW_LAST = PqAnchorLapse.windows().get(0).lastBlock();
+
+ /**
+ * Whether the certificate's indices are non-negative and pairwise DISTINCT, in any order.
+ *
+ * <p>This is the part of {@link #hasStrictlyIncreasingIndices(Collection)} that is load bearing
+ * against an attacker rather than against ambiguity. Sortedness fixes one accepted order for a
+ * given set; distinctness is what makes "inflate k by repeating one seal" unrepresentable in the
+ * grammar of the format. A historical exception may relax the first WITHOUT relaxing the second,
+ * and this method exists so that the exception cannot accidentally relax both.
+ *
+ * @param certificate the carried certificate
+ * @return true iff every index is non-negative and no index appears twice
+ */
+ public static boolean hasDistinctNonNegativeIndices(final Collection<FalconSeal> certificate) {
+ final java.util.Set<Integer> seen = new java.util.HashSet<>();
+ for (final FalconSeal seal : certificate) {
+ if (seal == null || seal.getSignature() == null) {
+ return false;
+ }
+ final int index = seal.getValidatorIndex();
+ if (index < 0 || !seen.add(index)) {
+ return false;
+ }
+ }
+ return true;
+ }
+
+ /**
+ * Whether a header at {@code blockNumber} may carry this certificate's index ordering.
+ *
+ * <p><b>Why this exists.</b> During a production interruption on 2026-08-10 some proposers wrote
+ * the certificate in the order the commits ARRIVED instead of sorted. {@code RoundState} holds
+ * commits in a {@code LinkedHashMap} keyed on author and {@code values()} yields arrival order, so
+ * a producer that skips {@link #sortedByIndex(Collection)} writes an unsorted certificate and
+ * nothing downstream notices: the anchor digest is taken IN THE ORDER GIVEN, so those headers'
+ * digests are perfectly consistent with their own bytes. 36 such headers are canonical today.
+ *
+ * <p>Nodes already holding the chain never revalidate them, which is exactly why this was invisible
+ * for a day. A node syncing from genesis under the plain rule would reject header 13,267,824 and
+ * stop there forever. That is the same shape as the base-fee floor episode: the history is what it
+ * is, and the exception belongs at VALIDATION, where a header is accepted as written, not in any
+ * recomputation. A patch anywhere else moves the error instead of ending it.
+ *
+ * <p><b>What the exception does NOT relax.</b> Inside the window the certificate must still have
+ * non-negative and pairwise distinct indices. Measured 2026-08-11 on all 36 headers: distinct in
+ * every one, no negative index in any. So this accepts exactly the history that exists and nothing
+ * weaker, and the "repeat one seal to inflate k" attack stays unrepresentable at every height.
+ *
+ * <p><b>Producers must not call this.</b> {@code PqAnchorProducer} keeps requiring strict
+ * sortedness, so no new unsorted header can ever be written, at any height. The window is closed by
+ * construction: it is bounded above by a measured constant, so it cannot grow.
+ *
+ * @param certificate the carried certificate
+ * @param blockNumber the number of the header carrying it
+ * @return true iff the ordering is acceptable for a header at that height
+ */
+ public static boolean hasAcceptableIndices(
+ final Collection<FalconSeal> certificate, final long blockNumber) {
+ if (hasStrictlyIncreasingIndices(certificate)) {
+ return true;
+ }
+ return PqAnchorLapse.isDisarmed(blockNumber) && hasDistinctNonNegativeIndices(certificate);
+ }
+
+ /**
+ * Return the certificate sorted by validator index, ascending. Producers use this before writing
+ * the certificate into extraData; validators never sort, they require sortedness.
+ *
+ * @param certificate the seals in any order
+ * @return a new list sorted by validator index
+ */
+ public static List<FalconSeal> sortedByIndex(final Collection<FalconSeal> certificate) {
+ final List<FalconSeal> sorted = new ArrayList<>(certificate);
+ sorted.sort(BY_INDEX);
+ return sorted;
+ }
+}
diff --git a/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/PqAnchorConfig.java b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/PqAnchorConfig.java
new file mode 100755
index 000000000..d04d52829
--- /dev/null
+++ b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/PqAnchorConfig.java
@@ -0,0 +1,1580 @@
+/*
+ * Copyright contributors to Besu / AERE Network.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.common.bft;
+
+import java.util.Collections;
+import java.util.Locale;
+import java.util.Map;
+import java.util.NavigableMap;
+import java.util.OptionalInt;
+import java.util.TreeMap;
+
+import com.google.common.base.Splitter;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+/**
+ * Height-indexed activation configuration for the V2 certificate anchor: {@code pqAnchorBlock} (H)
+ * and the staged {@code pqAnchorMinSeals} threshold schedule K(height), plus the two LOCAL emergency
+ * de-arm controls.
+ *
+ * <p><b>The gate is on the BLOCK NUMBER.</b> Below H no new rule applies at all: {@link
+ * #activeAt(long)} returns false and both new rules return true as their first statement, before
+ * they decode anything. The existing chain history is therefore untouched, with the same hashes,
+ * because neither the hash formula, nor the codec, nor the existing rule set changes for it. That
+ * property is cheap precisely because the gate is on the number and not on the content, and it is
+ * the condition under which a binary built from this code can be warmed on a live node without risk.
+ *
+ * <p><b>Emergency de-arm.</b> Two controls exist and are deliberately LOCAL to the node, not
+ * on-chain: a halted chain cannot deliver a height-scheduled configuration change, so the only
+ * control that works when the chain is ALREADY STOPPED is one that lives in the node's own
+ * configuration and takes effect on restart.
+ *
+ * <ul>
+ * <li>{@value #PROPERTY_MIN_SEALS_CEILING} lowers K, and can NEVER raise it: the effective
+ * threshold is {@code min(scheduled, ceiling)}. A control that could raise the threshold would
+ * be a way to halt the chain, not a way to recover it.
+ * <li>{@value #PROPERTY_DISABLE} switches both rules off entirely on this node.
+ * </ul>
+ *
+ * <p>Both take at least a quorum of nodes to restart before block production resumes, which is
+ * exactly the right threshold for a change of this weight.
+ *
+ * <p><b>AERE OPTIUNI-URGENTA (2026-08-02): both are now COMMAND-LINE OPTIONS.</b> Until this date
+ * they existed only as system properties and environment variables, which meant the documented way
+ * back from a bad activation was to edit a service unit or a wrapper script, and the javadoc above
+ * named two command-line options that did not exist. They now do: {@code
+ * --Xaere-pq-anchor-disarm} and {@code --Xaere-pq-anchor-min-seals-max}, defined in {@code
+ * org.hyperledger.besu.cli.options.AerePqEmergencyOptions} and applied onto these same property
+ * names before anything reads them, so there is exactly ONE place that decides what is in force. The
+ * property and environment forms keep working unchanged; the command line wins over both, and which
+ * source won is logged.
+ *
+ * <p><b>AERE CONFIGURATIE-STRICTA (2026-08-06): {@link #fromSystemConfiguration()} is FAIL-CLOSED on
+ * PRESENCE.</b> Until this date every reading fault in this loader ended in a value rather than in a
+ * refusal: an unparseable step DISCARDED the whole schedule and left K at 0 with the node ARMED; an
+ * unparseable ceiling was IGNORED while the command-line banner announced it as being in force; and
+ * an {@link IllegalArgumentException} from the constructor returned {@link #never(long)}, so the node
+ * ran with the anchor completely inert. None of the three stops a chain, which is exactly what makes
+ * them dangerous: the fleet keeps producing blocks, every head matches, every graph is green, and
+ * the post-quantum property we state in public is simply not being enforced. That is the Holesky
+ * shape - one wrong configuration field, silently defaulted, nodes that started perfectly and ran
+ * for months.
+ *
+ * <p>The gate is on PRESENCE, not on value, and that is what keeps the compatibility property
+ * intact:
+ *
+ * <ul>
+ * <li><b>No {@code aere.pq.*} name set at all</b> - not as a system property, not as an
+ * environment variable - and this method returns {@link #never(long)} at its first statement.
+ * No decode, no allocation, no log, bit for bit today's behaviour. Absence is not a
+ * misconfiguration, it is the absence of a configuration, and a binary built from this code
+ * can still be warmed on a live node that has none of these names set.
+ * <li><b>At least one name present</b>, even set to the empty string, and every field is read
+ * strictly: anything unparseable, an empty value, a discarded schedule, a threshold schedule
+ * with no step at H, an activation height without an explicit chain id, or a constructor that
+ * rejects the result, is a {@link FalconSealSupport.ActivationConfigException} carrying {@link
+ * #REFUSAL_CODE}, i.e. a refusal to start. An operator who typed {@code
+ * -Daere.pq.anchorBlock=} wanted an anchor and had a shell variable go empty on them; that is
+ * a mistake, not an absence.
+ * </ul>
+ *
+ * <p>The one deliberate exception is {@value #PROPERTY_DISABLE}. It is the brake, it is the only
+ * control that works when the chain is ALREADY STOPPED, and a brake that can itself be refused is
+ * not a brake. When it resolves to true the node STARTS: the rest of the configuration is still
+ * parsed, so that a valid one keeps {@link #anchorConfigured()} true and the per-block disarm
+ * announcement keeps shouting, and an invalid one is reported at ERROR and the node starts fully
+ * inert rather than not at all.
+ *
+ * <p>Refusing at STARTUP is not the class of failure that CrowdStrike and Cloudflare are cautionary
+ * tales about. Those were fail-closed at RUNTIME, delivered to an entire fleet at once. A refusal
+ * here happens before the node has joined the quorum, is visible in {@code systemctl status} in
+ * second zero, and is repaired with one line and one restart, at a pace the operator controls. The
+ * risk that IS real is a bad shared template plus a parallel fleet restart: at quorum 5 of 7 that is
+ * not degradation, it is a dead chain. The net for it is the one already written in the runbook -
+ * restart one at a time, never in parallel - and a preflight that computes its verdict from THIS
+ * code path rather than from a second reading of the same strings.
+ *
+ * <p><b>HONEST LIMITATION, stated in code because it is the same defect class as A8.</b> The values
+ * here are read from LOCAL system properties or environment variables, exactly like {@code
+ * aere.falcon.registry} is today. They are NOT yet read from the genesis {@code config.qbft} /
+ * {@code config.transitions.qbft}, and there is NO consensus binding on them: two nodes configured
+ * with different H or different K schedules will disagree about which headers are valid. Wiring
+ * these to genesis, and refusing to start when the Falcon registry does not match the genesis {@code
+ * pqRegistryHash}, is a PRECONDITION of arming and is tracked as the fork-activation and registry
+ * work items. Until that lands, a non-default value here is a laboratory setting, not a deployment.
+ */
+public final class PqAnchorConfig {
+
+ private static final Logger LOG = LoggerFactory.getLogger(PqAnchorConfig.class);
+
+ /** System property naming the activation height H. Env: {@code AERE_PQ_ANCHOR_BLOCK}. */
+ public static final String PROPERTY_ANCHOR_BLOCK = "aere.pq.anchorBlock";
+
+ /**
+ * System property naming the staged threshold schedule, as {@code block:minSeals} pairs separated
+ * by commas, e.g. {@code 12000000:0,12007200:1,12014400:3,12021600:5}. Env: {@code
+ * AERE_PQ_ANCHOR_MINSEALS}.
+ */
+ public static final String PROPERTY_MIN_SEALS = "aere.pq.anchorMinSeals";
+
+ /** System property naming the chain id used in the D and M pre-images. Env: {@code AERE_PQ_CHAINID}. */
+ public static final String PROPERTY_CHAIN_ID = "aere.pq.chainId";
+
+ /**
+ * EMERGENCY: an upper bound on K. Lowers the effective threshold, never raises it. This is the
+ * property behind the command-line option {@code --Xaere-pq-anchor-min-seals-max}. Env: {@code
+ * AERE_PQ_ANCHOR_MIN_SEALS_MAX}.
+ */
+ public static final String PROPERTY_MIN_SEALS_CEILING = "aere.pq.anchor.minSealsCeiling";
+
+ /**
+ * EMERGENCY: switch both anchor rules off on this node. This is the property behind the
+ * command-line option {@code --Xaere-pq-anchor-disarm}. Env: {@code AERE_PQ_ANCHOR_DISABLE}.
+ */
+ public static final String PROPERTY_DISABLE = "aere.pq.anchor.disable";
+
+ /**
+ * COST: the largest number of seals a proposer of THIS node writes into a certificate. K is a
+ * FLOOR, not a cap: a proposer includes every eligible seal it happened to hear in time, so at N=7
+ * a K=3 chain carries four, five, six or seven seals in practice, not three.
+ *
+ * <p>MEASURED 2026-08-07, and this is why the property exists. A Falcon-512 seal is 666 bytes. The
+ * seal counts observed on a live seven-node run with the threshold at 4 were: 42 blocks with 4, 36
+ * with 5, 5 with 6. The rehearsal's median header of 3838 bytes is {@code (3838-525)/666 = 4.97}
+ * seals. Per node per year, at ~165248 blocks/day: one seal 40.2 GB, three 120.5 GB, five 200.9
+ * GB, seven 281.2 GB. The figure carried in our own documents until that day, 45.2 GB/year, is
+ * 1.13 seals: it had been computed for a single seal and was wrong by 4.4x.
+ *
+ * <p>Setting this to K therefore removes ~40% of the anchor's disk cost and takes nothing from the
+ * quorum margin, because the margin is decided by the THRESHOLD a verifier requires, not by how
+ * many seals a proposer volunteers above it.
+ *
+ * <p>UNSET MEANS TODAY'S BEHAVIOUR: no cap. That is deliberate. A cap is a live-chain behaviour
+ * change and must be asked for, never arrive as a default.
+ *
+ * <p>FAIL-CLOSED: a cap below the highest K the schedule ever reaches would make every proposer
+ * assemble a certificate its own fleet rejects, so the loader REFUSES to start. See {@link
+ * #withMaxSealsCarried(OptionalInt)}. Env: {@code AERE_PQ_ANCHOR_MAX_SEALS}.
+ */
+ public static final String PROPERTY_MAX_SEALS = "aere.pq.anchor.maxSeals";
+
+ /** Environment variable twin of {@link #PROPERTY_MAX_SEALS}. */
+ public static final String ENV_MAX_SEALS = "AERE_PQ_ANCHOR_MAX_SEALS";
+
+ /**
+ * COST, and the big lever: carry a certificate every N-th block instead of every block.
+ *
+ * <p>WHY IT IS ALLOWED TO BE SAFE, and this is the whole argument. Block hashes chain: block N+1
+ * commits to block N's hash. So an anchor at height A, whose vanityData binds a Falcon certificate
+ * over A-1, transitively protects EVERYTHING below A. Rewriting any block under A changes A's
+ * parent hash, which forces A to be reproduced, which needs a Falcon quorum the adversary does not
+ * have. The only thing an adversary with every classical validator key can still rewrite is the
+ * TAIL: the blocks produced since the last anchor. The property is therefore
+ *
+ * <pre>fork depth &lt;= anchor interval</pre>
+ *
+ * and it is a knob, not an accident.
+ *
+ * <p>MEASURED 2026-08-07, at K=3 capped, ~165248 blocks/day, 666 bytes a seal, per node per year:
+ * every block 120.5 GB; every 10th 12.1 GB; every 100th 1.2 GB; every 256th 0.5 GB. Against a
+ * ~523 ms block, an interval of 100 buys a hundredfold saving for a rewritable tail that grows
+ * from about half a second to about fifty-two seconds. Algorand ships the same shape at 1 in 256.
+ *
+ * <p>UNSET MEANS EVERY BLOCK, which is today's design and the strongest setting. As with the seal
+ * cap, a weakening never arrives as a default; it has to be asked for.
+ *
+ * <p>ANCHOR HEIGHTS ARE COUNTED FROM H, not from zero: {@code (n - anchorBlock) % interval == 0}.
+ * H itself is therefore always an anchor height, which matters because H is the one height the
+ * whole fleet coordinates on. Env: {@code AERE_PQ_ANCHOR_INTERVAL}.
+ */
+ public static final String PROPERTY_ANCHOR_INTERVAL = "aere.pq.anchorInterval";
+
+ /** Environment variable twin of {@link #PROPERTY_ANCHOR_INTERVAL}. */
+ public static final String ENV_ANCHOR_INTERVAL = "AERE_PQ_ANCHOR_INTERVAL";
+
+ /**
+ * System property naming the INTERVAL SCHEDULE: "h:interval,h:interval". From each height h the
+ * certificate is carried every {@code interval} blocks instead of {@link #PROPERTY_ANCHOR_INTERVAL}.
+ * D-336 (2026-09-04): a hybrid anchor is ~53 KB, so at interval 32 the chain costs ~8.35 GB per
+ * month per node; a scheduled interval lets the fleet move to 128 at a coordinated height.
+ */
+ public static final String PROPERTY_ANCHOR_INTERVAL_SCHEDULE = "aere.pq.anchorIntervalSchedule";
+
+ /** Environment variable twin of {@link #PROPERTY_ANCHOR_INTERVAL_SCHEDULE}. */
+ public static final String ENV_ANCHOR_INTERVAL_SCHEDULE = "AERE_PQ_ANCHOR_INTERVAL_SCHEDULE";
+
+ /**
+ * AERE ANCHOR V2 (2026-09-03): from this height every anchor header carries the SCHEME-TAGGED
+ * certificate (PqAnchorV2: Falcon-512 plus every extra scheme the scheme schedule names at the
+ * parent height, K seals per scheme) and vanityData is the v2 digest under "AERE-PQ-ANCHOR-2".
+ * Below it nothing changes. A v2 certificate is refused below this height and a v1 one from it,
+ * so the switch is a consensus fork: every node of the fleet must carry the same value, exactly
+ * like {@link #PROPERTY_ANCHOR_BLOCK}. Absent means never. Env: {@code AERE_PQ_ANCHOR_V2_BLOCK}.
+ */
+ public static final String PROPERTY_ANCHOR_V2_BLOCK = "aere.pq.anchorV2Block";
+
+ /** Environment variable twin of {@link #PROPERTY_ANCHOR_V2_BLOCK}. */
+ public static final String ENV_ANCHOR_V2_BLOCK = "AERE_PQ_ANCHOR_V2_BLOCK";
+
+ /** Environment variable twin of {@link #PROPERTY_ANCHOR_BLOCK}. */
+ public static final String ENV_ANCHOR_BLOCK = "AERE_PQ_ANCHOR_BLOCK";
+
+ /** Environment variable twin of {@link #PROPERTY_MIN_SEALS}. */
+ public static final String ENV_MIN_SEALS = "AERE_PQ_ANCHOR_MINSEALS";
+
+ /** Environment variable twin of {@link #PROPERTY_CHAIN_ID}. */
+ public static final String ENV_CHAIN_ID = "AERE_PQ_CHAINID";
+
+ /** Environment variable twin of {@link #PROPERTY_MIN_SEALS_CEILING}. */
+ public static final String ENV_MIN_SEALS_CEILING = "AERE_PQ_ANCHOR_MIN_SEALS_MAX";
+
+ /** Environment variable twin of {@link #PROPERTY_DISABLE}. */
+ public static final String ENV_DISABLE = "AERE_PQ_ANCHOR_DISABLE";
+
+ /**
+ * The stable, greppable code carried by every startup refusal raised while reading this
+ * configuration, in the shape of the A8 registry refusal {@code AERE-PQC-REG-MISMATCH-01}.
+ */
+ public static final String REFUSAL_CODE = "AERE-PQC-ANCHOR-CONF-01";
+
+ /**
+ * D-147: the greppable name of the guard that refuses an armed anchor whose schedule never demands
+ * a single signature. Named, and not just a message, so that a check can ask whether the guard
+ * EXISTS rather than whether some prose happens to be present.
+ */
+ public static final String REFUSAL_MIN_SEALS_FLOOR = REFUSAL_CODE + "/minSealsFloor";
+
+ /** Sentinel meaning "the anchor never activates". */
+ public static final long NEVER = Long.MAX_VALUE;
+
+ /**
+ * Every name this loader reads, property first and environment twin second. Presence of ANY of
+ * them is what switches the loader from "this node has no anchor configuration" to "this node has
+ * an anchor configuration and every field of it must be readable".
+ */
+ private static final String[][] ANCHOR_NAMES = {
+ {PROPERTY_ANCHOR_BLOCK, ENV_ANCHOR_BLOCK},
+ {PROPERTY_MIN_SEALS, ENV_MIN_SEALS},
+ {PROPERTY_CHAIN_ID, ENV_CHAIN_ID},
+ {PROPERTY_MIN_SEALS_CEILING, ENV_MIN_SEALS_CEILING},
+ {PROPERTY_MAX_SEALS, ENV_MAX_SEALS},
+ {PROPERTY_ANCHOR_INTERVAL, ENV_ANCHOR_INTERVAL},
+ {PROPERTY_ANCHOR_INTERVAL_SCHEDULE, ENV_ANCHOR_INTERVAL_SCHEDULE},
+ {PROPERTY_ANCHOR_V2_BLOCK, ENV_ANCHOR_V2_BLOCK},
+ {PROPERTY_DISABLE, ENV_DISABLE}
+ };
+
+ private static final String SOURCE_PROPERTY = "system property (BESU_OPTS)";
+
+ private final long chainId;
+ private final long anchorBlock;
+ private final NavigableMap<Long, Integer> minSealsSchedule;
+ private final OptionalInt minSealsCeiling;
+ private final boolean disabled;
+ private final OptionalInt maxSealsCarried;
+ private final OptionalInt anchorInterval;
+ private final long anchorV2Block;
+ private final NavigableMap<Long, Integer> anchorIntervalSchedule;
+
+ /**
+ * Build an explicit configuration.
+ *
+ * @param chainId the chain id used in the D and M pre-images
+ * @param anchorBlock the activation height H, or {@link #NEVER}; must be at least 1 when set,
+ * because block H needs a parent
+ * @param minSealsSchedule the staged threshold, keyed on the height each step takes effect at; may
+ * be empty, in which case K is 0 everywhere
+ * @param minSealsCeiling an emergency upper bound on K, or empty
+ * @param disabled true to switch the anchor rules off entirely
+ */
+ public PqAnchorConfig(
+ final long chainId,
+ final long anchorBlock,
+ final Map<Long, Integer> minSealsSchedule,
+ final OptionalInt minSealsCeiling,
+ final boolean disabled) {
+ this(chainId, anchorBlock, minSealsSchedule, minSealsCeiling, disabled, OptionalInt.empty());
+ }
+
+ /**
+ * The full constructor, with the proposer-side seal cap.
+ *
+ * @param chainId the chain id used in the D and M pre-images
+ * @param anchorBlock the activation height H, or {@link #NEVER}
+ * @param minSealsSchedule the staged threshold, keyed on the height each step takes effect at
+ * @param minSealsCeiling an emergency upper bound on K, or empty
+ * @param disabled true to switch the anchor rules off entirely
+ * @param maxSealsCarried the largest certificate this node's proposer writes, or empty for no cap
+ */
+ public PqAnchorConfig(
+ final long chainId,
+ final long anchorBlock,
+ final Map<Long, Integer> minSealsSchedule,
+ final OptionalInt minSealsCeiling,
+ final boolean disabled,
+ final OptionalInt maxSealsCarried) {
+ this(chainId, anchorBlock, minSealsSchedule, minSealsCeiling, disabled, maxSealsCarried, OptionalInt.empty());
+ }
+
+ /**
+ * The full constructor, with both cost controls.
+ *
+ * @param chainId the chain id used in the D and M pre-images
+ * @param anchorBlock the activation height H, or {@link #NEVER}
+ * @param minSealsSchedule the staged threshold, keyed on the height each step takes effect at
+ * @param minSealsCeiling an emergency upper bound on K, or empty
+ * @param disabled true to switch the anchor rules off entirely
+ * @param maxSealsCarried the largest certificate this node's proposer writes, or empty for no cap
+ * @param anchorInterval carry a certificate every N-th block from H, or empty for every block
+ */
+ public PqAnchorConfig(
+ final long chainId,
+ final long anchorBlock,
+ final Map<Long, Integer> minSealsSchedule,
+ final OptionalInt minSealsCeiling,
+ final boolean disabled,
+ final OptionalInt maxSealsCarried,
+ final OptionalInt anchorInterval) {
+ this(chainId, anchorBlock, minSealsSchedule, minSealsCeiling, disabled, maxSealsCarried,
+ anchorInterval, NEVER);
+ }
+
+ /**
+ * Full constructor.
+ *
+ * @param anchorV2Block the height from which anchor headers carry the scheme-tagged v2
+ * certificate and the v2 digest, or {@link #NEVER}
+ */
+ public PqAnchorConfig(
+ final long chainId,
+ final long anchorBlock,
+ final Map<Long, Integer> minSealsSchedule,
+ final OptionalInt minSealsCeiling,
+ final boolean disabled,
+ final OptionalInt maxSealsCarried,
+ final OptionalInt anchorInterval,
+ final long anchorV2Block) {
+ this(chainId, anchorBlock, minSealsSchedule, minSealsCeiling, disabled, maxSealsCarried,
+ anchorInterval, anchorV2Block, new TreeMap<>());
+ }
+
+ /**
+ * Full constructor with the interval schedule (D-336).
+ *
+ * @param anchorIntervalSchedule heights from which the interval changes; every interval must be a
+ * positive multiple of the base interval and every height must sit on the NEW grid counted
+ * from H, so that the anchors of the new regime are a subset of the old ones and the change
+ * never invents an anchor height the old regime did not have
+ */
+ private PqAnchorConfig(
+ final long chainId,
+ final long anchorBlock,
+ final Map<Long, Integer> minSealsSchedule,
+ final OptionalInt minSealsCeiling,
+ final boolean disabled,
+ final OptionalInt maxSealsCarried,
+ final OptionalInt anchorInterval,
+ final long anchorV2Block,
+ final NavigableMap<Long, Integer> anchorIntervalSchedule) {
+ this.anchorInterval = anchorInterval;
+ this.anchorV2Block = anchorV2Block;
+ this.anchorIntervalSchedule = new TreeMap<>(anchorIntervalSchedule);
+ if (!this.anchorIntervalSchedule.isEmpty()) {
+ if (anchorInterval.isEmpty()) {
+ throw new IllegalArgumentException(
+ "AERE PQ ANCHOR: " + PROPERTY_ANCHOR_INTERVAL_SCHEDULE + " is set but "
+ + PROPERTY_ANCHOR_INTERVAL + " is not: a schedule changes an interval, it cannot"
+ + " create one");
+ }
+ if (anchorBlock == NEVER) {
+ throw new IllegalArgumentException(
+ "AERE PQ ANCHOR: " + PROPERTY_ANCHOR_INTERVAL_SCHEDULE
+ + " is set but no anchor activation height is");
+ }
+ final int base = anchorInterval.getAsInt();
+ for (final Map.Entry<Long, Integer> e : this.anchorIntervalSchedule.entrySet()) {
+ final long h = e.getKey();
+ final int iv = e.getValue();
+ if (iv < 1 || iv % base != 0) {
+ throw new IllegalArgumentException(
+ "AERE PQ ANCHOR: " + PROPERTY_ANCHOR_INTERVAL_SCHEDULE + " names interval " + iv
+ + " at " + h + ", which is not a positive multiple of the base interval " + base
+ + ": the anchors of the new regime must be a subset of the old ones");
+ }
+ if (h < anchorBlock || (h - anchorBlock) % iv != 0) {
+ throw new IllegalArgumentException(
+ "AERE PQ ANCHOR: " + PROPERTY_ANCHOR_INTERVAL_SCHEDULE + " changes the interval to "
+ + iv + " at " + h + ", which is not on the new grid counted from H=" + anchorBlock
+ + " ((h - H) % " + iv + " must be 0): the first anchor of the new regime is the"
+ + " activation height itself, so every node can check it by hand");
+ }
+ }
+ }
+ if (anchorV2Block != NEVER) {
+ if (anchorV2Block < 1) {
+ throw new IllegalArgumentException(
+ "AERE PQ ANCHOR: " + PROPERTY_ANCHOR_V2_BLOCK + " must be at least 1, got " + anchorV2Block);
+ }
+ if (anchorBlock == NEVER) {
+ throw new IllegalArgumentException(
+ "AERE PQ ANCHOR: " + PROPERTY_ANCHOR_V2_BLOCK + "=" + anchorV2Block
+ + " is set but no anchor activation height is: a v2 certificate is a form of the"
+ + " anchor certificate, it cannot exist where no anchor does");
+ }
+ if (anchorV2Block < anchorBlock) {
+ throw new IllegalArgumentException(
+ "AERE PQ ANCHOR: " + PROPERTY_ANCHOR_V2_BLOCK + "=" + anchorV2Block
+ + " is below the anchor activation height " + anchorBlock
+ + "; the v2 form cannot take effect before the anchor rules do");
+ }
+ }
+ if (anchorInterval.isPresent() && anchorInterval.getAsInt() < 1) {
+ throw new IllegalArgumentException(
+ "AERE PQ ANCHOR: "
+ + PROPERTY_ANCHOR_INTERVAL
+ + " must be at least 1, got "
+ + anchorInterval.getAsInt()
+ + "; 1 means every block, which is the strongest setting, and there is nothing below it");
+ }
+ this.maxSealsCarried = maxSealsCarried;
+ if (maxSealsCarried.isPresent() && maxSealsCarried.getAsInt() < 1) {
+ throw new IllegalArgumentException(
+ "AERE PQ ANCHOR: "
+ + PROPERTY_MAX_SEALS
+ + " must be at least 1, got "
+ + maxSealsCarried.getAsInt()
+ + "; a cap of 0 would make every proposer write an empty certificate");
+ }
+ if (anchorBlock != NEVER && anchorBlock < 1) {
+ throw new IllegalArgumentException(
+ "AERE PQ ANCHOR: pqAnchorBlock must be at least 1 (block H needs a parent), got "
+ + anchorBlock);
+ }
+ final NavigableMap<Long, Integer> schedule = new TreeMap<>();
+ for (final Map.Entry<Long, Integer> step : minSealsSchedule.entrySet()) {
+ final Long at = step.getKey();
+ final Integer k = step.getValue();
+ if (at == null || k == null) {
+ throw new IllegalArgumentException("AERE PQ ANCHOR: null entry in pqAnchorMinSeals");
+ }
+ if (k < 0) {
+ throw new IllegalArgumentException(
+ "AERE PQ ANCHOR: pqAnchorMinSeals step at " + at + " has a negative threshold " + k);
+ }
+ if (anchorBlock != NEVER && at < anchorBlock) {
+ throw new IllegalArgumentException(
+ "AERE PQ ANCHOR: pqAnchorMinSeals step at "
+ + at
+ + " is below pqAnchorBlock "
+ + anchorBlock
+ + "; a threshold cannot take effect before the rules do");
+ }
+ schedule.put(at, k);
+ }
+ if (minSealsCeiling.isPresent() && minSealsCeiling.getAsInt() < 0) {
+ throw new IllegalArgumentException(
+ "AERE PQ ANCHOR: emergency min-seals ceiling must not be negative");
+ }
+ this.chainId = chainId;
+ this.anchorBlock = anchorBlock;
+ this.minSealsSchedule = Collections.unmodifiableNavigableMap(schedule);
+ this.minSealsCeiling = minSealsCeiling;
+ this.disabled = disabled;
+ }
+
+ /**
+ * The configuration that behaves exactly like today: the anchor never activates, so both new rules
+ * are inert at every height.
+ *
+ * @param chainId the chain id (unused while inactive, carried for diagnostics)
+ * @return an inactive configuration
+ */
+ public static PqAnchorConfig never(final long chainId) {
+ return new PqAnchorConfig(chainId, NEVER, Collections.emptyMap(), OptionalInt.empty(), false);
+ }
+
+ // -----------------------------------------------------------------------------------------------
+ // Reading the names. ONE seam, used by both controls of the proof: a recording reader shows that
+ // the unconfigured path touches nothing, and a reader whose presence probe always answers "absent"
+ // is the negative control that makes every refusal below disappear.
+ // -----------------------------------------------------------------------------------------------
+
+ /** How this class reaches system properties and environment variables. */
+ interface NameReader {
+
+ /**
+ * The raw system property, or null when the name is not set.
+ *
+ * @param name the system property name
+ * @return the value as set, possibly empty, or null when absent
+ */
+ String property(String name);
+
+ /**
+ * The raw environment variable, or null when the name is not set.
+ *
+ * @param name the environment variable name
+ * @return the value as set, possibly empty, or null when absent
+ */
+ String environment(String name);
+ }
+
+ private static final NameReader REAL_NAMES =
+ new NameReader() {
+ @Override
+ public String property(final String name) {
+ return System.getProperty(name);
+ }
+
+ @Override
+ public String environment(final String name) {
+ return System.getenv(name);
+ }
+ };
+
+ private static volatile NameReader names = REAL_NAMES;
+
+ /**
+ * Replace the reader, for the positive and negative controls of the configuration proof.
+ *
+ * @param replacement the reader to use, or null to restore the real one
+ */
+ static void useNameReaderForTesting(final NameReader replacement) {
+ names = replacement == null ? REAL_NAMES : replacement;
+ }
+
+ /**
+ * The real reader, so a recording test reader can delegate to it instead of re-implementing it.
+ *
+ * @return the reader that reads actual system properties and environment variables
+ */
+ static NameReader realNameReader() {
+ return REAL_NAMES;
+ }
+
+ /**
+ * One name as this loader saw it.
+ *
+ * @param property the system property name
+ * @param environment the environment variable name
+ * @param present whether the name was set at all, INCLUDING being set to the empty string
+ * @param source human-readable origin, for the refusal message
+ * @param raw the trimmed value, possibly empty, or null when absent
+ */
+ private record Read(
+ String property, String environment, boolean present, String source, String raw) {
+
+ boolean hasValue() {
+ return present && !raw.isEmpty();
+ }
+ }
+
+ private static Read read(final String property, final String environment) {
+ final NameReader reader = names;
+ final String fromProperty = reader.property(property);
+ if (fromProperty != null) {
+ return new Read(property, environment, true, SOURCE_PROPERTY, fromProperty.trim());
+ }
+ final String fromEnvironment = reader.environment(environment);
+ if (fromEnvironment != null) {
+ return new Read(
+ property,
+ environment,
+ true,
+ "environment variable " + environment,
+ fromEnvironment.trim());
+ }
+ return new Read(property, environment, false, null, null);
+ }
+
+ private static boolean anyAnchorNamePresent() {
+ for (final String[] pair : ANCHOR_NAMES) {
+ if (read(pair[0], pair[1]).present()) {
+ return true;
+ }
+ }
+ return false;
+ }
+
+ // -----------------------------------------------------------------------------------------------
+ // The loader.
+ // -----------------------------------------------------------------------------------------------
+
+ /**
+ * Read the configuration from system properties, falling back to environment variables, and apply
+ * the emergency overrides.
+ *
+ * <p>A node with NONE of the {@code aere.pq.*} names set gets {@link #never(long)} at the first
+ * statement, i.e. exactly today's behaviour with no decode, no allocation and no log. A node with
+ * at least one of them set is read strictly and REFUSES TO START on any fault, except through the
+ * {@value #PROPERTY_DISABLE} brake. See the class javadoc for why the gate is on presence.
+ *
+ * @return the configuration this node will run with
+ * @throws FalconSealSupport.ActivationConfigException when an anchor name is present and the
+ * configuration cannot be read exactly as written
+ */
+ public static PqAnchorConfig fromSystemConfiguration() {
+ if (!anyAnchorNamePresent()) {
+ return never(0L);
+ }
+
+ final Read block = read(PROPERTY_ANCHOR_BLOCK, ENV_ANCHOR_BLOCK);
+ final Read seals = read(PROPERTY_MIN_SEALS, ENV_MIN_SEALS);
+ final Read chain = read(PROPERTY_CHAIN_ID, ENV_CHAIN_ID);
+ final Read ceiling = read(PROPERTY_MIN_SEALS_CEILING, ENV_MIN_SEALS_CEILING);
+ final Read disable = read(PROPERTY_DISABLE, ENV_DISABLE);
+
+ final boolean disabled = readDisable(disable);
+
+ if (disabled) {
+ // THE BRAKE IS ABSOLUTE. The whole reason this control is local to the node is that it has to
+ // work when the chain is already stopped; a brake that can refuse to engage is not a brake.
+ // The rest is still parsed, because a configuration that reads cleanly keeps
+ // anchorConfigured() true and therefore keeps the per-block disarm announcement shouting.
+ try {
+ final PqAnchorConfig braked = strict(block, seals, chain, ceiling, true);
+ if (braked.anchorConfigured()) {
+ LOG.warn(
+ "AERE PQ ANCHOR: DISABLED by emergency override {} even though {}={} is configured. "
+ + "Both anchor rules are inert on this node.",
+ PROPERTY_DISABLE,
+ PROPERTY_ANCHOR_BLOCK,
+ braked.anchorBlock);
+ }
+ return braked;
+ } catch (final RuntimeException e) {
+ LOG.error(
+ "AERE PQ ANCHOR: the emergency disarm {} is in force, so this node STARTS, but the rest "
+ + "of the anchor configuration cannot be read and is therefore NOT carried: {}. The "
+ + "node runs fully inert and the per-block disarm announcement is LOST, because "
+ + "there is no readable activation height to announce. Fix the configuration before "
+ + "removing the disarm.",
+ PROPERTY_DISABLE,
+ e.getMessage());
+ return never(0L);
+ }
+ }
+
+ final PqAnchorConfig bare = strict(block, seals, chain, ceiling, false);
+ final PqAnchorConfig config =
+ bare.withMaxSealsCarried(readMaxSeals())
+ .withAnchorInterval(readAnchorInterval())
+ .withAnchorIntervalSchedule(readAnchorIntervalSchedule())
+ .withAnchorV2Block(readAnchorV2Block());
+ requireMinSealsFloorOrRefuse(config);
+ if (config.anchorInterval().isPresent() && config.everActive()) {
+ final int iv = config.anchorInterval().getAsInt();
+ LOG.warn(
+ "AERE PQ ANCHOR: certificate carried every {} block(s) from H={}, not every block. The "
+ + "hash chain makes each anchor protect everything BELOW it, so what stays rewritable "
+ + "by an adversary holding every classical validator key is the TAIL since the last "
+ + "anchor: fork depth <= {} blocks. This is a DELIBERATE weakening bought for disk: "
+ + "at K=3 capped it is about {} GB per node per year instead of about 120.",
+ iv,
+ config.anchorBlock,
+ iv,
+ String.format("%.1f", 120.5 / iv));
+ }
+ if (!config.anchorIntervalSchedule().isEmpty() && config.everActive()) {
+ LOG.warn(
+ "AERE PQ ANCHOR: interval SCHEDULE in force - {} (height:interval). From each height the"
+ + " certificate is carried every that-many blocks; the anchors of every later regime are"
+ + " a subset of the earlier ones (D-336, disk).",
+ config.anchorIntervalSchedule());
+ }
+ if (config.maxSealsCarried().isPresent() && config.everActive()) {
+ LOG.warn(
+ "AERE PQ ANCHOR: proposer-side seal CAP in force - this node writes at most {} seal(s) "
+ + "per certificate, against a highest scheduled threshold of K={}. This lowers the "
+ + "header cost and takes NOTHING from the quorum margin, which is decided by the "
+ + "threshold a verifier demands, not by how many seals a proposer volunteers above "
+ + "it. Measured 2026-08-07: uncapped, a K=3 chain at N=7 carries about five seals, "
+ + "which is 200.9 GB per node per year; capped at K it is 120.5 GB.",
+ config.maxSealsCarried().getAsInt(),
+ config.highestEffectiveMinSeals());
+ }
+ if (config.everActive()) {
+ LOG.warn(
+ "AERE PQ ANCHOR: ARMED from LOCAL configuration - pqAnchorBlock={}, chainId={}, "
+ + "minSeals schedule={}, emergency ceiling={}. These values are NOT bound to genesis "
+ + "and NOT bound to consensus: two nodes with different values disagree about which "
+ + "headers are valid. Bind them to genesis before any deployment.",
+ config.anchorBlock,
+ config.chainId,
+ config.minSealsSchedule,
+ config.minSealsCeiling.isPresent() ? config.minSealsCeiling.getAsInt() : "none");
+ }
+ return config;
+ }
+
+ /**
+ * Every field read exactly as written, or a refusal. Nothing here falls back to a default: a
+ * default that silently replaces a value the operator typed is the defect this method exists to
+ * remove.
+ */
+ private static PqAnchorConfig strict(
+ final Read block,
+ final Read seals,
+ final Read chain,
+ final Read ceiling,
+ final boolean disabled) {
+
+ final OptionalInt ceilingValue =
+ ceiling.present()
+ ? OptionalInt.of(
+ readCeiling(ceiling))
+ : OptionalInt.empty();
+
+ final long chainId = chain.present() ? readChainId(chain) : 0L;
+
+ if (!block.present()) {
+ if (seals.present()) {
+ throw refuse(
+ seals,
+ FalconSealSupport.ActivationConfigException.Kind.UNSAFE,
+ "a threshold schedule is configured but "
+ + PROPERTY_ANCHOR_BLOCK
+ + " is not set anywhere, so the schedule can never apply and the anchor is dead "
+ + "while looking configured",
+ "either set "
+ + PROPERTY_ANCHOR_BLOCK
+ + " as well, or remove "
+ + PROPERTY_MIN_SEALS
+ + " entirely");
+ }
+ return new PqAnchorConfig(
+ chainId, NEVER, Collections.emptyMap(), ceilingValue, disabled);
+ }
+
+ final long anchorBlock = readAnchorBlock(block);
+
+ if (!chain.present()) {
+ // The Holesky field, by name. There, depositContractAddress was absent on three clients, the
+ // default zero took its place, every node started, and the chain lost finality for two weeks
+ // at the height where the value finally mattered. An absent field must not be indistinguishable
+ // from a zero field, so this one is required and explicit, exactly as go-ethereum made the
+ // deposit contract address required per network afterwards.
+ throw refuse(
+ chain,
+ FalconSealSupport.ActivationConfigException.Kind.UNSAFE,
+ PROPERTY_ANCHOR_BLOCK
+ + "="
+ + anchorBlock
+ + " is set but "
+ + PROPERTY_CHAIN_ID
+ + " is not set anywhere; the silent default 0 would enter the D and M pre-images and "
+ + "would remove domain separation without showing anywhere",
+ "an explicit chain id, for example " + PROPERTY_CHAIN_ID + "=2800");
+ }
+ if (chainId < 1) {
+ throw refuse(
+ chain,
+ FalconSealSupport.ActivationConfigException.Kind.UNSAFE,
+ "chain id " + chainId + "; zero and negative values separate no domain at all",
+ "an explicit chain id >= 1, for example " + PROPERTY_CHAIN_ID + "=2800");
+ }
+
+ if (!seals.hasValue()) {
+ throw refuse(
+ seals,
+ FalconSealSupport.ActivationConfigException.Kind.UNSAFE,
+ PROPERTY_ANCHOR_BLOCK
+ + "="
+ + anchorBlock
+ + " is set but the threshold schedule is missing or empty, so K would be 0 at every "
+ + "height and an ARMED node would accept empty certificates",
+ scheduleExpectation(anchorBlock));
+ }
+
+ final NavigableMap<Long, Integer> schedule = readSchedule(seals, anchorBlock);
+ if (schedule.floorEntry(anchorBlock) == null) {
+ throw refuse(
+ seals,
+ FalconSealSupport.ActivationConfigException.Kind.UNSAFE,
+ "the schedule has no step at the activation height "
+ + anchorBlock
+ + ", so K stays 0 from activation until the first step, and an ARMED node with K=0 "
+ + "accepts an empty certificate",
+ scheduleExpectation(anchorBlock));
+ }
+
+ try {
+ return new PqAnchorConfig(chainId, anchorBlock, schedule, ceilingValue, disabled);
+ } catch (final IllegalArgumentException e) {
+ throw refuse(
+ block,
+ FalconSealSupport.ActivationConfigException.Kind.UNSAFE,
+ "the configuration reads but is not valid: " + e.getMessage(),
+ scheduleExpectation(anchorBlock));
+ }
+ }
+
+ private static String scheduleExpectation(final long anchorBlock) {
+ return "block:threshold,block:threshold - every block >= "
+ + PROPERTY_ANCHOR_BLOCK
+ + "="
+ + anchorBlock
+ + ", whole threshold >= 0, and a step exactly at "
+ + anchorBlock;
+ }
+
+ /**
+ * Read the proposer-side seal cap. Absent means no cap, which is exactly today's behaviour; an
+ * unreadable value is a refusal, never a silent fallback to "no cap", because a cap that was asked
+ * for and quietly dropped costs disk nobody is watching.
+ */
+ private static OptionalInt readMaxSeals() {
+ final Read cap = read(PROPERTY_MAX_SEALS, ENV_MAX_SEALS);
+ if (!cap.hasValue()) {
+ return OptionalInt.empty();
+ }
+ try {
+ return OptionalInt.of(Integer.parseInt(cap.raw()));
+ } catch (final NumberFormatException e) {
+ throw new IllegalArgumentException(
+ REFUSAL_CODE
+ + ": "
+ + PROPERTY_MAX_SEALS
+ + " is set to '"
+ + cap.raw()
+ + "' from "
+ + cap.source()
+ + ", which is not a whole number. It is NOT ignored: a cap asked for and silently "
+ + "dropped costs disk nobody is watching.");
+ }
+ }
+
+ /**
+ * D-147, THE MIN-SEALS FLOOR. A schedule whose effective K is ZERO at every height leaves the
+ * anchor ARMED as a structure and completely toothless, for ever.
+ *
+ * <p>WHAT THE CODE ALREADY GUARDED, and why that was not enough. The loader already refuses a
+ * MISSING schedule, in its own words: {@code "the threshold schedule is missing or empty, so K
+ * would be 0 at every height and an ARMED node would accept empty certificates"}. The author knew
+ * exactly what the danger was. But the guard only fired on an ABSENT schedule. A schedule that is
+ * PRESENT and of the shape {@code <H>:0} reaches the same end state and went through unseen.
+ *
+ * <p>WHY THIS IS NOT THEORETICAL: it is the very shape our activation plan recommends, one that
+ * STARTS at K=0 as a warm-up window and rises to 3 later. If the second half of the line is lost,
+ * to a truncated environment variable or a misplaced quote, what is left is {@code <H>:0}. The
+ * nodes start, every tool comes out green because each of them measures what was ASKED FOR and
+ * the ask is valid, and the threshold stays zero for ever. Not even ancora-prag-efectiv.sh
+ * catches this: it compares what came out against what was asked for, and here both are zero.
+ *
+ * <p>The warm-up window stays perfectly legal: this looks at the HIGHEST K in the whole schedule,
+ * after the emergency ceiling, so {@code H:0,H+165000:3} passes and {@code H:0} on its own does
+ * not.
+ *
+ * <p>THE LIMIT, written down because it is real: the check sits on the LOADING path, not in the
+ * constructor. A test that builds an all-zero-schedule object directly is not stopped. The real
+ * danger is an operator configuration in BESU_OPTS, and that is where the guard is placed.
+ */
+ private static void requireMinSealsFloorOrRefuse(final PqAnchorConfig config) {
+ if (!config.everActive() || config.disabled) {
+ return;
+ }
+ if (config.highestEffectiveMinSeals() >= 1) {
+ return;
+ }
+ throw new IllegalArgumentException(
+ REFUSAL_MIN_SEALS_FLOOR
+ + ": "
+ + PROPERTY_ANCHOR_BLOCK
+ + "="
+ + config.anchorBlock
+ + " is armed, but the highest threshold in the WHOLE schedule "
+ + PROPERTY_MIN_SEALS
+ + "="
+ + config.minSealsSchedule
+ + (config.minSealsCeiling.isPresent()
+ ? " (after the emergency ceiling " + config.minSealsCeiling.getAsInt() + ")"
+ : "")
+ + " is ZERO. A node started like this has the anchor armed and NO signature requirement"
+ + " at all, for ever, and every tool comes out green because it measures what was asked"
+ + " for. A warm-up window with K=0 is legal, but the schedule has to rise somewhere to"
+ + " at least 1: for example "
+ + config.anchorBlock
+ + ":0,"
+ + (config.anchorBlock + 165000L)
+ + ":3");
+ }
+
+ /**
+ * Read the anchor interval. Absent means every block, the strongest setting; an unreadable value
+ * is a refusal, never a silent fallback, because a weakening asked for and quietly dropped and a
+ * weakening quietly APPLIED are both states an operator must never be left guessing between.
+ */
+ /**
+ * Read the v2 activation height. Absent means never; an unreadable value is a refusal, because
+ * this height is a consensus fork and a node guessing it differently from its peers rejects
+ * every anchor header its peers accept, or the other way round.
+ */
+ private static long readAnchorV2Block() {
+ final Read v2 = read(PROPERTY_ANCHOR_V2_BLOCK, ENV_ANCHOR_V2_BLOCK);
+ if (!v2.hasValue()) {
+ return NEVER;
+ }
+ try {
+ return Long.parseLong(v2.raw().trim());
+ } catch (final NumberFormatException e) {
+ throw new IllegalArgumentException(
+ REFUSAL_CODE
+ + ": "
+ + PROPERTY_ANCHOR_V2_BLOCK
+ + " is set to '"
+ + v2.raw()
+ + "' from "
+ + v2.source()
+ + ", which is not a whole number. It is NOT ignored: this height decides which form of"
+ + " the anchor certificate is valid, and a node guessing it differently from its peers"
+ + " parts from the chain at the first anchor.");
+ }
+ }
+
+ private static NavigableMap<Long, Integer> readAnchorIntervalSchedule() {
+ final Read sc = read(PROPERTY_ANCHOR_INTERVAL_SCHEDULE, ENV_ANCHOR_INTERVAL_SCHEDULE);
+ final NavigableMap<Long, Integer> out = new TreeMap<>();
+ if (!sc.hasValue()) {
+ return out;
+ }
+ for (final String part : Splitter.on(',').split(sc.raw())) {
+ final String p = part.trim();
+ if (p.isEmpty()) {
+ continue;
+ }
+ final int colon = p.indexOf(':');
+ try {
+ if (colon < 1) {
+ throw new NumberFormatException(p);
+ }
+ out.put(Long.parseLong(p.substring(0, colon).trim()), Integer.parseInt(p.substring(colon + 1).trim()));
+ } catch (final NumberFormatException e) {
+ throw new IllegalArgumentException(
+ REFUSAL_CODE
+ + ": "
+ + PROPERTY_ANCHOR_INTERVAL_SCHEDULE
+ + " is set to '"
+ + sc.raw()
+ + "' from "
+ + sc.source()
+ + ", which is not a list of height:interval. It is NOT ignored: two nodes that read"
+ + " it differently disagree about which headers carry a certificate.");
+ }
+ }
+ return out;
+ }
+
+ private static OptionalInt readAnchorInterval() {
+ final Read iv = read(PROPERTY_ANCHOR_INTERVAL, ENV_ANCHOR_INTERVAL);
+ if (!iv.hasValue()) {
+ return OptionalInt.empty();
+ }
+ try {
+ return OptionalInt.of(Integer.parseInt(iv.raw()));
+ } catch (final NumberFormatException e) {
+ throw new IllegalArgumentException(
+ REFUSAL_CODE
+ + ": "
+ + PROPERTY_ANCHOR_INTERVAL
+ + " is set to '"
+ + iv.raw()
+ + "' from "
+ + iv.source()
+ + ", which is not a whole number. It is NOT ignored: this value decides how much of "
+ + "the chain tip stays rewritable, and a node guessing it differently from its peers "
+ + "disagrees about which headers carry a certificate at all.");
+ }
+ }
+
+ private static boolean readDisable(final Read disable) {
+ if (!disable.present()) {
+ return false;
+ }
+ final String value = disable.raw().toLowerCase(Locale.ROOT);
+ switch (value) {
+ case "true":
+ case "1":
+ case "yes":
+ case "on":
+ return true;
+ case "false":
+ case "0":
+ case "no":
+ case "off":
+ return false;
+ default:
+ // Boolean.parseBoolean turns "1", "yes" and "on" into FALSE without a word. That is a brake
+ // pedal that reports nothing when it does not engage, on the one control an operator reaches
+ // for while the chain is down.
+ throw refuse(
+ disable,
+ FalconSealSupport.ActivationConfigException.Kind.SYNTAX,
+ "the value cannot be read as true or false",
+ "true, false, 1, 0, yes, no, on or off");
+ }
+ }
+
+ private static long readAnchorBlock(final Read block) {
+ if (!block.hasValue()) {
+ throw refuse(
+ block,
+ FalconSealSupport.ActivationConfigException.Kind.SYNTAX,
+ "the name is set but the value is empty; that is what an unexpanded shell variable in "
+ + "BESU_OPTS looks like, and until today this started the node with the anchor fully "
+ + "inert, without a single line in the log",
+ "the activation height H as a decimal number, for example 10141734");
+ }
+ final long value = readLong(block);
+ if (value < 1) {
+ throw refuse(
+ block,
+ FalconSealSupport.ActivationConfigException.Kind.UNSAFE,
+ "activation height " + value + " leaves no room for a parent",
+ "an activation height H >= 1, and in practice a height ahead of the chain head");
+ }
+ return value;
+ }
+
+ private static long readChainId(final Read chain) {
+ if (!chain.hasValue()) {
+ throw refuse(
+ chain,
+ FalconSealSupport.ActivationConfigException.Kind.SYNTAX,
+ "the name is set but the value is empty",
+ "a chain id as a decimal number, for example 2800");
+ }
+ return readLong(chain);
+ }
+
+ private static int readCeiling(final Read ceiling) {
+ if (!ceiling.hasValue()) {
+ throw refuse(
+ ceiling,
+ FalconSealSupport.ActivationConfigException.Kind.SYNTAX,
+ "the name is set but the value is empty",
+ "a whole ceiling >= 0; 0 disarms the threshold completely");
+ }
+ final int value;
+ try {
+ value = Integer.parseInt(ceiling.raw());
+ } catch (final NumberFormatException e) {
+ // Until today this was IGNORED while AerePqEmergencyOptions announced "SEAL THRESHOLD CAPPED"
+ // anyway, so the operator read the banner as proof that the brake had engaged when it had not.
+ throw refuse(
+ ceiling,
+ FalconSealSupport.ActivationConfigException.Kind.SYNTAX,
+ "the value cannot be read as a whole number, and an emergency ceiling silently ignored "
+ + "is worse than no ceiling at all: the startup banner announces it as being in "
+ + "force anyway",
+ "a whole ceiling >= 0; 0 disarms the threshold completely");
+ }
+ if (value < 0) {
+ throw refuse(
+ ceiling,
+ FalconSealSupport.ActivationConfigException.Kind.UNSAFE,
+ "negative ceiling; until today this silently disarmed the WHOLE anchor, while the banner "
+ + "announced no more than a capped threshold",
+ "a whole ceiling >= 0; 0 disarms the threshold completely");
+ }
+ return value;
+ }
+
+ private static long readLong(final Read where) {
+ try {
+ return Long.parseLong(where.raw());
+ } catch (final NumberFormatException e) {
+ throw refuse(
+ where,
+ FalconSealSupport.ActivationConfigException.Kind.SYNTAX,
+ "the value cannot be read as a decimal number",
+ "a decimal number, no separators, no 0x prefix and no suffixes");
+ }
+ }
+
+ private static NavigableMap<Long, Integer> readSchedule(
+ final Read seals, final long anchorBlock) {
+ final NavigableMap<Long, Integer> schedule = new TreeMap<>();
+ for (final String step : Splitter.on(',').split(seals.raw())) {
+ final String trimmed = step.trim();
+ if (trimmed.isEmpty()) {
+ throw refuse(
+ seals,
+ FalconSealSupport.ActivationConfigException.Kind.SYNTAX,
+ "an empty step, that is one comma too many or two commas side by side",
+ scheduleExpectation(anchorBlock));
+ }
+ final int colon = trimmed.indexOf(':');
+ if (colon < 0) {
+ throw refuse(
+ seals,
+ FalconSealSupport.ActivationConfigException.Kind.SYNTAX,
+ "step \"" + trimmed + "\" has no ':'",
+ scheduleExpectation(anchorBlock));
+ }
+ if (colon == 0) {
+ throw refuse(
+ seals,
+ FalconSealSupport.ActivationConfigException.Kind.SYNTAX,
+ "step \"" + trimmed + "\" has no block before the ':'",
+ scheduleExpectation(anchorBlock));
+ }
+ if (colon == trimmed.length() - 1) {
+ throw refuse(
+ seals,
+ FalconSealSupport.ActivationConfigException.Kind.SYNTAX,
+ "step \"" + trimmed + "\" has no threshold after the ':'",
+ scheduleExpectation(anchorBlock));
+ }
+ final long at;
+ final int k;
+ try {
+ at = Long.parseLong(trimmed.substring(0, colon).trim());
+ k = Integer.parseInt(trimmed.substring(colon + 1).trim());
+ } catch (final NumberFormatException e) {
+ throw refuse(
+ seals,
+ FalconSealSupport.ActivationConfigException.Kind.SYNTAX,
+ "step \"" + trimmed + "\" carries a number that cannot be read",
+ scheduleExpectation(anchorBlock));
+ }
+ if (k < 0) {
+ throw refuse(
+ seals,
+ FalconSealSupport.ActivationConfigException.Kind.UNSAFE,
+ "step \"" + trimmed + "\" asks for a negative threshold",
+ scheduleExpectation(anchorBlock));
+ }
+ if (at < anchorBlock) {
+ throw refuse(
+ seals,
+ FalconSealSupport.ActivationConfigException.Kind.UNSAFE,
+ "step \""
+ + trimmed
+ + "\" is below the activation height "
+ + anchorBlock
+ + ", so a threshold would take effect before the rules do",
+ scheduleExpectation(anchorBlock));
+ }
+ final Integer previous = schedule.put(at, k);
+ if (previous != null && previous != k) {
+ throw refuse(
+ seals,
+ FalconSealSupport.ActivationConfigException.Kind.UNSAFE,
+ "height "
+ + at
+ + " appears twice with different thresholds, "
+ + previous
+ + " and "
+ + k
+ + ", so the threshold at that height depends on the order within the string",
+ scheduleExpectation(anchorBlock));
+ }
+ }
+ return schedule;
+ }
+
+ /**
+ * The one shape a refusal takes: the field, where it was read from, what was actually read, what
+ * is wrong with it, what was expected, and the two operating instructions that matter more than
+ * any of it - repair this node, and never restart the fleet in parallel.
+ */
+ private static FalconSealSupport.ActivationConfigException refuse(
+ final Read where,
+ final FalconSealSupport.ActivationConfigException.Kind kind,
+ final String problem,
+ final String expected) {
+ final StringBuilder message = new StringBuilder(768);
+ message
+ .append("AERE PQ ANCHOR: REFUSING TO START\n")
+ .append(" FIELD ")
+ .append(where.property())
+ .append('\n')
+ .append(" SOURCE ")
+ .append(where.present() ? where.source() : "not set anywhere")
+ .append('\n')
+ .append(" READ ")
+ .append(where.present() ? "\"" + where.raw() + "\"" : "(nothing)")
+ .append('\n')
+ .append(" PROBLEM ")
+ .append(problem)
+ .append('\n')
+ .append(" EXPECTED ")
+ .append(expected)
+ .append('\n')
+ .append(" FIX correct BESU_OPTS on THIS node and restart ONLY this node\n")
+ .append(" WARNING if the same value is on every node: restart one at a time,\n")
+ .append(" never in parallel. The chain stops as soon as more than f\n")
+ .append(" validators are down at once, whatever the set size is today.\n")
+ .append(" EMERGENCY ")
+ .append(PROPERTY_DISABLE)
+ .append("=true starts the node with the anchor off and shouts at every block");
+ return new FalconSealSupport.ActivationConfigException(kind, REFUSAL_CODE, message.toString());
+ }
+
+ /**
+ * Whether the anchor rules apply to a block at this height.
+ *
+ * @param blockNumber the height being validated
+ * @return true iff the anchor is configured, not emergency-disabled, and the height is at or above
+ * H
+ */
+ public boolean activeAt(final long blockNumber) {
+ return !disabled && anchorBlock != NEVER && blockNumber >= anchorBlock;
+ }
+
+ /**
+ * Whether the anchor can ever apply on this node.
+ *
+ * @return true iff configured and not emergency-disabled
+ */
+ public boolean everActive() {
+ return !disabled && anchorBlock != NEVER;
+ }
+
+ /**
+ * The minimum number of Falcon seals a certificate must carry at this height, after the emergency
+ * ceiling is applied.
+ *
+ * @param blockNumber the height being validated
+ * @return the effective threshold K, never negative
+ */
+ public int minSealsAt(final long blockNumber) {
+ final int scheduled = scheduledMinSealsAt(blockNumber);
+ return minSealsCeiling.isPresent() ? Math.min(scheduled, minSealsCeiling.getAsInt()) : scheduled;
+ }
+
+ /**
+ * The threshold the SCHEDULE asks for at this height, before the emergency ceiling is applied.
+ *
+ * <p>AERE OPTIUNI-URGENTA (2026-08-02). This exists so the per-block emergency announcement can
+ * state both numbers from the SAME object the rules read, rather than re-deriving one of them from
+ * configuration a second time. A message that re-computes its own version of what the enforcement
+ * did can drift away from it, and a shout that says something other than what is actually in force
+ * is worse than no shout.
+ *
+ * @param blockNumber the height being validated
+ * @return the scheduled threshold K, never negative, ignoring any emergency ceiling
+ */
+ public int scheduledMinSealsAt(final long blockNumber) {
+ final Map.Entry<Long, Integer> step = minSealsSchedule.floorEntry(blockNumber);
+ return step == null ? 0 : step.getValue();
+ }
+
+ /**
+ * Whether the emergency ceiling is ACTUALLY lowering the threshold at this height, as opposed to
+ * merely being set.
+ *
+ * <p>A ceiling of 5 over a scheduled threshold of 1 changes nothing, and a node announcing "the
+ * threshold is lowered" in that state would be shouting about a control that is carrying no
+ * weight. Operators stop reading a log that cries wolf, so the announcement is tied to the ceiling
+ * having an effect, not to it being present.
+ *
+ * @param blockNumber the height being validated
+ * @return true iff the anchor is active here and the ceiling is strictly below the scheduled
+ * threshold
+ */
+ public boolean emergencyCeilingLowersAt(final long blockNumber) {
+ return activeAt(blockNumber)
+ && minSealsCeiling.isPresent()
+ && minSealsCeiling.getAsInt() < scheduledMinSealsAt(blockNumber);
+ }
+
+ /**
+ * The emergency ceiling on K, if one is configured.
+ *
+ * @return the ceiling, or empty
+ */
+ public OptionalInt minSealsCeiling() {
+ return minSealsCeiling;
+ }
+
+ /**
+ * The largest certificate this node's proposer writes, or empty for no cap (today's behaviour).
+ *
+ * @return the proposer-side seal cap
+ */
+ public OptionalInt maxSealsCarried() {
+ return maxSealsCarried;
+ }
+
+ /**
+ * The highest EFFECTIVE threshold this configuration ever demands, that is the largest {@code K}
+ * across every step of the schedule after the emergency ceiling has been applied. This is the one
+ * number a proposer-side cap must never fall below.
+ *
+ * @return the highest effective K, or 0 if the schedule is empty
+ */
+ public int highestEffectiveMinSeals() {
+ int highest = 0;
+ for (final Integer k : minSealsSchedule.values()) {
+ final int effective = minSealsCeiling.isPresent() ? Math.min(k, minSealsCeiling.getAsInt()) : k;
+ highest = Math.max(highest, effective);
+ }
+ return highest;
+ }
+
+ /**
+ * Return a copy carrying a proposer-side seal cap, refusing any cap that cannot work.
+ *
+ * <p>THE REFUSAL IS THE POINT. A cap below {@link #highestEffectiveMinSeals()} makes this node's
+ * proposer assemble certificates its own fleet must reject, at every height from the step that
+ * raises K past the cap. The chain would not diverge and would not corrupt: it would simply stop
+ * accepting anything this node proposes, which at N=7 costs a seventh of the proposers and, if the
+ * same cap is deployed fleet-wide, every one of them. That failure is silent in every existing
+ * tool, because each of them measures what was ASKED and the ask is internally consistent. So it
+ * is refused here, at startup, where a refusal is cheap.
+ *
+ * @param cap the cap to carry, or empty for none
+ * @return a copy of this configuration carrying the cap
+ * @throws IllegalArgumentException if the cap is below the highest effective threshold
+ */
+ public PqAnchorConfig withMaxSealsCarried(final OptionalInt cap) {
+ if (cap.isPresent()) {
+ final int highest = highestEffectiveMinSeals();
+ if (cap.getAsInt() < highest) {
+ throw new IllegalArgumentException(
+ REFUSAL_CODE
+ + ": "
+ + PROPERTY_MAX_SEALS
+ + "="
+ + cap.getAsInt()
+ + " is below the highest threshold this schedule ever demands, K="
+ + highest
+ + ". A proposer capped below K writes certificates its own fleet rejects, and every "
+ + "existing check stays GREEN while it happens, because each one measures what was "
+ + "asked. Raise the cap to at least "
+ + highest
+ + ", or lower the schedule.");
+ }
+ }
+ // CAREFUL: the interval is carried across too. A copy method that drops a field along the way
+ // is exactly how a disarm or an interval would vanish silently when the other control is set.
+ return new PqAnchorConfig(
+ chainId, anchorBlock, minSealsSchedule, minSealsCeiling, disabled, cap, anchorInterval,
+ anchorV2Block);
+ }
+
+ /**
+ * How often a certificate is carried, counted from H. Empty means every block, which is the
+ * strongest setting and today's design.
+ *
+ * @return the anchor interval
+ */
+ public OptionalInt anchorInterval() {
+ return anchorInterval;
+ }
+
+ /**
+ * The interval in force at a height: the base interval, or the last scheduled change at or below
+ * the height (D-336).
+ *
+ * @param blockNumber the height
+ * @return the interval in force there; 1 when no interval is configured
+ */
+ public int intervalAt(final long blockNumber) {
+ if (anchorInterval.isEmpty()) {
+ return 1;
+ }
+ final Map.Entry<Long, Integer> e = anchorIntervalSchedule.floorEntry(blockNumber);
+ return e == null ? anchorInterval.getAsInt() : e.getValue();
+ }
+
+ /**
+ * The interval schedule (D-336), possibly empty.
+ *
+ * @return an unmodifiable view, height to interval
+ */
+ public NavigableMap<Long, Integer> anchorIntervalSchedule() {
+ return java.util.Collections.unmodifiableNavigableMap(anchorIntervalSchedule);
+ }
+
+ /**
+ * Return a copy carrying an interval schedule (D-336). Refused unless every entry keeps the new
+ * anchors a subset of the old ones; see the private constructor.
+ *
+ * @param schedule heights to intervals
+ * @return a copy of this configuration carrying the schedule
+ */
+ public PqAnchorConfig withAnchorIntervalSchedule(final Map<Long, Integer> schedule) {
+ return new PqAnchorConfig(
+ chainId, anchorBlock, minSealsSchedule, minSealsCeiling, disabled, maxSealsCarried,
+ anchorInterval, anchorV2Block, new TreeMap<>(schedule));
+ }
+
+ /**
+ * Is this a height at which a certificate is carried and demanded?
+ *
+ * <p>Counted FROM H, so H itself is always an anchor height. That matters because H is the single
+ * height the whole fleet coordinates on, and a scheme whose first anchor lands somewhere else
+ * would be a scheme nobody can check by hand on activation day.
+ *
+ * @param blockNumber the height to test
+ * @return true if a certificate belongs in this block
+ */
+ public boolean isAnchorHeight(final long blockNumber) {
+ if (anchorInterval.isEmpty()) {
+ return true;
+ }
+ if (anchorBlock == NEVER || blockNumber < anchorBlock) {
+ return false;
+ }
+ return (blockNumber - anchorBlock) % intervalAt(blockNumber) == 0;
+ }
+
+ /**
+ * The single question both anchor rules ask: do I judge this header at all?
+ *
+ * <p>Two conditions, and they are different in kind. {@link #activeAt(long)} is about WHETHER the
+ * scheme is switched on for this node at this height; {@link #isAnchorHeight(long)} is about
+ * whether this particular height is one that carries a certificate. Folding them into one method
+ * is deliberate: two rules asking the same question two different ways is exactly how R1 and R2
+ * would drift apart, and a header accepted by one and refused by the other is a chain split.
+ *
+ * @param blockNumber the height to test
+ * @return true if the anchor rules judge this header
+ */
+ public boolean anchorAppliesAt(final long blockNumber) {
+ return activeAt(blockNumber) && isAnchorHeight(blockNumber);
+ }
+
+ /**
+ * The v2 activation height, or {@link #NEVER}.
+ *
+ * @return the height from which anchor headers carry the scheme-tagged certificate
+ */
+ public long anchorV2Block() {
+ return anchorV2Block;
+ }
+
+ /**
+ * Whether the header at this height must carry the SCHEME-TAGGED (v2) certificate and the v2
+ * digest. True only at an anchor height ({@link #anchorAppliesAt}) at or above the v2 activation
+ * height. The producer and both rules ask THIS question, not one that resembles it.
+ *
+ * @param blockNumber the height
+ * @return true when the v2 form is the only accepted form at this height
+ */
+ public boolean anchorV2AppliesAt(final long blockNumber) {
+ return anchorV2Block != NEVER && blockNumber >= anchorV2Block && anchorAppliesAt(blockNumber);
+ }
+
+ /**
+ * Copy with a v2 activation height.
+ *
+ * @param v2Block the height, or {@link #NEVER}
+ * @return a configuration identical to this one except for the v2 height
+ */
+ public PqAnchorConfig withAnchorV2Block(final long v2Block) {
+ return new PqAnchorConfig(
+ chainId, anchorBlock, minSealsSchedule, minSealsCeiling, disabled, maxSealsCarried,
+ anchorInterval, v2Block, anchorIntervalSchedule);
+ }
+
+ /**
+ * Return a copy carrying an anchor interval.
+ *
+ * <p>THE SECURITY PROPERTY, stated so it can be argued with: block hashes chain, so an anchor at
+ * height A protects everything below A, because rewriting anything under A changes A's parent hash
+ * and forces A to be reproduced, which needs a Falcon quorum. What an adversary holding every
+ * classical validator key can still rewrite is the TAIL since the last anchor. Therefore
+ * {@code fork depth <= interval}. At ~523 ms a block, an interval of 100 is about 52 seconds of
+ * rewritable tail, against about half a second at interval 1, and it costs a hundredth of the disk.
+ *
+ * @param interval the interval, or empty for every block
+ * @return a copy of this configuration carrying the interval
+ */
+ public PqAnchorConfig withAnchorInterval(final OptionalInt interval) {
+ return new PqAnchorConfig(
+ chainId, anchorBlock, minSealsSchedule, minSealsCeiling, disabled, maxSealsCarried, interval,
+ anchorV2Block, anchorIntervalSchedule);
+ }
+
+ /**
+ * Whether the anchor is configured at all, INDEPENDENTLY of whether it has been emergency
+ * disarmed.
+ *
+ * <p>{@link #everActive()} answers "will the rules ever fire", which is false both when nothing is
+ * configured and when a configured anchor has been disarmed. Telling those two states apart is the
+ * whole point of the per-block disarm announcement: a node that never had an anchor has nothing to
+ * shout about, and a node running disarmed over a configured anchor has to shout at every block.
+ *
+ * @return true iff an activation height is configured
+ */
+ public boolean anchorConfigured() {
+ return anchorBlock != NEVER;
+ }
+
+ /**
+ * The activation height H.
+ *
+ * @return H, or {@link #NEVER}
+ */
+ public long anchorBlock() {
+ return anchorBlock;
+ }
+
+ /**
+ * The height at which the legacy log-only {@code FalconSealValidationRule} retires. It is the same
+ * height the new rules take over at, so exactly one of the two regimes is in force at any height.
+ *
+ * @return H, or {@link #NEVER} when the anchor never activates and the legacy rule never retires
+ */
+ public long legacyFalconRuleRetirementBlock() {
+ return everActive() ? anchorBlock : NEVER;
+ }
+
+ /**
+ * The chain id used in the D and M pre-images.
+ *
+ * @return the chain id
+ */
+ public long chainId() {
+ return chainId;
+ }
+
+ /**
+ * The staged threshold schedule.
+ *
+ * @return an unmodifiable view keyed on activation height
+ */
+ public NavigableMap<Long, Integer> minSealsSchedule() {
+ return minSealsSchedule;
+ }
+
+ /**
+ * Whether the emergency disable override is in force.
+ *
+ * @return true iff the anchor rules are switched off on this node
+ */
+ public boolean disabled() {
+ return disabled;
+ }
+
+ @Override
+ public String toString() {
+ return "PqAnchorConfig{chainId="
+ + chainId
+ + ", anchorBlock="
+ + (anchorBlock == NEVER ? "NEVER" : anchorBlock)
+ + ", minSeals="
+ + minSealsSchedule
+ + ", ceiling="
+ + (minSealsCeiling.isPresent() ? minSealsCeiling.getAsInt() : "none")
+ + ", disabled="
+ + disabled
+ + '}';
+ }
+}
diff --git a/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/PqAnchorLapse.java b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/PqAnchorLapse.java
new file mode 100755
index 000000000..a7c8c9bf1
--- /dev/null
+++ b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/PqAnchorLapse.java
@@ -0,0 +1,375 @@
+/*
+ * Copyright contributors to Besu / Aere Network.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.common.bft;
+
+import java.util.Comparator;
+import java.util.List;
+import java.util.Optional;
+import java.util.OptionalInt;
+
+/**
+ * The historical ranges on chain 2800 in which the anchor rules were not fully in force.
+ *
+ * <p><b>WHAT HAPPENED.</b> On 2026-08-10 all nine validators were restarted inside a few minutes. A
+ * node that has just restarted holds no Falcon seals until it takes part in one commit, so for a
+ * moment every node held none; the very next height was an anchor height, its threshold asked for
+ * three seals, nobody could propose, and the chain stopped for nine minutes. The measure that
+ * restarted it was to switch the anchor rules off on all nine nodes at once, and then to restore
+ * them with the emergency seal ceiling lowered rather than at the scheduled threshold. That leaves
+ * TWO ranges of canonical headers, not one, and they fail a strict validator for different reasons:
+ *
+ * <ol>
+ * <li><b>The rules off entirely.</b> vanityData carries the client's usual version string instead
+ * of the anchor digest, although the certificate is attached, so the digest binding does not
+ * hold; and the certificate's validator indices are in the order the commit messages ARRIVED
+ * rather than sorted, so they are distinct but not increasing.
+ * <li><b>The rules on, the threshold lowered.</b> vanityData carries a correct digest and the
+ * indices are sorted, so both of those bind exactly as they should. What differs is the COUNT:
+ * a proposer running under the lowered ceiling legitimately wrote fewer seals than the
+ * configured schedule asks for, so the header is short of the threshold and nothing else.
+ * </ol>
+ *
+ * <p><b>WHY THE EXCEPTION BELONGS AT VALIDATION AND NOWHERE ELSE.</b> Nodes that already hold these
+ * blocks never revalidate them, which is why the damage was invisible. A node built from this source
+ * and synced from genesis does validate them, and under the plain rules it stops at the first header
+ * of each range and never passes it. The history is what it is: no recomputation can turn these
+ * headers into headers that satisfy a rule they were written without. What a correct client can do
+ * is name the ranges and judge those headers by the rule that was actually in force when they were
+ * written, which is what every node holding the chain does today. A patch anywhere else moves the
+ * error instead of ending it.
+ *
+ * <p><b>THE BOUNDS, MEASURED, NOT SEARCHED.</b> Neither property is monotone: inside the second
+ * range only about one anchor header in seven is short of the threshold and the rest are not, so a
+ * binary search would return a height that looks exactly like an answer and is not one. Every anchor
+ * height from the activation height 13,014,000 to the head at the time of measurement, 14,077,000,
+ * was therefore read one by one and its vanityData and certificate decoded: 25,252 heights,
+ * zero transport errors, and exactly the two contiguous ranges named below. Outside them there is
+ * not one header without a digest, not one with unsorted indices, and not one below the threshold.
+ *
+ * <p><b>WHAT THE RANGES DO NOT RELAX, AT ANY HEIGHT.</b> Over the first range a certificate must
+ * still decode and must still carry non-negative, pairwise DISTINCT indices: sortedness fixes one
+ * accepted order for a given set, while distinctness is the part that is load bearing against an
+ * attacker, because it is what makes "repeat one seal to inflate the count" unrepresentable in the
+ * grammar of the format. Over the second range NOTHING is relaxed except the count, and even the
+ * count keeps a floor: the lowest number of seals measured anywhere in that range is
+ * 1, which is the ceiling that was actually in force, so that is the floor applied,
+ * not zero. Both ranges therefore admit exactly the history that exists and nothing weaker.
+ *
+ * <p><b>THE BOUNDS ARE FIXED IN CODE ON PURPOSE.</b> A range a node could widen at runtime would let
+ * a future lapse pass unnoticed. Outside these ranges nothing changes at all, so a NEW unenforced
+ * header still stops this client, which is what should happen. Producers never consult this class:
+ * new headers are always written with the digest, with sorted indices and at the scheduled
+ * threshold, so the ranges are closed by construction and cannot grow.
+ *
+ * <p><b>THE TYPE IS A LIST BECAUSE A THIRD RANGE MUST NOT REQUIRE TOUCHING A RULE.</b> The two
+ * entries below are the two the chain has. Adding another is an edit to this file alone.
+ */
+public final class PqAnchorLapse {
+
+ /** The chain these ranges belong to. They describe no other chain. */
+ public static final long CHAIN_ID = 2800L;
+
+ /** The anchor spacing in force over both ranges, used by the self-check below. */
+ public static final long ANCHOR_SPACING = 32L;
+
+ /** What was not in force over a range. */
+ public enum Relaxation {
+ /** Nothing was in force: no digest binding, no ordering, no threshold. */
+ EVERYTHING,
+ /** The digest and the ordering were in force; only the seal threshold was lowered. */
+ THRESHOLD_ONLY
+ }
+
+ /**
+ * One contiguous range of heights over which the anchor rules were not fully in force.
+ *
+ * <p>Both bounds are INCLUSIVE and both are measured anchor heights: the first is the first header
+ * that shows the defect and the last is the last one that shows it.
+ */
+ public static final class Window {
+
+ private final long firstBlock;
+ private final long lastBlock;
+ private final long anchorHeights;
+ private final Relaxation relaxation;
+ private final int effectiveMinSeals;
+ private final String reason;
+
+ /**
+ * Names a range.
+ *
+ * @param firstBlock the first affected height, inclusive
+ * @param lastBlock the last affected height, inclusive
+ * @param anchorHeights how many anchor heights the range spans; carried so that the count and
+ * the bounds are checked against each other rather than written twice
+ * @param relaxation what was not in force
+ * @param effectiveMinSeals the seal threshold that WAS in force over the range, which is the
+ * floor still applied inside it; zero when nothing was in force
+ * @param reason why the range exists, and what was measured
+ */
+ public Window(
+ final long firstBlock,
+ final long lastBlock,
+ final long anchorHeights,
+ final Relaxation relaxation,
+ final int effectiveMinSeals,
+ final String reason) {
+ if (firstBlock < 0L || lastBlock < firstBlock) {
+ throw new IllegalArgumentException(
+ "AERE PQ ANCHOR LAPSE: a window must be a non-negative, non-empty range, got ["
+ + firstBlock
+ + ", "
+ + lastBlock
+ + "]");
+ }
+ if (anchorHeights < 1L) {
+ throw new IllegalArgumentException(
+ "AERE PQ ANCHOR LAPSE: a window must span at least one anchor height, got "
+ + anchorHeights);
+ }
+ if (effectiveMinSeals < 0) {
+ throw new IllegalArgumentException(
+ "AERE PQ ANCHOR LAPSE: the threshold in force cannot be negative, got "
+ + effectiveMinSeals);
+ }
+ this.firstBlock = firstBlock;
+ this.lastBlock = lastBlock;
+ this.anchorHeights = anchorHeights;
+ this.relaxation = relaxation;
+ this.effectiveMinSeals = effectiveMinSeals;
+ this.reason = reason;
+ }
+
+ /**
+ * The first affected height.
+ *
+ * @return the inclusive lower bound
+ */
+ public long firstBlock() {
+ return firstBlock;
+ }
+
+ /**
+ * The last affected height.
+ *
+ * @return the inclusive upper bound
+ */
+ public long lastBlock() {
+ return lastBlock;
+ }
+
+ /**
+ * How many anchor heights this range spans.
+ *
+ * @return the span, in anchor heights
+ */
+ public long anchorHeights() {
+ return anchorHeights;
+ }
+
+ /**
+ * What was not in force over this range.
+ *
+ * @return the relaxation
+ */
+ public Relaxation relaxation() {
+ return relaxation;
+ }
+
+ /**
+ * The seal threshold that WAS in force over this range.
+ *
+ * @return the measured floor, zero when no rule was in force
+ */
+ public int effectiveMinSeals() {
+ return effectiveMinSeals;
+ }
+
+ /**
+ * Why this range exists.
+ *
+ * @return the reason, with what was measured
+ */
+ public String reason() {
+ return reason;
+ }
+
+ /**
+ * Whether a height falls inside this range.
+ *
+ * @param blockNumber the height being judged
+ * @return true iff the height is within the inclusive bounds
+ */
+ public boolean covers(final long blockNumber) {
+ return blockNumber >= firstBlock && blockNumber <= lastBlock;
+ }
+
+ @Override
+ public String toString() {
+ return "["
+ + firstBlock
+ + ", "
+ + lastBlock
+ + "] "
+ + relaxation
+ + " ("
+ + anchorHeights
+ + " anchor heights, threshold in force "
+ + effectiveMinSeals
+ + ")";
+ }
+ }
+
+ private static final List<Window> WINDOWS =
+ List.of(
+ new Window(
+ 13_267_824L,
+ 13_268_944L,
+ 36L,
+ Relaxation.EVERYTHING,
+ 0,
+ "2026-08-10: the anchor rules were switched off on the whole validator set to restart "
+ + "a stopped chain, so the headers produced meanwhile carry the client version "
+ + "string in vanityData instead of the anchor digest, and their certificates "
+ + "carry the indices in arrival order rather than sorted. Measured: 36 anchor "
+ + "heights, all 36 affected, all with distinct non-negative indices"),
+ new Window(
+ 13_268_976L,
+ 13_890_544L,
+ 19_425L,
+ Relaxation.THRESHOLD_ONLY,
+ 1,
+ "2026-08-10 onwards: the rules were restored immediately afterwards "
+ + "but with the emergency seal ceiling lowered, because raising the threshold "
+ + "back in one step had stopped the chain a second time. Every header here binds "
+ + "its digest and carries sorted indices; 2,926 of the 19,425 "
+ + "anchor heights in the range simply carry fewer seals than the schedule asks, "
+ + "the fewest being 1"));
+
+ static {
+ // The list is ordered and disjoint, and each entry's stated span agrees with its own bounds.
+ // This runs at class initialisation so that a future entry which contradicts itself, or which
+ // overlaps its neighbour, fails loudly at startup rather than silently widening what a node
+ // accepts.
+ Window previous = null;
+ for (final Window window : WINDOWS) {
+ if (previous != null && window.firstBlock() <= previous.lastBlock()) {
+ throw new IllegalStateException(
+ "AERE PQ ANCHOR LAPSE: windows must be ordered and disjoint, "
+ + previous
+ + " overlaps "
+ + window);
+ }
+ final long derived = (window.lastBlock() - window.firstBlock()) / ANCHOR_SPACING + 1L;
+ if (derived != window.anchorHeights()) {
+ throw new IllegalStateException(
+ "AERE PQ ANCHOR LAPSE: window "
+ + window
+ + " says it spans "
+ + window.anchorHeights()
+ + " anchor heights, but its bounds at spacing "
+ + ANCHOR_SPACING
+ + " span "
+ + derived);
+ }
+ if (window.relaxation() == Relaxation.EVERYTHING && window.effectiveMinSeals() != 0) {
+ throw new IllegalStateException(
+ "AERE PQ ANCHOR LAPSE: window " + window + " has no rule in force, so no threshold");
+ }
+ if (window.relaxation() == Relaxation.THRESHOLD_ONLY && window.effectiveMinSeals() < 1) {
+ throw new IllegalStateException(
+ "AERE PQ ANCHOR LAPSE: window "
+ + window
+ + " relaxes only the threshold, so the threshold it replaces it with must be at "
+ + "least 1; a floor of zero would accept an empty certificate where a certificate "
+ + "was in fact required");
+ }
+ previous = window;
+ }
+ }
+
+ private PqAnchorLapse() {}
+
+ /**
+ * Every named range, ordered by first height.
+ *
+ * @return an unmodifiable list, never null, possibly empty
+ */
+ public static List<Window> windows() {
+ return WINDOWS;
+ }
+
+ /**
+ * Whether the anchor rules were out of force ENTIRELY at this height.
+ *
+ * <p>This is the single question both anchor rules ask before they judge anything. They ask it
+ * through this one method, for the same reason they share {@code anchorAppliesAt}: two rules that
+ * each decided the boundary their own way could disagree about one header, and a header accepted
+ * by one rule and refused by the other is a chain break.
+ *
+ * <p>It is deliberately FALSE inside a threshold-only range. There the digest binding and the
+ * ordering did hold and are still required; only {@link #historicMinSeals(long)} moves.
+ *
+ * @param blockNumber the height being judged
+ * @return true iff the height falls inside a range where nothing was in force
+ */
+ public static boolean isDisarmed(final long blockNumber) {
+ for (final Window window : WINDOWS) {
+ if (window.covers(blockNumber) && window.relaxation() == Relaxation.EVERYTHING) {
+ return true;
+ }
+ }
+ return false;
+ }
+
+ /**
+ * The seal threshold that was actually in force at this height, when it was lower than the
+ * configured schedule.
+ *
+ * <p>This is the same lever the fleet itself used at the time, the emergency ceiling, replayed
+ * from a fixed range instead of from a runtime option. A node validating history therefore asks
+ * the certificate for what was asked of the proposer that wrote it, and nothing more.
+ *
+ * @param blockNumber the height being judged
+ * @return the threshold in force, or empty when the configured schedule applies unchanged
+ */
+ public static OptionalInt historicMinSeals(final long blockNumber) {
+ for (final Window window : WINDOWS) {
+ if (window.covers(blockNumber) && window.relaxation() == Relaxation.THRESHOLD_ONLY) {
+ return OptionalInt.of(window.effectiveMinSeals());
+ }
+ }
+ return OptionalInt.empty();
+ }
+
+ /**
+ * The range covering a height, when there is one.
+ *
+ * @param blockNumber the height being judged
+ * @return the range, or empty
+ */
+ public static Optional<Window> windowCovering(final long blockNumber) {
+ return WINDOWS.stream().filter(w -> w.covers(blockNumber)).findFirst();
+ }
+
+ /**
+ * The first height of the earliest named range, or empty when there is none.
+ *
+ * @return the earliest affected height
+ */
+ public static Optional<Long> earliestAffectedBlock() {
+ return WINDOWS.stream().map(Window::firstBlock).min(Comparator.naturalOrder());
+ }
+}
diff --git a/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/PqAnchorNotReadyException.java b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/PqAnchorNotReadyException.java
new file mode 100755
index 000000000..2501920f3
--- /dev/null
+++ b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/PqAnchorNotReadyException.java
@@ -0,0 +1,132 @@
+/*
+ * Copyright contributors to Besu / AERE Network.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.common.bft;
+
+/**
+ * Raised by the block producer when this node cannot back the block it is about to propose with a
+ * certificate that reaches the staged threshold K.
+ *
+ * <p>THIS IS A DECISION, NOT A FAULT. The alternative, proposing anyway, means emitting a header
+ * this node has ALREADY COMPUTED to be invalid under its own rules. In QBFT both choices cost the
+ * same thing, one round timeout, because there is no way for a proposer to yield its turn early:
+ * a proposal everyone rejects and a proposal nobody sends both end at the round timer. So proposing
+ * anyway buys no liveness at all and only puts a header that cannot be imported into gossip. The
+ * refusal is the strictly better of two equal-cost options.
+ *
+ * <p>WHEN IT CAN HAPPEN. Only above the activation height, and only once the operator has raised K
+ * past zero: the first stage is required to be K=0, so activation itself can never refuse. In
+ * steady state the usual cause is a node that restarted and has not yet taken part in a commit, at
+ * most one proposer turn. The other cause, f validators withholding Falcon seals, is the measured
+ * A10 exposure and is the reason the validator set must grow to N&gt;=9 before K is raised to
+ * quorum, because at N=7, f=2 the margin is exactly zero.
+ *
+ * <p>Callers on the consensus path must catch this and simply not propose. It carries the numbers a
+ * human needs to see why, so the refusal is never silent.
+ */
+public class PqAnchorNotReadyException extends RuntimeException {
+
+ private static final long serialVersionUID = 1L;
+
+ /**
+ * Find a refusal anywhere in a throwable's cause chain.
+ *
+ * <p>MEASURED REASON THIS EXISTS, 2026-08-02. {@code AbstractBlockCreator.createBlock} wraps
+ * EVERY exception thrown by the extra-data calculator into {@code IllegalStateException("Block
+ * creation failed unexpectedly. Will restart on next block added to chain.")} at
+ * AbstractBlockCreator.java:366 of commit d2032017, and the producer is called from inside that
+ * same try block, at AbstractBlockCreator.java:333. A plain {@code catch
+ * (PqAnchorNotReadyException)} on the consensus path is therefore DEAD CODE. Measured on an
+ * isolated N=4 network with an unreachable threshold (K=4 from height 30, chain halted at 29):
+ * the refusal WARN was logged 0 times on 4 of 4 nodes, while "Block creation failed unexpectedly"
+ * and "State machine threw exception while processing event" were each logged once per node, and
+ * the escape aborted {@code handleRoundChangePayload} rather than skipping one proposal.
+ *
+ * <p>Callers must rethrow when this returns null: a refusal is the ONLY exception the consensus
+ * path is allowed to swallow, and a broad catch that ate the rest would hide real faults.
+ *
+ * @param thrown the exception caught on the consensus path
+ * @return the refusal carried by that exception, or null when it is not a refusal
+ */
+ public static PqAnchorNotReadyException findIn(final Throwable thrown) {
+ Throwable cursor = thrown;
+ // Bounded so a self-referential or cyclic cause chain cannot spin the consensus thread.
+ for (int hop = 0; cursor != null && hop < 16; hop++) {
+ if (cursor instanceof PqAnchorNotReadyException) {
+ return (PqAnchorNotReadyException) cursor;
+ }
+ final Throwable next = cursor.getCause();
+ if (next == cursor) {
+ return null;
+ }
+ cursor = next;
+ }
+ return null;
+ }
+
+ private final long parentNumber;
+ private final int seals;
+ private final int required;
+
+ /**
+ * Instantiates the refusal.
+ *
+ * @param parentNumber the number of the parent block the certificate would attest
+ * @param seals how many valid, eligible seals this node holds for that parent
+ * @param required the staged threshold K for the block being produced
+ * @param detail a human readable explanation of where the seals came from and what was rejected
+ */
+ public PqAnchorNotReadyException(
+ final long parentNumber, final int seals, final int required, final String detail) {
+ super(
+ "AERE-PQ-ANCHOR-NOT-READY: refusing to propose on top of block "
+ + parentNumber
+ + " because this node holds "
+ + seals
+ + " valid eligible Falcon seal(s) for it and the staged threshold is "
+ + required
+ + ". "
+ + detail);
+ this.parentNumber = parentNumber;
+ this.seals = seals;
+ this.required = required;
+ }
+
+ /**
+ * The parent the certificate would have attested.
+ *
+ * @return the parent block number
+ */
+ public long parentNumber() {
+ return parentNumber;
+ }
+
+ /**
+ * How many valid eligible seals were available.
+ *
+ * @return the seal count
+ */
+ public int seals() {
+ return seals;
+ }
+
+ /**
+ * The staged threshold that was not reached.
+ *
+ * @return the threshold K
+ */
+ public int required() {
+ return required;
+ }
+}
diff --git a/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/PqAnchorSyncModeGuard.java b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/PqAnchorSyncModeGuard.java
new file mode 100755
index 000000000..2dc16d8e9
--- /dev/null
+++ b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/PqAnchorSyncModeGuard.java
@@ -0,0 +1,130 @@
+/*
+ * Copyright contributors to Besu / AERE Network.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.common.bft;
+
+import java.util.Locale;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+/**
+ * AERE SINCRONIZARE (2026-08-02). Refuse to start when the V2 certificate anchor is configured and
+ * this node is going to acquire its history through a sync mode whose header import path does not
+ * run the block header validator at all.
+ *
+ * <p><b>The hole this closes, read in the source and not assumed.</b> On the SNAP path the backward
+ * header pipeline ends in {@code
+ * org.hyperledger.besu.ethereum.eth.sync.common.ImportHeadersStep}. That class takes a {@code
+ * MutableBlockchain}, an anchor header and a pivot header, and nothing else: it holds no {@code
+ * ProtocolSchedule}, no {@code ProtocolContext} and no {@code BlockHeaderValidator}. Its {@code
+ * accept(List)} checks one thing, that the first header of the batch hashes to the parent hash the
+ * previously imported child declared, and then calls {@code storeBlockHeaders} directly. There is no
+ * {@code HeaderValidationMode} anywhere in the file. So every header between the checkpoint and the
+ * pivot enters the database having been checked for hash chaining and for nothing else. No QBFT
+ * rule runs on it: not the validator set rule, not the committed seals rule, and not either half of
+ * the certificate anchor. Bodies and receipts below the pivot arrive through the same pipeline
+ * family and are imported without executing the blocks.
+ *
+ * <p><b>Why refusal and not coverage.</b> Covering the SNAP header path properly means giving that
+ * step a header validator and a parent for every header it imports. The backward pipeline does not
+ * have the parent when it imports a header - the parent is downloaded in a later batch - so the
+ * attached half of the anchor cannot run there at all, and the detached half would run against a
+ * parent that is not yet known. Refusing to start is the only repair that is complete: it has no
+ * window, no partial coverage and nothing for an operator to get subtly wrong. What it costs is
+ * stated plainly rather than hidden: with the anchor armed, a new public node has to acquire the
+ * chain by full sync.
+ *
+ * <p><b>Fail closed on the unknown.</b> A null, blank or unrecognised mode name aborts. A guard that
+ * treats "I could not tell" as "probably fine" is the class of defect this whole programme exists to
+ * remove.
+ *
+ * <p><b>Inert when the anchor is not configured.</b> With no {@code aere.pq.anchorBlock} this method
+ * returns before it looks at the sync mode, so a binary carrying it behaves exactly as today on
+ * chain 2800 as it stands, where the anchor is not configured on any node.
+ */
+public final class PqAnchorSyncModeGuard {
+
+ private static final Logger LOG = LoggerFactory.getLogger(PqAnchorSyncModeGuard.class);
+
+ /** The stable machine-readable code emitted when this guard refuses to start a node. */
+ public static final String CODE = "AERE-PQC-SYNC-MODE-01";
+
+ /** The only sync mode whose import path runs the block header validator on every block. */
+ public static final String REQUIRED_MODE = "FULL";
+
+ private PqAnchorSyncModeGuard() {}
+
+ /**
+ * Refuse to start when the anchor is armed and the sync mode bypasses header validation.
+ *
+ * <p>Call this exactly once during node startup, from a point where a chain head already exists
+ * and before the network and the consensus state machine are started, so that a refusal is a clean
+ * refusal to start rather than a mid-flight halt.
+ *
+ * @param syncModeName the configured sync mode, as its enum name; null or blank aborts
+ * @param anchorConfig the height-indexed certificate-anchor configuration; a null or never-active
+ * configuration makes this method a no-op
+ * @throws FalconSealSupport.ActivationConfigException when the anchor is armed and the sync mode
+ * is anything other than {@value #REQUIRED_MODE}
+ */
+ public static void verifySyncModeOrAbort(
+ final String syncModeName, final PqAnchorConfig anchorConfig) {
+
+ if (anchorConfig == null || !anchorConfig.everActive() || anchorConfig.disabled()) {
+ LOG.debug(
+ "AERE PQ ANCHOR: sync-mode guard inert, the certificate anchor is not armed on this node.");
+ return;
+ }
+
+ final String mode =
+ syncModeName == null ? "" : syncModeName.trim().toUpperCase(Locale.ROOT);
+
+ if (REQUIRED_MODE.equals(mode)) {
+ LOG.info(
+ "AERE PQ ANCHOR: sync mode is {} and the certificate anchor is armed at H={}. Every header "
+ + "this node imports goes through the block header validator, so both halves of the "
+ + "anchor apply to synced history as well as to proposed blocks.",
+ mode,
+ anchorConfig.anchorBlock());
+ return;
+ }
+
+ throw new FalconSealSupport.ActivationConfigException(
+ FalconSealSupport.ActivationConfigException.Kind.UNSAFE,
+ CODE,
+ "AERE PQ ANCHOR: REFUSING TO START (fail-closed). The V2 certificate anchor is armed at "
+ + "H="
+ + anchorConfig.anchorBlock()
+ + " but --sync-mode is "
+ + (mode.isEmpty() ? "(null or blank)" : mode)
+ + ", not "
+ + REQUIRED_MODE
+ + ". WHAT THIS MEANS: outside "
+ + REQUIRED_MODE
+ + " sync, history is acquired through the backward header pipeline, which ends in "
+ + "ImportHeadersStep. That step holds no ProtocolSchedule and no BlockHeaderValidator; "
+ + "it checks that each batch of headers hash-chains onto the child already imported and "
+ + "then writes them straight to storage. No HeaderValidationMode appears in that file. "
+ + "So the anchor digest rule and the anchor seals rule would both be skipped for every "
+ + "block between the checkpoint and the pivot, and this node would accept, as its own "
+ + "history, blocks whose certificates were stripped or swapped in flight. A defence that "
+ + "does not apply to a node that is syncing is missing exactly when it matters, because "
+ + "that is the moment a node takes history from strangers. WHAT TO DO: start this node "
+ + "with --sync-mode="
+ + REQUIRED_MODE
+ + ". To start it unchanged for diagnosis, unset aere.pq.anchorBlock; the anchor rules "
+ + "are then inert and this node enforces nothing.");
+ }
+}
diff --git a/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/PqAnchorThresholdGuard.java b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/PqAnchorThresholdGuard.java
new file mode 100755
index 000000000..963c64b23
--- /dev/null
+++ b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/PqAnchorThresholdGuard.java
@@ -0,0 +1,282 @@
+/*
+ * Copyright contributors to Besu / AERE Network.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.common.bft;
+
+import java.util.Map;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+/**
+ * AERE GARDA-PRAG (2026-08-02). Refuse to start when the staged Falcon seal threshold K is set to a
+ * value that STOPS THE CHAIN, instead of letting the node boot quietly and discover it one block
+ * later.
+ *
+ * <p><b>The hole this closes, measured before it was written.</b> Searched across the whole fork
+ * tree, {@code grep -rn "minSeals" --include=*.java consensus app} filtered for any of {@code
+ * quorum}, {@code throw}, {@code refus}, {@code abort} or {@code Illegal}: ZERO matches. {@link
+ * PqAnchorConfig} refuses a NEGATIVE threshold and a step scheduled below the activation height, and
+ * nothing else. The only guard that looked at the threshold at all was {@code
+ * PqAnchorProducer.warnIfActivationHeightCanRefuse}, and it covers a different question (K at the
+ * activation height itself), reaches only {@code LOG.error}, and returns. A halting threshold was
+ * therefore a configuration a node accepted in silence.
+ *
+ * <p><b>THE BOUND, AND WHERE THE ARITHMETIC COMES FROM.</b> The refusal is {@code K >= quorum(N)},
+ * i.e. the highest value that may be configured is {@code quorum(N) - 1}.
+ *
+ * <ul>
+ * <li>{@code quorum(N)} is Besu's own {@link BftHelpers#calculateRequiredValidatorQuorum(int)},
+ * {@code ceil(2N/3)}. At N=7 that is {@code ceil(14/3) = 5}, so the highest configurable
+ * threshold on chain 2800 as it stands is <b>4</b>.
+ * <li>{@code K = quorum} is a GUARANTEED HALT, and that is measured, not argued. A proposer
+ * assembles its certificate out of the Falcon seals it heard on Commit messages, and the block
+ * is IMPORTED at the quorum-th Commit; after the import {@code QbftController.consumeMessage}
+ * discards every message that targets a height not above the chain head, so the Commits that
+ * arrive afterwards never reach the seal cache. A proposer can therefore gather at most {@code
+ * quorum} seals, at ANY N. Measured on an isolated N=4 network (quorum 3): {@code k = 3} on
+ * EVERY header above the activation height, never 4, with all four nodes keyed and healthy.
+ * Requiring K=quorum thus requires that ALL of the first {@code quorum} Commits carry a valid,
+ * eligible Falcon seal: one validator without a key among them, or one seal that does not
+ * verify, and no proposer can ever propose again.
+ * <li><b>{@code K > N - f} is the WRONG bound and this guard deliberately does not use it.</b> At
+ * N=7 the two agree by coincidence, because {@code N - f = 7 - 2 = 5} equals {@code quorum} and
+ * both reject 5. They part company as soon as the set grows: at N=9, {@code quorum = 6} while
+ * {@code N - f = 7}, so {@code K > N - f} would happily accept K=7, which is two rungs above
+ * what a proposer can physically gather. Growing the validator set does not buy quorum margin;
+ * that was measured too, and it is asserted in the test.
+ * </ul>
+ *
+ * <p><b>What is a refusal and what is only a shout.</b> Above {@code quorum - f} the schedule is
+ * still reachable but has no margin against f silent or keyless signers, which is the measured A10
+ * and A13 exposure. That is a deliberate operator choice with a real cost, so it gets a loud WARN and
+ * the node starts. At or above {@code quorum} the schedule is not reachable at all, so it gets a
+ * refusal. A guard that refused both would take the emergency ladder away; a guard that shouted for
+ * both would be the log line this class exists to replace.
+ *
+ * <p><b>The verdict is computed from the SAME code path enforcement reads.</b> Every step is scored
+ * with {@link PqAnchorConfig#minSealsAt(long)}, the exact method the producer calls, not with a
+ * second reading of the raw schedule. That is why the emergency ceiling is honoured here for free: a
+ * ceiling that lowers a fatal schedule below the bound makes the node start, which is precisely what
+ * an operator needs at three in the morning, and a ceiling ABOVE the schedule rescues nothing,
+ * because the ceiling can only ever lower.
+ *
+ * <p><b>Fail closed on the unknown.</b> A validator-set size of zero or less aborts. "I could not
+ * count the validators" is not "the threshold is probably fine".
+ *
+ * <p><b>Inert when the anchor is not armed.</b> With no {@code aere.pq.anchorBlock}, or with the
+ * anchor emergency-disarmed, this method returns before it computes anything, so a binary carrying it
+ * behaves exactly as today on chain 2800, where the anchor is armed on no node.
+ */
+public final class PqAnchorThresholdGuard {
+
+ private static final Logger LOG = LoggerFactory.getLogger(PqAnchorThresholdGuard.class);
+
+ /** The stable machine-readable code emitted when this guard refuses to start a node. */
+ public static final String CODE = "AERE-PQC-THRESHOLD-01";
+
+ private PqAnchorThresholdGuard() {}
+
+ /**
+ * The highest seal threshold that may be configured for a validator set of this size.
+ *
+ * <p>REVISED 2026-08-20, and the revision is a measurement, not an opinion. Until D-227
+ * (2026-08-14) a proposer could gather at most {@code quorum} seals: the block imported at the
+ * quorum-th Commit and {@code QbftController.consumeMessage} discarded every later Commit, so this
+ * method returned {@code quorum - 1} and the class doc below carries that history. D-227 (the
+ * late-seal salvage, {@code PqLateSealSalvageTest}) extracts the Falcon seal BEFORE the height
+ * gate discards the message, so the cache now accumulates seals from every ALIVE keyed validator.
+ * Measured on mainnet 2800 across 5,400 anchor blocks (2026-08-18..20): certificates carry 8 and 9
+ * seals at N=9, i.e. strictly more than quorum=6, which under the old mechanics was impossible.
+ *
+ * <p>The bound that remains fatal is availability under the tolerated fault budget: with f
+ * validators Byzantine or down, at most {@code N - f} seals can ever exist, so a threshold above
+ * {@code N - f} halts anchors inside the design's own fault model. At N=9 this is 7; at N=7 it is
+ * 5. A threshold at or above the quorum is now a LIVENESS TAX (anchors wait for late seals),
+ * shouted below, not a guaranteed halt.
+ *
+ * @param validatorCount the number of validators, at least 1
+ * @return the highest configurable threshold K, {@code N - f}
+ */
+ public static int maxConfigurableThreshold(final int validatorCount) {
+ return validatorCount - byzantineBudget(validatorCount);
+ }
+
+ /**
+ * The number of faulty validators QBFT tolerates at this set size, {@code floor((N-1)/3)}.
+ *
+ * @param validatorCount the number of validators, at least 1
+ * @return f
+ */
+ public static int byzantineBudget(final int validatorCount) {
+ return (validatorCount - 1) / 3;
+ }
+
+ /**
+ * Refuse to start when any step of the staged threshold schedule is at or above the QBFT quorum.
+ *
+ * <p>Call this exactly once during node startup, from a point where the validator set is already
+ * known and before the network and the consensus state machine are started, so that a refusal is a
+ * clean refusal to start rather than a mid-flight halt.
+ *
+ * @param anchorConfig the height-indexed certificate-anchor configuration; a null, never-active or
+ * disarmed configuration makes this method a no-op
+ * @param validatorCount the size of the validator set this node is starting into; zero or less
+ * aborts
+ * @throws FalconSealSupport.ActivationConfigException when the anchor is armed and any step of the
+ * effective threshold schedule reaches the quorum, or when the validator set size is unknown
+ */
+ public static void verifyThresholdAgainstQuorumOrAbort(
+ final PqAnchorConfig anchorConfig, final int validatorCount) {
+
+ if (anchorConfig == null || !anchorConfig.everActive()) {
+ LOG.debug(
+ "AERE PQ ANCHOR: threshold guard inert, the certificate anchor is not armed on this node.");
+ return;
+ }
+
+ if (validatorCount < 1) {
+ throw new FalconSealSupport.ActivationConfigException(
+ FalconSealSupport.ActivationConfigException.Kind.UNSAFE,
+ CODE,
+ "AERE PQ ANCHOR: REFUSING TO START (fail-closed). The V2 certificate anchor is armed at H="
+ + anchorConfig.anchorBlock()
+ + " but this node counted "
+ + validatorCount
+ + " validators, so the QBFT quorum cannot be computed and the configured seal "
+ + "threshold cannot be checked against it. A threshold at or above the quorum stops "
+ + "the chain, and a guard that treated an uncountable validator set as safe would be "
+ + "exactly the silence this guard exists to remove. WHAT TO DO: start this node "
+ + "without aere.pq.anchorBlock to diagnose, or fix whatever prevented the validator "
+ + "set from being read.");
+ }
+
+ final int quorum = BftHelpers.calculateRequiredValidatorQuorum(validatorCount);
+ final int maxConfigurable = maxConfigurableThreshold(validatorCount);
+ final int f = byzantineBudget(validatorCount);
+ final int noMarginAbove = quorum - f;
+
+ long fatalHeight = -1L;
+ int fatalThreshold = -1;
+ long highestAt = anchorConfig.anchorBlock();
+ int highest = anchorConfig.minSealsAt(anchorConfig.anchorBlock());
+
+ for (final Map.Entry<Long, Integer> step : anchorConfig.minSealsSchedule().entrySet()) {
+ final long at = step.getKey();
+ // Scored through minSealsAt, the SAME method the producer calls, so the emergency ceiling is
+ // applied here by exactly the code that will apply it in enforcement. A guard that re-derived
+ // the effective threshold from the raw schedule could drift away from what is in force.
+ final int effective = anchorConfig.minSealsAt(at);
+ if (effective > highest) {
+ highest = effective;
+ highestAt = at;
+ }
+ if (effective > validatorCount - f && fatalHeight < 0L) {
+ fatalHeight = at;
+ fatalThreshold = effective;
+ }
+ }
+
+ if (fatalHeight >= 0L) {
+ throw new FalconSealSupport.ActivationConfigException(
+ FalconSealSupport.ActivationConfigException.Kind.UNSAFE,
+ CODE,
+ "AERE PQ ANCHOR: REFUSING TO START (fail-closed). The staged Falcon seal threshold reaches "
+ + fatalThreshold
+ + " at height "
+ + fatalHeight
+ + ", and the QBFT quorum for the "
+ + validatorCount
+ + " validators this node is starting into is "
+ + quorum
+ + " (ceil(2N/3)) with f = "
+ + f
+ + ". The highest threshold that may be configured at this set size is "
+ + maxConfigurable
+ + " = N - f. WHAT THIS MEANS (doctrine revised 2026-08-20 for D-227 late-seal "
+ + "salvage): the seal cache accumulates seals from every ALIVE keyed validator, "
+ + "measured on mainnet 2800 as 8-9 seals per certificate at N=9 across 5,400 anchors. "
+ + "But with f validators Byzantine or down - the design's own fault budget - at most "
+ + "N - f seals can ever exist, so a threshold of "
+ + fatalThreshold
+ + " makes anchor blocks unreachable inside the tolerated fault model. That is a halt "
+ + "bought by configuration, and it starts at height "
+ + fatalHeight
+ + ". WHAT TO DO: lower the step to at most "
+ + maxConfigurable
+ + " in aere.pq.anchorMinSeals, or, if the chain is already stopped, restart with "
+ + "--Xaere-pq-anchor-min-seals-max="
+ + maxConfigurable
+ + " which lowers the effective threshold without editing the schedule, or with "
+ + "--Xaere-pq-anchor-disarm to switch the anchor rules off on this node entirely. "
+ + "Schedule as read: "
+ + anchorConfig.minSealsSchedule()
+ + ", emergency ceiling: "
+ + (anchorConfig.minSealsCeiling().isPresent()
+ ? Integer.toString(anchorConfig.minSealsCeiling().getAsInt())
+ : "none")
+ + ".");
+ }
+
+ if (highest >= quorum) {
+ LOG.warn(
+ "AERE PQ ANCHOR: threshold guard PASSED at a QUORUM-OR-ABOVE threshold. K reaches {} at "
+ + "height {}; quorum for {} validators is {} and N - f is {}. Reachability now rests "
+ + "on the D-227 late-seal salvage (measured on mainnet: 8-9 seals per certificate), "
+ + "and the margin under the fault budget is {}: with f={} validators down, anchors "
+ + "wait until {} of the remaining {} carry valid seals. This is the operator's "
+ + "explicit choice of a liveness tax for a quorum-grade certificate.",
+ highest,
+ highestAt,
+ validatorCount,
+ quorum,
+ validatorCount - f,
+ (validatorCount - f) - highest,
+ f,
+ highest,
+ validatorCount - f);
+ return;
+ }
+
+ if (highest > noMarginAbove) {
+ LOG.warn(
+ "AERE PQ ANCHOR: threshold guard PASSED but the schedule has NO MARGIN. K reaches {} at "
+ + "height {}, the quorum for {} validators is {} and f is {}, so the largest threshold "
+ + "that survives f silent or keyless signers is {}. Above that line every one of the "
+ + "first {} committers has to carry a valid Falcon seal minus at most {}. This is "
+ + "allowed because it is an operator's decision, not because it is safe.",
+ highest,
+ highestAt,
+ validatorCount,
+ quorum,
+ f,
+ noMarginAbove,
+ quorum,
+ quorum - highest);
+ return;
+ }
+
+ LOG.info(
+ "AERE PQ ANCHOR: threshold guard passed. K reaches {} at height {}; quorum for {} "
+ + "validators is {}, highest configurable threshold is {}, margin against silent "
+ + "signers is {} of a tolerated f={}.",
+ highest,
+ highestAt,
+ validatorCount,
+ quorum,
+ maxConfigurable,
+ noMarginAbove - highest,
+ f);
+ }
+}
diff --git a/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/PqAnchorV2.java b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/PqAnchorV2.java
new file mode 100755
index 000000000..11931438d
--- /dev/null
+++ b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/PqAnchorV2.java
@@ -0,0 +1,185 @@
+/*
+ * AERE crypto-agility, step 2: the versioned anchor certificate.
+ *
+ * WHY A NEW FORMAT. The legacy certificate (PqAnchor.writeCertificate, live on chain 2800) is an
+ * RLP list of [index, signature] pairs: it cannot say WHICH mathematics signed, so it can never
+ * carry the founder-approved hybrid (Falcon + SLH-DSA in one certificate, decision of
+ * 2026-08-07). V2 tags every seal with the one-byte scheme id from SealSchemes.
+ *
+ * HOW THE TWO FORMATS CANNOT BE CONFUSED, by construction and proven in tests:
+ * legacy: RLP [ [idx, sig], ... ] - first element is a LIST
+ * v2: RLP [ 0x02, [ [scheme, idx, sig], ... ] ] - first element is a SCALAR byte
+ * A legacy reader entering v2 bytes finds a scalar where it demands a list and fails loudly; this
+ * decoder REFUSES bytes whose first element is a list (that is legacy, not a malformed v2). The
+ * digest uses a NEW domain string, so a v2 digest can never collide with a v1 digest over related
+ * content: domain separation, same discipline as ANCHOR_DOMAIN v1.
+ *
+ * CANONICAL ORDER. Seals are strictly increasing by (validatorIndex, schemeWireId). One validator
+ * may seal with BOTH schemes (that is the hybrid), but the same (validator, scheme) pair can
+ * appear only once, and any deviation from the canonical order is a decode REFUSAL, not a repair:
+ * a certificate with two encodings would have two digests, and a digest that depends on encoder
+ * mood is not a commitment.
+ */
+package org.hyperledger.besu.consensus.common.bft;
+
+import java.nio.charset.StandardCharsets;
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.Comparator;
+import java.util.List;
+
+import org.apache.tuweni.bytes.Bytes;
+import org.apache.tuweni.bytes.Bytes32;
+import org.hyperledger.besu.crypto.Hash;
+import org.hyperledger.besu.ethereum.rlp.BytesValueRLPInput;
+import org.hyperledger.besu.ethereum.rlp.BytesValueRLPOutput;
+import org.hyperledger.besu.ethereum.rlp.RLPInput;
+
+/** Encoder/decoder and digest for the v2 (scheme-tagged) anchor certificate. */
+public final class PqAnchorV2 {
+
+ /** The version scalar that opens every v2 certificate. */
+ public static final int VERSION = 2;
+
+ /** Domain for the v2 anchor digest. NEW string: v1 and v2 digests can never collide. */
+ public static final String ANCHOR_DOMAIN_V2 = "AERE-PQ-ANCHOR-2";
+
+ /** The domain bytes written into every v2 digest preimage. */
+ public static final Bytes ANCHOR_DOMAIN_V2_BYTES =
+ Bytes.wrap(ANCHOR_DOMAIN_V2.getBytes(StandardCharsets.UTF_8));
+
+ /** Canonical order: strictly increasing (validatorIndex, schemeWireId). */
+ public static final Comparator<SchemeSeal> CANONICAL =
+ Comparator.comparingInt(SchemeSeal::getValidatorIndex)
+ .thenComparingInt(s -> s.getSchemeWireId() & 0xff);
+
+ /** Hard cap mirroring the legacy store's defence: a certificate is small and bounded. */
+ public static final int MAX_SEALS = 64;
+
+ private PqAnchorV2() {}
+
+ /** Encode a v2 certificate. The input must already be in canonical order with no duplicate
+ * (validator, scheme) pair and only known schemes; anything else throws: an encoder that
+ * silently reorders would let two byte-strings claim the same certificate. */
+ public static Bytes encode(final List<SchemeSeal> seals) {
+ requireCanonical(seals);
+ final BytesValueRLPOutput out = new BytesValueRLPOutput();
+ out.startList();
+ out.writeIntScalar(VERSION);
+ out.writeList(
+ seals,
+ (seal, rlp) -> {
+ rlp.startList();
+ rlp.writeIntScalar(seal.getSchemeWireId() & 0xff);
+ rlp.writeIntScalar(seal.getValidatorIndex());
+ rlp.writeBytes(seal.getSignature());
+ rlp.endList();
+ });
+ out.endList();
+ return out.encoded();
+ }
+
+ /** Decode a v2 certificate. Throws IllegalArgumentException on ANYTHING that is not a
+ * well-formed, canonical, known-scheme v2 certificate - including legacy bytes, which are
+ * named as such in the message so the caller can tell "old format" from "garbage". */
+ public static List<SchemeSeal> decode(final Bytes encoded) {
+ if (encoded == null || encoded.isEmpty()) {
+ throw new IllegalArgumentException("AERE PQ V2: empty certificate bytes");
+ }
+ final RLPInput in = new BytesValueRLPInput(encoded, false);
+ in.enterList();
+ if (in.nextIsList()) {
+ throw new IllegalArgumentException(
+ "AERE PQ V2: first element is a list - this is a LEGACY (v1) certificate, not v2");
+ }
+ final int version = in.readIntScalar();
+ if (version != VERSION) {
+ throw new IllegalArgumentException(
+ "AERE PQ V2: unknown certificate version " + version + " (this build understands 2)");
+ }
+ final List<SchemeSeal> seals = new ArrayList<>();
+ in.enterList();
+ while (!in.isEndOfCurrentList()) {
+ if (seals.size() >= MAX_SEALS) {
+ throw new IllegalArgumentException(
+ "AERE PQ V2: certificate exceeds " + MAX_SEALS + " seals");
+ }
+ in.enterList();
+ final int scheme = in.readIntScalar();
+ final int index = in.readIntScalar();
+ final Bytes signature = in.readBytes();
+ in.leaveList();
+ if (scheme < 0 || scheme > 0xff) {
+ throw new IllegalArgumentException("AERE PQ V2: scheme tag out of byte range: " + scheme);
+ }
+ seals.add(new SchemeSeal((byte) scheme, index, signature));
+ }
+ in.leaveList();
+ in.leaveList();
+ requireCanonical(seals);
+ return seals;
+ }
+
+ /** The v2 anchor digest: same shape as v1 (chainId, parent number, parent hash, certificate)
+ * under the NEW domain, over the CANONICAL encoding. */
+ public static Bytes32 anchorDigestV2(
+ final long chainId,
+ final long parentNumber,
+ final Bytes parentHash,
+ final List<SchemeSeal> seals) {
+ if (parentNumber < 0) {
+ throw new IllegalArgumentException("AERE PQ V2: parentNumber must not be negative");
+ }
+ if (parentHash == null || parentHash.size() != 32) {
+ throw new IllegalArgumentException("AERE PQ V2: parentHash must be 32 bytes");
+ }
+ final BytesValueRLPOutput out = new BytesValueRLPOutput();
+ out.startList();
+ out.writeBytes(ANCHOR_DOMAIN_V2_BYTES);
+ out.writeLongScalar(chainId);
+ out.writeLongScalar(parentNumber);
+ out.writeBytes(parentHash);
+ out.writeBytes(encode(seals));
+ out.endList();
+ return Hash.keccak256(out.encoded());
+ }
+
+ /** How many DISTINCT validators sealed with the given scheme. The hybrid threshold question
+ * ("K of N under scheme X") is asked per scheme, and a validator counts once per scheme no
+ * matter what canonicality allowed. */
+ public static int distinctValidatorsWith(final Collection<SchemeSeal> seals, final byte wireId) {
+ return (int)
+ seals.stream()
+ .filter(s -> s.getSchemeWireId() == wireId)
+ .mapToInt(SchemeSeal::getValidatorIndex)
+ .distinct()
+ .count();
+ }
+
+ private static void requireCanonical(final List<SchemeSeal> seals) {
+ if (seals == null) {
+ throw new IllegalArgumentException("AERE PQ V2: null seal list");
+ }
+ SchemeSeal prev = null;
+ for (final SchemeSeal s : seals) {
+ if (s.getValidatorIndex() < 0) {
+ throw new IllegalArgumentException(
+ "AERE PQ V2: negative validator index " + s.getValidatorIndex());
+ }
+ if (SealSchemes.byWireId(s.getSchemeWireId()).isEmpty()) {
+ throw new IllegalArgumentException(
+ "AERE PQ V2: unknown scheme tag 0x"
+ + Integer.toHexString(s.getSchemeWireId() & 0xff)
+ + " - refusing the whole certificate, an unknown scheme must be loud");
+ }
+ if (prev != null && CANONICAL.compare(prev, s) >= 0) {
+ throw new IllegalArgumentException(
+ "AERE PQ V2: seals not in strictly increasing (validator, scheme) order: "
+ + prev
+ + " then "
+ + s);
+ }
+ prev = s;
+ }
+ }
+}
diff --git a/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/PqRegistryBinding.java b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/PqRegistryBinding.java
new file mode 100755
index 000000000..780bf8360
--- /dev/null
+++ b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/PqRegistryBinding.java
@@ -0,0 +1,496 @@
+/*
+ * Copyright contributors to Besu.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.common.bft;
+
+import org.hyperledger.besu.crypto.SECPSignature;
+import org.hyperledger.besu.crypto.SignatureAlgorithmFactory;
+import org.hyperledger.besu.datatypes.Address;
+import org.hyperledger.besu.datatypes.Hash;
+import org.hyperledger.besu.ethereum.core.Util;
+
+import java.io.ByteArrayOutputStream;
+import java.nio.charset.StandardCharsets;
+import java.util.List;
+
+import org.apache.tuweni.bytes.Bytes;
+import org.apache.tuweni.bytes.Bytes32;
+import org.bouncycastle.crypto.digests.KeccakDigest;
+import org.bouncycastle.pqc.crypto.falcon.FalconParameters;
+import org.bouncycastle.pqc.crypto.falcon.FalconPublicKeyParameters;
+import org.bouncycastle.pqc.crypto.falcon.FalconSigner;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+/**
+ * AERE D-146: bind each registry row's FALCON PUBLIC KEY to the VALIDATOR ADDRESS it sits next to.
+ *
+ * <h2>The defect, measured on the real code path on 2026-08-06</h2>
+ *
+ * <p>{@link PqRegistryHash} makes the registry a chain-committed object: two nodes cannot hold
+ * different files without one of them refusing to start. It says so itself, in its own class
+ * javadoc: "It says nothing about whether any validator actually holds the private key matching its
+ * registered public key." That sentence is the whole of D-146.
+ *
+ * <p>Concretely, the registry is a table from index i to the pair (ECDSA validator address,
+ * Falcon public key). Seal verification uses the KEY at index i; signer eligibility is checked
+ * against the parent block's VALIDATOR SET, i.e. against the ADDRESS at index i. Nothing whatsoever
+ * connects the two halves of a row, so whoever writes the registry file may place any key under any
+ * address. Four consequences were measured with probes on the real verification path, all with the
+ * startup gate reporting MATCH and the header ACCEPTED:
+ *
+ * <ul>
+ * <li>T3: rebinding one row's address credits a seal made by validator 0's key to validator 1.
+ * <li>T4: putting ONE public key at TWO indices lets a SINGLE key holder produce two seals that
+ * are credited to two different addresses, so the threshold K is satisfied by one signer. The
+ * threshold itself becomes fiction, not merely the attribution.
+ * <li>T6A: SWAPPING two rows' public keys - no duplicate key, no duplicate address - is accepted.
+ * <li>T6B: SWAPPING two rows' addresses - again no duplicate of anything - is accepted, and every
+ * seal is then attributed to the wrong validator.
+ * </ul>
+ *
+ * <p>T6A and T6B are why this class exists and why a uniqueness check alone was not enough. Measured
+ * on 2026-08-06: both permuted registries carry 4 distinct public keys and 4 distinct addresses, so
+ * every uniqueness test passes, and the forged header is still ACCEPTED. Uniqueness restores the
+ * THRESHOLD (K verifying seals at K distinct indices are then necessarily K distinct keys); it can
+ * never restore ATTRIBUTION. Attribution needs a signature.
+ *
+ * <h2>What a row must now carry</h2>
+ *
+ * <p>Two proofs over ONE canonical pre-image, because one signature closes only half the defect:
+ *
+ * <ul>
+ * <li>POSSESSION, a Falcon signature by the row's own key. Proves the row is not an invented or
+ * truncated key and that somebody holds the matching secret. It does NOT close T3, T4 or T6:
+ * at the key ceremony the registry writer holds every Falcon secret, so it can sign a
+ * possession proof for key 0 sitting under validator 1's address. Anyone who claims a Falcon
+ * proof-of-possession repairs D-146 is wrong, and the probe measures it.
+ * <li>CLAIM, an ECDSA signature by the row's own VALIDATOR key. This is the half that cuts. The
+ * registry writer cannot forge it without validator i's consensus key, so a key cannot be
+ * moved under another validator's address, indices cannot be swapped, and a key cannot appear
+ * under an address whose owner did not ask for it.
+ * </ul>
+ *
+ * <h2>The canonical pre-image</h2>
+ *
+ * <pre>
+ * "AERE-PQ-POP-1" 13 bytes ASCII, at offset 0
+ * uint8(formatVersion) 1
+ * uint64be(chainId) 8
+ * uint64be(bindHeight) 8 the height in pqRegistryHash that makes THIS registry active
+ * uint32be(count) 4
+ * uint32be(index) 4
+ * address 20
+ * uint32be(len(publicKey)) 4
+ * publicKey len
+ * </pre>
+ *
+ * <p>Every field earns its place against a specific, named attack:
+ *
+ * <ul>
+ * <li>THE DOMAIN TAG, at offset 0 and inside the hashed pre-image rather than beside it. The same
+ * Falcon key signs anchor seals over {@code keccak(RLP["AERE-PQ-COMMIT-1", chainId, number,
+ * hash])} - also a 32-byte digest, also handed to the same {@link FalconSigner}. Without a
+ * distinct tag a possession proof would be a valid Falcon signature over a 32-byte digest and
+ * could be replayed as a SEAL, filling the threshold K with a validator that never ran a
+ * block. Ristenpart and Yilek (EUROCRYPT 2007) is the general form of this: a
+ * proof-of-possession that can be reused as a working signature is not a defence, it is a
+ * second door, and the repair is separate hash inputs for the two purposes.
+ * <li>publicKey IS IN THE SIGNED MESSAGE. Falcon is not Dilithium here: Cremers, Duzlu, Fiedler,
+ * Fischlin and Janson (IEEE S&amp;P 2021) measured that Falcon does NOT have exclusive
+ * ownership, because {@code HashToPoint(r || m)} never absorbs the public key. Putting the key
+ * into the message is the Pornin-Stern PS-3 transform applied at the application layer, with
+ * no change to the Falcon implementation and no growth in signature size. NOT MEASURED HERE: a
+ * concrete key-substitution forgery against Falcon-512 at our parameters was not executed;
+ * what is established is the missing property, from the literature.
+ * <li>chainId, from Ethereum's own scar. {@code DOMAIN_DEPOSIT} omits the genesis validators root,
+ * so deposit signatures replay BETWEEN CHAINS; EIP-8205 exists to add the separation. Our
+ * scratch chain 442807 runs the same binaries and can run the same Falcon keys.
+ * <li>index and bindHeight, so a row cannot be lifted to a different index, and a row retired at
+ * one rotation cannot be replayed into a later registry.
+ * <li>count, so a registry cannot be truncated and have its surviving proofs stay valid.
+ * </ul>
+ *
+ * <p>The CLAIM signs {@code keccak256(0x19 || 0x00 || context || preimage)}, the EIP-191 version-0
+ * envelope, with {@code context} the low 20 bytes of {@code keccak256("AERE-PQ-CLAIM-1" ||
+ * uint64be(chainId))}. The leading {@code 0x19} is the point: it cannot begin an RLP-encoded legacy
+ * transaction (those start at {@code 0xc0}) nor a typed one ({@code 0x01}..{@code 0x04}), so a
+ * validator's claim can never be replayed as a transaction it signed. The context byte string keeps
+ * this registry's claims disjoint from any other EIP-191 message on the same chain.
+ *
+ * <h2>Where this runs, and where it deliberately does not</h2>
+ *
+ * <p>AT LOAD, ONCE, from {@code PqRegistryHash.assemble}, which is the single point every loader
+ * funnels through, and fail-closed. The registry is immutable for the whole of an epoch, so the cost
+ * is N Falcon verifications plus N ecrecover per PROCESS START and exactly ZERO per block. At N=7,
+ * against the 0.068 ms median quoted in {@code PqAnchorSealsRule}, that is under a millisecond of
+ * startup.
+ *
+ * <p>NOT per seal. That would add K verifications to every block - about 0.2 ms at K=3 out of a
+ * 523 ms block - to re-establish a fact that cannot change within an epoch, and every line added to
+ * that loop is a permanent reconciliation cost against upstream Besu.
+ *
+ * <h2>What this does NOT defend against, stated plainly</h2>
+ *
+ * <ul>
+ * <li>NOT the holder of the vault. Every validator ECDSA key lives in one place; whoever has
+ * them signs a perfectly valid claim for any Falcon key they like. This moves the attack from
+ * "whoever can edit a file" to "whoever holds the consensus keys". The answer to "how many
+ * independent people must agree to stop this chain" is unchanged, and is one.
+ * <li>NOT the rewriting of historical epochs. The immutable anchor contract pins ONE hash, the
+ * head registry's at activation; earlier scheduled epochs are pinned by nothing on chain.
+ * <li>NOT key duplication. Possession is not exclusivity: a claim proves validator i asked for
+ * this key, never that nobody else has a copy. T4 is closed by the uniqueness rule in {@code
+ * PqRegistryHash.assemble}, not by either signature.
+ * <li>NOT anything about how a private key is stored or whether it was ever copied.
+ * </ul>
+ */
+public final class PqRegistryBinding {
+
+ private static final Logger LOG = LoggerFactory.getLogger(PqRegistryBinding.class);
+
+ /** Domain tag of the binding pre-image. Distinct from every other Falcon message we sign. */
+ public static final String DOMAIN_POSSESSION = "AERE-PQ-POP-1";
+
+ /** Domain tag mixed into the EIP-191 context of the ECDSA claim. */
+ public static final String DOMAIN_CLAIM = "AERE-PQ-CLAIM-1";
+
+ /** Registry format version that carries binding proofs. Version 1 carries none. */
+ public static final int FORMAT_VERSION = 2;
+
+ /** r(32) || s(32) || recId(1), the encoding {@code decodeSignature} expects. */
+ private static final int CLAIM_SIGNATURE_LENGTH = 65;
+
+ private PqRegistryBinding() {}
+
+ // ===================================================================================
+ // The canonical binding pre-image and its two digests
+ // ===================================================================================
+
+ /**
+ * The canonical binding pre-image for one registry row. Domain-separated, length-prefixed,
+ * chain-bound, height-bound and index-bound. See the class javadoc for why each field is there.
+ *
+ * @param chainId the chain this registry is bound to
+ * @param bindHeight the pqRegistryHash schedule height that makes this registry active
+ * @param count the number of rows in the registry
+ * @param index the row index
+ * @param address the 20-byte validator address of the row
+ * @param publicKey the Falcon public key of the row
+ * @return the pre-image bytes
+ */
+ public static byte[] bindingPreimage(
+ final long chainId,
+ final long bindHeight,
+ final int count,
+ final int index,
+ final byte[] address,
+ final byte[] publicKey) {
+ final ByteArrayOutputStream out = new ByteArrayOutputStream();
+ writeAll(out, DOMAIN_POSSESSION.getBytes(StandardCharsets.US_ASCII));
+ out.write(FORMAT_VERSION);
+ writeAll(out, uint64be(chainId));
+ writeAll(out, uint64be(bindHeight));
+ writeAll(out, uint32be(count));
+ writeAll(out, uint32be(index));
+ writeAll(out, address);
+ writeAll(out, uint32be(publicKey.length));
+ writeAll(out, publicKey);
+ return out.toByteArray();
+ }
+
+ /**
+ * The 32-byte message the row's FALCON key signs.
+ *
+ * @param chainId the chain id
+ * @param bindHeight the activation height of this registry
+ * @param count the registry size
+ * @param index the row index
+ * @param address the row's validator address
+ * @param publicKey the row's Falcon public key
+ * @return the possession digest
+ */
+ public static Bytes32 possessionDigest(
+ final long chainId,
+ final long bindHeight,
+ final int count,
+ final int index,
+ final byte[] address,
+ final byte[] publicKey) {
+ return Bytes32.wrap(
+ keccak(bindingPreimage(chainId, bindHeight, count, index, address, publicKey)));
+ }
+
+ /**
+ * The 32-byte message the row's VALIDATOR ECDSA key signs: the EIP-191 version-0 envelope around
+ * the same pre-image. The leading {@code 0x19} makes the claim unrepresentable as a transaction.
+ *
+ * @param chainId the chain id
+ * @param bindHeight the activation height of this registry
+ * @param count the registry size
+ * @param index the row index
+ * @param address the row's validator address
+ * @param publicKey the row's Falcon public key
+ * @return the claim digest
+ */
+ public static Bytes32 claimDigest(
+ final long chainId,
+ final long bindHeight,
+ final int count,
+ final int index,
+ final byte[] address,
+ final byte[] publicKey) {
+ final ByteArrayOutputStream out = new ByteArrayOutputStream();
+ out.write(0x19);
+ out.write(0x00);
+ writeAll(out, claimContext(chainId));
+ writeAll(out, bindingPreimage(chainId, bindHeight, count, index, address, publicKey));
+ return Bytes32.wrap(keccak(out.toByteArray()));
+ }
+
+ /**
+ * The 20-byte EIP-191 version-0 "intended validator" field for this chain's registry claims.
+ *
+ * @param chainId the chain id
+ * @return 20 context bytes
+ */
+ public static byte[] claimContext(final long chainId) {
+ final ByteArrayOutputStream out = new ByteArrayOutputStream();
+ writeAll(out, DOMAIN_CLAIM.getBytes(StandardCharsets.US_ASCII));
+ writeAll(out, uint64be(chainId));
+ final byte[] d = keccak(out.toByteArray());
+ final byte[] ctx = new byte[20];
+ System.arraycopy(d, 12, ctx, 0, 20);
+ return ctx;
+ }
+
+ // ===================================================================================
+ // Verification of one row
+ // ===================================================================================
+
+ /**
+ * Verify a Falcon possession proof. Never throws.
+ *
+ * @param publicKey the row's raw Falcon-512 public key
+ * @param digest the possession digest
+ * @param signature the Falcon signature bytes
+ * @return true iff the signature verifies under that key
+ */
+ public static boolean verifyPossession(
+ final byte[] publicKey, final Bytes32 digest, final byte[] signature) {
+ if (publicKey == null || digest == null || signature == null || signature.length == 0) {
+ return false;
+ }
+ try {
+ final FalconPublicKeyParameters pub =
+ new FalconPublicKeyParameters(FalconParameters.falcon_512, publicKey);
+ final FalconSigner verifier = new FalconSigner();
+ verifier.init(false, pub);
+ return verifier.verifySignature(digest.toArray(), signature);
+ } catch (final RuntimeException e) {
+ LOG.debug("AERE PQC D-146: Falcon possession verify threw: {}", e.toString());
+ return false;
+ }
+ }
+
+ /**
+ * Recover the address that produced an ECDSA claim. Never throws.
+ *
+ * @param digest the claim digest
+ * @param signature 65 bytes, r || s || recId
+ * @return the recovered address, or null when the signature is malformed or unrecoverable
+ */
+ public static Address recoverClaim(final Bytes32 digest, final byte[] signature) {
+ if (digest == null || signature == null || signature.length != CLAIM_SIGNATURE_LENGTH) {
+ return null;
+ }
+ try {
+ final SECPSignature s =
+ SignatureAlgorithmFactory.getInstance().decodeSignature(Bytes.wrap(signature));
+ return Util.signatureToAddress(s, Hash.wrap(digest));
+ } catch (final RuntimeException e) {
+ LOG.debug("AERE PQC D-146: claim recovery threw: {}", e.toString());
+ return null;
+ }
+ }
+
+ // ===================================================================================
+ // Verification of a whole registry, fail-closed
+ // ===================================================================================
+
+ /**
+ * Verify every binding proof in a proof-bound registry, and REFUSE on the first row that does not
+ * hold. Called from {@code PqRegistryHash.assemble}, so it runs on every load, on every node, at
+ * every restart, and not merely once at the key ceremony.
+ *
+ * <p>Fail-closed is the whole point and it is not a preference. The neighbouring defect recorded
+ * on 2026-08-06 is a configuration path that fails OPEN: a misplaced comma drops the schedule, the
+ * threshold falls to zero, and the node starts DISARMED with nothing visible anywhere. A binding
+ * check that logged and continued would be the same mistake with a different name.
+ *
+ * @param registry the loaded registry
+ * @throws PqRegistryHash.RegistryConfigException when any row's binding does not hold
+ */
+ public static void verifyOrThrow(final PqRegistryHash.Registry registry) {
+ if (!registry.proofBound()) {
+ return;
+ }
+ final String source = registry.sourcePath();
+ if (!registry.addressBound()) {
+ throw new PqRegistryHash.RegistryConfigException(
+ "AERE-PQC-REG-BIND-06",
+ "AERE PQC D-146: registry '"
+ + source
+ + "' carries binding proofs but is NOT address-bound. A proof binds a Falcon key to a "
+ + "validator ADDRESS; with no addresses there is nothing to bind to. Refusing "
+ + "(fail-closed).");
+ }
+ final long chainId = registry.declaredChainId();
+ final long bindHeight = registry.bindHeight();
+ final int count = registry.count();
+ final List<PqRegistryHash.Entry> entries = registry.entries();
+
+ for (final PqRegistryHash.Entry e : entries) {
+ final byte[] addr = e.address();
+ final byte[] pk = e.publicKey();
+ final byte[] pop = e.possessionProof();
+ final byte[] claim = e.claimProof();
+
+ if (pop == null || pop.length == 0) {
+ throw new PqRegistryHash.RegistryConfigException(
+ "AERE-PQC-REG-BIND-01",
+ "AERE PQC D-146: registry '"
+ + source
+ + "' index "
+ + e.index()
+ + " has NO possession proof while other rows have one. Binding must be all or "
+ + "nothing: one unproven row is a row whose key nobody has shown they hold, and it "
+ + "counts toward the threshold exactly like a proven one. Refusing (fail-closed).");
+ }
+ if (claim == null || claim.length == 0) {
+ throw new PqRegistryHash.RegistryConfigException(
+ "AERE-PQC-REG-BIND-02",
+ "AERE PQC D-146: registry '"
+ + source
+ + "' index "
+ + e.index()
+ + " has NO validator claim. The claim is the half that stops a key being filed "
+ + "under somebody else's address. Refusing (fail-closed).");
+ }
+
+ final Bytes32 popDigest =
+ possessionDigest(chainId, bindHeight, count, e.index(), addr, pk);
+ if (!verifyPossession(pk, popDigest, pop)) {
+ throw new PqRegistryHash.RegistryConfigException(
+ "AERE-PQC-REG-BIND-03",
+ "AERE PQC D-146: registry '"
+ + source
+ + "' index "
+ + e.index()
+ + " (address 0x"
+ + hex(addr)
+ + ") carries a possession proof that DOES NOT VERIFY under the public key on the "
+ + "same row, for chainId="
+ + chainId
+ + " bindHeight="
+ + bindHeight
+ + " count="
+ + count
+ + ". Either the key was replaced without re-signing, or the row was lifted from "
+ + "another index, another height or another chain. Refusing (fail-closed).");
+ }
+
+ final Bytes32 clDigest = claimDigest(chainId, bindHeight, count, e.index(), addr, pk);
+ final Address recovered = recoverClaim(clDigest, claim);
+ if (recovered == null) {
+ throw new PqRegistryHash.RegistryConfigException(
+ "AERE-PQC-REG-BIND-05",
+ "AERE PQC D-146: registry '"
+ + source
+ + "' index "
+ + e.index()
+ + " carries a claim of "
+ + claim.length
+ + " bytes that cannot be decoded as an ECDSA signature (expected exactly "
+ + CLAIM_SIGNATURE_LENGTH
+ + ": r||s||recId). Refusing (fail-closed).");
+ }
+ final Address bound = Address.wrap(Bytes.wrap(addr));
+ if (!recovered.equals(bound)) {
+ throw new PqRegistryHash.RegistryConfigException(
+ "AERE-PQC-REG-BIND-04",
+ "AERE PQC D-146: registry '"
+ + source
+ + "' index "
+ + e.index()
+ + " is bound to validator "
+ + bound
+ + " but its claim was signed by "
+ + recovered
+ + ". THIS IS THE DEFECT D-146 EXISTS FOR: the Falcon key on this row was filed "
+ + "under an address whose owner did not sign for it, so every seal made with that "
+ + "key would be credited to the wrong validator - and if the same key sits at two "
+ + "indices, a single key holder alone satisfies the quorum threshold. Refusing "
+ + "(fail-closed). WHAT TO DO: have validator "
+ + bound
+ + " sign the row with its own consensus key, or put the key back under the address "
+ + "that did sign it.");
+ }
+ }
+ LOG.info(
+ "AERE PQC D-146: registry '{}' - all {} rows carry a verified Falcon possession proof and a "
+ + "verified validator claim (chainId={}, bindHeight={}).",
+ source,
+ count,
+ chainId,
+ bindHeight);
+ }
+
+ // ===================================================================================
+ // Local helpers. Same shape as PqRegistryHash's, deliberately, so the two files can be read
+ // against each other without holding two conventions in your head.
+ // ===================================================================================
+
+ private static void writeAll(final ByteArrayOutputStream out, final byte[] b) {
+ out.write(b, 0, b.length);
+ }
+
+ private static byte[] uint32be(final int v) {
+ return new byte[] {(byte) (v >>> 24), (byte) (v >>> 16), (byte) (v >>> 8), (byte) v};
+ }
+
+ private static byte[] uint64be(final long v) {
+ final byte[] b = new byte[8];
+ for (int i = 0; i < 8; i++) {
+ b[i] = (byte) (v >>> (56 - 8 * i));
+ }
+ return b;
+ }
+
+ private static byte[] keccak(final byte[] input) {
+ final KeccakDigest kd = new KeccakDigest(256);
+ kd.update(input, 0, input.length);
+ final byte[] d = new byte[32];
+ kd.doFinal(d, 0);
+ return d;
+ }
+
+ private static String hex(final byte[] b) {
+ final StringBuilder s = new StringBuilder(b.length * 2);
+ for (final byte x : b) {
+ s.append(Character.forDigit((x >> 4) & 0xf, 16)).append(Character.forDigit(x & 0xf, 16));
+ }
+ return s.toString();
+ }
+}
diff --git a/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/PqRegistryHash.java b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/PqRegistryHash.java
new file mode 100755
index 000000000..01ee406ad
--- /dev/null
+++ b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/PqRegistryHash.java
@@ -0,0 +1,2339 @@
+/*
+ * Copyright contributors to Besu.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.common.bft;
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Locale;
+import java.util.Optional;
+import java.util.Properties;
+import java.util.TreeMap;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.google.common.base.Splitter;
+import org.bouncycastle.crypto.digests.KeccakDigest;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+/**
+ * AERE A8: bind the Falcon validator-index-to-public-key REGISTRY to consensus.
+ *
+ * <p>THE DEFECT THIS EXISTS TO CLOSE. Measured by reading {@code FalconSealSupport}: the registry
+ * that answers "which Falcon public key is validator index i" can be loaded from a plain local
+ * properties FILE named by {@code aere.falcon.registry} / {@code AERE_FALCON_REGISTRY}. Nothing ties
+ * that file to the chain. Two nodes handed two different files disagree about who index i is, so the
+ * SAME certificate verifies on one node and fails on the other. That is a network split with no
+ * attacker in it at all: an operator copying the wrong file is enough. The genesis-anchored and
+ * late-anchor sources do check a hash, but their failure mode is to leave the registry EMPTY and log
+ * an error, and the process still STARTS - so a node can run for a long time believing it is a
+ * verifying validator while it can verify nothing.
+ *
+ * <p>THE FIX. A canonical hash of the registry, {@code pqRegistryHash}, is fixed in the genesis
+ * configuration and bound to HEIGHT. At startup a node computes the canonical hash of whatever
+ * registry it actually loaded and compares it with the hash the schedule makes active at its chain
+ * head. On a mismatch the node REFUSES TO START, and the refusal states what it found and what it
+ * expected, entry by entry, so an operator can find the wrong file in one read instead of diffing
+ * seven nodes by hand.
+ *
+ * <p>WHY HEIGHT-BOUND. Chain 2800 has roughly 11.8 million blocks that were produced with no
+ * registry binding at all. A schedule whose first entry is at height H leaves every height below H
+ * completely unenforced, so nothing existing is invalidated, and a later entry expresses a key
+ * rotation. This is the same shape as every other fork gate in this codebase: the gate is on the
+ * block NUMBER, never on content.
+ *
+ * <p>WHAT THIS CLASS DOES NOT DO, stated plainly so nobody relies on absent protection:
+ *
+ * <ul>
+ * <li>The guard runs at STARTUP. It cannot stop a node that is already running when a scheduled
+ * rotation height arrives underneath it. {@link #requiredHashAt(Schedule, long)} and {@link
+ * #matchesAt} are public precisely so a per-block header rule can enforce the same binding on
+ * the consensus path once such a rule exists. No such rule exists today.
+ * <li>It does not check that the registry is the RIGHT one in any sense other than "it hashes to
+ * the value the chain's genesis says it must". The genesis value is a root of trust exactly
+ * like the genesis hash itself.
+ * <li>It says nothing about whether any validator actually holds the private key matching its
+ * registered public key.
+ * </ul>
+ */
+public final class PqRegistryHash {
+
+ private static final Logger LOG = LoggerFactory.getLogger(PqRegistryHash.class);
+
+ /** Domain tag of the canonical v1 pre-image. Any change here is a new format and a new height. */
+ public static final String DOMAIN_V1 = "AERE-PQ-REGISTRY-1";
+
+ /**
+ * Domain tag of the canonical v2 pre-image: the same registry PLUS the D-146 binding proofs. A
+ * separate tag, and not a flag inside v1, so that a v1 file and a v2 file can never hash equal and
+ * a downgrade that strips the proofs cannot satisfy a schedule entry that was written for v2.
+ */
+ public static final String DOMAIN_V2 = "AERE-PQ-REGISTRY-2";
+
+ /**
+ * Expected length of the Falcon-512 public key as THIS registry format stores it: the raw {@code
+ * h} polynomial, 512 coefficients at 14 bits, i.e. 896 bytes. MEASURED: every entry of
+ * {@code opt/aere-pqc/falcon-registry.properties} is 896 bytes. The 897 figure that appears in
+ * some notes is the standard encoding, which prepends a one-byte header; that header is NOT in
+ * these files, and {@code FalconSealSupport} feeds the bytes straight into
+ * {@code new FalconPublicKeyParameters(falcon_512, h)}, which also wants the bare {@code h}.
+ *
+ * <p>Used only for a diagnostic warning. It never rejects, because the canonical form is
+ * length-prefixed and is correct for any length.
+ */
+ private static final int FALCON_512_PK_LENGTH = 896;
+
+ /** Max registry entries printed in a refusal message before it is elided. */
+ private static final int MAX_ENTRIES_IN_REPORT = 64;
+
+ private PqRegistryHash() {}
+
+ // ===================================================================================
+ // Registry model
+ // ===================================================================================
+
+ /** Where a loaded registry came from. Part of every diagnostic, because it decides trust. */
+ public enum SourceKind {
+ /** {@code aere.falcon.registry}: a plain local properties file. No binding of its own. */
+ LEGACY_PROPERTIES,
+ /** {@code aere.falcon.manifest}: the address-bound JSON manifest of the late-anchor path. */
+ MANIFEST_JSON,
+ /** {@code aere.falcon.genesis}: the {@code config.aereFalconRegistry} manifest in genesis. */
+ GENESIS_MANIFEST,
+ /** No registry configured at all. */
+ NONE
+ }
+
+ /** One registry row: a validator index, its Falcon public key, and optionally its address. */
+ public static final class Entry {
+ private final int index;
+ private final byte[] address; // 20 bytes, or null when the source is not address-bound
+ private final byte[] publicKey;
+ private final byte[] possessionProof; // D-146, or null in a v1 registry
+ private final byte[] claimProof; // D-146, or null in a v1 registry
+
+ Entry(final int index, final byte[] address, final byte[] publicKey) {
+ this(index, address, publicKey, null, null);
+ }
+
+ Entry(
+ final int index,
+ final byte[] address,
+ final byte[] publicKey,
+ final byte[] possessionProof,
+ final byte[] claimProof) {
+ this.index = index;
+ this.address = address;
+ this.publicKey = publicKey;
+ this.possessionProof = possessionProof;
+ this.claimProof = claimProof;
+ }
+
+ /**
+ * The validator index this row binds.
+ *
+ * @return the index
+ */
+ public int index() {
+ return index;
+ }
+
+ /**
+ * The bound validator address, or null when the source carries public keys only.
+ *
+ * @return 20 address bytes, or null
+ */
+ public byte[] address() {
+ return address == null ? null : address.clone();
+ }
+
+ /**
+ * The Falcon-512 public key bytes.
+ *
+ * @return the public key
+ */
+ public byte[] publicKey() {
+ return publicKey.clone();
+ }
+
+ /**
+ * D-146. The Falcon signature by this row's own key over the binding pre-image, proving somebody
+ * holds the matching secret.
+ *
+ * @return the possession proof, or null in a v1 registry
+ */
+ public byte[] possessionProof() {
+ return possessionProof == null ? null : possessionProof.clone();
+ }
+
+ /**
+ * D-146. The ECDSA signature by this row's own VALIDATOR key over the binding pre-image. This is
+ * the half a registry writer cannot forge, and therefore the half that closes T3 and T6.
+ *
+ * @return the claim proof, or null in a v1 registry
+ */
+ public byte[] claimProof() {
+ return claimProof == null ? null : claimProof.clone();
+ }
+ }
+
+ /**
+ * A loaded registry in canonical order, with the provenance needed to explain a refusal.
+ *
+ * <p>Loading is STRICT and fail-closed. A registry whose shape is ambiguous has no well defined
+ * hash, and hashing an ambiguous object would produce a number that looks authoritative and means
+ * nothing. Every loader therefore rejects rather than guesses: {@code count} must be present,
+ * indices must be exactly {@code 0..count-1} with no gap and no extra, address binding must be
+ * all-or-nothing, and hex must be even-length and strictly hexadecimal.
+ */
+ public static final class Registry {
+ private final SourceKind kind;
+ private final String sourcePath;
+ private final List<Entry> entries; // ascending index, contiguous from 0
+ private final boolean addressBound;
+ private final boolean proofBound; // D-146: every row carries both binding proofs
+ private final long declaredChainId; // D-146: the chainId the proofs were signed over
+ private final long bindHeight; // D-146: the activation height the proofs were signed over
+
+ Registry(
+ final SourceKind kind,
+ final String sourcePath,
+ final List<Entry> entries,
+ final boolean addressBound) {
+ this(kind, sourcePath, entries, addressBound, false, -1L, -1L);
+ }
+
+ Registry(
+ final SourceKind kind,
+ final String sourcePath,
+ final List<Entry> entries,
+ final boolean addressBound,
+ final boolean proofBound,
+ final long declaredChainId,
+ final long bindHeight) {
+ this.kind = kind;
+ this.sourcePath = sourcePath;
+ this.entries = entries;
+ this.addressBound = addressBound;
+ this.proofBound = proofBound;
+ this.declaredChainId = declaredChainId;
+ this.bindHeight = bindHeight;
+ }
+
+ /**
+ * Where this registry was loaded from.
+ *
+ * @return the source kind
+ */
+ public SourceKind kind() {
+ return kind;
+ }
+
+ /**
+ * The file this registry was read from.
+ *
+ * @return the path as configured, or "(none)"
+ */
+ public String sourcePath() {
+ return sourcePath == null ? "(none)" : sourcePath;
+ }
+
+ /**
+ * Number of registry rows.
+ *
+ * @return the entry count
+ */
+ public int count() {
+ return entries.size();
+ }
+
+ /**
+ * The rows, ascending by index.
+ *
+ * @return an unmodifiable list
+ */
+ public List<Entry> entries() {
+ return List.copyOf(entries);
+ }
+
+ /**
+ * Whether every row carries a validator address.
+ *
+ * @return true iff address-bound
+ */
+ public boolean addressBound() {
+ return addressBound;
+ }
+
+ /**
+ * D-146. Whether every row carries a verified Falcon possession proof and a verified validator
+ * claim. False for every registry written before 2026-08-06.
+ *
+ * @return true iff proof-bound
+ */
+ public boolean proofBound() {
+ return proofBound;
+ }
+
+ /**
+ * D-146. The chain id the binding proofs were signed over, as the FILE declares it. Cross-checked
+ * against the node's real chain id by {@link #verifyOrAbort}: a registry lifted from the scratch
+ * chain carries proofs that verify perfectly among themselves and belong to another chain.
+ *
+ * @return the declared chain id, or -1 when not proof-bound
+ */
+ public long declaredChainId() {
+ return declaredChainId;
+ }
+
+ /**
+ * D-146. The pqRegistryHash schedule height the binding proofs were signed over, so a row
+ * retired at one rotation cannot be replayed into a later registry.
+ *
+ * @return the bind height, or -1 when not proof-bound
+ */
+ public long bindHeight() {
+ return bindHeight;
+ }
+ }
+
+ // ===================================================================================
+ // Canonical encodings
+ // ===================================================================================
+
+ /**
+ * The canonical v1 pre-image: domain-separated, length-prefixed, chain-bound.
+ *
+ * <pre>
+ * "AERE-PQ-REGISTRY-1" 18 bytes, ASCII
+ * uint64be(chainId) 8 bytes
+ * uint32be(count) 4 bytes
+ * for i in 0..count-1:
+ * uint32be(i) 4 bytes
+ * uint8(addressBound?1:0) 1 byte
+ * address 20 bytes, only when address-bound
+ * uint32be(len(publicKey)) 4 bytes
+ * publicKey len bytes
+ * </pre>
+ *
+ * <p>Three properties this buys, and each one is the answer to a specific way the older
+ * concatenation form could be argued with:
+ *
+ * <ul>
+ * <li>LENGTH PREFIXES. The legacy form concatenates raw keys with no separator. It is
+ * unambiguous only because Falcon-512 public keys happen to be a fixed 897 bytes. "Happens
+ * to be" is not a proof, and a future parameter set or a truncated key would silently make
+ * two different registries hash the same. With a length prefix in front of every variable
+ * field that argument cannot be made at all.
+ * <li>THE INDEX IS IN THE PRE-IMAGE. Not just the order. A registry that permutes two rows
+ * hashes differently even under a hash function that ignored order.
+ * <li>chainId IS IN THE PRE-IMAGE. The scratch chain 442807 runs the same binaries and can run
+ * the same Falcon keys; without chainId a registry lifted from there would hash equal here.
+ * </ul>
+ *
+ * @param registry the loaded registry
+ * @param chainId the chain id this registry is being bound to
+ * @return the pre-image bytes
+ */
+ public static byte[] canonicalPreimageV1(final Registry registry, final long chainId) {
+ final java.io.ByteArrayOutputStream out = new java.io.ByteArrayOutputStream();
+ writeAll(out, DOMAIN_V1.getBytes(StandardCharsets.US_ASCII));
+ writeAll(out, uint64be(chainId));
+ writeAll(out, uint32be(registry.count()));
+ for (final Entry e : registry.entries) {
+ writeAll(out, uint32be(e.index));
+ out.write(registry.addressBound ? 1 : 0);
+ if (registry.addressBound) {
+ writeAll(out, e.address);
+ }
+ writeAll(out, uint32be(e.publicKey.length));
+ writeAll(out, e.publicKey);
+ }
+ return out.toByteArray();
+ }
+
+ /**
+ * keccak256 of the canonical v1 pre-image, as 64-hex with no {@code 0x}.
+ *
+ * @param registry the loaded registry
+ * @param chainId the chain id this registry is bound to
+ * @return the canonical hash, lower-case, unprefixed
+ */
+ public static String hashV1(final Registry registry, final long chainId) {
+ return keccakHex(canonicalPreimageV1(registry, chainId));
+ }
+
+ /**
+ * D-146. The canonical v2 pre-image: everything v1 commits to, plus the activation height and the
+ * two binding proofs of every row.
+ *
+ * <pre>
+ * "AERE-PQ-REGISTRY-2" 18 bytes, ASCII
+ * uint64be(chainId) 8 bytes
+ * uint64be(bindHeight) 8 bytes
+ * uint32be(count) 4 bytes
+ * for i in 0..count-1:
+ * uint32be(i) 4 bytes
+ * uint8(1) 1 byte, address binding is mandatory in v2
+ * address 20 bytes
+ * uint32be(len(publicKey)) 4 bytes
+ * publicKey len bytes
+ * uint32be(len(possession)) 4 bytes
+ * possession len bytes
+ * uint32be(len(claim)) 4 bytes
+ * claim len bytes
+ * </pre>
+ *
+ * <p>WHY THE PROOFS ARE INSIDE THE HASH and not merely checked at load. The hash is the value that
+ * genesis anchors and, at arming, that the immutable anchor contract pins. If the proofs sat
+ * outside it, they would be advisory: a node could be handed the same registry with the proof
+ * fields deleted, it would hash the same, satisfy the schedule, and load without ever verifying
+ * anything. With them inside, stripping a proof is a different registry with a different hash and
+ * the existing A8 guard refuses it. That is also why v2 has its OWN domain tag: a v1 file cannot
+ * collide with a v2 schedule entry, so a format downgrade is refused by machinery that already
+ * exists rather than by a new rule that could be forgotten.
+ *
+ * @param registry the loaded registry, which must be proof-bound
+ * @param chainId the chain id this registry is being bound to
+ * @return the pre-image bytes
+ */
+ public static byte[] canonicalPreimageV2(final Registry registry, final long chainId) {
+ final java.io.ByteArrayOutputStream out = new java.io.ByteArrayOutputStream();
+ writeAll(out, DOMAIN_V2.getBytes(StandardCharsets.US_ASCII));
+ writeAll(out, uint64be(chainId));
+ writeAll(out, uint64be(registry.bindHeight()));
+ writeAll(out, uint32be(registry.count()));
+ for (final Entry e : registry.entries) {
+ writeAll(out, uint32be(e.index));
+ out.write(1);
+ writeAll(out, e.address);
+ writeAll(out, uint32be(e.publicKey.length));
+ writeAll(out, e.publicKey);
+ writeAll(out, uint32be(e.possessionProof.length));
+ writeAll(out, e.possessionProof);
+ writeAll(out, uint32be(e.claimProof.length));
+ writeAll(out, e.claimProof);
+ }
+ return out.toByteArray();
+ }
+
+ /**
+ * D-146. keccak256 of the canonical v2 pre-image, as 64-hex with no {@code 0x}.
+ *
+ * @param registry the loaded registry, which must be proof-bound
+ * @param chainId the chain id this registry is bound to
+ * @return the canonical v2 hash, lower-case, unprefixed
+ */
+ public static String hashV2(final Registry registry, final long chainId) {
+ return keccakHex(canonicalPreimageV2(registry, chainId));
+ }
+
+ /**
+ * D-146. The canonical hash OF THIS REGISTRY: v2 when it carries binding proofs, v1 when it does
+ * not. Every comparison against a schedule entry goes through here, so a proof-bound registry is
+ * compared as v2 everywhere and a legacy one keeps exactly the number it had before this change.
+ *
+ * @param registry the loaded registry
+ * @param chainId the chain id this registry is bound to
+ * @return the canonical hash for this registry's format
+ */
+ public static String hashFor(final Registry registry, final long chainId) {
+ return registry.proofBound() ? hashV2(registry, chainId) : hashV1(registry, chainId);
+ }
+
+ /**
+ * D-146. The ARMING precondition: refuse to arm the anchor over a registry whose rows are not
+ * bound to their validator addresses by signatures.
+ *
+ * <p>The shape is deliberately the same as {@code AERE-PQC-REG-ARM-01}, which already refuses to
+ * arm over a registry with no validator addresses at all, and for the same reason: arming is the
+ * last moment at which the registry format can still be changed. The anchor contract is immutable
+ * once written, so a fleet armed over unbound rows carries D-146 for the life of the chain.
+ *
+ * <p>WIRED 2026-08-06. It is called from {@code
+ * FalconSealSupport.requireRegistryBindingProofsOrAbort()}, in the constructor, immediately after
+ * {@code armingReadinessDiagnostic()} raises AERE-PQC-REG-ARM-01, and only when this node is armed
+ * (a configured {@code aere.falcon.forkBlock}, or an active certificate anchor). Until 2026-08-06
+ * this javadoc read "NOT WIRED YET", and while that was true a v1 registry with no proofs loaded
+ * on an armed node exactly as before.
+ *
+ * @param registry the registry the fleet is about to arm over
+ * @throws RegistryConfigException when the registry carries no binding proofs
+ */
+ public static void requireBindingsOrThrow(final Registry registry) {
+ if (registry != null && registry.proofBound()) {
+ return;
+ }
+ throw new RegistryConfigException(
+ "AERE-PQC-REG-ARM-02",
+ "AERE PQC D-146: REFUSING TO ARM (fail-closed) over the registry "
+ + (registry == null ? "(none)" : "'" + registry.sourcePath() + "'")
+ + ", which carries NO binding proofs. Nothing in such a registry connects a Falcon "
+ + "public key to the validator address on the same row, so whoever writes the file "
+ + "decides who a seal is credited to, and one key placed at two indices satisfies the "
+ + "quorum threshold on its own. Measured on the real verification path 2026-08-06: a "
+ + "registry with two rows' keys swapped, carrying no duplicate key and no duplicate "
+ + "address, produced an ACCEPTED header. WHAT TO DO: rebuild the registry in the v2 "
+ + "format, where every row carries a Falcon possession proof and an ECDSA claim signed "
+ + "by that validator's own consensus key, and set config.pqRegistryHash to its v2 hash.");
+ }
+
+ /**
+ * keccak256 of the LEGACY pre-image, byte-for-byte what {@code FalconSealSupport.parseManifest}
+ * already computes: the concatenation, in ascending index order, of {@code address||publicKey}
+ * when address-bound and {@code publicKey} alone otherwise.
+ *
+ * <p>Kept so that a {@code pqRegistryHash} can be cross-checked against the manifest hash already
+ * committed in the genesis {@code alloc} anchor slot, and so an operator can tell which of the two
+ * numbers they are holding. It is NOT the value {@code pqRegistryHash} is compared against: it has
+ * no domain tag, no chain binding and no length prefixes.
+ *
+ * @param registry the loaded registry
+ * @return the legacy hash, lower-case, unprefixed
+ */
+ public static String hashV0Legacy(final Registry registry) {
+ final java.io.ByteArrayOutputStream out = new java.io.ByteArrayOutputStream();
+ for (final Entry e : registry.entries) {
+ if (registry.addressBound) {
+ writeAll(out, e.address);
+ }
+ writeAll(out, e.publicKey);
+ }
+ return keccakHex(out.toByteArray());
+ }
+
+ /**
+ * A short, safe fingerprint of one row: the first 8 hex of {@code keccak256(address||publicKey)}.
+ *
+ * <p>This is the field that turns a refusal into a five-second diagnosis. Two operators comparing
+ * refusal messages from two nodes see immediately WHICH index differs, without moving any key
+ * material and without either of them having to trust the other's file.
+ *
+ * @param registry the loaded registry
+ * @param index the row index
+ * @return an 8-hex fingerprint, or "(absent)" when the index is not present
+ */
+ public static String fingerprint(final Registry registry, final int index) {
+ for (final Entry e : registry.entries) {
+ if (e.index == index) {
+ final java.io.ByteArrayOutputStream out = new java.io.ByteArrayOutputStream();
+ if (e.address != null) {
+ writeAll(out, e.address);
+ }
+ writeAll(out, e.publicKey);
+ return keccakHex(out.toByteArray()).substring(0, 8);
+ }
+ }
+ return "(absent)";
+ }
+
+ // ===================================================================================
+ // Loaders. All STRICT, all fail-closed.
+ // ===================================================================================
+
+ /**
+ * Load the LEGACY properties registry: {@code count=N} plus rows {@code i=<pk hex>}, and
+ * optionally {@code i.addr=<20-byte hex>} to make it address-bound.
+ *
+ * <p>Comments, blank lines, line order and surrounding whitespace do not affect the canonical
+ * hash: the hash is computed over the DECODED registry, not the file bytes. That is deliberate.
+ * Hashing the file bytes would make a node refuse to start because somebody added a comment, and a
+ * guard that fires on nothing real is a guard operators learn to switch off.
+ *
+ * @param path the properties file
+ * @return the loaded registry
+ * @throws RegistryConfigException on any ambiguity
+ */
+ public static Registry loadPropertiesRegistry(final Path path) {
+ final Properties p = new Properties();
+ try (InputStream in = Files.newInputStream(path)) {
+ p.load(in);
+ } catch (final IOException e) {
+ throw new RegistryConfigException(
+ "AERE-PQC-REG-LOAD-01",
+ "AERE PQC A8: cannot read the Falcon registry file '"
+ + path
+ + "': "
+ + e
+ + ". Refusing to continue (fail-closed): a node that cannot read its registry cannot "
+ + "verify a single Falcon seal, and starting it anyway would put an unverifying node "
+ + "into the validator set while it reports itself healthy.");
+ }
+
+ final String countRaw = p.getProperty("count");
+ if (countRaw == null) {
+ throw new RegistryConfigException(
+ "AERE-PQC-REG-LOAD-02",
+ "AERE PQC A8: the Falcon registry '"
+ + path
+ + "' has no 'count' property. Refusing to continue (fail-closed): without a declared "
+ + "count there is no way to tell a complete registry from one that lost its last "
+ + "lines in transit, and both would hash to something that looks valid. Add "
+ + "'count=<number of validators>'.");
+ }
+ final int count = parsePositiveInt(countRaw, "count", path.toString());
+
+ // AERE D-146. Header fields of the v2 format. A v1 node reading a v2 file does NOT silently
+ // ignore these: parseIndexOrThrow refuses an unrecognised key, so an old binary handed a bound
+ // registry REFUSES rather than loading it with the proofs dropped. That is the correct
+ // direction of failure and it is why the fields are plain top-level names.
+ final long declaredChainId = parseOptionalLong(p.getProperty("chainId"), "chainId", path.toString());
+ final long bindHeight = parseOptionalLong(p.getProperty("bindHeight"), "bindHeight", path.toString());
+ final int formatVersion =
+ (int) parseOptionalLong(p.getProperty("formatVersion"), "formatVersion", path.toString());
+
+ final TreeMap<Integer, byte[]> pks = new TreeMap<>();
+ final TreeMap<Integer, byte[]> addrs = new TreeMap<>();
+ final TreeMap<Integer, byte[]> pops = new TreeMap<>();
+ final TreeMap<Integer, byte[]> claims = new TreeMap<>();
+ for (final String name : p.stringPropertyNames()) {
+ if ("count".equals(name)
+ || "chainId".equals(name)
+ || "bindHeight".equals(name)
+ || "formatVersion".equals(name)) {
+ continue;
+ }
+ final String key = name.trim();
+ if (key.endsWith(".pop")) {
+ final int i =
+ parseIndexOrThrow(key.substring(0, key.length() - ".pop".length()), path.toString());
+ pops.put(i, strictHex(p.getProperty(name).trim(), "entry " + i + ".pop", path.toString()));
+ } else if (key.endsWith(".claim")) {
+ final int i =
+ parseIndexOrThrow(key.substring(0, key.length() - ".claim".length()), path.toString());
+ claims.put(
+ i, strictHex(p.getProperty(name).trim(), "entry " + i + ".claim", path.toString()));
+ } else if (key.endsWith(".addr")) {
+ final int i =
+ parseIndexOrThrow(key.substring(0, key.length() - ".addr".length()), path.toString());
+ final byte[] a = strictHex(p.getProperty(name).trim(), "entry " + i + ".addr", path.toString());
+ if (a.length != 20) {
+ throw new RegistryConfigException(
+ "AERE-PQC-REG-LOAD-03",
+ "AERE PQC A8: registry '"
+ + path
+ + "' entry "
+ + i
+ + ".addr is "
+ + a.length
+ + " bytes, expected exactly 20. Refusing to continue (fail-closed).");
+ }
+ addrs.put(i, a);
+ } else {
+ final int i = parseIndexOrThrow(key, path.toString());
+ pks.put(i, strictHex(p.getProperty(name).trim(), "entry " + i, path.toString()));
+ }
+ }
+ return assemble(
+ SourceKind.LEGACY_PROPERTIES,
+ path.toString(),
+ count,
+ pks,
+ addrs,
+ pops,
+ claims,
+ declaredChainId,
+ bindHeight,
+ formatVersion);
+ }
+
+ /**
+ * Load an address-bound JSON manifest: {@code {"count": N, "0": {"addr": "0x..", "pk": ".."},
+ * ...}}, or the legacy bare-string form {@code {"count": N, "0": "<pk hex>", ...}}.
+ *
+ * @param path the manifest file
+ * @return the loaded registry
+ * @throws RegistryConfigException on any ambiguity
+ */
+ public static Registry loadManifestJson(final Path path) {
+ return fromManifestNode(readJson(path), SourceKind.MANIFEST_JSON, path.toString());
+ }
+
+ /**
+ * Load the manifest embedded in a genesis file at {@code config.aereFalconRegistry}.
+ *
+ * @param genesisPath the genesis file
+ * @return the loaded registry
+ * @throws RegistryConfigException on any ambiguity
+ */
+ public static Registry loadGenesisManifest(final Path genesisPath) {
+ final JsonNode cfg = readJson(genesisPath).path("config").path("aereFalconRegistry");
+ if (cfg.isMissingNode()) {
+ throw new RegistryConfigException(
+ "AERE-PQC-REG-LOAD-04",
+ "AERE PQC A8: genesis '"
+ + genesisPath
+ + "' has no config.aereFalconRegistry manifest. Refusing to continue (fail-closed).");
+ }
+ return fromManifestNode(cfg, SourceKind.GENESIS_MANIFEST, genesisPath.toString());
+ }
+
+ /**
+ * Sniff the file and load it with the right loader: a genesis file if it has
+ * {@code config.aereFalconRegistry}, a bare manifest if it is JSON, otherwise properties.
+ *
+ * @param path any registry file
+ * @return the loaded registry
+ */
+ public static Registry loadAuto(final Path path) {
+ final byte[] raw;
+ try {
+ raw = Files.readAllBytes(path);
+ } catch (final IOException e) {
+ throw new RegistryConfigException(
+ "AERE-PQC-REG-LOAD-01",
+ "AERE PQC A8: cannot read '" + path + "': " + e + ". Refusing to continue (fail-closed).");
+ }
+ int i = 0;
+ while (i < raw.length && Character.isWhitespace((char) (raw[i] & 0xff))) {
+ i++;
+ }
+ if (i < raw.length && raw[i] == '{') {
+ final JsonNode root = readJson(path);
+ if (!root.path("config").path("aereFalconRegistry").isMissingNode()) {
+ return loadGenesisManifest(path);
+ }
+ return fromManifestNode(root, SourceKind.MANIFEST_JSON, path.toString());
+ }
+ return loadPropertiesRegistry(path);
+ }
+
+ private static Registry fromManifestNode(
+ final JsonNode cfg, final SourceKind kind, final String source) {
+ if (cfg == null || cfg.isMissingNode() || !cfg.has("count")) {
+ throw new RegistryConfigException(
+ "AERE-PQC-REG-LOAD-05",
+ "AERE PQC A8: manifest '" + source + "' has no 'count'. Refusing (fail-closed).");
+ }
+ final int count = parsePositiveInt(cfg.get("count").asText(), "count", source);
+
+ // Every numeric field present must be inside 0..count-1.
+ //
+ // FOUND BY THE PLANTED-FAILURE HARNESS, case L1, in the first run of this code: without this
+ // check a manifest that declares count=6 while carrying 7 rows loaded happily as a 6-row
+ // registry, because the loop below only ever asks for indices 0..count-1 and never looks at
+ // what else is in the file. That is precisely the failure this whole class exists to prevent -
+ // a registry that is quietly not the file the operator thinks it is - reintroduced one level
+ // down. Two nodes with the same file but different 'count' would have hashed differently.
+ final List<String> strays = new ArrayList<>();
+ final java.util.Iterator<String> names = cfg.fieldNames();
+ while (names.hasNext()) {
+ final String n = names.next();
+ if ("count".equals(n)
+ || "chainId".equals(n)
+ || "bindHeight".equals(n)
+ || "formatVersion".equals(n)) {
+ continue;
+ }
+ final int idx;
+ try {
+ idx = Integer.parseInt(n.trim());
+ } catch (final NumberFormatException e) {
+ throw new RegistryConfigException(
+ "AERE-PQC-REG-LOAD-18",
+ "AERE PQC A8: manifest '"
+ + source
+ + "' has the unrecognised field '"
+ + n
+ + "'. Every field must be 'count' or a validator index. Refusing (fail-closed).");
+ }
+ if (idx < 0 || idx >= count) {
+ strays.add(n);
+ }
+ }
+ if (!strays.isEmpty()) {
+ throw new RegistryConfigException(
+ "AERE-PQC-REG-LOAD-09",
+ "AERE PQC A8: manifest '"
+ + source
+ + "' declares count="
+ + count
+ + " but also carries entr"
+ + (strays.size() == 1 ? "y " : "ies ")
+ + strays
+ + ", outside 0.."
+ + (count - 1)
+ + ". Refusing (fail-closed): those rows would have been SILENTLY DROPPED and the "
+ + "remainder would still have hashed to a perfectly valid-looking value.");
+ }
+
+ final long declaredChainId =
+ cfg.has("chainId") ? parseOptionalLong(cfg.get("chainId").asText(), "chainId", source) : -1L;
+ final long bindHeight =
+ cfg.has("bindHeight")
+ ? parseOptionalLong(cfg.get("bindHeight").asText(), "bindHeight", source)
+ : -1L;
+ final int formatVersion =
+ cfg.has("formatVersion")
+ ? (int) parseOptionalLong(cfg.get("formatVersion").asText(), "formatVersion", source)
+ : -1;
+
+ final TreeMap<Integer, byte[]> pks = new TreeMap<>();
+ final TreeMap<Integer, byte[]> addrs = new TreeMap<>();
+ final TreeMap<Integer, byte[]> pops = new TreeMap<>();
+ final TreeMap<Integer, byte[]> claims = new TreeMap<>();
+ for (int i = 0; i < count; i++) {
+ final JsonNode e = cfg.get(Integer.toString(i));
+ if (e == null) {
+ throw new RegistryConfigException(
+ "AERE-PQC-REG-LOAD-06",
+ "AERE PQC A8: manifest '"
+ + source
+ + "' declares count="
+ + count
+ + " but has no entry '"
+ + i
+ + "'. Refusing (fail-closed).");
+ }
+ if (e.isObject()) {
+ final JsonNode a = e.get("addr");
+ final JsonNode k = e.get("pk");
+ if (a == null || !a.isTextual() || k == null || !k.isTextual()) {
+ throw new RegistryConfigException(
+ "AERE-PQC-REG-LOAD-07",
+ "AERE PQC A8: manifest '"
+ + source
+ + "' entry "
+ + i
+ + " is an object but lacks textual 'addr' and 'pk'. Refusing (fail-closed).");
+ }
+ final byte[] addr = strictHex(a.asText().trim(), "entry " + i + ".addr", source);
+ if (addr.length != 20) {
+ throw new RegistryConfigException(
+ "AERE-PQC-REG-LOAD-03",
+ "AERE PQC A8: manifest '"
+ + source
+ + "' entry "
+ + i
+ + " addr is "
+ + addr.length
+ + " bytes, expected 20. Refusing (fail-closed).");
+ }
+ addrs.put(i, addr);
+ pks.put(i, strictHex(k.asText().trim(), "entry " + i + ".pk", source));
+ final JsonNode pop = e.get("pop");
+ final JsonNode claim = e.get("claim");
+ if (pop != null && pop.isTextual()) {
+ pops.put(i, strictHex(pop.asText().trim(), "entry " + i + ".pop", source));
+ }
+ if (claim != null && claim.isTextual()) {
+ claims.put(i, strictHex(claim.asText().trim(), "entry " + i + ".claim", source));
+ }
+ } else if (e.isTextual()) {
+ pks.put(i, strictHex(e.asText().trim(), "entry " + i, source));
+ } else {
+ throw new RegistryConfigException(
+ "AERE-PQC-REG-LOAD-08",
+ "AERE PQC A8: manifest '"
+ + source
+ + "' entry "
+ + i
+ + " is neither an object nor a hex string. Refusing (fail-closed).");
+ }
+ }
+ return assemble(
+ kind, source, count, pks, addrs, pops, claims, declaredChainId, bindHeight, formatVersion);
+ }
+
+ /**
+ * MEASURED 2026-08-02, on the first build of this class INSIDE Besu. These two parameters were
+ * declared {@code TreeMap}. Besu compiles with Error Prone's {@code NonApiType} check and {@code
+ * -Werror}, so a concrete collection type in a method signature is a build FAILURE, not a style
+ * note. This file had been type-checked standalone with {@code javac -Xlint:all} and reported
+ * clean; that is a weaker statement than it sounds, and the difference is the whole reason the
+ * wiring had to be compiled in the real tree before A8 could be called closed. {@code
+ * NavigableMap} keeps the guarantee the code actually relies on, which is ascending key order.
+ */
+ private static Registry assemble(
+ final SourceKind kind,
+ final String source,
+ final int count,
+ final java.util.NavigableMap<Integer, byte[]> pks,
+ final java.util.NavigableMap<Integer, byte[]> addrs,
+ final java.util.NavigableMap<Integer, byte[]> pops,
+ final java.util.NavigableMap<Integer, byte[]> claims,
+ final long declaredChainId,
+ final long bindHeight,
+ final int declaredFormatVersion) {
+
+ if (pks.size() != count) {
+ throw new RegistryConfigException(
+ "AERE-PQC-REG-LOAD-09",
+ "AERE PQC A8: registry '"
+ + source
+ + "' declares count="
+ + count
+ + " but carries "
+ + pks.size()
+ + " public-key entr"
+ + (pks.size() == 1 ? "y" : "ies")
+ + " (indices present: "
+ + pks.keySet()
+ + "). Refusing (fail-closed): a registry whose declared size and real size disagree "
+ + "has no canonical form, so any hash of it would be meaningless.");
+ }
+ for (int i = 0; i < count; i++) {
+ if (!pks.containsKey(i)) {
+ throw new RegistryConfigException(
+ "AERE-PQC-REG-LOAD-10",
+ "AERE PQC A8: registry '"
+ + source
+ + "' is missing index "
+ + i
+ + "; indices must be exactly 0.."
+ + (count - 1)
+ + " with no gap. Indices present: "
+ + pks.keySet()
+ + ". Refusing (fail-closed).");
+ }
+ if (pks.get(i).length == 0) {
+ throw new RegistryConfigException(
+ "AERE-PQC-REG-LOAD-11",
+ "AERE PQC A8: registry '" + source + "' index " + i + " has an EMPTY public key. "
+ + "Refusing (fail-closed).");
+ }
+ }
+ final boolean bound;
+ if (addrs.isEmpty()) {
+ bound = false;
+ } else if (addrs.size() == count) {
+ bound = true;
+ for (int i = 0; i < count; i++) {
+ if (!addrs.containsKey(i)) {
+ throw new RegistryConfigException(
+ "AERE-PQC-REG-LOAD-12",
+ "AERE PQC A8: registry '"
+ + source
+ + "' binds addresses for "
+ + addrs.keySet()
+ + " but not for index "
+ + i
+ + ". Address binding must be all or nothing. Refusing (fail-closed).");
+ }
+ }
+ } else {
+ throw new RegistryConfigException(
+ "AERE-PQC-REG-LOAD-12",
+ "AERE PQC A8: registry '"
+ + source
+ + "' is MIXED: "
+ + addrs.size()
+ + " of "
+ + count
+ + " entries carry a validator address. Address binding must be all or nothing, "
+ + "otherwise the eligible-signer set is not well defined. Refusing (fail-closed).");
+ }
+
+ // ===============================================================================
+ // AERE D-146 (2026-08-06). UNIQUENESS. Nothing here needs a signature, and it is the half that
+ // makes the THRESHOLD real again.
+ //
+ // MEASURED on the real verification path: a registry carrying ONE public key at TWO indices was
+ // loaded without a word, and two seals produced by a SINGLE Falcon private key - distinct
+ // signatures, because Falcon is randomised - were credited to two different validator addresses
+ // and satisfied a threshold of K=2. At K=3 one key holder alone would produce a certificate the
+ // chain calls a quorum. With distinct keys at every index, K verifying seals at K distinct
+ // indices are necessarily K distinct key holders again.
+ //
+ // Duplicate ADDRESSES are refused here too. Today they are already caught one layer up, by the
+ // `counted` set in PqAnchorSealsRule, but that is an availability trap rather than a defence:
+ // one address duplicated by mistake stops the chain instead of falsifying it, and it stops it at
+ // the activation height rather than at the moment the bad file was written. Refusing at load
+ // turns a fleet-wide halt into a node that will not start and says why.
+ final java.util.Map<String, Integer> seenPk = new java.util.HashMap<>();
+ for (int i = 0; i < count; i++) {
+ final String fp = keccakHex(pks.get(i));
+ final Integer first = seenPk.putIfAbsent(fp, i);
+ if (first != null) {
+ throw new RegistryConfigException(
+ "AERE-PQC-REG-LOAD-19",
+ "AERE PQC D-146: registry '"
+ + source
+ + "' carries the SAME Falcon public key at index "
+ + first
+ + " and index "
+ + i
+ + " (key digest "
+ + fp.substring(0, 16)
+ + "). Refusing (fail-closed): the anchor threshold counts DISTINCT INDICES, so one "
+ + "key holder sitting at two indices produces two seals that satisfy a threshold of "
+ + "two on their own. The threshold would stop meaning 'K validators attested' and "
+ + "start meaning 'K rows attested', which is not a quorum of anything.");
+ }
+ }
+ if (bound) {
+ final java.util.Map<String, Integer> seenAddr = new java.util.HashMap<>();
+ for (int i = 0; i < count; i++) {
+ final String a = hex(addrs.get(i));
+ final Integer first = seenAddr.putIfAbsent(a, i);
+ if (first != null) {
+ throw new RegistryConfigException(
+ "AERE-PQC-REG-LOAD-20",
+ "AERE PQC D-146: registry '"
+ + source
+ + "' binds the SAME validator address 0x"
+ + a
+ + " at index "
+ + first
+ + " and index "
+ + i
+ + ". Refusing (fail-closed): the seals rule counts each address once, so the "
+ + "second index can never contribute and the fleet silently loses a signer - "
+ + "measured as a REJECTED header at threshold K=2 with two honest signers.");
+ }
+ }
+ }
+
+ // AERE D-146. FORMAT COHERENCE. Binding proofs are all-or-nothing, exactly like address binding,
+ // and for the same reason: one unproven row counts toward the threshold like a proven one.
+ final boolean anyProof = !pops.isEmpty() || !claims.isEmpty();
+ final boolean proofBound;
+ if (anyProof || declaredFormatVersion == PqRegistryBinding.FORMAT_VERSION) {
+ if (pops.size() != count || claims.size() != count) {
+ throw new RegistryConfigException(
+ "AERE-PQC-REG-LOAD-21",
+ "AERE PQC D-146: registry '"
+ + source
+ + "' declares count="
+ + count
+ + " but carries "
+ + pops.size()
+ + " possession proof(s) and "
+ + claims.size()
+ + " validator claim(s). Binding must be ALL OR NOTHING. Refusing (fail-closed): a "
+ + "registry that is bound for some rows and unbound for others has exactly the "
+ + "security of its unbound rows, while looking bound.");
+ }
+ if (declaredChainId < 0 || bindHeight < 0) {
+ throw new RegistryConfigException(
+ "AERE-PQC-REG-LOAD-22",
+ "AERE PQC D-146: registry '"
+ + source
+ + "' carries binding proofs but does not declare both 'chainId' and 'bindHeight'. "
+ + "Both are inside the signed message, so without them the proofs cannot even be "
+ + "checked, let alone trusted. Refusing (fail-closed).");
+ }
+ proofBound = true;
+ } else {
+ proofBound = false;
+ }
+
+ final List<Entry> entries = new ArrayList<>(count);
+ for (int i = 0; i < count; i++) {
+ entries.add(
+ new Entry(
+ i,
+ bound ? addrs.get(i) : null,
+ pks.get(i),
+ proofBound ? pops.get(i) : null,
+ proofBound ? claims.get(i) : null));
+ if (pks.get(i).length != FALCON_512_PK_LENGTH) {
+ LOG.warn(
+ "AERE PQC A8: registry '{}' index {} carries a {}-byte public key; Falcon-512 public "
+ + "keys are {} bytes. The registry is NOT rejected for this (the canonical form is "
+ + "length-prefixed and handles any length), but it is almost certainly the wrong "
+ + "file or a truncated copy.",
+ source,
+ i,
+ pks.get(i).length,
+ FALCON_512_PK_LENGTH);
+ }
+ }
+ final Registry assembled =
+ new Registry(kind, source, entries, bound, proofBound, declaredChainId, bindHeight);
+ // AERE D-146. THE VERIFICATION ITSELF, on the single path every loader funnels through, so it
+ // runs at every restart on every node and not only once at the ceremony. Fail-closed, and O(N)
+ // per process start with zero cost per block.
+ PqRegistryBinding.verifyOrThrow(assembled);
+ if (!proofBound) {
+ LOG.warn(
+ "AERE PQC D-146: registry '{}' ({} rows) carries NO binding proofs. Nothing in it "
+ + "connects a Falcon public key to the validator address on the same row, so whoever "
+ + "wrote this file decided who every seal is credited to. Measured 2026-08-06 on the "
+ + "real verification path: swapping two rows produces an ACCEPTED header with no "
+ + "duplicate key and no duplicate address. This is D-146 and it is not closed on this "
+ + "node.",
+ source,
+ count);
+ }
+ return assembled;
+ }
+
+ // ===================================================================================
+ // The height-bound schedule
+ // ===================================================================================
+
+ /** One scheduled binding: from {@code block} onwards the registry must hash to {@code hash}. */
+ public static final class ScheduleEntry {
+ private final long block;
+ private final String hash; // 64-hex, lower-case, no 0x
+
+ ScheduleEntry(final long block, final String hash) {
+ this.block = block;
+ this.hash = hash;
+ }
+
+ /**
+ * First height at which this binding applies.
+ *
+ * @return the block number
+ */
+ public long block() {
+ return block;
+ }
+
+ /**
+ * The required canonical registry hash.
+ *
+ * @return 64-hex, lower-case, no 0x prefix
+ */
+ public String hash() {
+ return hash;
+ }
+
+ @Override
+ public String toString() {
+ return "{block=" + block + ", hash=0x" + hash + "}";
+ }
+ }
+
+ /** The parsed {@code config.pqRegistryHash} schedule; possibly empty, meaning NOT ENFORCED. */
+ public static final class Schedule {
+ private final List<ScheduleEntry> entries; // strictly increasing block
+ private final String source;
+
+ Schedule(final List<ScheduleEntry> entries, final String source) {
+ this.entries = entries;
+ this.source = source;
+ }
+
+ /**
+ * Whether any binding is configured at all.
+ *
+ * @return true iff at least one schedule entry exists
+ */
+ public boolean enforced() {
+ return !entries.isEmpty();
+ }
+
+ /**
+ * The schedule entries, ascending by block.
+ *
+ * @return an unmodifiable list
+ */
+ public List<ScheduleEntry> entries() {
+ return List.copyOf(entries);
+ }
+
+ /**
+ * Where the schedule was read from.
+ *
+ * @return a human-readable source description
+ */
+ public String source() {
+ return source;
+ }
+
+ @Override
+ public String toString() {
+ return entries.toString();
+ }
+ }
+
+ /** An empty schedule: nothing is enforced. Preserves today's behaviour exactly. */
+ public static Schedule emptySchedule() {
+ return new Schedule(List.of(), "(none)");
+ }
+
+ /**
+ * Parse {@code config.pqRegistryHash} from a genesis file.
+ *
+ * <p>Two accepted shapes:
+ *
+ * <pre>
+ * "pqRegistryHash": "0x&lt;64 hex&gt;" -- bound from block 0
+ * "pqRegistryHash": [ {"block": H, "hash": "0x.."},
+ * {"block": H2, "hash": "0x.."} ] -- height-bound, with rotation
+ * </pre>
+ *
+ * <p>ABSENT means NOT ENFORCED, which is the only choice that leaves the 11.8 million existing
+ * blocks and every existing test network untouched. Absence is logged loudly, once, because a
+ * guard everybody believes is on and is not is worse than no guard.
+ *
+ * @param genesisPath the genesis file
+ * @return the parsed schedule, possibly empty
+ * @throws RegistryConfigException when the value is present but malformed
+ */
+ public static Schedule loadScheduleFromGenesis(final Path genesisPath) {
+ final JsonNode config = readJson(genesisPath).path("config");
+ return parseSchedule(config.get("pqRegistryHash"), genesisPath + " config.pqRegistryHash");
+ }
+
+ /**
+ * Parse a {@code pqRegistryHash} JSON value into a schedule.
+ *
+ * @param node the value, or null when absent
+ * @param source human-readable provenance for diagnostics
+ * @return the schedule, empty when the node is null or JSON null
+ * @throws RegistryConfigException when present but malformed
+ */
+ public static Schedule parseSchedule(final JsonNode node, final String source) {
+ if (node == null || node.isNull() || node.isMissingNode()) {
+ return new Schedule(List.of(), source + " (ABSENT)");
+ }
+ final List<ScheduleEntry> out = new ArrayList<>();
+ if (node.isTextual()) {
+ out.add(new ScheduleEntry(0L, normHash(node.asText().trim(), source)));
+ } else if (node.isArray()) {
+ if (node.isEmpty()) {
+ throw new RegistryConfigException(
+ "AERE-PQC-REG-SCHED-01",
+ "AERE PQC A8: "
+ + source
+ + " is an EMPTY array. Refusing to start (fail-closed): an empty schedule is not "
+ + "the same statement as an absent one, and guessing which was meant is exactly how "
+ + "a guard ends up switched off without anybody deciding to switch it off. Either "
+ + "remove the key entirely, or give it at least one {block, hash} entry.");
+ }
+ long previous = Long.MIN_VALUE;
+ for (final JsonNode e : node) {
+ if (!e.isObject() || !e.has("block") || !e.has("hash")) {
+ throw new RegistryConfigException(
+ "AERE-PQC-REG-SCHED-02",
+ "AERE PQC A8: "
+ + source
+ + " entry "
+ + e
+ + " is not an object with 'block' and 'hash'. Refusing to start (fail-closed).");
+ }
+ final long block = e.get("block").asLong(-1L);
+ if (block < 0) {
+ throw new RegistryConfigException(
+ "AERE-PQC-REG-SCHED-03",
+ "AERE PQC A8: "
+ + source
+ + " has a negative or unparseable block in "
+ + e
+ + ". Refusing to start (fail-closed).");
+ }
+ if (block <= previous) {
+ throw new RegistryConfigException(
+ "AERE-PQC-REG-SCHED-04",
+ "AERE PQC A8: "
+ + source
+ + " blocks are not STRICTLY INCREASING ("
+ + previous
+ + " then "
+ + block
+ + "). Refusing to start (fail-closed): with a repeated or out-of-order height "
+ + "two nodes reading the same file could pick different active entries, which is "
+ + "the very split this binding exists to prevent.");
+ }
+ previous = block;
+ out.add(new ScheduleEntry(block, normHash(e.get("hash").asText(), source)));
+ }
+ } else {
+ throw new RegistryConfigException(
+ "AERE-PQC-REG-SCHED-05",
+ "AERE PQC A8: "
+ + source
+ + " must be a 0x-prefixed 32-byte hash or an array of {block, hash}; found "
+ + node.getNodeType()
+ + ". Refusing to start (fail-closed).");
+ }
+ return new Schedule(out, source);
+ }
+
+ /**
+ * The registry hash required at a given height, or empty when no binding is active there.
+ *
+ * <p>Public because the startup guard is not the only place this belongs: a per-block header rule
+ * enforcing the same binding on the consensus path would call exactly this.
+ *
+ * @param schedule the parsed schedule
+ * @param blockNumber the height
+ * @return the active entry, or empty
+ */
+ public static Optional<ScheduleEntry> requiredHashAt(
+ final Schedule schedule, final long blockNumber) {
+ ScheduleEntry active = null;
+ for (final ScheduleEntry e : schedule.entries) {
+ if (e.block <= blockNumber) {
+ active = e;
+ } else {
+ break;
+ }
+ }
+ return Optional.ofNullable(active);
+ }
+
+ /** The first scheduled entry strictly after the given height, or empty. */
+ private static Optional<ScheduleEntry> nextAfter(final Schedule schedule, final long blockNumber) {
+ for (final ScheduleEntry e : schedule.entries) {
+ if (e.block > blockNumber) {
+ return Optional.of(e);
+ }
+ }
+ return Optional.empty();
+ }
+
+ /**
+ * Whether the given registry satisfies the binding active at a height. Never throws.
+ *
+ * @param schedule the parsed schedule
+ * @param registry the loaded registry, may be null
+ * @param blockNumber the height
+ * @param chainId the chain id
+ * @return true iff no binding is active there, or the registry hashes to the required value
+ */
+ public static boolean matchesAt(
+ final Schedule schedule,
+ final Registry registry,
+ final long blockNumber,
+ final long chainId) {
+ final Optional<ScheduleEntry> req = requiredHashAt(schedule, blockNumber);
+ if (req.isEmpty()) {
+ return true;
+ }
+ if (registry == null) {
+ return false;
+ }
+ return hashFor(registry, chainId).equalsIgnoreCase(req.get().hash);
+ }
+
+ // ===================================================================================
+ // D-081: the whole scheduled history, not only the entry in force at the head
+ // ===================================================================================
+
+ /**
+ * D-081. The registries a node holds, indexed by the SCHEDULE ENTRY each one satisfies.
+ *
+ * <p>THE DEFECT THIS EXISTS TO CLOSE, measured and not assumed. {@code config.pqRegistryHash} is a
+ * schedule, and a second entry is how a key rotation or a revocation is expressed. Enforcement,
+ * however, took exactly ONE loaded registry: {@link #matchesAt(Schedule, Registry, long, long)}
+ * resolves the entry active at a height and compares it against that single registry. After one
+ * rotation at H2 there are two intervals with two different required hashes, and one file can
+ * satisfy at most one of them. Measured on the real classes in {@code PqRegistryRotationTest}:
+ * a node holding the pre-rotation registry was refused at {12100000, 12100001}, a node holding the
+ * post-rotation registry was refused at {12000000, 12000001, 12099999}, and there was no third
+ * choice.
+ *
+ * <p>That is not confined to the rotation moment. {@code PqRegistryBindingRule} is DETACHED, so it
+ * runs on the header-download path, and {@code PqAnchorSyncModeGuard} refuses to start an armed
+ * node in anything but FULL sync. Every node acquiring history therefore validates the interval
+ * before the rotation AND has to reach the head. Using the rotation mechanism once made the chain
+ * permanently unjoinable, which means the mechanism was expressible and was not usable.
+ *
+ * <p>THE SHAPE OF THE REPAIR, and where it was learned. Cosmos ADR-016 keeps a rotation HISTORY
+ * mapping height to the consensus key in force there, precisely so that blocks signed under an
+ * older key stay verifiable, and bounds that history by the unbonding period. We keep the same
+ * mapping and we do NOT bound it: chain 2800 has no unbonding period and a node syncing from
+ * genesis must verify every block ever produced, so every entry ever scheduled stays loadable
+ * forever. Besu's own answer to the same class of question, the genesis {@code transitions} list,
+ * has the same shape: the value in force at a height is fixed by the height, lives in a document
+ * every node already holds byte-identically, and is never re-read from mutable state.
+ *
+ * <p>A set that does not cover every scheduled entry is NOT silently degraded. {@link
+ * #uncoveredEntryBlocks()} names exactly which heights have no registry, so the startup guard can
+ * refuse with the missing heights in hand instead of the operator discovering them one header at
+ * a time.
+ */
+ public static final class RegistrySet {
+ private final List<Registry> loaded;
+ private final List<Long> entryBlocks; // ascending, one per COVERED schedule entry
+ private final List<Registry> entryRegistries; // parallel to entryBlocks
+ private final List<Long> uncovered; // schedule entry blocks with no matching registry
+ private final List<Misbound> misbound; // D-B: hash matched, signed height did not
+
+ RegistrySet(
+ final List<Registry> loaded,
+ final List<Long> entryBlocks,
+ final List<Registry> entryRegistries,
+ final List<Long> uncovered) {
+ this(loaded, entryBlocks, entryRegistries, uncovered, List.of());
+ }
+
+ RegistrySet(
+ final List<Registry> loaded,
+ final List<Long> entryBlocks,
+ final List<Registry> entryRegistries,
+ final List<Long> uncovered,
+ final List<Misbound> misbound) {
+ this.loaded = loaded;
+ this.entryBlocks = entryBlocks;
+ this.entryRegistries = entryRegistries;
+ this.uncovered = uncovered;
+ this.misbound = misbound;
+ }
+
+ /**
+ * Every registry this node was given, in the order it was given them.
+ *
+ * @return an unmodifiable list
+ */
+ public List<Registry> loaded() {
+ return List.copyOf(loaded);
+ }
+
+ /**
+ * The registry this node SIGNS with, i.e. the first one it was given. Every other held file is
+ * history: loadable so that old blocks stay verifiable, never the one this node writes under.
+ *
+ * @return the primary registry, or null when this node holds none
+ */
+ public Registry primary() {
+ return loaded.isEmpty() ? null : loaded.get(0);
+ }
+
+ /**
+ * D-B. The schedule entries a held registry reproduces BY HASH and yet was not signed for.
+ *
+ * @return an unmodifiable list, empty when every covered entry is coherently signed
+ */
+ public List<Misbound> misbound() {
+ return List.copyOf(misbound);
+ }
+
+ /**
+ * The scheduled heights this node CAN answer for.
+ *
+ * @return an unmodifiable ascending list
+ */
+ public List<Long> coveredEntryBlocks() {
+ return List.copyOf(entryBlocks);
+ }
+
+ /**
+ * How many registries this node holds.
+ *
+ * @return the count
+ */
+ public int count() {
+ return loaded.size();
+ }
+
+ /**
+ * The scheduled heights for which this node holds NO registry at all.
+ *
+ * @return an unmodifiable ascending list, empty when the whole schedule is covered
+ */
+ public List<Long> uncoveredEntryBlocks() {
+ return List.copyOf(uncovered);
+ }
+
+ /**
+ * Whether this node can satisfy every entry the schedule contains.
+ *
+ * @return true iff nothing is uncovered
+ */
+ public boolean coversWholeSchedule() {
+ return uncovered.isEmpty();
+ }
+
+ /** The registry bound to a schedule entry, or null when that entry is uncovered. */
+ Registry forEntryBlock(final long entryBlock) {
+ for (int i = 0; i < entryBlocks.size(); i++) {
+ if (entryBlocks.get(i).longValue() == entryBlock) {
+ return entryRegistries.get(i);
+ }
+ }
+ return null;
+ }
+
+ @Override
+ public String toString() {
+ return "RegistrySet{held="
+ + loaded.size()
+ + ", covered="
+ + entryBlocks
+ + ", uncovered="
+ + uncovered
+ + '}';
+ }
+ }
+
+ /**
+ * D-081. Bind a set of loaded registries to the schedule by canonical hash.
+ *
+ * <p>The binding is by HASH and never by order or by file name: a registry covers the entry whose
+ * required hash it reproduces, and nothing else makes it cover anything. An operator therefore
+ * cannot mis-assign a file, only fail to supply one, and that failure is named.
+ *
+ * @param schedule the parsed schedule
+ * @param registries every registry this node holds; nulls are ignored
+ * @param chainId the chain id, part of the canonical pre-image
+ * @return the height-resolved set
+ */
+ public static RegistrySet buildSet(
+ final Schedule schedule, final List<Registry> registries, final long chainId) {
+ final List<Registry> held = new ArrayList<>();
+ for (final Registry r : registries) {
+ if (r != null) {
+ held.add(r);
+ }
+ }
+ final List<Long> blocks = new ArrayList<>();
+ final List<Registry> mapped = new ArrayList<>();
+ final List<Long> uncovered = new ArrayList<>();
+ final List<Misbound> misbound = new ArrayList<>();
+ for (final ScheduleEntry e : schedule.entries) {
+ Registry match = null;
+ for (final Registry r : held) {
+ if (!hashFor(r, chainId).equalsIgnoreCase(e.hash)) {
+ continue;
+ }
+ // AERE D-B (2026-08-06). THE LINK THAT WAS NEVER DRAWN. Both numbers have been in this
+ // lexical scope since D-081 was written and they were never put on the same expression.
+ //
+ // bindHeight is the height every row's possession proof and every row's validator claim
+ // were SIGNED OVER (PqRegistryBinding.bindingPreimage). e.block is the height from which
+ // genesis puts this registry IN FORCE. They are supposed to be the same number, and the
+ // hash cannot notice when they are not: bindHeight is INSIDE the v2 pre-image, so a file
+ // signed for 40 and scheduled from 70 reproduces its own hash perfectly. Measured
+ // 2026-08-06 on a network of seven: all 7 started, the chain ran to head 95, agreement was
+ // 7 of 7, zero errors and zero refusals - and the offline tool, on the same files, said RED.
+ // The node and the tool disagreed and nothing put them face to face.
+ //
+ // WHAT THAT BUYS AN OPERATOR WHO IS NOT SUPPOSED TO HAVE IT: moving the activation day
+ // costs two fresh signatures per validator if this is checked, and ZERO if it is not.
+ // The validators' agreement on a height is only an agreement if something refuses the
+ // heights they did not sign.
+ if (r.proofBound() && r.bindHeight() != e.block) {
+ misbound.add(new Misbound(e.block, e.hash, r.sourcePath(), r.bindHeight()));
+ continue;
+ }
+ match = r;
+ break;
+ }
+ if (match == null) {
+ uncovered.add(e.block);
+ } else {
+ blocks.add(e.block);
+ mapped.add(match);
+ }
+ }
+ return new RegistrySet(held, blocks, mapped, uncovered, misbound);
+ }
+
+ /**
+ * D-B. One schedule entry whose required hash a held registry reproduces, and whose height that
+ * registry's binding proofs were not signed over.
+ *
+ * @param entryBlock the height genesis puts the registry in force from
+ * @param entryHash the hash genesis requires there
+ * @param registryPath the file that reproduces that hash
+ * @param signedHeight the height the file's proofs were actually signed over
+ */
+ public record Misbound(
+ long entryBlock, String entryHash, String registryPath, long signedHeight) {}
+
+ /**
+ * D-081. Load every registry named and bind the result to the schedule.
+ *
+ * @param schedule the parsed schedule
+ * @param paths the registry files this node holds
+ * @param chainId the chain id
+ * @return the height-resolved set
+ * @throws RegistryConfigException when any file is unreadable or ambiguous
+ */
+ public static RegistrySet loadSet(
+ final Schedule schedule, final List<Path> paths, final long chainId) {
+ final List<Registry> registries = new ArrayList<>();
+ for (final Path p : paths) {
+ registries.add(loadAuto(p));
+ }
+ return buildSet(schedule, registries, chainId);
+ }
+
+ /**
+ * D-081. Split a comma-separated list of registry paths. Blank elements are dropped; a null or
+ * blank list gives an empty result rather than a path named "".
+ *
+ * @param raw the configured value, may be null
+ * @return the paths, in the order written
+ */
+ public static List<Path> parseRegistryPaths(final String raw) {
+ final List<Path> out = new ArrayList<>();
+ if (raw == null || raw.isBlank()) {
+ return out;
+ }
+ for (final String piece : Splitter.on(',').split(raw)) {
+ final String trimmed = piece.trim();
+ if (!trimmed.isEmpty()) {
+ out.add(Path.of(trimmed));
+ }
+ }
+ return out;
+ }
+
+ /**
+ * D-081. The registry in force at a height: the one bound to the schedule entry active there.
+ *
+ * <p>This is the function Falcon verification needs. A certificate in a block at height h was
+ * produced under the key set the chain required at h, so it must be checked against that key set
+ * and not against whatever the node happens to hold for the head.
+ *
+ * @param schedule the parsed schedule
+ * @param set the registries this node holds, may be null
+ * @param blockNumber the height
+ * @return the registry in force there, or empty when no binding is active or none is held
+ */
+ public static Optional<Registry> registryAt(
+ final Schedule schedule, final RegistrySet set, final long blockNumber) {
+ final Optional<ScheduleEntry> required = requiredHashAt(schedule, blockNumber);
+ if (required.isEmpty() || set == null) {
+ return Optional.empty();
+ }
+ return Optional.ofNullable(set.forEntryBlock(required.get().block));
+ }
+
+ /**
+ * D-081. Whether the registries this node holds satisfy the binding active at a height.
+ *
+ * <p>The hash is RECOMPUTED here rather than trusted from the binding built earlier, so that this
+ * answer is a positive proof about the bytes the node is holding right now and not a restatement
+ * of an earlier decision.
+ *
+ * @param schedule the parsed schedule
+ * @param set the registries this node holds, may be null
+ * @param blockNumber the height
+ * @param chainId the chain id
+ * @return true iff no binding is active there, or a held registry reproduces the required hash
+ */
+ public static boolean matchesAt(
+ final Schedule schedule,
+ final RegistrySet set,
+ final long blockNumber,
+ final long chainId) {
+ final Optional<ScheduleEntry> required = requiredHashAt(schedule, blockNumber);
+ if (required.isEmpty()) {
+ return true;
+ }
+ if (set == null) {
+ return false;
+ }
+ final Registry r = set.forEntryBlock(required.get().block);
+ return r != null && hashFor(r, chainId).equalsIgnoreCase(required.get().hash);
+ }
+
+ // ===================================================================================
+ // The startup guard
+ // ===================================================================================
+
+ /** Outcome of the startup guard. Exposed so tests and diagnostics can assert on it. */
+ public enum GateState {
+ /** No {@code pqRegistryHash} in genesis: nothing is enforced, exactly as before this change. */
+ NOT_ENFORCED_NO_SCHEDULE,
+ /** A schedule exists but its first height is still ahead of this node's chain head. */
+ NOT_ENFORCED_BELOW_FIRST_HEIGHT,
+ /** A binding is active at this height and the loaded registry satisfies it. */
+ MATCH,
+ /**
+ * AERE OPTIUNI-URGENTA: a binding is active, the registry does NOT satisfy it, and an operator
+ * explicitly overrode the refusal. The node is running and is NOT verifying certificates.
+ */
+ OVERRIDDEN_UNSAFE
+ }
+
+ /**
+ * Refusal to start, or refusal to accept a registry. Carries a stable machine-readable code so
+ * fleet tooling can match on it without parsing prose.
+ */
+ public static final class RegistryConfigException extends IllegalStateException {
+
+ private static final long serialVersionUID = 1L;
+
+ private final String code;
+
+ RegistryConfigException(final String code, final String message) {
+ super("[" + code + "] " + message);
+ this.code = code;
+ }
+
+ /**
+ * The stable code, e.g. {@code AERE-PQC-REG-MISMATCH-01}.
+ *
+ * @return the code
+ */
+ public String code() {
+ return code;
+ }
+ }
+
+ /**
+ * THE GUARD. Verify the registry this node actually loaded against the hash the genesis schedule
+ * makes active at the NEXT height this node will be asked to validate, chainHead + 1, and REFUSE
+ * TO START on a mismatch.
+ *
+ * <p>AERE CONSENS-LENS (2026-08-02): chainHead + 1, and not chainHead. That one block of
+ * difference was a permanent chain stop, measured on real nodes; the measurement and the
+ * reasoning are on the line that computes the height.
+ *
+ * <p>Call once during startup, from a point where a chain head exists and BEFORE the network and
+ * the consensus state machine are started, so that a refusal is a clean refusal to start rather
+ * than a mid-flight abort. The same place {@code verifyAttachHeightAgainstChainHeadOrAbort} is
+ * called from is correct.
+ *
+ * @param schedule the parsed {@code config.pqRegistryHash} schedule
+ * @param registry the registry this node loaded, or null if it loaded none
+ * @param chainHeadNumber this node's local chain head at startup
+ * @param chainId the chain id, which is part of the canonical pre-image
+ * @return the gate state on success
+ * @throws RegistryConfigException when a binding is active and the registry does not satisfy it
+ */
+ public static GateState verifyOrAbort(
+ final Schedule schedule,
+ final Registry registry,
+ final long chainHeadNumber,
+ final long chainId) {
+ return verifyOrAbort(
+ schedule,
+ buildSet(schedule, registry == null ? List.of() : List.of(registry), chainId),
+ chainHeadNumber,
+ chainId);
+ }
+
+ /**
+ * AERE D-A (2026-08-06). THE SAME GUARD, ASKED OF EVERY REGISTRY THIS NODE HOLDS.
+ *
+ * <p>WHY THIS OVERLOAD HAD TO EXIST, and it is not tidiness. D-081 gave a node a HISTORY of
+ * registry files, one per rotation the chain has ever performed, precisely so that a node can
+ * validate blocks produced under a retired key set. The startup guard was never told. It compared
+ * the schedule against ONE registry, the one named by {@code registrySourcePath}, and the history
+ * was read 41 lines further down - after the refusal had already been thrown. So the order of two
+ * blocks of code WAS the defect: after the first rotation, a node whose primary file is the
+ * post-rotation registry and whose history holds the pre-rotation one is correctly configured, and
+ * was refused to start with {@code AERE-PQC-REG-MISMATCH-01}. Re-confirmed 2026-08-06 with head at
+ * 2554. The consequence, stated plainly: after the first key rotation, no node in the fleet could
+ * be restarted with its own correct configuration without hand intervention.
+ *
+ * <p>The question this asks is unchanged - "is the binding the chain requires at the next height I
+ * will validate satisfied by something I hold" - only the word "something" is now honest.
+ *
+ * @param schedule the parsed {@code config.pqRegistryHash} schedule
+ * @param set every registry this node holds, resolved against the schedule
+ * @param chainHeadNumber this node's local chain head at startup
+ * @param chainId the chain id, which is part of the canonical pre-image
+ * @return the gate state on success
+ * @throws RegistryConfigException when a binding is active and nothing held satisfies it
+ */
+ public static GateState verifyOrAbort(
+ final Schedule schedule,
+ final RegistrySet set,
+ final long chainHeadNumber,
+ final long chainId) {
+
+ // AERE D-146. The proofs are signed over a chainId the FILE declares. A registry lifted from
+ // the scratch chain 442807 carries proofs that verify perfectly among themselves - they are
+ // internally consistent, just for another chain - and would otherwise pass. Fail-closed here,
+ // where the node's real chain id is known and the file's is not yet trusted.
+ //
+ // AERE D-A (2026-08-06): over EVERY held file, not only the primary. A history file lifted from
+ // the scratch chain is exactly as dangerous as a primary one - it is the file that answers for
+ // an interval of history - and before this it was never asked.
+ for (final Registry r : set.loaded()) {
+ if (r.proofBound() && r.declaredChainId() != chainId) {
+ throw new RegistryConfigException(
+ "AERE-PQC-REG-BIND-07",
+ "AERE PQC D-146: registry '"
+ + r.sourcePath()
+ + "' declares chainId="
+ + r.declaredChainId()
+ + " and its binding proofs are signed over that value, but this node is on chainId="
+ + chainId
+ + ". Refusing to start (fail-closed): the proofs in this file are valid, and they "
+ + "are valid for a different chain.");
+ }
+ }
+
+ final Registry registry = set.primary();
+
+ if (!schedule.enforced()) {
+ LOG.warn(
+ "AERE PQC A8: pqRegistryHash is NOT CONFIGURED ({}), so the Falcon registry is NOT bound "
+ + "to consensus on this node. The registry currently loaded is {} ({}, {} entries, "
+ + "address-bound={}), canonical hash 0x{}. Two nodes holding DIFFERENT registry files "
+ + "will disagree about which public key validator index i has, so the same "
+ + "certificate can verify on one and fail on the other. Put that hash into genesis as "
+ + "config.pqRegistryHash to close this.",
+ schedule.source(),
+ registry == null ? "(none)" : registry.sourcePath(),
+ registry == null ? SourceKind.NONE : registry.kind(),
+ registry == null ? 0 : registry.count(),
+ registry != null && registry.addressBound(),
+ // A8, measured on a fleet of seven on 2026-08-06: this printed hashV1 next to the text
+ // "put this in config.pqRegistryHash", while THE GATE compares hashFor, which for a
+ // registry carrying proofs is hashV2. With the printed value put into genesis, all seven
+ // nodes start, all seven report the registry loaded, and THE CHAIN STOPS AT H-1. The
+ // guard shouts NOT CORRECTLY STAGED, so it is not a silent halt, but the operator who
+ // follows the node's own instruction halts the fleet. A wrong instruction is more
+ // dangerous than no instruction at all.
+ registry == null ? "(no registry)" : hashFor(registry, chainId));
+ return GateState.NOT_ENFORCED_NO_SCHEDULE;
+ }
+
+ // AERE D-B (2026-08-06). THE SILENT DEFERRAL. Placed HERE, below the not-enforced exit above,
+ // and that position is a rule and not a preference: on chain 2800 config.pqRegistryHash does not
+ // exist, schedule.enforced() is false, and the return above is the first executable statement
+ // this guard reaches. Nothing new is ever put above it.
+ //
+ // WHY REFUSING IS RIGHT AND NOT MERELY SAFE. A misbound entry is not a missing file, which an
+ // operator can legitimately have; it is a file the operator DOES hold, which reproduces exactly
+ // the hash genesis names, and which the fleet signed for a DIFFERENT height. There is no honest
+ // reading of it. Refusing at startup also catches it before the height arrives, which is the
+ // whole point: an activation day moved under signed proofs is invisible until the day itself.
+ if (!set.misbound().isEmpty()) {
+ final StringBuilder rows = new StringBuilder();
+ for (final Misbound m : set.misbound()) {
+ rows.append(" genesis puts registry '")
+ .append(m.registryPath())
+ .append("' in force FROM BLOCK ")
+ .append(m.entryBlock())
+ .append(", and every binding proof in that file is signed over bindHeight=")
+ .append(m.signedHeight())
+ .append(" (entry hash 0x")
+ .append(m.entryHash())
+ .append(")\n");
+ }
+ throw new RegistryConfigException(
+ "AERE-PQC-REG-BIND-08",
+ "AERE PQC D-B: REFUSING TO START - a registry this node holds is scheduled at a height "
+ + "its validators never signed for.\n"
+ + " FIELD: 'bindHeight', inside the registry file, versus 'block' of the matching "
+ + "entry of config.pqRegistryHash in genesis ("
+ + schedule.source()
+ + ").\n"
+ + " READ:\n"
+ + rows
+ + " EXPECTED: bindHeight and the schedule entry's block are THE SAME NUMBER. Every "
+ + "row of a v2 registry carries a Falcon possession proof and an ECDSA claim by that "
+ + "validator's own consensus key, and both signatures cover the bind height. A "
+ + "registry in force from block B is every one of those validators stating that B is "
+ + "the height they agreed to.\n"
+ + " WHY THE HASH DID NOT CATCH THIS: bindHeight is INSIDE the v2 pre-image, so the "
+ + "file reproduces its own hash perfectly no matter which height genesis schedules it "
+ + "at. Hash-against-hash can never see this; only these two numbers side by side can. "
+ + "Measured 2026-08-06 on a network of seven: all seven started, the chain ran, "
+ + "agreement was 7 of 7, zero errors, zero refusals.\n"
+ + " WHAT IT WOULD HAVE COST AN ATTACKER OR A HURRIED OPERATOR: moving the activation "
+ + "day costs 14 fresh validator signatures when this is checked, and zero when it is "
+ + "not.\n"
+ + " REMEDY, and there are exactly two honest ones. EITHER put the schedule entry back "
+ + "to the height the file was signed for, on every node, because genesis is the "
+ + "document all seven hold byte-identically. OR re-run the key ceremony and have every "
+ + "validator re-sign its row for the new height, then set config.pqRegistryHash to the "
+ + "NEW hash of the re-signed file - it will be a different hash, because the height is "
+ + "inside it.\n"
+ + " DO NOT edit bindHeight in the file. The proofs are over it; the file would stop "
+ + "loading at all (AERE-PQC-REG-BIND-03).");
+ }
+
+ // AERE CONSENS-LENS (2026-08-02). THE HEIGHT THIS GUARD ASKS ABOUT IS chainHead + 1, and the
+ // one-block difference was a PERMANENT CHAIN STOP, measured on real nodes before this line was
+ // changed. With a schedule of two entries and a rotation at height X:
+ // - every node runs to X-1 and REFUSES header X (PqRegistryBindingRule,
+ // AERE-PQC-REG-BLOCK-01). Measured: head stopped at 11 with a rotation at 12.
+ // - the operator installs the registry the schedule requires FROM X and restarts. This guard,
+ // asked about the HEAD X-1, demanded the OLD hash and refused to start with
+ // AERE-PQC-REG-MISMATCH-01, exit 2. Measured.
+ // - the operator puts the OLD registry back: the node starts and still cannot pass X.
+ // Measured.
+ // Old registry: starts, cannot advance. New registry: cannot start. There was no third file,
+ // and the only exit measured was to set the emergency bypass on every node, i.e. to switch A8
+ // off across the whole fleet in order to cross a PLANNED rotation.
+ //
+ // chainHead + 1 is the question the node can actually act on: the only header it will be
+ // offered next is chainHead + 1, and PqRegistryBindingRule judges that header against the entry
+ // active AT THAT HEIGHT. Asking the same question here means the startup guard and the
+ // per-block rule can no longer disagree, which is the property that was missing. A node halted
+ // at X-1 now starts with the registry required from X. A node staged EARLY is refused at
+ // startup, and that is the honest verdict: it could not validate the blocks between its head
+ // and the rotation, and refusing at startup is better than stalling on the first header.
+ final long validationHeight =
+ chainHeadNumber == Long.MAX_VALUE ? chainHeadNumber : chainHeadNumber + 1;
+ final Optional<ScheduleEntry> active = requiredHashAt(schedule, validationHeight);
+
+ if (active.isEmpty()) {
+ final ScheduleEntry first = schedule.entries.get(0);
+ // AERE D-A: ask the SET, not only the primary. A node staged for the activation may already
+ // hold the activation registry as history while still signing under the current one.
+ final Registry staged = set.forEntryBlock(first.block());
+ final String computed = registry == null ? null : hashFor(registry, chainId);
+ if (staged != null) {
+ LOG.info(
+ "AERE PQC A8: registry binding is scheduled to start at block {} and this node's chain "
+ + "head is {}, so nothing is enforced yet. The registry already loaded ({}, {} "
+ + "entries) ALREADY MATCHES the hash required from block {}: 0x{}. This node is "
+ + "correctly staged for the activation.",
+ first.block(),
+ chainHeadNumber,
+ staged.sourcePath(),
+ staged.count(),
+ first.block(),
+ hashFor(staged, chainId));
+ } else {
+ LOG.error(
+ "AERE PQC A8: registry binding starts at block {} and this node's chain head is {}, so "
+ + "nothing is enforced yet AND THIS NODE IS NOT CORRECTLY STAGED. Required from "
+ + "block {}: 0x{}. Loaded here: {}. This node will run normally and will then "
+ + "REFUSE the header at block {} (AERE-PQC-REG-BLOCK-01) and stop there. Install "
+ + "the registry named above AT THAT HALT and restart. Do NOT install it earlier: "
+ + "from the moment it is installed this node can no longer validate the blocks "
+ + "between here and the rotation, and it will be refused at startup. NOTE the "
+ + "honest limitation: this guard runs at STARTUP only, so it will NOT stop this "
+ + "node while it keeps running.",
+ first.block(),
+ chainHeadNumber,
+ first.block(),
+ first.hash(),
+ computed == null ? "NO REGISTRY LOADED AT ALL" : "0x" + computed,
+ first.block());
+ }
+ return GateState.NOT_ENFORCED_BELOW_FIRST_HEIGHT;
+ }
+
+ final ScheduleEntry required = active.get();
+
+ if (set.count() == 0) {
+ throw new RegistryConfigException(
+ "AERE-PQC-REG-MISMATCH-02",
+ "AERE PQC A8: REFUSING TO START.\n"
+ + " EXPECTED: a Falcon validator registry whose canonical hash is\n"
+ + " 0x"
+ + required.hash()
+ + "\n"
+ + " required from block "
+ + required.block()
+ + " by genesis config.pqRegistryHash ("
+ + schedule.source()
+ + ").\n"
+ + " FOUND: NO REGISTRY AT ALL. None of the three registry sources is configured.\n"
+ + " Searched, in this order:\n"
+ + " 1) aere.falcon.genesis / AERE_FALCON_GENESIS (genesis manifest)\n"
+ + " 2) aere.falcon.manifest / AERE_FALCON_MANIFEST (late-anchor)\n"
+ + " 3) aere.falcon.registry / AERE_FALCON_REGISTRY (legacy properties)\n"
+ + " CHAIN HEAD: "
+ + chainHeadNumber
+ + " NEXT HEIGHT TO VALIDATE: "
+ + validationHeight
+ + " (the binding above is the one active AT THAT HEIGHT)\n"
+ + " CHAIN ID: "
+ + chainId
+ + "\n"
+ + " WHY THIS IS FATAL: from block "
+ + required.block()
+ + " this chain states which registry every node must hold. A node with no registry "
+ + "verifies no Falcon seal at all, so it would sit in the validator set reporting "
+ + "itself healthy while contributing nothing to the post-quantum layer.\n"
+ + " REMEDY: point one of the three properties above at the registry file whose hash "
+ + "is 0x"
+ + required.hash()
+ + ", then restart. Compute a file's hash with:\n"
+ + " java -cp <besu lib> "
+ + "org.hyperledger.besu.consensus.common.bft.tools.PqRegistryHashTool "
+ + "<file> --chain-id "
+ + chainId);
+ }
+
+ final String computed = hashFor(registry, chainId);
+ // AERE D-A (2026-08-06): the binding is satisfied by ANY file this node holds for this entry,
+ // not only by the one it signs with. Before this line the answer came from the primary registry
+ // alone, and after the first rotation the primary is by definition NOT the file that answers for
+ // the interval below the rotation.
+ final Registry bound = set.forEntryBlock(required.block());
+ if (bound != null) {
+ LOG.info(
+ "AERE PQC A8: registry binding SATISFIED. Loaded {} ({}, {} entries, address-bound={}); "
+ + "canonical hash 0x{} equals the hash required from block {} by genesis "
+ + "config.pqRegistryHash, read from [{}]. Chain head {}, chainId {}. This node holds "
+ + "{} registry file(s) in total. {}",
+ bound.sourcePath(),
+ bound.kind(),
+ bound.count(),
+ bound.addressBound(),
+ hashFor(bound, chainId),
+ required.block(),
+ // AERE A8: naming the PROVENANCE of the schedule is not decoration. The whole defect
+ // class is "a value that came from somewhere nobody checked", so a line that says the
+ // binding is satisfied without saying what it was read from asserts more than it knows.
+ schedule.source(),
+ chainHeadNumber,
+ chainId,
+ set.count(),
+ nextAfter(schedule, validationHeight)
+ .map(
+ n ->
+ "NEXT ROTATION: from block "
+ + n.block()
+ + " this node must hold a registry hashing to 0x"
+ + n.hash()
+ + (set.forEntryBlock(n.block()) != null
+ ? " - already satisfied by a file this node holds."
+ : " - NOTHING this node holds satisfies it. This node will run"
+ + " to block "
+ + (n.block() - 1)
+ + ", REFUSE the header at "
+ + n.block()
+ + " (AERE-PQC-REG-BLOCK-01) and stop there. Install the new file"
+ + " and name it in "
+ + "aere.falcon.registry.history, then restart."))
+ .orElse("No further rotation is scheduled."));
+ return GateState.MATCH;
+ }
+
+ throw new RegistryConfigException(
+ "AERE-PQC-REG-MISMATCH-01",
+ "AERE PQC A8: REFUSING TO START - the Falcon validator registry on this node is NOT the one "
+ + "this chain requires.\n"
+ + " EXPECTED hash: 0x"
+ + required.hash()
+ + "\n"
+ + " required from block "
+ + required.block()
+ + " by genesis config.pqRegistryHash ("
+ + schedule.source()
+ + ")\n"
+ + " FOUND hash: 0x"
+ + computed
+ + "\n"
+ + " CHAIN HEAD: "
+ + chainHeadNumber
+ + " NEXT HEIGHT TO VALIDATE: "
+ + validationHeight
+ + " (the binding above is the one active AT THAT HEIGHT)\n"
+ + " CHAIN ID: "
+ + chainId
+ + " (chainId is part of the hashed pre-image)\n"
+ + " FULL SCHEDULE: "
+ + schedule
+ + "\n"
+ + describeHeld(set, chainId)
+ + describeRegistry(registry, chainId)
+ + " WHY THIS IS FATAL: this file decides which Falcon public key belongs to validator "
+ + "index i. A node holding a different file disagrees with its peers about who index i "
+ + "is, so the SAME certificate verifies on one node and fails on another and the "
+ + "network splits with no attacker involved. Starting with the wrong file is strictly "
+ + "worse than not starting.\n"
+ + " HOW TO FIND THE WRONG ROW: every node prints the per-index fingerprints above. "
+ + "Compare them with a node that starts cleanly; the first index that differs is the "
+ + "row that was changed. The fingerprints are keccak digests, so they can be pasted "
+ + "into a chat without moving key material.\n"
+ + " REMEDY: this node must HOLD a file whose canonical hash is 0x"
+ + required.hash()
+ + ". It does not have to be the file this node signs with: name it in "
+ + "aere.falcon.registry.history (comma-separated) and every file listed there answers "
+ + "for the interval the schedule gives it. That list is never pruned - one file per "
+ + "rotation the chain has ever performed, kept forever. Then restart. To check a "
+ + "candidate file before restarting:\n"
+ + " java -cp <besu lib> "
+ + "org.hyperledger.besu.consensus.common.bft.tools.PqRegistryHashTool "
+ + "<file> --chain-id "
+ + chainId
+ + "\n"
+ + " DO NOT 'fix' this by editing genesis. The genesis value is what the rest of the "
+ + "fleet agrees on; changing it on this node alone makes this node the odd one out.");
+ }
+
+ /**
+ * AERE D-A. Every registry file this node holds and which scheduled interval each one answers for.
+ * Without this an operator reading {@code MISMATCH-01} cannot tell "I gave this node one file and
+ * it is the wrong one" from "I gave it four and none covers this height", which are different
+ * mistakes with different fixes.
+ */
+ private static String describeHeld(final RegistrySet set, final long chainId) {
+ final StringBuilder b = new StringBuilder();
+ b.append(" REGISTRY FILES THIS NODE HOLDS: ").append(set.count()).append('\n');
+ for (final Registry r : set.loaded()) {
+ final String h = hashFor(r, chainId);
+ Long covers = null;
+ for (final Long blk : set.coveredEntryBlocks()) {
+ if (set.forEntryBlock(blk) == r) {
+ covers = blk;
+ break;
+ }
+ }
+ b.append(" ")
+ .append(r.sourcePath())
+ .append(" hash=0x")
+ .append(h)
+ .append(" bindHeight=")
+ .append(r.proofBound() ? Long.toString(r.bindHeight()) : "(v1, unsigned)")
+ .append(" covers=")
+ .append(covers == null ? "NO SCHEDULED ENTRY" : "from block " + covers)
+ .append('\n');
+ }
+ if (!set.uncoveredEntryBlocks().isEmpty()) {
+ b.append(" scheduled heights covered by NOTHING held here: ")
+ .append(set.uncoveredEntryBlocks())
+ .append('\n');
+ }
+ return b.toString();
+ }
+
+ /** The "what I found" block of a refusal: source, shape, both hashes, per-index fingerprints. */
+ private static String describeRegistry(final Registry registry, final long chainId) {
+ final StringBuilder b = new StringBuilder();
+ b.append(" REGISTRY ACTUALLY LOADED:\n");
+ b.append(" source : ").append(registry.sourcePath()).append('\n');
+ b.append(" source kind : ").append(registry.kind()).append('\n');
+ b.append(" entries : ").append(registry.count()).append('\n');
+ b.append(" addressBound: ").append(registry.addressBound()).append('\n');
+ b.append(" format: ")
+ .append(registry.proofBound() ? "v2, D-146 binding proofs present" : "v1, NO binding proofs")
+ .append('\n');
+ // A8: the report printed both v1 and v2 without saying WHICH one goes into genesis, and
+ // whoever took the last value off the screen took v1 and halted the fleet at H-1. The one
+ // that matters is now named explicitly, and it is the very one the gate compares: hashFor.
+ b.append(" >>> FOR config.pqRegistryHash: 0x")
+ .append(hashFor(registry, chainId))
+ .append(" <<< this one, and only this one\n");
+ if (registry.proofBound()) {
+ b.append(" bindHeight: ").append(registry.bindHeight()).append('\n');
+ b.append(" canonical v2: 0x").append(hashV2(registry, chainId)).append(" (= the one above)\n");
+ }
+ b.append(" canonical v1: 0x").append(hashV1(registry, chainId))
+ .append(registry.proofBound() ? " (NOT this one: the registry carries proofs)\n" : " (= the one above)\n");
+ b.append(" legacy v0 : 0x")
+ .append(hashV0Legacy(registry))
+ .append(" (the older concat form, for cross-checking the genesis alloc anchor only)\n");
+ b.append(" per-index fingerprints, keccak256(addr||pk) first 8 hex:\n");
+ final int shown = Math.min(registry.count(), MAX_ENTRIES_IN_REPORT);
+ for (int i = 0; i < shown; i++) {
+ final Entry e = registry.entries.get(i);
+ b.append(" [")
+ .append(i)
+ .append("] ")
+ .append(fingerprint(registry, i))
+ .append(" pkLen=")
+ .append(e.publicKey.length);
+ if (e.address != null) {
+ b.append(" addr=0x").append(hex(e.address));
+ }
+ b.append('\n');
+ }
+ if (registry.count() > shown) {
+ b.append(" ... ").append(registry.count() - shown).append(" more entries\n");
+ }
+ return b.toString();
+ }
+
+ // ===================================================================================
+ // Small helpers. Deliberately local so this class needs nothing from Besu itself and
+ // can be compiled, hashed and tested standalone.
+ // ===================================================================================
+
+ private static JsonNode readJson(final Path path) {
+ try {
+ return new ObjectMapper().readTree(Files.readAllBytes(path));
+ } catch (final IOException e) {
+ throw new RegistryConfigException(
+ "AERE-PQC-REG-LOAD-13",
+ "AERE PQC A8: cannot read or parse JSON at '"
+ + path
+ + "': "
+ + e
+ + ". Refusing (fail-closed).");
+ }
+ }
+
+ private static int parseIndexOrThrow(final String raw, final String source) {
+ try {
+ final int i = Integer.parseInt(raw.trim());
+ if (i < 0) {
+ throw new NumberFormatException("negative");
+ }
+ return i;
+ } catch (final NumberFormatException e) {
+ throw new RegistryConfigException(
+ "AERE-PQC-REG-LOAD-14",
+ "AERE PQC A8: registry '"
+ + source
+ + "' has the unrecognised key '"
+ + raw
+ + "'. Every key must be 'count', a non-negative validator index, or '<index>.addr'. "
+ + "Refusing (fail-closed): the old loader SKIPPED keys it did not understand and "
+ + "logged a warning, which means a typo'd index silently produced a smaller registry "
+ + "that still hashed to something.");
+ }
+ }
+
+ /**
+ * AERE D-146. Parse an OPTIONAL non-negative header field: absent means -1, present means it must
+ * be a well formed non-negative number. Absent-or-garbage is never collapsed into a default,
+ * because a default is how a threshold quietly becomes zero.
+ */
+ private static long parseOptionalLong(
+ final String raw, final String what, final String source) {
+ if (raw == null || raw.trim().isEmpty()) {
+ return -1L;
+ }
+ final long v;
+ try {
+ v = Long.parseLong(raw.trim());
+ } catch (final NumberFormatException e) {
+ throw new RegistryConfigException(
+ "AERE-PQC-REG-LOAD-23",
+ "AERE PQC D-146: registry '"
+ + source
+ + "' has "
+ + what
+ + "='"
+ + raw
+ + "', which is not a number. Refusing (fail-closed).");
+ }
+ if (v < 0) {
+ throw new RegistryConfigException(
+ "AERE-PQC-REG-LOAD-23",
+ "AERE PQC D-146: registry '"
+ + source
+ + "' has a negative "
+ + what
+ + " ("
+ + v
+ + "). Refusing (fail-closed).");
+ }
+ return v;
+ }
+
+ private static int parsePositiveInt(final String raw, final String what, final String source) {
+ try {
+ final int v = Integer.parseInt(raw.trim());
+ if (v <= 0) {
+ throw new NumberFormatException("not positive");
+ }
+ return v;
+ } catch (final NumberFormatException e) {
+ throw new RegistryConfigException(
+ "AERE-PQC-REG-LOAD-15",
+ "AERE PQC A8: registry '"
+ + source
+ + "' has a malformed "
+ + what
+ + " '"
+ + raw
+ + "'. Refusing (fail-closed).");
+ }
+ }
+
+ /**
+ * Strict hex: optional {@code 0x}, then an EVEN number of hex digits and nothing else.
+ *
+ * <p>Deliberately NOT the lenient parser the old loader used. Lenient parsing accepts an odd digit
+ * count and silently left-pads, so a public key that lost one character would load as a DIFFERENT
+ * key with no complaint, and hash to something that looks perfectly valid.
+ */
+ private static byte[] strictHex(final String raw, final String what, final String source) {
+ String s = raw == null ? "" : raw.trim();
+ if (s.startsWith("0x") || s.startsWith("0X")) {
+ s = s.substring(2);
+ }
+ if (s.isEmpty() || (s.length() & 1) == 1) {
+ throw new RegistryConfigException(
+ "AERE-PQC-REG-LOAD-16",
+ "AERE PQC A8: registry '"
+ + source
+ + "' "
+ + what
+ + " has "
+ + s.length()
+ + " hex digits, which is "
+ + (s.isEmpty() ? "empty" : "ODD")
+ + ". Refusing (fail-closed): a lenient parser would left-pad this and load a "
+ + "DIFFERENT key without saying anything.");
+ }
+ final byte[] out = new byte[s.length() / 2];
+ for (int i = 0; i < out.length; i++) {
+ final int hi = Character.digit(s.charAt(2 * i), 16);
+ final int lo = Character.digit(s.charAt(2 * i + 1), 16);
+ if (hi < 0 || lo < 0) {
+ throw new RegistryConfigException(
+ "AERE-PQC-REG-LOAD-17",
+ "AERE PQC A8: registry '"
+ + source
+ + "' "
+ + what
+ + " contains a non-hex character at position "
+ + (2 * i)
+ + ". Refusing (fail-closed).");
+ }
+ out[i] = (byte) ((hi << 4) | lo);
+ }
+ return out;
+ }
+
+ private static String normHash(final String raw, final String source) {
+ String s = raw == null ? "" : raw.trim();
+ if (s.startsWith("0x") || s.startsWith("0X")) {
+ s = s.substring(2);
+ }
+ s = s.toLowerCase(Locale.ROOT);
+ if (s.length() != 64) {
+ throw new RegistryConfigException(
+ "AERE-PQC-REG-SCHED-06",
+ "AERE PQC A8: "
+ + source
+ + " carries the hash '"
+ + raw
+ + "' which is "
+ + s.length()
+ + " hex digits, not 64. Refusing to start (fail-closed).");
+ }
+ for (int i = 0; i < 64; i++) {
+ if (Character.digit(s.charAt(i), 16) < 0) {
+ throw new RegistryConfigException(
+ "AERE-PQC-REG-SCHED-07",
+ "AERE PQC A8: " + source + " hash '" + raw + "' is not hexadecimal. Refusing to start.");
+ }
+ }
+ return s;
+ }
+
+ private static void writeAll(final java.io.ByteArrayOutputStream out, final byte[] b) {
+ out.write(b, 0, b.length);
+ }
+
+ private static byte[] uint32be(final int v) {
+ return new byte[] {(byte) (v >>> 24), (byte) (v >>> 16), (byte) (v >>> 8), (byte) v};
+ }
+
+ private static byte[] uint64be(final long v) {
+ final byte[] b = new byte[8];
+ for (int i = 0; i < 8; i++) {
+ b[i] = (byte) (v >>> (56 - 8 * i));
+ }
+ return b;
+ }
+
+ private static String keccakHex(final byte[] input) {
+ final KeccakDigest kd = new KeccakDigest(256);
+ kd.update(input, 0, input.length);
+ final byte[] d = new byte[32];
+ kd.doFinal(d, 0);
+ return hex(d);
+ }
+
+ private static String hex(final byte[] b) {
+ final StringBuilder s = new StringBuilder(b.length * 2);
+ for (final byte x : b) {
+ s.append(Character.forDigit((x >> 4) & 0xf, 16)).append(Character.forDigit(x & 0xf, 16));
+ }
+ return s.toString();
+ }
+}
diff --git a/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/PqRegistryHashTool.java b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/PqRegistryHashTool.java
new file mode 100755
index 000000000..14071c5e4
--- /dev/null
+++ b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/PqRegistryHashTool.java
@@ -0,0 +1,481 @@
+/*
+ * Copyright contributors to Besu / AERE Network.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.common.bft;
+
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+
+/**
+ * D-145. The tool that writes and checks the two configuration values without which the D2 repair
+ * changes nothing.
+ *
+ * <p>WHY IT LIVES IN THE CONSENSUS MODULE AND NOT IN A SCRIPT. The value being computed is a
+ * keccak digest over a domain-separated, length-prefixed, chain-bound pre-image, and the node
+ * refuses to start when what it computes differs by one bit from what genesis names. A second
+ * implementation in another language is a second thing that can drift, and the drift would show up
+ * as seven validators refusing to start. This tool calls the SAME methods the node calls, from the
+ * same jar, so "the tool says the hash is X" and "the node computes X" cannot come apart. Run it
+ * from a node's own distribution:
+ *
+ * <pre>
+ * java -cp 'besu/lib/*' org.hyperledger.besu.consensus.common.bft.PqRegistryHashTool \
+ * verify --chain-id 2800 --genesis ./genesis-2800.json \
+ * --history ./falcon/registry-epoch-0.properties
+ * </pre>
+ *
+ * <p>THREE VERBS.
+ *
+ * <ul>
+ * <li>{@code hash} prints the canonical hash of every registry file named. This is the value
+ * that goes into genesis.
+ * <li>{@code generate} prints the exact genesis fragment and the exact
+ * {@code aere.falcon.registry.history} line, given an arming height and one registry file per
+ * epoch. It writes nothing by itself: arming is a founder decision, and a tool that edits a
+ * live genesis is a tool that can arm a chain by accident.
+ * <li>{@code verify} recomputes everything from the files on THIS machine and answers one
+ * question: is there a scheduled height this node could not resolve. Exit 0 green, 1 red, 2
+ * not measurable.
+ * </ul>
+ *
+ * <p>THE NEGATIVE CONTROL IS A VERB, not a promise: {@code verify --CONTROL-NEGATIV} changes one
+ * hex digit of the first required hash in memory and requires the verification to go RED. A check
+ * that has never failed cannot be trusted, so the tool proves it can fail every time it is run
+ * that way.
+ */
+public final class PqRegistryHashTool {
+
+ private PqRegistryHashTool() {}
+
+ /**
+ * Entry point.
+ *
+ * @param args the verb and its options
+ */
+ public static void main(final String[] args) {
+ System.exit(run(args));
+ }
+
+ /**
+ * The tool, as a function of its arguments, so a test can drive it without exiting the JVM.
+ *
+ * @param args the verb and its options
+ * @return 0 green, 1 red, 2 not measurable
+ */
+ public static int run(final String[] args) {
+ if (args.length == 0) {
+ utilizare();
+ return 2;
+ }
+ final Map<String, String> o = optiuni(args);
+ final long chainId = Long.parseLong(o.getOrDefault("chain-id", "2800"));
+ try {
+ switch (args[0]) {
+ case "hash":
+ return hash(o, chainId);
+ case "generate":
+ return generate(o, chainId);
+ case "verify":
+ return verify(o, chainId);
+ default:
+ utilizare();
+ return 2;
+ }
+ } catch (final PqRegistryHash.RegistryConfigException e) {
+ System.out.println("RED: " + e.getMessage());
+ return 1;
+ } catch (final RuntimeException e) {
+ System.out.println("NOT MEASURED: " + e);
+ return 2;
+ }
+ }
+
+ // ---------------------------------------------------------------------------------------------
+
+ private static int hash(final Map<String, String> o, final long chainId) {
+ final List<Path> files = files(o, "registry");
+ if (files.isEmpty()) {
+ System.out.println("NOT MEASURED: --registry <file>[,<file>...] is missing");
+ return 2;
+ }
+ System.out.println("chainId=" + chainId + " (goes INTO the pre-image; 2800 and 442807 give different hashes for the same registry)");
+ for (final Path p : files) {
+ final PqRegistryHash.Registry r = PqRegistryHash.loadAuto(p);
+ // AERE D-C (2026-08-06): hashFor, not hashV1. For a registry that carries binding proofs,
+ // hashV1 is a number NOTHING in the node ever compares against: the guard compares hashFor,
+ // that is hashV2. The same mistake, in the `generate` verb below, writes into genesis a hash
+ // the node will never recognise, and then all seven start and the chain stops at H-1.
+ // On top of that, hashV1 does NOT tell two rotation epochs of the same fleet apart, because the
+ // bind height does not enter the v1 pre-image; so it cannot serve even as an epoch identifier
+ // for diagnostics.
+ System.out.println(
+ "0x"
+ + PqRegistryHash.hashFor(r, chainId)
+ + " "
+ + p
+ + " (entries="
+ + r.count()
+ + ", address-bound="
+ + r.addressBound()
+ + ", format="
+ + (r.proofBound() ? "v2, bind-height=" + r.bindHeight() : "v1, no proofs")
+ + ")");
+ }
+ return 0;
+ }
+
+ // ---------------------------------------------------------------------------------------------
+
+ private static int generate(final Map<String, String> o, final long chainId) {
+ final String armingHeightRaw = o.get("arming-height");
+ if (armingHeightRaw == null) {
+ System.out.println("NOT MEASURED: --arming-height <H> is missing. The first entry of the");
+ System.out.println(" schedule must be EXACTLY at aere.pq.anchorBlock; see case D");
+ System.out.println(" of dovezi-d2-2026-08-06.");
+ return 2;
+ }
+ final long h = Long.parseLong(armingHeightRaw);
+ final List<Path> files = files(o, "registry");
+ if (files.isEmpty()) {
+ System.out.println("NOT MEASURED: --registry is missing");
+ return 2;
+ }
+ // The epochs: the first at the arming height, then one per --rotation <height>=<file>.
+ final Map<Long, Path> epoci = new LinkedHashMap<>();
+ epoci.put(h, files.get(0));
+ for (final String rot : list(o.get("rotation"))) {
+ final int eq = rot.indexOf('=');
+ if (eq < 0) {
+ System.out.println("NOT MEASURED: --rotation is written <height>=<file>, got: " + rot);
+ return 2;
+ }
+ epoci.put(Long.parseLong(rot.substring(0, eq).trim()), Path.of(rot.substring(eq + 1).trim()));
+ }
+
+ final List<Long> inaltimi = new ArrayList<>(epoci.keySet());
+ inaltimi.sort(Long::compare);
+ if (inaltimi.get(0) != h) {
+ System.out.println("RED: the first epoch is at " + inaltimi.get(0) + ", not at the arming height " + h);
+ return 1;
+ }
+
+ // NO COMMENT INSIDE THE FRAGMENT, and that is a measurement, not a matter of taste. The first
+ // form of this method put the file path after every entry, as `// /path/registry.json`.
+ // The fragment LOOKS fine and CANNOT BE USED: genesis is read with Jackson without
+ // ALLOW_COMMENTS, so a node handed one of those refuses to start with
+ // [AERE-PQC-REG-LOAD-13] "Unexpected character ('/')", and it then refuses EVERY header from
+ // the arming height upwards. Measured 2026-08-06, cases U3/U4 in d2-v2/dovezi/controale/.
+ // Whatever is explanation is printed outside the JSON, on lines beginning with #.
+ final StringBuilder json = new StringBuilder();
+ json.append(" \"pqRegistryHash\": [\n");
+ final StringBuilder history = new StringBuilder();
+ final StringBuilder harta = new StringBuilder();
+ for (int i = 0; i < inaltimi.size(); i++) {
+ final long b = inaltimi.get(i);
+ final Path p = epoci.get(b);
+ final PqRegistryHash.Registry reg = PqRegistryHash.loadAuto(p);
+ // AERE D-C (2026-08-06). THIS IS THE DANGEROUS VERB: what is printed here gets pasted into
+ // genesis, and genesis is the document all seven nodes hold identical. hashV1 next to a
+ // registry that carries proofs writes into genesis a number the node's guard (hashFor) never
+ // produces, so all seven nodes start, all report the registry loaded, and the chain stops at
+ // H-1. A wrong indication is more dangerous than a missing one.
+ final String hash = PqRegistryHash.hashFor(reg, chainId);
+ // AERE D-B (2026-08-06). The recipe we print has to be the one the NEW code accepts. Since
+ // 2026-08-06 the node refuses to start (AERE-PQC-REG-BIND-08) on a registry forced in at a
+ // height its proofs did not sign. If the tool printed that recipe, it would manufacture
+ // exactly the configuration the node rejects, and it would do so in a file that reaches all
+ // seven at once.
+ if (reg.proofBound() && reg.bindHeight() != b) {
+ System.out.println(
+ "RED: registry "
+ + p
+ + " has bind height "
+ + reg.bindHeight()
+ + ", while here it is scheduled from block "
+ + b
+ + ". The two numbers must be EQUAL: every row of the registry carries a proof of "
+ + "possession and a claim, and both sign the bind height. A registry forced in from "
+ + "another block is an activation day no validator signed, and the node refuses to "
+ + "start on it with AERE-PQC-REG-BIND-08. It is not repaired by editing the "
+ + "bindHeight field: the proofs are over it, and the file would no longer load at "
+ + "all (AERE-PQC-REG-BIND-03). It is repaired either by scheduling the epoch at "
+ + reg.bindHeight()
+ + ", or by re-signing the registry for "
+ + b
+ + ", which means the key ceremony and a NEW hash.");
+ return 1;
+ }
+ json.append(" {\"block\": ").append(b).append(", \"hash\": \"0x").append(hash).append("\"}");
+ if (i < inaltimi.size() - 1) {
+ json.append(',');
+ }
+ json.append('\n');
+ harta.append("# block ").append(b).append(" -> ").append(p.toAbsolutePath()).append('\n');
+ if (history.length() > 0) {
+ history.append(',');
+ }
+ history.append(p.toAbsolutePath());
+ }
+ json.append(" ]");
+
+ System.out.println("# 1. In the genesis of chain " + chainId + ", inside the \"config\" object:");
+ System.out.println("# The fragment below is VALID JSON and is pasted as it stands. No comments");
+ System.out.println("# are added to it: genesis is read WITHOUT ALLOW_COMMENTS and the node refuses to start.");
+ System.out.println(json);
+ System.out.println("# Which registry file stands behind each epoch:");
+ System.out.print(harta);
+ System.out.println();
+ System.out.println("# 2. On EVERY node, the second client included, in BESU_OPTS:");
+ System.out.println("-Daere.falcon.registry.history=" + history);
+ System.out.println();
+ System.out.println("# 3. The order, and it is not negotiable: the registry files are placed on all");
+ System.out.println("# seven AND the hash goes into genesis BEFORE the restart. A node armed");
+ System.out.println("# without a schedule refuses every header from the arming height upwards.");
+ System.out.println("# 4. After they are placed, on each node:");
+ System.out.println("# PqRegistryHashTool verify --chain-id " + chainId + " --genesis <genesis> --history <list>");
+ return 0;
+ }
+
+ // ---------------------------------------------------------------------------------------------
+
+ private static int verify(final Map<String, String> o, final long chainId) {
+ final String genesisRaw = o.get("genesis");
+ if (genesisRaw == null) {
+ System.out.println("NOT MEASURED: --genesis <file> is missing");
+ return 2;
+ }
+ final Path genesis = Path.of(genesisRaw);
+ if (!Files.isReadable(genesis)) {
+ System.out.println("NOT MEASURED: genesis cannot be read: " + genesis);
+ return 2;
+ }
+
+ PqRegistryHash.Schedule schedule = PqRegistryHash.loadScheduleFromGenesis(genesis);
+ if (!schedule.enforced()) {
+ System.out.println(
+ "RED: "
+ + genesis
+ + " does not carry config.pqRegistryHash. This is D-145 exactly as it was measured: "
+ + "the machinery exists, it is complete, and it is OFF. A node armed without a "
+ + "schedule falls back on TODAY's registry and says ACCEPTED for a header it has "
+ + "bound to no height (case D of dovezi-d2-2026-08-06).");
+ return 1;
+ }
+
+ boolean controlNegativ = o.containsKey("CONTROL-NEGATIV");
+ if (controlNegativ) {
+ schedule = strica(schedule);
+ System.out.println(
+ "NEGATIVE CONTROL: the first required hash was changed by ONE hex character, in memory. "
+ + "The verification below MUST come out RED.");
+ }
+
+ final List<Path> history = files(o, "history");
+ final List<PqRegistryHash.Registry> tinute = new ArrayList<>();
+ for (final Path p : history) {
+ tinute.add(PqRegistryHash.loadAuto(p));
+ }
+ if (tinute.isEmpty()) {
+ System.out.println(
+ "WARNING: --history is empty, so no registry was loaded. On a real node the signing "
+ + "registry is added automatically; here it is asked for explicitly, so that nothing "
+ + "is reported green on the strength of what was not measured.");
+ }
+
+ final PqRegistryHash.RegistrySet set = PqRegistryHash.buildSet(schedule, tinute, chainId);
+
+ System.out.println("chainId = " + chainId);
+ System.out.println("genesis = " + genesis);
+ System.out.println("schedule source = " + schedule.source());
+ System.out.println("epochs scheduled = " + schedule.entries().size());
+ for (final PqRegistryHash.ScheduleEntry e : schedule.entries()) {
+ final boolean acoperita = !set.uncoveredEntryBlocks().contains(e.block());
+ System.out.println(
+ " block " + e.block() + " 0x" + e.hash() + " " + (acoperita ? "COVERED" : "NOT COVERED"));
+ }
+ System.out.println("registries held = " + set.count());
+ for (final Path p : history) {
+ // AERE D-C: hashFor. This line sits immediately under the list of scheduled epochs printed
+ // with their hashes; two numbers laid one under the other so that they get compared by eye,
+ // and computed with two different functions, are a comparison that can never match.
+ final PqRegistryHash.Registry r = PqRegistryHash.loadAuto(p);
+ System.out.println(
+ " "
+ + PqRegistryHash.hashFor(r, chainId)
+ + " "
+ + p
+ + (r.proofBound() ? " (bind-height=" + r.bindHeight() + ")" : " (v1)"));
+ }
+ final String armareRaw = o.get("arming-height");
+ int rc = 0;
+ // AERE D-B: the registries that reproduce the required hash and did NOT sign that height. This
+ // is exactly what the node now refuses to start on; until 2026-08-06 the node started and the
+ // tool said nothing.
+ for (final PqRegistryHash.Misbound m : set.misbound()) {
+ System.out.println(
+ "RED: "
+ + m.registryPath()
+ + " reproduces the hash required at block "
+ + m.entryBlock()
+ + ", but its proofs sign height "
+ + m.signedHeight()
+ + ". The node refuses to start with AERE-PQC-REG-BIND-08.");
+ rc = 1;
+ }
+ if (armareRaw != null) {
+ final long h = Long.parseLong(armareRaw);
+ final long first = schedule.entries().get(0).block();
+ if (first != h) {
+ System.out.println(
+ "RED: the first entry of the schedule is at "
+ + first
+ + ", while aere.pq.anchorBlock is "
+ + h
+ + ". They must be EQUAL. If the first entry is higher, the heights between H and it "
+ + "are bound to nothing and the node falls back on the head registry exactly where "
+ + "the certificate begins to matter.");
+ rc = 1;
+ } else {
+ System.out.println("OK: the first epoch is exactly at the arming height " + h + ".");
+ }
+ } else {
+ System.out.println(
+ "NOT MEASURED: --arming-height was not given, so it was NOT checked that the first "
+ + "epoch coincides with aere.pq.anchorBlock.");
+ }
+
+ final List<Long> neacoperite = set.uncoveredEntryBlocks();
+ if (!neacoperite.isEmpty()) {
+ System.out.println(
+ "RED: heights "
+ + neacoperite
+ + " are covered by NOTHING this node holds. Every header from such a height upwards "
+ + "will be REFUSED, and a node syncing from genesis stops there. Name the missing "
+ + "file in aere.falcon.registry.history.");
+ rc = 1;
+ } else {
+ System.out.println("OK: every epoch in the schedule is covered by a registry this node holds.");
+ }
+
+ // Positive probe: the registry in force at the height of every epoch resolves right now.
+ for (final PqRegistryHash.ScheduleEntry e : schedule.entries()) {
+ final Optional<PqRegistryHash.Registry> r =
+ PqRegistryHash.registryAt(schedule, set, e.block());
+ if (r.isEmpty()) {
+ System.out.println("RED: registryAt(" + e.block() + ") resolves nothing.");
+ rc = 1;
+ } else if (!PqRegistryHash.matchesAt(schedule, set, e.block(), chainId)) {
+ System.out.println("RED: registryAt(" + e.block() + ") resolves a registry with a different hash.");
+ rc = 1;
+ }
+ }
+
+ if (controlNegativ) {
+ if (rc == 1) {
+ System.out.println("NEGATIVE CONTROL OK: with a single character changed, the verification is RED.");
+ return 0;
+ }
+ System.out.println(
+ "NEGATIVE CONTROL FAILED: a hash was changed and the verification stayed GREEN. The "
+ + "verification cannot be trusted.");
+ return 1;
+ }
+ System.out.println(rc == 0 ? "GREEN" : "RED");
+ return rc;
+ }
+
+ // ---------------------------------------------------------------------------------------------
+
+ /** Change exactly one hex digit of the first required hash, through the real parser. */
+ private static PqRegistryHash.Schedule strica(final PqRegistryHash.Schedule s) {
+ final StringBuilder sb = new StringBuilder("{\"config\":{\"pqRegistryHash\":[");
+ for (int i = 0; i < s.entries().size(); i++) {
+ final PqRegistryHash.ScheduleEntry e = s.entries().get(i);
+ String h = e.hash();
+ if (i == 0) {
+ final char c = h.charAt(h.length() - 1);
+ h = h.substring(0, h.length() - 1) + (c == '0' ? '1' : '0');
+ }
+ if (i > 0) {
+ sb.append(',');
+ }
+ sb.append("{\"block\":").append(e.block()).append(",\"hash\":\"0x").append(h).append("\"}");
+ }
+ sb.append("]}}");
+ try {
+ final Path t = Files.createTempFile("aere-control-negativ-", ".json");
+ t.toFile().deleteOnExit();
+ Files.writeString(t, sb.toString());
+ return PqRegistryHash.loadScheduleFromGenesis(t);
+ } catch (final java.io.IOException io) {
+ throw new IllegalStateException("cannot write the negative-control file: " + io, io);
+ }
+ }
+
+ private static List<Path> files(final Map<String, String> o, final String key) {
+ final List<Path> out = new ArrayList<>();
+ for (final String s : list(o.get(key))) {
+ out.add(Path.of(s));
+ }
+ return out;
+ }
+
+ private static List<String> list(final String raw) {
+ final List<String> out = new ArrayList<>();
+ if (raw == null || raw.isBlank()) {
+ return out;
+ }
+ for (final String s : com.google.common.base.Splitter.on(',').split(raw)) {
+ if (!s.trim().isEmpty()) {
+ out.add(s.trim());
+ }
+ }
+ return out;
+ }
+
+ private static Map<String, String> optiuni(final String[] args) {
+ final Map<String, String> o = new LinkedHashMap<>();
+ for (int i = 1; i < args.length; i++) {
+ if (!args[i].startsWith("--")) {
+ continue;
+ }
+ final String k = args[i].substring(2);
+ if (i + 1 < args.length && !args[i + 1].startsWith("--")) {
+ final String prev = o.get(k);
+ o.put(k, prev == null ? args[i + 1] : prev + "," + args[i + 1]);
+ i++;
+ } else {
+ o.put(k, "");
+ }
+ }
+ return o;
+ }
+
+ private static void utilizare() {
+ System.out.println("D-145. The height-indexed registry schedule: hash, generate, verify.");
+ System.out.println();
+ System.out.println(" hash --chain-id 2800 --registry <f>[,<f>...]");
+ System.out.println(" generate --chain-id 2800 --arming-height <H> --registry <f>");
+ System.out.println(" [--rotation <H2>=<f2> ...]");
+ System.out.println(" verify --chain-id 2800 --genesis <g.json> --history <f>[,<f>...]");
+ System.out.println(" [--arming-height <H>] [--CONTROL-NEGATIV]");
+ System.out.println();
+ System.out.println("Exit code: 0 green, 1 red, 2 not measurable.");
+ }
+}
diff --git a/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/PqSchemeSchedule.java b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/PqSchemeSchedule.java
new file mode 100755
index 000000000..a4d1bd43e
--- /dev/null
+++ b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/PqSchemeSchedule.java
@@ -0,0 +1,139 @@
+/*
+ * AERE crypto-agility, step 5: the height-indexed scheme schedule.
+ *
+ * WHAT IT IS. The same shape as aere.pq.anchorMinSeals ("H:K,H:K,..."), but the value at each
+ * step is a SET of scheme ids: "14000000:falcon-512,15500000:falcon-512+slh-dsa-128s" reads
+ * "from 14,000,000 anchors carry Falcon; from 15,500,000 they carry Falcon AND SLH-DSA".
+ * Changing the mathematics of the chain becomes one property plus keys, never a code edit -
+ * that is the whole point of the abstraction layer.
+ *
+ * THE D-147 LESSON, APPLIED AT THE LOADER. The min-seals schedule once accepted a shape whose
+ * DANGEROUS step was later in the schedule, because validation looked only at the first step.
+ * Here every rule runs over the WHOLE schedule at parse time, and the armability gate
+ * (firstUnsatisfied) walks every step against the registry's per-scheme coverage: arming a
+ * threshold K under a scheme whose coverage is below K is a chain stop, so it must be refused
+ * at configuration time, loudly, before any node boots with it.
+ *
+ * SEMANTICS OF "BEFORE THE FIRST STEP": schemesAt returns the empty set, which callers read as
+ * "the v2 scheme world is not armed here" (the legacy untagged Falcon certificate governs).
+ * Empty is never a default INSIDE the schedule: a step with zero schemes is a parse refusal.
+ */
+package org.hyperledger.besu.consensus.common.bft;
+
+import com.google.common.base.Splitter;
+
+import java.util.ArrayList;
+import java.util.LinkedHashSet;
+import java.util.List;
+import java.util.Optional;
+import java.util.Set;
+
+/** Immutable, validated height-to-scheme-set schedule. */
+public final class PqSchemeSchedule {
+
+ /** One step: from {@code fromBlock} (inclusive) the anchor carries {@code schemeIds}. */
+ public record Step(long fromBlock, Set<String> schemeIds) {}
+
+ private final List<Step> steps;
+
+ private PqSchemeSchedule(final List<Step> steps) {
+ this.steps = steps;
+ }
+
+ /** Parse "H:scheme[+scheme...],H:...". Refuses the WHOLE schedule on any defect: unknown or
+ * repeated scheme in a step, empty step, non-increasing heights, negative height, garbage. */
+ public static PqSchemeSchedule parse(final String raw) {
+ if (raw == null || raw.isBlank()) {
+ throw new IllegalArgumentException("AERE PQ ORAR-SCHEME: empty schedule");
+ }
+ final List<Step> steps = new ArrayList<>();
+ long lastHeight = -1;
+ for (final String piesa : Splitter.on(',').split(raw)) {
+ final List<String> parti = Splitter.on(':').splitToList(piesa.trim());
+ if (parti.size() != 2) {
+ throw new IllegalArgumentException(
+ "AERE PQ ORAR-SCHEME: step '" + piesa.trim() + "' is not H:schemes");
+ }
+ final long h;
+ try {
+ h = Long.parseLong(parti.get(0).trim());
+ } catch (final NumberFormatException e) {
+ throw new IllegalArgumentException(
+ "AERE PQ ORAR-SCHEME: height '" + parti.get(0).trim() + "' is not a number");
+ }
+ if (h < 0) {
+ throw new IllegalArgumentException("AERE PQ ORAR-SCHEME: negative height " + h);
+ }
+ if (h <= lastHeight) {
+ throw new IllegalArgumentException(
+ "AERE PQ ORAR-SCHEME: heights must strictly increase ("
+ + lastHeight
+ + " then "
+ + h
+ + ") - a schedule read out of order would arm the wrong mathematics");
+ }
+ lastHeight = h;
+ final Set<String> schemes = new LinkedHashSet<>();
+ for (final String id : Splitter.on('+').split(parti.get(1))) {
+ final String curat = id.trim();
+ if (curat.isEmpty()) {
+ throw new IllegalArgumentException(
+ "AERE PQ ORAR-SCHEME: step at " + h + " carries an empty scheme name");
+ }
+ if (SealSchemes.byId(curat).isEmpty()) {
+ throw new IllegalArgumentException(
+ "AERE PQ ORAR-SCHEME: step at " + h + " names UNKNOWN scheme '" + curat
+ + "' - refusing the whole schedule");
+ }
+ if (!schemes.add(curat)) {
+ throw new IllegalArgumentException(
+ "AERE PQ ORAR-SCHEME: step at " + h + " repeats scheme '" + curat + "'");
+ }
+ }
+ if (schemes.isEmpty()) {
+ throw new IllegalArgumentException(
+ "AERE PQ ORAR-SCHEME: step at " + h + " has no schemes at all");
+ }
+ steps.add(new Step(h, Set.copyOf(schemes)));
+ }
+ return new PqSchemeSchedule(List.copyOf(steps));
+ }
+
+ /** The scheme set in force at {@code height}: the last step at or below it, or the empty set
+ * when the schedule has not started yet (= v2 not armed, legacy governs). */
+ public Set<String> schemesAt(final long height) {
+ Set<String> inForce = Set.of();
+ for (final Step s : steps) {
+ if (s.fromBlock() <= height) {
+ inForce = s.schemeIds();
+ } else {
+ break;
+ }
+ }
+ return inForce;
+ }
+
+ /** All steps, ascending. */
+ public List<Step> steps() {
+ return steps;
+ }
+
+ /** The armability gate: walk EVERY step and every scheme in it against the registry's
+ * per-scheme coverage; the first (height, scheme) whose coverage is below {@code minSeals}
+ * is returned as the refusal, with numbers. Empty means the whole schedule is armable.
+ * This is the D-147 discipline: the dangerous step may be the LAST one, so all are walked. */
+ public Optional<String> firstUnsatisfied(final HybridSignerRegistry registry, final int minSeals) {
+ for (final Step s : steps) {
+ for (final String scheme : s.schemeIds()) {
+ final int acoperire = registry.coverage(scheme);
+ if (acoperire < minSeals) {
+ return Optional.of(
+ "step at height " + s.fromBlock() + " arms scheme '" + scheme
+ + "' with required seals " + minSeals + " but the registry covers only "
+ + acoperire + " validator(s) - arming this would stop the chain");
+ }
+ }
+ }
+ return Optional.empty();
+ }
+}
diff --git a/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/PqSealCache.java b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/PqSealCache.java
new file mode 100755
index 000000000..dac0d63dd
--- /dev/null
+++ b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/PqSealCache.java
@@ -0,0 +1,431 @@
+/*
+ * Copyright contributors to Besu / AERE Network.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.common.bft;
+
+import org.hyperledger.besu.datatypes.Hash;
+
+import java.nio.file.Path;
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.Iterator;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+/**
+ * AERE ANCHOR V2: the bounded store of Falcon seals this node HEARD for recent blocks, in memory and
+ * - for the chain head only - on disk.
+ *
+ * <p>WHAT IT IS FOR. The proposer of block N must carry a certificate over block N-1. Under
+ * V2 that certificate is chosen by the proposer out of what it heard, so the seals gossiped on
+ * Commit messages have to survive from the height where they arrive to the height where the next
+ * block is built. That is all this class does.
+ *
+ * <p>KEYED ON THE ON-CHAIN BLOCK HASH, NEVER ON THE COMMIT DIGEST. The digest carried by a Commit
+ * message is the committed-seal hash, which INCLUDES the round number, so it differs between rounds
+ * for one and the same block. The producer looks the certificate up by {@code
+ * parentHeader.getHash()}, which is the round-independent on-chain hash. Storing under anything
+ * else would silently produce empty certificates at every round change.
+ *
+ * <p>AERE PERSISTENTA-SIGILII (2026-08-05): PERSISTENT FOR THE CHAIN HEAD, AND THE OLD REASONING FOR
+ * NOT BEING SO WAS MEASURED WRONG. This class used to say, in this exact place, that losing the map
+ * on restart costs "at most one proposer turn per restart". That reasoning is correct for ONE node
+ * restarted inside a LIVE fleet, which is the case it was written for. For a fleet restarted
+ * ENTIRELY it is false, and the falsehood was measured on a seven-node network: with K&gt;0 every
+ * node came back holding zero seals, no certificate could reach K, nobody could propose, so no
+ * Commit was ever sent, so no node ever heard a seal again. The chain was dead, permanently, and no
+ * amount of waiting healed it. The seals over M(head) exist nowhere else: they travel only on the
+ * Commit messages of the head block, and those are never replayed.
+ *
+ * <p>AND IT IS NOT DEFECT A8 IN ANOTHER COAT. A8 was a registry of public keys read from a file and
+ * BELIEVED. Every seal read back here is re-verified, cryptographically, against the anchored
+ * registry over M rebuilt from the header this process just loaded - see {@link PqSealStore}. A
+ * forged file cannot inject a seal without forging a Falcon-512 signature; the worst it achieves is
+ * the empty cache an absent file already gives. Persistence is OFF unless a caller enables it, and
+ * the only caller that does is the QBFT controller builder, only when the anchor is actually armed.
+ *
+ * <p>WHAT IT DOES NOT DO. The in-memory path verifies nothing. Whether a seal is valid, whether its
+ * index maps to an eligible validator, and whether there are enough of them, are decided at
+ * SELECTION time by the producer, against the message M of the specific parent. A seal that was
+ * signed under the pre-fork message simply fails that check and is dropped, which is what makes the
+ * height switch safe without any coordination beyond the shared activation height.
+ */
+public final class PqSealCache {
+
+ private static final Logger LOG = LoggerFactory.getLogger(PqSealCache.class);
+
+ /** How many distinct block hashes are retained. Several rounds at one height each add one. */
+ private static final int MAX_ENTRIES = 1024;
+
+ /** How far below the highest seen height entries are kept, in blocks. */
+ private static final long HEIGHT_WINDOW = 256L;
+
+ private static final PqSealCache INSTANCE = new PqSealCache();
+
+ private final LinkedHashMap<Hash, Entry> byHash = new LinkedHashMap<>();
+ private long highestSeen = -1L;
+
+ /** Guards the file, never the map, so a slow disk cannot hold up the consensus thread's map. */
+ private final Object writeLock = new Object();
+
+ private volatile Path persistenceFile;
+ private volatile long persistenceChainId;
+
+ private long persistedBlock = -1L;
+ private Hash persistedHash;
+ private int persistedCount = -1;
+
+ private PqSealCache() {}
+
+ /**
+ * The process-wide cache.
+ *
+ * @return the singleton
+ */
+ public static PqSealCache instance() {
+ return INSTANCE;
+ }
+
+ /**
+ * Turn on writing the chain head's seals to the node's data directory.
+ *
+ * <p>The path is DERIVED from the data directory Besu was started with, never configured
+ * separately: a second configurable path is a second thing that can be pointed at the wrong node's
+ * state, and this file is per-node by construction.
+ *
+ * @param dataDirectory the node's data directory, or null to leave persistence off
+ * @param chainId the chain id used in the M pre-image, which must be the SAME value the producer
+ * uses or every restored seal would fail verification
+ */
+ public void enablePersistence(final Path dataDirectory, final long chainId) {
+ if (dataDirectory == null) {
+ LOG.warn(
+ "AERE PERSISTENTA-SIGILII: no data directory was supplied, so heard seals stay in memory "
+ + "only. A simultaneous restart of the whole fleet with K>0 stops the chain.");
+ return;
+ }
+ this.persistenceChainId = chainId;
+ this.persistenceFile = PqSealStore.fileIn(dataDirectory);
+ LOG.info(
+ "AERE PERSISTENTA-SIGILII: heard seals for the chain head are kept in {} (chainId={}). "
+ + "Every seal read back is re-verified against the anchored registry before it is used.",
+ this.persistenceFile,
+ chainId);
+ }
+
+ /**
+ * Turn persistence off again. For tests, and for an operator who wants the previous behaviour.
+ */
+ public void disablePersistence() {
+ this.persistenceFile = null;
+ synchronized (writeLock) {
+ persistedBlock = -1L;
+ persistedHash = null;
+ persistedCount = -1;
+ }
+ }
+
+ /**
+ * The file heard seals are written to, or null when persistence is off.
+ *
+ * @return the seal file, or null
+ */
+ public Path persistenceFile() {
+ return persistenceFile;
+ }
+
+ /**
+ * Refill the cache from disk for a specific block, normally this node's chain head at startup.
+ *
+ * <p>Call this AFTER the Falcon registry has been activated, or every seal will be rejected for
+ * the entirely correct reason that the registry cannot resolve its index yet, and the restore will
+ * silently do nothing.
+ *
+ * @param blockNumber the head block's height
+ * @param onchainBlockHash the head block's ON-CHAIN hash
+ * @param registry the anchored registry every restored seal is re-verified against
+ * @return how many seals survived verification and entered the cache
+ */
+ public int restoreFromDisk(
+ final long blockNumber, final Hash onchainBlockHash, final PqSignerRegistry registry) {
+ final Path file = persistenceFile;
+ if (file == null) {
+ return 0;
+ }
+ List<FalconSeal> verified;
+ try {
+ verified =
+ PqSealStore.readVerified(
+ file, persistenceChainId, blockNumber, onchainBlockHash, registry);
+ if (verified.isEmpty()) {
+ // MAGAZIA TINE VARFUL (D-330): the main file may hold a later height that never imported;
+ // the previous slot may hold exactly the head. Same verification, same registry.
+ final Path previous = file.resolveSibling(PqSealStore.PREVIOUS_FILE_NAME);
+ verified =
+ PqSealStore.readVerified(
+ previous, persistenceChainId, blockNumber, onchainBlockHash, registry);
+ if (!verified.isEmpty()) {
+ LOG.info(
+ "AERE PERSISTENTA-SIGILII: {} seal(s) for the chain head {} restored from the PREVIOUS slot {}"
+ + " (the main file held a later height).",
+ verified.size(),
+ blockNumber,
+ previous);
+ }
+ }
+ } catch (final RuntimeException e) {
+ // readVerified is written not to throw; this is the belt on top of the braces, because an
+ // exception escaping here would turn a lost cache into a node that refuses to start.
+ LOG.warn(
+ "AERE PERSISTENTA-SIGILII: restoring seals from {} failed unexpectedly ({}); the cache "
+ + "starts empty, which is exactly the behaviour before this file existed.",
+ file,
+ e.toString());
+ return 0;
+ }
+ if (verified.isEmpty()) {
+ return 0;
+ }
+ synchronized (this) {
+ final Entry entry =
+ byHash.computeIfAbsent(onchainBlockHash, unused -> new Entry(blockNumber));
+ for (final FalconSeal seal : verified) {
+ entry.seals.putIfAbsent(seal.getValidatorIndex(), seal);
+ }
+ if (blockNumber > highestSeen) {
+ highestSeen = blockNumber;
+ }
+ prune();
+ }
+ return verified.size();
+ }
+
+ /**
+ * Remember the seals heard for a block. Idempotent per validator index: the first seal seen for
+ * an index wins, so a later duplicate cannot displace it.
+ *
+ * @param blockNumber the height of the block the seals attest
+ * @param onchainBlockHash the ON-CHAIN hash of that block
+ * @param seals the seals heard, possibly empty
+ */
+ public void record(
+ final long blockNumber, final Hash onchainBlockHash, final Collection<FalconSeal> seals) {
+ final List<FalconSeal> toPersist;
+ synchronized (this) {
+ if (onchainBlockHash == null || seals == null || seals.isEmpty()) {
+ return;
+ }
+ final Entry entry =
+ byHash.computeIfAbsent(onchainBlockHash, unused -> new Entry(blockNumber));
+ for (final FalconSeal seal : seals) {
+ if (seal != null && seal.getValidatorIndex() >= 0 && seal.getSignature() != null) {
+ entry.seals.putIfAbsent(seal.getValidatorIndex(), seal);
+ }
+ }
+ if (blockNumber > highestSeen) {
+ highestSeen = blockNumber;
+ }
+ prune();
+ if (persistenceFile == null || blockNumber < highestSeen) {
+ // Only the HIGHEST block is worth a file: the producer of the next block asks for the head's
+ // seals and nothing else, and writing older heights would just churn the disk.
+ return;
+ }
+ toPersist = PqAnchor.sortedByIndex(new ArrayList<>(entry.seals.values()));
+ }
+ // Deliberately OUTSIDE the map lock: a file write must never be able to stall a caller that only
+ // wants to read the cache.
+ persist(blockNumber, onchainBlockHash, toPersist);
+ }
+
+ private void persist(
+ final long blockNumber, final Hash onchainBlockHash, final List<FalconSeal> seals) {
+ final Path file = persistenceFile;
+ if (file == null) {
+ return;
+ }
+ synchronized (writeLock) {
+ if (blockNumber < persistedBlock) {
+ return;
+ }
+ if (blockNumber == persistedBlock
+ && onchainBlockHash.equals(persistedHash)
+ && seals.size() <= persistedCount) {
+ return;
+ }
+ try {
+ // MAGAZIA TINE VARFUL (D-330, 2026-09-03): before the main file moves to a HIGHER height, what it
+ // held becomes the previous slot. The main file may hold a proposal that never imports; the
+ // previous slot then still holds the head, and a restart can restore the head's seals from it.
+ if (persistedBlock >= 0 && blockNumber > persistedBlock && java.nio.file.Files.isRegularFile(file)) {
+ java.nio.file.Files.move(
+ file,
+ file.resolveSibling(PqSealStore.PREVIOUS_FILE_NAME),
+ java.nio.file.StandardCopyOption.REPLACE_EXISTING);
+ }
+ PqSealStore.writeAtomically(
+ file,
+ PqSealStore.encode(
+ persistenceChainId, blockNumber, onchainBlockHash.getBytes(), seals));
+ persistedBlock = blockNumber;
+ persistedHash = onchainBlockHash;
+ persistedCount = seals.size();
+ } catch (final Exception e) {
+ // A disk fault must not be able to stop this node from taking part in consensus. It costs
+ // the restart protection, which is what the log line says, and nothing else.
+ LOG.warn(
+ "AERE PERSISTENTA-SIGILII: could not write the {} heard seal(s) for block {} to {} "
+ + "({}). This node keeps working; it just loses its seals if it restarts now.",
+ seals.size(),
+ blockNumber,
+ file,
+ e.toString());
+ }
+ }
+ }
+
+ /**
+ * The seals heard for a block, in canonical order.
+ *
+ * @param blockNumber the height of the block the seals must attest
+ * @param onchainBlockHash the ON-CHAIN hash of that block
+ * @return the seals, sorted by strictly increasing validator index, possibly empty
+ */
+ /**
+ * AERE ANCHOR V2: remember the extra (non-Falcon) scheme seals heard on the commits of a block.
+ * Same key as {@link #record}, same window, same idempotence (first seal per validator and
+ * scheme wins). NOT persisted across a restart: a node that restarts holds no extras until it
+ * takes part in one commit, exactly the Falcon situation before PqSealStore, and the producer
+ * then refuses the v2 certificate for one proposer turn rather than writing a short one.
+ *
+ * @param blockNumber the height of the block the seals are over
+ * @param onchainBlockHash the round-independent on-chain hash of that block
+ * @param extraSeals the heard scheme seals, unverified
+ */
+ public void recordExtras(
+ final long blockNumber, final Hash onchainBlockHash, final Collection<SchemeSeal> extraSeals) {
+ synchronized (this) {
+ if (onchainBlockHash == null || extraSeals == null || extraSeals.isEmpty()) {
+ return;
+ }
+ final Entry entry =
+ byHash.computeIfAbsent(onchainBlockHash, unused -> new Entry(blockNumber));
+ for (final SchemeSeal seal : extraSeals) {
+ if (seal == null
+ || seal.getValidatorIndex() < 0
+ || seal.getSignature() == null
+ || seal.getSchemeWireId() == SealSchemes.FALCON_512.wireId()) {
+ continue;
+ }
+ final long key = ((long) seal.getValidatorIndex() << 8) | (seal.getSchemeWireId() & 0xffL);
+ entry.extras.putIfAbsent(key, seal);
+ }
+ if (blockNumber > highestSeen) {
+ highestSeen = blockNumber;
+ }
+ prune();
+ }
+ }
+
+ /**
+ * AERE ANCHOR V2: the extra scheme seals heard for a block, canonical order, unverified.
+ *
+ * @param blockNumber the height
+ * @param onchainBlockHash the round-independent on-chain hash
+ * @return the seals, or empty when nothing was heard under that key
+ */
+ public synchronized List<SchemeSeal> extrasFor(
+ final long blockNumber, final Hash onchainBlockHash) {
+ final Entry entry = byHash.get(onchainBlockHash);
+ if (entry == null || entry.blockNumber != blockNumber) {
+ return List.of();
+ }
+ final List<SchemeSeal> out = new ArrayList<>(entry.extras.values());
+ out.sort(PqAnchorV2.CANONICAL);
+ return out;
+ }
+
+ public synchronized List<FalconSeal> sealsFor(
+ final long blockNumber, final Hash onchainBlockHash) {
+ final Entry entry = byHash.get(onchainBlockHash);
+ if (entry == null || entry.blockNumber != blockNumber) {
+ return List.of();
+ }
+ return PqAnchor.sortedByIndex(new ArrayList<>(entry.seals.values()));
+ }
+
+ /**
+ * How many block hashes are currently retained.
+ *
+ * @return the number of entries
+ */
+ public synchronized int entryCount() {
+ return byHash.size();
+ }
+
+ /**
+ * How many seals are retained for a block hash.
+ *
+ * @param onchainBlockHash the ON-CHAIN hash
+ * @return the seal count, 0 when nothing is retained
+ */
+ public synchronized int sealCount(final Hash onchainBlockHash) {
+ final Entry entry = byHash.get(onchainBlockHash);
+ return entry == null ? 0 : entry.seals.size();
+ }
+
+ /**
+ * Drop everything held in memory. For tests, and for a deliberate operator reset. The file, if
+ * one exists, is deliberately left alone: it is rewritten by the next commit this node hears.
+ */
+ public synchronized void clear() {
+ byHash.clear();
+ highestSeen = -1L;
+ synchronized (writeLock) {
+ persistedBlock = -1L;
+ persistedHash = null;
+ persistedCount = -1;
+ }
+ }
+
+ private void prune() {
+ final Iterator<Map.Entry<Hash, Entry>> it = byHash.entrySet().iterator();
+ while (it.hasNext()) {
+ final Map.Entry<Hash, Entry> e = it.next();
+ if (highestSeen - e.getValue().blockNumber > HEIGHT_WINDOW) {
+ it.remove();
+ }
+ }
+ while (byHash.size() > MAX_ENTRIES) {
+ final Iterator<Hash> oldest = byHash.keySet().iterator();
+ oldest.next();
+ oldest.remove();
+ }
+ }
+
+ private static final class Entry {
+ private final long blockNumber;
+ private final Map<Integer, FalconSeal> seals = new LinkedHashMap<>();
+ /** AERE ANCHOR V2: heard extra (non-Falcon) scheme seals, keyed (index << 8 | wire). */
+ private final Map<Long, SchemeSeal> extras = new LinkedHashMap<>();
+
+ private Entry(final long blockNumber) {
+ this.blockNumber = blockNumber;
+ }
+ }
+}
diff --git a/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/PqSealStore.java b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/PqSealStore.java
new file mode 100755
index 000000000..6427140de
--- /dev/null
+++ b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/PqSealStore.java
@@ -0,0 +1,401 @@
+/*
+ * Copyright contributors to Besu / AERE Network.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.common.bft;
+
+import org.hyperledger.besu.datatypes.Hash;
+import org.hyperledger.besu.ethereum.rlp.BytesValueRLPInput;
+import org.hyperledger.besu.ethereum.rlp.BytesValueRLPOutput;
+import org.hyperledger.besu.ethereum.rlp.RLPInput;
+
+import java.io.IOException;
+import java.nio.ByteBuffer;
+import java.nio.channels.FileChannel;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.nio.file.StandardCopyOption;
+import java.nio.file.StandardOpenOption;
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.LinkedHashSet;
+import java.util.List;
+import java.util.Set;
+
+import org.apache.tuweni.bytes.Bytes;
+import org.apache.tuweni.bytes.Bytes32;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+/**
+ * AERE PERSISTENTA-SIGILII (2026-08-05): the ON-DISK half of {@link PqSealCache}, holding the Falcon
+ * seals this node heard for its CHAIN HEAD so that a restart does not start from zero.
+ *
+ * <p><b>THE SECOND HALF OF A MEASURED CHAIN DEATH.</b> With the anchor armed at K&gt;0, a
+ * SIMULTANEOUS restart of the whole fleet was measured to kill the chain for good. The first half of
+ * the deadlock was the registry, which only ever activated while a block was being imported; that is
+ * repaired (QbftBesuControllerBuilder, marker "AERE BLOCAJ-REPORNIRE") and the seven nodes now report
+ * "anchor activation at STARTUP from head state: SUCCEEDED". The chain still died, with the refusal
+ * changing shape only: "registry address-bound=TRUE ... Heard 0 seal(s)". This class is the second
+ * half. The seals over M(head) travel on nothing but the Commit messages of the head block, which are
+ * never replayed after a restart, so every node came back holding zero seals, nobody could reach K,
+ * and nobody could propose. Seals come from Commits, Commits come from proposals, proposals need
+ * seals - the same circle, one level down.
+ *
+ * <p><b>WHY THIS IS NOT DEFECT A8 IN ANOTHER COAT, and the distinction is the whole safety
+ * argument.</b> A8 was a REGISTRY read from a local file and BELIEVED: the public keys that decide
+ * who is a legitimate signer came out of a file a node could be pointed at wrongly, so the file was
+ * authority. Nothing here is believed. A Falcon seal is SELF-AUTHENTICATING: {@link
+ * #readVerified(Path, long, long, Hash, PqSignerRegistry)} re-verifies EVERY seal it reads against
+ * the anchored registry, over the message M rebuilt from the chain-head header this process just
+ * loaded, exactly as the producer does at selection time. A forged, edited or replayed file cannot
+ * inject a seal, because forging one means forging a Falcon-512 signature. The worst a hostile file
+ * can achieve is what an absent file already achieves: an empty cache, which is today's behaviour.
+ *
+ * <p><b>WHAT THE FILE IS BOUND TO.</b> The domain label, the chain id, the block NUMBER and the block
+ * HASH are all in the file and all checked before a single signature is verified. A file from another
+ * chain, another height, or another fork of the same height is discarded whole. That is not a
+ * security property (the signature check is), it is an honesty property: it makes "these are the
+ * seals for THIS head" checkable rather than assumed.
+ *
+ * <p><b>FAILURE IS NEVER FATAL.</b> Missing, truncated, corrupt, oversized, from another height, or
+ * unreadable for any reason at all: the answer is an empty list and a log line, never an exception
+ * that reaches the caller. A node that cannot read its seal file must behave exactly like a node that
+ * has none, because that is precisely the state this whole class exists to make survivable.
+ */
+public final class PqSealStore {
+
+ private static final Logger LOG = LoggerFactory.getLogger(PqSealStore.class);
+
+ /** The file name, inside the node's data directory. Never an absolute configured path. */
+ public static final String FILE_NAME = "aere-pq-seals.rlp";
+
+ /** The temporary file the atomic write goes through before the rename. */
+ public static final String TEMP_FILE_NAME = "aere-pq-seals.rlp.tmp";
+
+ /**
+ * D-330 (2026-09-03): the PREVIOUS slot. The main file holds the highest height heard, which can be
+ * a proposal that never imported (testnet 28001: the file held 168032 while the head was 168031,
+ * and after a fleet-wide restart every node had zero seals for the head). The previous slot keeps
+ * what the main file held before its last rotation, so the head's seals survive one extra height.
+ */
+ public static final String PREVIOUS_FILE_NAME = "aere-pq-seals-anterior.rlp";
+
+ /** Domain label, so a file written for any other purpose cannot be read as a seal set. */
+ public static final String DOMAIN = "AERE-PQ-SEALSTORE-1";
+
+ private static final Bytes DOMAIN_BYTES =
+ Bytes.wrap(DOMAIN.getBytes(StandardCharsets.US_ASCII));
+
+ /**
+ * Refuse to even parse a file larger than this. A Falcon-512 signature is 666 bytes and a fleet is
+ * seven, so a real file is about 5 kB; 1 MiB is four orders of magnitude of headroom and still
+ * bounds what a corrupt or hostile file can make this process allocate.
+ */
+ public static final int MAX_FILE_BYTES = 1024 * 1024;
+
+ /** Refuse to accumulate more seals than this from one file, for the same reason. */
+ public static final int MAX_SEALS = 1024;
+
+ /**
+ * System property forcing an fsync of the temporary file before the rename. Default true: the
+ * whole point of the file is to survive an unplanned restart, and the measured cost is small
+ * against the block interval.
+ */
+ public static final String PROPERTY_FSYNC = "aere.pq.sealStore.fsync";
+
+ private PqSealStore() {}
+
+ /**
+ * The seal file inside a node's data directory.
+ *
+ * @param dataDirectory the node's data directory, as Besu was started with
+ * @return the path of the seal file
+ */
+ public static Path fileIn(final Path dataDirectory) {
+ return dataDirectory.resolve(FILE_NAME);
+ }
+
+ /**
+ * The previous-slot file beside {@link #fileIn}.
+ *
+ * @param dataDirectory the node data directory
+ * @return the previous slot's path
+ */
+ public static Path previousFileIn(final Path dataDirectory) {
+ return dataDirectory.resolve(PREVIOUS_FILE_NAME);
+ }
+
+ /**
+ * The canonical bytes of a seal set.
+ *
+ * <p>The certificate itself is written by {@link PqAnchor#writeCertificate}, the SAME encoder that
+ * produces the bytes carried in element 6 of a header and hashed into the anchor digest. One
+ * logical object, one byte string, no second encoder to drift.
+ *
+ * @param chainId the chain id, also part of the M pre-image
+ * @param blockNumber the height of the block the seals attest
+ * @param blockHash the ON-CHAIN hash of that block
+ * @param seals the seals to store, in the order given
+ * @return the file payload
+ */
+ public static byte[] encode(
+ final long chainId,
+ final long blockNumber,
+ final Bytes blockHash,
+ final Collection<FalconSeal> seals) {
+ final BytesValueRLPOutput out = new BytesValueRLPOutput();
+ out.startList();
+ out.writeBytes(DOMAIN_BYTES);
+ out.writeLongScalar(chainId);
+ out.writeLongScalar(blockNumber);
+ out.writeBytes(blockHash);
+ PqAnchor.writeCertificate(out, seals);
+ out.endList();
+ return out.encoded().toArrayUnsafe();
+ }
+
+ /**
+ * Write the payload so that no reader can ever observe a half-written file.
+ *
+ * <p>Temporary file, optional fsync, then an ATOMIC_MOVE onto the target. A process killed at any
+ * instant leaves either the previous complete file or the new complete file, never a prefix of
+ * either. The fallback to a non-atomic move exists because ATOMIC_MOVE is not universally
+ * supported; a filesystem that cannot do it is still better served by a rename than by writing in
+ * place.
+ *
+ * @param file the target file
+ * @param payload the bytes to write
+ * @throws IOException if the write or the rename fails
+ */
+ public static void writeAtomically(final Path file, final byte[] payload) throws IOException {
+ final Path directory = file.toAbsolutePath().getParent();
+ if (directory != null) {
+ Files.createDirectories(directory);
+ }
+ final Path temp =
+ directory == null ? Path.of(TEMP_FILE_NAME) : directory.resolve(TEMP_FILE_NAME);
+ try (FileChannel channel =
+ FileChannel.open(
+ temp,
+ StandardOpenOption.CREATE,
+ StandardOpenOption.WRITE,
+ StandardOpenOption.TRUNCATE_EXISTING)) {
+ final ByteBuffer buffer = ByteBuffer.wrap(payload);
+ while (buffer.hasRemaining()) {
+ channel.write(buffer);
+ }
+ if (!"false".equalsIgnoreCase(System.getProperty(PROPERTY_FSYNC))) {
+ channel.force(true);
+ }
+ }
+ try {
+ Files.move(
+ temp, file, StandardCopyOption.REPLACE_EXISTING, StandardCopyOption.ATOMIC_MOVE);
+ } catch (final UnsupportedOperationException | IOException atomicUnsupported) {
+ Files.move(temp, file, StandardCopyOption.REPLACE_EXISTING);
+ }
+ }
+
+ /**
+ * Read the seals stored for a block and return ONLY those that verify RIGHT NOW against the
+ * anchored registry.
+ *
+ * <p>Every seal is put through the same two questions the producer asks at selection time: does
+ * the index map to a signer in the registry, and does the Falcon signature verify over M(this
+ * block). Nothing is accepted because it is in the file. What is deliberately NOT re-checked here
+ * is validator-set eligibility, and that is not a gap: the producer re-checks it against the
+ * validator set FOR THE PARENT every time it assembles a certificate, so a seal from a former
+ * validator is dropped there whether it came from a Commit message or from this file.
+ *
+ * @param file the seal file
+ * @param chainId the chain id this node runs, part of the M pre-image
+ * @param blockNumber the height the seals must attest, normally this node's chain head
+ * @param blockHash the ON-CHAIN hash the seals must attest
+ * @param registry the anchored Falcon registry to verify against
+ * @return the surviving seals sorted by strictly increasing index, empty on any fault whatsoever
+ */
+ public static List<FalconSeal> readVerified(
+ final Path file,
+ final long chainId,
+ final long blockNumber,
+ final Hash blockHash,
+ final PqSignerRegistry registry) {
+
+ if (file == null || registry == null || blockHash == null) {
+ return List.of();
+ }
+
+ final byte[] raw;
+ try {
+ if (!Files.isRegularFile(file)) {
+ LOG.debug("AERE PERSISTENTA-SIGILII: no seal file at {}; starting with an empty cache.", file);
+ return List.of();
+ }
+ final long size = Files.size(file);
+ if (size <= 0 || size > MAX_FILE_BYTES) {
+ LOG.warn(
+ "AERE PERSISTENTA-SIGILII: seal file {} has an implausible size ({} bytes); IGNORED, "
+ + "the cache starts empty exactly as it did before this file existed.",
+ file,
+ size);
+ return List.of();
+ }
+ raw = Files.readAllBytes(file);
+ } catch (final Exception e) {
+ LOG.warn(
+ "AERE PERSISTENTA-SIGILII: seal file {} could not be read ({}); IGNORED, the cache starts "
+ + "empty. A node that cannot read this file must behave like a node that has none.",
+ file,
+ e.toString());
+ return List.of();
+ }
+
+ final List<FalconSeal> decoded = new ArrayList<>();
+ final long storedNumber;
+ final Bytes storedHash;
+ try {
+ final RLPInput in = new BytesValueRLPInput(Bytes.wrap(raw), false);
+ in.enterList();
+ final Bytes domain = in.readBytes();
+ if (!DOMAIN_BYTES.equals(domain)) {
+ LOG.warn(
+ "AERE PERSISTENTA-SIGILII: seal file {} carries domain {} instead of {}; IGNORED.",
+ file,
+ domain,
+ DOMAIN);
+ return List.of();
+ }
+ final long storedChainId = in.readLongScalar();
+ if (storedChainId != chainId) {
+ LOG.warn(
+ "AERE PERSISTENTA-SIGILII: seal file {} was written for chain {} and this node runs "
+ + "chain {}; IGNORED.",
+ file,
+ storedChainId,
+ chainId);
+ return List.of();
+ }
+ storedNumber = in.readLongScalar();
+ storedHash = in.readBytes();
+ in.enterList();
+ while (!in.isEndOfCurrentList()) {
+ if (decoded.size() >= MAX_SEALS) {
+ LOG.warn(
+ "AERE PERSISTENTA-SIGILII: seal file {} holds more than {} seals; IGNORED.",
+ file,
+ MAX_SEALS);
+ return List.of();
+ }
+ in.enterList();
+ final int index = in.readIntScalar();
+ final Bytes signature = in.readBytes();
+ in.leaveList();
+ decoded.add(new FalconSeal(index, signature));
+ }
+ in.leaveList();
+ in.leaveList();
+ } catch (final RuntimeException e) {
+ LOG.warn(
+ "AERE PERSISTENTA-SIGILII: seal file {} is CORRUPT and did not decode ({}); IGNORED, the "
+ + "cache starts empty. This costs at most one proposer turn; refusing to start would "
+ + "cost the chain.",
+ file,
+ e.toString());
+ return List.of();
+ }
+
+ if (storedNumber != blockNumber || !storedHash.equals(blockHash.getBytes())) {
+ LOG.info(
+ "AERE PERSISTENTA-SIGILII: seal file {} holds seals for block {} ({}), this node's head is "
+ + "{} ({}); IGNORED. Seals over another block are of no use to the proposer of the "
+ + "next one.",
+ file,
+ storedNumber,
+ storedHash,
+ blockNumber,
+ blockHash);
+ return List.of();
+ }
+
+ final Bytes32 message = PqAnchor.commitMessage(chainId, blockNumber, blockHash.getBytes());
+ final List<FalconSeal> verified = new ArrayList<>();
+ final Set<Integer> seen = new LinkedHashSet<>();
+ int rejectedUnknownIndex = 0;
+ int rejectedSignature = 0;
+ for (final FalconSeal seal : PqAnchor.sortedByIndex(decoded)) {
+ if (seal.getValidatorIndex() < 0
+ || seal.getSignature() == null
+ || !seen.add(seal.getValidatorIndex())
+ // D2 (2026-08-06): height-resolved. These seals are over block `blockNumber`, which the
+ // caller has already matched against the stored header, so the height is known exactly.
+ // On a restart at the head this resolves to the same registry it always did; the point is
+ // that it can no longer resolve to a DIFFERENT one without saying so.
+ // D2 (b-v2): the OWN-HEAD door. The caller has already refused this file unless the
+ // stored block number and hash equal this node's head, so the subject is this node's
+ // own head by construction.
+ || registry.addressForIndexAtOwnHead(blockNumber, seal.getValidatorIndex()) == null) {
+ rejectedUnknownIndex++;
+ continue;
+ }
+ if (!sealVerifiesAgainstAnchoredRegistry(
+ registry, blockNumber, message, seal.getValidatorIndex(), seal.getSignature())) {
+ rejectedSignature++;
+ continue;
+ }
+ verified.add(seal);
+ }
+
+ LOG.info(
+ "AERE PERSISTENTA-SIGILII: restored {} of {} stored seal(s) for head {} from {}; {} had no "
+ + "registry index, {} FAILED Falcon verification over M(head) and were dropped.",
+ verified.size(),
+ decoded.size(),
+ blockNumber,
+ file,
+ rejectedUnknownIndex,
+ rejectedSignature);
+ return verified;
+ }
+
+ /**
+ * THE LOAD-BEARING LINE OF THIS WHOLE FILE, isolated so that removing it is a one-line edit and
+ * the test suite's negative control can prove that removing it turns the forged-seal test RED.
+ *
+ * <p>This is the same call, on the same registry interface, that {@code PqAnchorProducer.apply}
+ * makes when it decides which heard seals may enter a certificate. Nothing about a seal is trusted
+ * because it was on disk.
+ *
+ * <p>D2 (2026-08-06): it now carries the HEIGHT the seals belong to. The adversarial review of
+ * 2026-08-02 measured that every registry question in this stack was height-less, so a restart
+ * after a key rotation re-checked seals over an old block against today's keys and dropped them
+ * all as forged. Here the height is not in doubt: the caller has already refused the file unless
+ * the stored block number and hash equal this node's head.
+ *
+ * @param registry the anchored Falcon registry
+ * @param blockNumber the height of the block the stored seals attest
+ * @param message the message M over the block the seals attest
+ * @param validatorIndex the seal's registry index
+ * @param signature the Falcon-512 signature bytes
+ * @return true iff the signature verifies
+ */
+ private static boolean sealVerifiesAgainstAnchoredRegistry(
+ final PqSignerRegistry registry,
+ final long blockNumber,
+ final Bytes32 message,
+ final int validatorIndex,
+ final Bytes signature) {
+ return registry.verifyAtOwnHead(blockNumber, validatorIndex, message, signature);
+ }
+}
diff --git a/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/PqSignerRegistry.java b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/PqSignerRegistry.java
new file mode 100755
index 000000000..bfaa45662
--- /dev/null
+++ b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/PqSignerRegistry.java
@@ -0,0 +1,167 @@
+/*
+ * Copyright contributors to Besu / AERE Network.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.common.bft;
+
+import org.hyperledger.besu.datatypes.Address;
+
+import org.apache.tuweni.bytes.Bytes;
+
+/**
+ * The index-to-signer view the anchor seals rule needs: which validator ADDRESS a registry index
+ * belongs to, and whether a Falcon signature by that index verifies over a message.
+ *
+ * <p>This exists as an interface for one reason that matters and one that is convenience. The one
+ * that matters: header validation must be able to state its dependency on the registry explicitly,
+ * so the registry can be bound to consensus (genesis {@code pqRegistryHash}) rather than picked up
+ * implicitly from a process-wide singleton whose contents are a local file. The convenience: a rule
+ * with an injectable registry can be unit-tested without standing up the whole Falcon subsystem.
+ *
+ * <p>The production implementation is {@link #falconSealSupport()}, which resolves {@link
+ * FalconSealSupport#instance()} LAZILY, per call. Lazily matters: constructing a rule must not
+ * trigger the Falcon subsystem's start-up guards, because rules are constructed while the protocol
+ * schedule is being built and the ONE place that deliberately forces those guards early is {@code
+ * QbftBlockHeaderValidationRulesetFactory}, which does it explicitly.
+ */
+public interface PqSignerRegistry {
+
+ /**
+ * D-081 / D2 HARDENING (a). The validator address bound to a registry index AT A HEIGHT.
+ *
+ * <p>WHY THERE IS NO HEIGHT-LESS FORM HERE, and why this is the change and not a nicety. Until
+ * 2026-08-06 this interface carried BOTH {@code addressForIndex(int)} and a {@code
+ * addressForIndexAt(long,int)} whose body was {@code default { return addressForIndex(idx); }}.
+ * That default is precisely what the adversarial review of 2026-08-02 measured as D2: a registry
+ * has no height argument, so a header that verified yesterday is refused the moment index 0's
+ * Falcon key is rotated. The default made the defect INVISIBLE TO ITS OWN PROOF - the D2 harness
+ * (adversar-2026-08-02/harness/RuleProbe.java lines 115-131) injects a registry that overrides
+ * only the height-less pair, inherits the default, and therefore returns exactly the same verdict
+ * on repaired and unrepaired code. A probe that cannot go red is not a probe.
+ *
+ * <p>So the height-less pair is DELETED rather than deprecated, and both survivors are abstract.
+ * The compiler is now the negative control: any implementation, test double included, that cannot
+ * answer "at which height" fails to compile. The signing side keeps its height-less identity, but
+ * on {@link FalconSealSupport} and under a name that cannot be mistaken for a verification path -
+ * see {@code FalconSealSupport.localSigningAddress()}.
+ *
+ * <p>D2 HARDENING (b-v2), 2026-08-06: this is the HISTORY half of the pair. It is reachable
+ * only from the two header-validation rules, and it REFUSES an unbound height at or above the
+ * arming height. The own-head half is {@link #addressForIndexAtOwnHead}, which carries the
+ * measurement that forced the split.
+ *
+ * @param blockNumber the height of the header being validated
+ * @param validatorIndex the index carried by a Falcon seal
+ * @return the bound address, or null when the index is unregistered at that height, the registry
+ * active there is not address-bound, or no registry is covered there at all
+ */
+ Address addressForIndexAtHistoric(long blockNumber, int validatorIndex);
+
+ /**
+ * D2 HARDENING (b-v2). The address bound to a registry index at a height, asked about THIS NODE'S
+ * OWN HEAD: a block this node is building, or the head it has just restarted onto.
+ *
+ * <p>WHY THIS SECOND NAME EXISTS, and it is a measurement and not a taste. The first shape of
+ * hardening (b) refused every unbound height at or above the arming height and decided that from
+ * the block NUMBER alone. On 2026-08-06 that turned six tests red - five in {@code
+ * PqSealPersistenceTest}, the restart path, and one in {@code PqForkValidatorSetChangeTest}, the
+ * proposer - and the D078 message states the operational consequence in one line: the node stops
+ * producing blocks. In all six the number handed to the guard was 1030 with an arming height of
+ * 1000, which is exactly what a genuinely historical question at the same instant would hand it.
+ * There is no arithmetic on the height that separates the two. What separates them is WHO SUPPLIES
+ * THE SUBJECT, and that is known at every call site and was being thrown away at the boundary.
+ *
+ * <p>THIS pair does not refuse for a missing height binding, because at this node's own head the
+ * head registry IS the answer by construction, and a wrong local acceptance cannot manufacture
+ * history: the certificate is re-checked by the other six through {@code PqAnchorSealsRule}, on
+ * the HISTORIC pair, at the parent's height. The cost of a mistake here is one lost round, not a
+ * branch. It still returns null when a schedule IS configured and covers this height with a
+ * registry this node does not hold - that is not a missing binding, it is a node running a
+ * registry the chain has moved off, and that must fail closed on every path.
+ *
+ * @param blockNumber this node's own head, or the block it is building
+ * @param validatorIndex the registry index
+ * @return the bound address, or null
+ */
+ Address addressForIndexAtOwnHead(long blockNumber, int validatorIndex);
+
+ /**
+ * D-081 / D2 HARDENING (a). Verify a Falcon signature by a registry index AT A HEIGHT. Must never
+ * throw. Abstract for the reason given on {@link #addressForIndexAtHistoric}.
+ *
+ * @param blockNumber the height of the header carrying the seal
+ * @param validatorIndex the signer's registry index
+ * @param message the 32-byte message M that was signed
+ * @param signature the Falcon-512 signature bytes
+ * @return true iff a public key exists for the index at that height and the signature verifies
+ */
+ boolean verifyAtHistoric(long blockNumber, int validatorIndex, Bytes message, Bytes signature);
+
+ /**
+ * D2 HARDENING (b-v2). Verify a Falcon signature over a block THIS NODE holds as its own head or
+ * is building right now. Never refuses for a missing height binding; see {@link
+ * #addressForIndexAtOwnHead} for the measurement that forced the split and for what it still does
+ * refuse.
+ *
+ * @param blockNumber this node's own head, or the block it is building
+ * @param validatorIndex the signer's registry index
+ * @param message the 32-byte message M that was signed
+ * @param signature the Falcon-512 signature bytes
+ * @return true iff a key exists for the index there and the signature verifies
+ */
+ boolean verifyAtOwnHead(long blockNumber, int validatorIndex, Bytes message, Bytes signature);
+
+ /**
+ * The production registry, backed by the Falcon subsystem singleton and resolved per call.
+ *
+ * @return a registry view over {@link FalconSealSupport#instance()}
+ */
+ static PqSignerRegistry falconSealSupport() {
+ return new PqSignerRegistry() {
+ @Override
+ public Address addressForIndexAtHistoric(final long blockNumber, final int validatorIndex) {
+ return FalconSealSupport.instance().addressForIndexAtHistoric(blockNumber, validatorIndex);
+ }
+
+ @Override
+ public boolean verifyAtHistoric(
+ final long blockNumber,
+ final int validatorIndex,
+ final Bytes message,
+ final Bytes signature) {
+ return FalconSealSupport.instance()
+ .verifyAtHistoric(blockNumber, validatorIndex, message, signature);
+ }
+
+ @Override
+ public Address addressForIndexAtOwnHead(final long blockNumber, final int validatorIndex) {
+ return FalconSealSupport.instance().addressForIndexAtOwnHead(blockNumber, validatorIndex);
+ }
+
+ @Override
+ public boolean verifyAtOwnHead(
+ final long blockNumber,
+ final int validatorIndex,
+ final Bytes message,
+ final Bytes signature) {
+ return FalconSealSupport.instance()
+ .verifyAtOwnHead(blockNumber, validatorIndex, message, signature);
+ }
+
+ @Override
+ public String toString() {
+ return "FalconSealSupport";
+ }
+ };
+ }
+}
diff --git a/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/SchemeSeal.java b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/SchemeSeal.java
new file mode 100755
index 000000000..ed5a63807
--- /dev/null
+++ b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/SchemeSeal.java
@@ -0,0 +1,69 @@
+/* AERE crypto-agility, step 2: a seal that names its scheme. The legacy FalconSeal cannot say
+ * what mathematics signed it, so a certificate of FalconSeals can never carry a hybrid. This one
+ * carries the one-byte scheme wire tag from {@link SealSchemes}, which is the whole difference. */
+package org.hyperledger.besu.consensus.common.bft;
+
+import java.util.Objects;
+
+import org.apache.tuweni.bytes.Bytes;
+
+/** One validator seal tagged with the scheme that produced it. Immutable. */
+public final class SchemeSeal {
+
+ private final byte schemeWireId;
+ private final int validatorIndex;
+ private final Bytes signature;
+
+ /** @param schemeWireId the {@link SealScheme#wireId()} of the producing scheme
+ * @param validatorIndex the signer registry index, non-negative
+ * @param signature the raw signature bytes */
+ public SchemeSeal(final byte schemeWireId, final int validatorIndex, final Bytes signature) {
+ this.schemeWireId = schemeWireId;
+ this.validatorIndex = validatorIndex;
+ this.signature = signature;
+ }
+
+ /** The wire tag of the scheme that produced this seal. */
+ public byte getSchemeWireId() {
+ return schemeWireId;
+ }
+
+ /** The signer registry index. */
+ public int getValidatorIndex() {
+ return validatorIndex;
+ }
+
+ /** The raw signature bytes. */
+ public Bytes getSignature() {
+ return signature;
+ }
+
+ @Override
+ public boolean equals(final Object o) {
+ if (this == o) {
+ return true;
+ }
+ if (!(o instanceof SchemeSeal that)) {
+ return false;
+ }
+ return schemeWireId == that.schemeWireId
+ && validatorIndex == that.validatorIndex
+ && Objects.equals(signature, that.signature);
+ }
+
+ @Override
+ public int hashCode() {
+ return Objects.hash(schemeWireId, validatorIndex, signature);
+ }
+
+ @Override
+ public String toString() {
+ return "SchemeSeal{scheme=0x"
+ + Integer.toHexString(schemeWireId & 0xff)
+ + ", index="
+ + validatorIndex
+ + ", sig="
+ + signature.size()
+ + "B}";
+ }
+}
diff --git a/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/SealScheme.java b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/SealScheme.java
new file mode 100755
index 000000000..228b9a0f8
--- /dev/null
+++ b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/SealScheme.java
@@ -0,0 +1,96 @@
+/*
+ * AERE crypto-agility layer, step 1 (2026-08-24, TOP-3 list item 9).
+ *
+ * WHY THIS EXISTS. Until today the anchor certificate code talked to exactly one algorithm,
+ * Falcon-512, by name: FalconSeal, FalconSealSupport, FalconPublicKeyParameters. "Safe when the
+ * math changes" was a slogan the code could not honour, because changing the math meant editing
+ * every call site. This interface is the seam that makes the slogan checkable: the protocol talks
+ * to a SealScheme; which lattice (or hash) sits behind it is configuration.
+ *
+ * WHAT IT DELIBERATELY IS NOT. It does not touch FalconSealSupport yet (that rewiring is step 2,
+ * and that file is an overwrite-class file under the D-152 patch discipline). It does not load
+ * private keys from disk (production loading stays per-scheme, exactly as today). It does not
+ * invent a private-key wire encoding: private keys live only as in-memory handles, so no new
+ * secret format exists to leak or to get wrong.
+ */
+package org.hyperledger.besu.consensus.common.bft;
+
+import java.security.SecureRandom;
+import java.util.Optional;
+
+/** A pluggable post-quantum signature scheme for validator seals. Implementations never throw
+ * from {@link #verify}: a malformed key or signature is simply an invalid seal. */
+public interface SealScheme {
+
+ /** Stable human-readable identifier, e.g. {@code "falcon-512"}. Matches the naming the chain
+ * already uses publicly (precompile docs, /v1/pq/verify schemes). */
+ String id();
+
+ /** One-byte wire tag reserved for the versioned certificate format (v2) in which each seal
+ * names its scheme. 0x00 is reserved for "unversioned legacy Falcon". */
+ byte wireId();
+
+ /** Parse the registry form of a public key (the exact bytes a signer registry stores).
+ * Empty when the bytes cannot be a key of this scheme. */
+ Optional<PublicHandle> parsePublicKey(byte[] registryForm);
+
+ /** The registry-form length in bytes, so registries can sanity-check entries per scheme. */
+ int publicKeyLength();
+
+ /** Sign a message. Empty on any failure; never throws. */
+ Optional<byte[]> sign(PrivateHandle key, byte[] message);
+
+ /** Verify. False on any failure, including a handle from another scheme; never throws. */
+ boolean verify(PublicHandle key, byte[] message, byte[] signature);
+
+ /** Convenience: parse-then-verify straight from registry bytes. False on any failure. */
+ default boolean verifyRaw(final byte[] registryForm, final byte[] message, final byte[] signature) {
+ try {
+ return parsePublicKey(registryForm).map(k -> verify(k, message, signature)).orElse(false);
+ } catch (final RuntimeException e) {
+ return false;
+ }
+ }
+
+ /** Generate a fresh key pair. Used by test networks only: real validator keys are born in the
+ * vault ceremony, never inside a node. */
+ GeneratedPair generate(SecureRandom random);
+
+ /**
+ * The scheme's OWN canonical private-key encoding, when it has one. Empty by default.
+ *
+ * <p>DATED NOTE 2026-08-25, refining the sentence at the top of this file. The layer
+ * still does NOT invent a private-key format: the methods below expose exactly the
+ * encoding the scheme's library already has, and only schemes that truly have one
+ * implement them. Measured today on the shipped jar: SLH-DSA-128s has {@code getEncoded()}
+ * with an exact round-trip, so it implements them; Falcon-512 keeps its key in components
+ * and its PRODUCTION loading stays untouched in FalconSealSupport, so it does NOT implement
+ * them and returns empty. Why it was needed: the hybrid producer must be able to receive
+ * the second scheme's key without every call site knowing which scheme it is.
+ *
+ * @param key the private handle
+ * @return the encoding, or empty when this scheme has no canonical one
+ */
+ default Optional<byte[]> serializePrivateKey(final PrivateHandle key) {
+ return Optional.empty();
+ }
+
+ /**
+ * Rebuild a private handle from {@link #serializePrivateKey}. Empty on anything unusable.
+ *
+ * @param raw the encoding
+ * @return the handle, or empty
+ */
+ default Optional<PrivateHandle> parsePrivateKey(final byte[] raw) {
+ return Optional.empty();
+ }
+
+ /** Opaque scheme-specific public key. */
+ interface PublicHandle {}
+
+ /** Opaque scheme-specific private key. Never serialised by this layer. */
+ interface PrivateHandle {}
+
+ /** A freshly generated pair plus the registry form of its public key. */
+ record GeneratedPair(PublicHandle publicKey, PrivateHandle privateKey, byte[] publicRegistryForm) {}
+}
diff --git a/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/SealSchemes.java b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/SealSchemes.java
new file mode 100755
index 000000000..a3e39f4f2
--- /dev/null
+++ b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/SealSchemes.java
@@ -0,0 +1,56 @@
+/* AERE crypto-agility: the scheme registry. The protocol asks here by name or wire tag and gets
+ * an algorithm; swapping the mathematics becomes configuration plus keys, never call-site edits.
+ * Wire tags are the certificate-v2 vocabulary: 0x00 stays reserved for the unversioned legacy
+ * Falcon certificate already live on chain 2800, so old certificates can never be confused with
+ * tagged ones. */
+package org.hyperledger.besu.consensus.common.bft;
+
+import java.util.List;
+import java.util.Optional;
+
+/** Static registry of the seal schemes this build understands. */
+public final class SealSchemes {
+
+ /** Falcon-512 (lattice), the scheme live on chain 2800 today. */
+ public static final SealScheme FALCON_512 = new FalconSealScheme();
+
+ /** SLH-DSA-128s (hash-based, FIPS 205), the founder-approved hybrid counterpart. */
+ public static final SealScheme SLH_DSA_128S = new SlhDsaSealScheme();
+
+ private static final List<SealScheme> ALL = List.of(FALCON_512, SLH_DSA_128S);
+
+ private SealSchemes() {}
+
+ /** All schemes this build understands, in wire-tag order. */
+ public static List<SealScheme> all() {
+ return ALL;
+ }
+
+ /** Look up by stable id, e.g. {@code "falcon-512"}. Empty for unknown ids: an unknown scheme
+ * must be a loud configuration error at the caller, never a silent default. */
+ public static Optional<SealScheme> byId(final String id) {
+ if (id == null) {
+ return Optional.empty();
+ }
+ // D-325: the SLH-DSA scheme is named "slh-dsa-sha2-128s" on both clients now; the old short id
+ // is still understood so an existing schedule string keeps meaning the same mathematics.
+ final String wanted = SlhDsaSealScheme.LEGACY_ID.equals(id) ? SLH_DSA_128S.id() : id;
+ for (final SealScheme s : ALL) {
+ if (s.id().equals(wanted)) {
+ return Optional.of(s);
+ }
+ }
+ return Optional.empty();
+ }
+
+ /** Look up by certificate-v2 wire tag. Empty for 0x00 (legacy, not a tagged scheme) and for
+ * anything unknown. */
+ public static Optional<SealScheme> byWireId(final byte wireId) {
+ for (final SealScheme s : ALL) {
+ if (s.wireId() == wireId) {
+ return Optional.of(s);
+ }
+ }
+ return Optional.empty();
+ }
+}
diff --git a/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/SlhDsaSealScheme.java b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/SlhDsaSealScheme.java
new file mode 100755
index 000000000..27a8f8e7e
--- /dev/null
+++ b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/SlhDsaSealScheme.java
@@ -0,0 +1,136 @@
+/* AERE crypto-agility: SLH-DSA-128s (NIST FIPS 205, the standardised SPHINCS+) behind the
+ * SealScheme seam. This is the second half of the founder-approved hybrid direction of
+ * 2026-08-07 (option 3): hash-based security alongside lattice-based Falcon, so that a break in
+ * either mathematics leaves the other standing. The scheme name matches the precompile the chain
+ * already runs at 0x0AE4 since block 9,189,161, so the public naming stays consistent.
+ *
+ * NOTE ON KEYS: introducing this scheme creates NO keys anywhere. Real hybrid validator keys
+ * require a separate founder-approved ceremony (standing rule, 2026-08-07); test networks
+ * generate throwaway pairs per run via {@link #generate}. */
+package org.hyperledger.besu.consensus.common.bft;
+
+import java.security.SecureRandom;
+import java.util.Optional;
+
+import org.bouncycastle.crypto.AsymmetricCipherKeyPair;
+import org.hyperledger.besu.consensus.common.bft.slhdsa.SLHDSAKeyGenerationParameters;
+import org.hyperledger.besu.consensus.common.bft.slhdsa.SLHDSAKeyPairGenerator;
+import org.hyperledger.besu.consensus.common.bft.slhdsa.SLHDSAParameters;
+import org.hyperledger.besu.consensus.common.bft.slhdsa.SLHDSAPrivateKeyParameters;
+import org.hyperledger.besu.consensus.common.bft.slhdsa.SLHDSAPublicKeyParameters;
+import org.hyperledger.besu.consensus.common.bft.slhdsa.SLHDSASigner;
+
+/** SLH-DSA-128s (small, SHA2 family) as a pluggable seal scheme. */
+/*
+ * D-337 (2026-09-04): the SLH-DSA classes come from the in-tree copy of Bouncy Castle's engine
+ * (package ..bft.slhdsa) whose SHA-2 runs on the JDK's SHA-NI intrinsics. Bouncy Castle's pure-Java
+ * digest made one sha2_128s signature cost 1.4-2.7 s on the validators' CPUs, on the QBFT thread, at
+ * every anchor parent, and the chain slowed from 0.56 to 0.76 s per block. Measured on the same CPUs
+ * the in-tree engine signs in 0.3-0.7 s; same keys, same bytes (SlhDsaFastEngineTest pins that
+ * against the original).
+ */
+public final class SlhDsaSealScheme implements SealScheme {
+
+ /** Registry form: the encoded SLH-DSA-128s public key (PK.seed || PK.root), 32 bytes. */
+ public static final int PUBLIC_KEY_LENGTH = 32;
+
+ private static final SLHDSAParameters PARAMS = SLHDSAParameters.sha2_128s;
+
+ private record Pub(SLHDSAPublicKeyParameters params) implements PublicHandle {}
+
+ private record Priv(SLHDSAPrivateKeyParameters params) implements PrivateHandle {}
+
+ // D-325 (2026-09-03): the id the SECOND client and the public verifier use, "slh-dsa-sha2-128s";
+ // the shorter "slh-dsa-128s" stays accepted as an alias in SealSchemes.byId so no schedule breaks.
+ @Override
+ public String id() {
+ return "slh-dsa-sha2-128s";
+ }
+
+ /** The alias this build accepted before D-325. */
+ public static final String LEGACY_ID = "slh-dsa-128s";
+
+ @Override
+ public byte wireId() {
+ return 0x02;
+ }
+
+ @Override
+ public int publicKeyLength() {
+ return PUBLIC_KEY_LENGTH;
+ }
+
+ @Override
+ public Optional<PublicHandle> parsePublicKey(final byte[] registryForm) {
+ if (registryForm == null || registryForm.length != PUBLIC_KEY_LENGTH) {
+ return Optional.empty();
+ }
+ try {
+ return Optional.of(new Pub(new SLHDSAPublicKeyParameters(PARAMS, registryForm)));
+ } catch (final RuntimeException e) {
+ return Optional.empty();
+ }
+ }
+
+ @Override
+ public Optional<byte[]> sign(final PrivateHandle key, final byte[] message) {
+ if (!(key instanceof Priv p) || message == null) {
+ return Optional.empty();
+ }
+ try {
+ final SLHDSASigner signer = new SLHDSASigner();
+ signer.init(true, p.params());
+ return Optional.of(signer.generateSignature(message));
+ } catch (final RuntimeException e) {
+ return Optional.empty();
+ }
+ }
+
+ @Override
+ public boolean verify(final PublicHandle key, final byte[] message, final byte[] signature) {
+ if (!(key instanceof Pub p) || message == null || signature == null) {
+ return false;
+ }
+ try {
+ final SLHDSASigner verifier = new SLHDSASigner();
+ verifier.init(false, p.params());
+ return verifier.verifySignature(message, signature);
+ } catch (final RuntimeException e) {
+ return false;
+ }
+ }
+
+ @Override
+ public Optional<byte[]> serializePrivateKey(final PrivateHandle key) {
+ if (!(key instanceof Priv p)) {
+ return Optional.empty();
+ }
+ try {
+ return Optional.ofNullable(p.params().getEncoded());
+ } catch (final RuntimeException e) {
+ return Optional.empty();
+ }
+ }
+
+ @Override
+ public Optional<PrivateHandle> parsePrivateKey(final byte[] raw) {
+ if (raw == null || raw.length == 0) {
+ return Optional.empty();
+ }
+ try {
+ return Optional.of(new Priv(new SLHDSAPrivateKeyParameters(PARAMS, raw)));
+ } catch (final RuntimeException e) {
+ return Optional.empty();
+ }
+ }
+
+ @Override
+ public GeneratedPair generate(final SecureRandom random) {
+ final SLHDSAKeyPairGenerator gen = new SLHDSAKeyPairGenerator();
+ gen.init(new SLHDSAKeyGenerationParameters(random, PARAMS));
+ final AsymmetricCipherKeyPair pair = gen.generateKeyPair();
+ final SLHDSAPublicKeyParameters pub = (SLHDSAPublicKeyParameters) pair.getPublic();
+ final SLHDSAPrivateKeyParameters priv = (SLHDSAPrivateKeyParameters) pair.getPrivate();
+ return new GeneratedPair(new Pub(pub), new Priv(priv), pub.getEncoded());
+ }
+}
diff --git a/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/blockcreation/BftBlockCreatorFactory.java b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/blockcreation/BftBlockCreatorFactory.java
index 20c072202..1ecdcbf34 100644
--- a/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/blockcreation/BftBlockCreatorFactory.java
+++ b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/blockcreation/BftBlockCreatorFactory.java
@@ -11,6 +11,12 @@
* specific language governing permissions and limitations under the License.
*
* SPDX-License-Identifier: Apache-2.0
+ *
+ * Modifications Copyright contributors to the Aere Network.
+ *
+ * This file was modified by contributors to the Aere Network, as required by section 4(b) of the
+ * Apache License 2.0. The copyright header above is the upstream one and is left exactly as it was
+ * found, as section 4(c) requires. The change itself is in patches/0003-aere-pq-anchor.patch.
*/
package org.hyperledger.besu.consensus.common.bft.blockcreation;
@@ -157,6 +163,23 @@ public class BftBlockCreatorFactory<T extends BftConfigOptions> {
* @return the bytes
*/
public Bytes createExtraData(final int round, final BlockHeader parentHeader) {
+ return bftExtraDataCodec.encode(buildExtraData(round, parentHeader));
+ }
+
+ /**
+ * Build the extra data VALUE for a block on this parent, before it is encoded.
+ *
+ * <p>AERE ANCHOR V2: split out of {@link #createExtraData(int, BlockHeader)} with NO behaviour
+ * change, so a subclass can post-process the value (QBFT rewrites vanityData with the anchor
+ * digest and fills element 6 with the parent's certificate) without decoding and
+ * re-encoding bytes it just produced. IBFT, which shares this class, keeps the old path exactly:
+ * it never overrides this and never sees the anchor.
+ *
+ * @param round the round
+ * @param parentHeader the parent header
+ * @return the extra data value
+ */
+ protected BftExtraData buildExtraData(final int round, final BlockHeader parentHeader) {
final BftContext bftContext = protocolContext.getConsensusContext(BftContext.class);
final ValidatorProvider validatorProvider = bftContext.getValidatorProvider();
Optional<VoteProvider> voteProviderAfterBlock =
@@ -177,7 +200,7 @@ public class BftBlockCreatorFactory<T extends BftConfigOptions> {
round,
validators);
- return bftExtraDataCodec.encode(extraData);
+ return extraData;
}
/**
diff --git a/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/blockcreation/PqAnchorProducer.java b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/blockcreation/PqAnchorProducer.java
new file mode 100755
index 000000000..a46b7d887
--- /dev/null
+++ b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/blockcreation/PqAnchorProducer.java
@@ -0,0 +1,524 @@
+/*
+ * Copyright contributors to Besu / AERE Network.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.common.bft.blockcreation;
+
+import org.apache.tuweni.bytes.Bytes;
+import org.hyperledger.besu.datatypes.Hash;
+import org.hyperledger.besu.consensus.common.bft.BftContext;
+import org.hyperledger.besu.consensus.common.bft.BftExtraData;
+import org.hyperledger.besu.consensus.common.bft.FalconSeal;
+import org.hyperledger.besu.consensus.common.bft.FalconSealSupport;
+import org.hyperledger.besu.consensus.common.bft.HybridSealSupport;
+import org.hyperledger.besu.consensus.common.bft.HybridSignerRegistry;
+import org.hyperledger.besu.consensus.common.bft.PqAnchor;
+import org.hyperledger.besu.consensus.common.bft.PqAnchorConfig;
+import org.hyperledger.besu.consensus.common.bft.PqAnchorNotReadyException;
+import org.hyperledger.besu.consensus.common.bft.PqAnchorV2;
+import org.hyperledger.besu.consensus.common.bft.PqSealCache;
+import org.hyperledger.besu.consensus.common.bft.PqSignerRegistry;
+import org.hyperledger.besu.consensus.common.bft.SchemeSeal;
+import org.hyperledger.besu.consensus.common.bft.SealScheme;
+import org.hyperledger.besu.consensus.common.bft.SealSchemes;
+import org.hyperledger.besu.datatypes.Address;
+import org.hyperledger.besu.ethereum.ProtocolContext;
+import org.hyperledger.besu.ethereum.core.BlockHeader;
+
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.LinkedHashSet;
+import java.util.List;
+import java.util.Optional;
+import java.util.Set;
+import java.util.concurrent.atomic.AtomicBoolean;
+
+import org.apache.tuweni.bytes.Bytes32;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+/**
+ * AERE ANCHOR V2, THE PRODUCER SIDE: the proposer of block N chooses the certificate over
+ * block N-1 out of what IT heard, writes it into element 6 of N's extraData, and writes the anchor
+ * digest D of that certificate into all 32 bytes of N's vanityData.
+ *
+ * <p>WHY THE OBJECT MOVED. Option V summarised the certificate sitting in the PARENT's header.
+ * Measured on the live chain, that object is not unique: over 200 consecutive headers read
+ * simultaneously from two nodes with identical block hashes, seal ORDER differed on 68 and the seal
+ * SET differed on 11, because RoundState keeps commits in a LinkedHashMap keyed on author and each
+ * node writes what IT heard. V2 summarises an object ONE node writes, which reaches everybody as
+ * the same bytes inside the same proposal. This class is that one node's choice.
+ *
+ * <p>THE ONE PLACE THE CERTIFICATE IS CHOSEN. Which heard seals are eligible, which of them
+ * actually verify, whether there are enough of them, and what D is, are all decided here. Keeping
+ * it in one method is not tidiness, it is the correctness argument: the decision "can I propose"
+ * and the bytes that go into the header are computed by the SAME code on the SAME inputs, so a
+ * proposal can never be emitted that this node's own arithmetic already rejected. A verdict
+ * computed by a different path than the run is the exact defect class this project keeps having to
+ * fix.
+ *
+ * <p>WHAT IS SELECTED, in order, and each step is the mirror of a validator-side rule:
+ *
+ * <ol>
+ * <li>every seal heard for the parent, sorted by validator index (rule: strictly increasing);
+ * <li>dropped unless the index maps, through the address-bound Falcon registry, to an address in
+ * the validator set FOR THE PARENT (rule: eligible signer);
+ * <li>dropped unless the Falcon signature verifies over M(parent) (rule: k verifications);
+ * <li>refused entirely if fewer than K(N) survive (rule: k &gt;= K).
+ * </ol>
+ *
+ * <p>SO THE PROPOSER NEVER EMITS A SEAL IT HAS NOT ITSELF VERIFIED. The cost is k Falcon
+ * verifications per proposal, measured median 0.068 ms and p95 0.249 ms each, so five of them are
+ * about 1.3 ms against a measured 517 ms block interval.
+ *
+ * <p>THE PROPOSER NEVER COMPARES ANYTHING WITH WHAT ITS PEERS HEARD, and nothing downstream does
+ * either. That asymmetry is the whole reason V2 works where option V could not: a node that heard
+ * seven seals accepts a five-seal certificate written by a node that heard five, because Falcon
+ * verification is public.
+ */
+public final class PqAnchorProducer {
+
+ private static final Logger LOG = LoggerFactory.getLogger(PqAnchorProducer.class);
+
+ private static final AtomicBoolean LOGGED_ACTIVATION_THRESHOLD = new AtomicBoolean(false);
+
+ private static volatile PqAnchorConfig config;
+
+ private PqAnchorProducer() {}
+
+ /**
+ * The activation configuration this process produces blocks under.
+ *
+ * <p>Read once from system configuration and memoised. It is deliberately a process-wide value
+ * rather than an injected one: the two producer entry points that need it (the QBFT block creator
+ * factory and the sealing path in {@code QbftRound}) sit in different modules with no shared
+ * construction site, and inventing one would mean threading a new argument through the QBFT round
+ * factory for no gain. The honest cost is that this cannot be varied per instance inside one JVM,
+ * which only matters for tests; {@link #useConfigForTesting(PqAnchorConfig)} covers that.
+ *
+ * @return the anchor configuration
+ */
+ public static PqAnchorConfig config() {
+ PqAnchorConfig local = config;
+ if (local == null) {
+ synchronized (PqAnchorProducer.class) {
+ local = config;
+ if (local == null) {
+ local = PqAnchorConfig.fromSystemConfiguration();
+ warnIfActivationHeightCanRefuse(local);
+ config = local;
+ }
+ }
+ }
+ return local;
+ }
+
+ /**
+ * Override the memoised configuration. For tests, and for a controller builder that wants to feed
+ * a genesis-derived configuration in before the first block is produced.
+ *
+ * @param replacement the configuration to use, or null to force a re-read
+ */
+ public static void useConfigForTesting(final PqAnchorConfig replacement) {
+ synchronized (PqAnchorProducer.class) {
+ config = replacement;
+ LOGGED_ACTIVATION_THRESHOLD.set(false);
+ }
+ }
+
+ /**
+ * Whether a Falcon seal produced FOR this block must be signed over the V2 message M rather than
+ * over the legacy ECDSA committed-seal hash.
+ *
+ * <p>ONE BLOCK EARLIER than {@link PqAnchorConfig#activeAt(long)}, and that offset is the whole
+ * bootstrap of the scheme: the certificate carried by block H is made of seals over block H-1, so
+ * H-1 must already be sealed in the new form. Every node flips at the same height because the
+ * height is a pure function of the same configured H.
+ *
+ * @param blockNumber the number of the block being sealed
+ * @return true iff the seal must be over M
+ */
+ public static boolean sealMessageIsAnchorForm(final long blockNumber) {
+ final PqAnchorConfig cfg = config();
+ // DELIBERATELY LEFT UNTOUCHED BY THE INTERVAL, 2026-08-07. With an interval in force,
+ // seals made at heights that feed no anchor reach no certificate at all, so they are WASTE.
+ // The temptation is to stop signing them. It is not done here, and the reason is that this
+ // method decides the FORM of the seal: if the form depended on the interval, two nodes
+ // reading the interval differently would sign different forms and would no longer recognise
+ // each other. The form stays a function of H alone, which is the one value the fleet
+ // coordinates anyway.
+ //
+ // The waste remains, and it is BANDWIDTH, not DISK: the seals still travel on the Commit
+ // messages of every block, they simply no longer reach any header. The disk, which was the
+ // problem, drops by a factor of <interval>. Cutting the pointless signing is done separately,
+ // at the attachment gate, where it cannot change the form.
+ return cfg.everActive() && blockNumber + 1L >= cfg.anchorBlock();
+ }
+
+ /**
+ * AERE D-311 (2026-09-02): THE ONE PLACE that says which bytes a commit's post-quantum seal
+ * signs. Both the emitter ({@code QbftRound.pqSealMessageFor}) and the verifier
+ * ({@code MessageValidator.SubsequentMessageValidator}, feeding {@code PqCommitEnforcement})
+ * call this and nothing else.
+ *
+ * <p>Why it exists, measured on the public testnet 28001 the day it was born: with the anchor
+ * armed (as on 2800 since 13,014,000) the emitter signed the anchor form, while the commit
+ * enforcement verified over the ECDSA committed-seal hash. Two copies of one rule, and they
+ * drifted: at {@code aere.pq.commitPq.forkBlock} every commit of every validator was refused
+ * ("does NOT verify over the commit digest") and the chain stopped. The rehearsal (F95) never
+ * saw it because its kit runs without the anchor armed. Arming H1 on 2800 with the old
+ * verifier would have stopped the live chain.
+ *
+ * @param blockNumber the height of the block the commit votes for
+ * @param onchainHash the ROUND-INDEPENDENT on-chain hash of that block (round forced to 0)
+ * @param commitHash the ECDSA committed-seal hash (round-specific)
+ * @return the 32 bytes the Falcon seal (and any hybrid extras) must sign at this height
+ */
+ public static Bytes32 commitSealMessage(
+ final long blockNumber, final Bytes onchainHash, final Hash commitHash) {
+ return commitSealMessage(blockNumber, () -> onchainHash, commitHash);
+ }
+
+ /**
+ * Same as {@link #commitSealMessage(long, Bytes, Hash)}, with the on-chain hash supplied LAZILY:
+ * it is only needed (and only computed) in the anchor form. Below the anchor the ECDSA digest is
+ * the message and no round-0 re-encoding happens, which is also what keeps every upstream test
+ * that mocks {@code QbftBlockInterface} exactly as it was.
+ *
+ * @param blockNumber the height of the block the commit votes for
+ * @param onchainHash supplier of the ROUND-INDEPENDENT on-chain hash (round forced to 0)
+ * @param commitHash the ECDSA committed-seal hash (round-specific)
+ * @return the 32 bytes the Falcon seal (and any hybrid extras) must sign at this height
+ */
+ public static Bytes32 commitSealMessage(
+ final long blockNumber,
+ final java.util.function.Supplier<Bytes> onchainHash,
+ final Hash commitHash) {
+ if (sealMessageIsAnchorForm(blockNumber)) {
+ return PqAnchor.commitMessage(config().chainId(), blockNumber, onchainHash.get());
+ }
+ return Bytes32.wrap(commitHash.getBytes());
+ }
+
+ /**
+ * Return the extra data the proposer should encode for a block on top of this parent.
+ *
+ * <p>Below the activation height the input is returned UNCHANGED, so pre-fork behaviour is
+ * identical byte for byte and the 11.8 million existing blocks stay untouched. The gate is on the
+ * block NUMBER, never on content.
+ *
+ * @param base the extra data the unmodified Besu path would have produced
+ * @param parentHeader the parent header, whose number and ON-CHAIN hash bind the certificate
+ * @param protocolContext the protocol context, used only to read the validator set for the parent
+ * @return either {@code base} itself, or a copy carrying the certificate and the anchor digest
+ * @throws PqAnchorNotReadyException when the staged threshold cannot be met, meaning this node
+ * must not propose at all this round
+ */
+ public static BftExtraData apply(
+ final BftExtraData base,
+ final BlockHeader parentHeader,
+ final ProtocolContext protocolContext) {
+
+ final PqAnchorConfig cfg = config();
+ final long blockNumber = parentHeader.getNumber() + 1L;
+ // THE SAME QUESTION BOTH RULES ASK, through the same method: anchorAppliesAt.
+ // The producer and the validator have to agree on which heights carry a certificate. If the
+ // producer wrote one where the rule does not ask for it, that would only be waste; if it
+ // skipped one where the rule DOES ask for it, every block it proposes would be rejected. So
+ // the same question is asked, not one that merely resembles it.
+ if (!cfg.anchorAppliesAt(blockNumber)) {
+ return base;
+ }
+
+ final long parentNumber = parentHeader.getNumber();
+ final Bytes32 message =
+ PqAnchor.commitMessage(cfg.chainId(), parentNumber, parentHeader.getHash().getBytes());
+
+ final List<FalconSeal> heard =
+ PqSealCache.instance().sealsFor(parentNumber, parentHeader.getHash());
+
+ final PqSignerRegistry registry = PqSignerRegistry.falconSealSupport();
+ final Set<Address> eligible = validatorsForParent(parentHeader, protocolContext);
+
+ final List<FalconSeal> certificate = new ArrayList<>();
+ final Set<Address> seen = new LinkedHashSet<>();
+ // Integer.MAX_VALUE means "no cap", i.e. exactly what every node did before 2026-08-07.
+ final int sealCap = cfg.maxSealsCarried().orElse(Integer.MAX_VALUE);
+ int rejectedIneligible = 0;
+ int rejectedInvalid = 0;
+ // D2 (2026-08-06): the proposer resolves keys AT THE PARENT'S HEIGHT, the same height R2 will
+ // use when it re-checks this certificate. Before this the producer asked a height-less registry
+ // while R2 asked a height-resolved one, so at a rotation height the two could disagree about
+ // which key set applies - the proposer would assemble a certificate the fleet then refuses, and
+ // the round would fail for a reason no log named. Building and validating now read the same
+ // question.
+ for (final FalconSeal seal : PqAnchor.sortedByIndex(heard)) {
+ // D2 (b-v2): the OWN-HEAD door. parentHeader is this node's own head - this method is
+ // reached only from the proposer, building the block on top of it. Refusing here for a
+ // missing schedule is what stopped block production in PqForkValidatorSetChangeTest.
+ final Address signer =
+ registry.addressForIndexAtOwnHead(parentNumber, seal.getValidatorIndex());
+ if (signer == null || !eligible.contains(signer) || !seen.add(signer)) {
+ rejectedIneligible++;
+ continue;
+ }
+ if (!registry.verifyAtOwnHead(
+ parentNumber, seal.getValidatorIndex(), message, seal.getSignature())) {
+ rejectedInvalid++;
+ continue;
+ }
+ certificate.add(seal);
+ // THE COST CAP. K is a FLOOR, not a ceiling: without this break the proposer writes every
+ // eligible seal it happened to hear, so a K=3 chain at N=7 carries four, five, six or seven.
+ // Measured 2026-08-07 on a live seven-node run with the threshold at 4: 42 blocks carried 4
+ // seals, 36 carried 5, 5 carried 6. At 666 bytes a seal that is 200.9 GB per node per year
+ // instead of 120.5, and the extra buys NOTHING: what a verifier demands is the threshold, not
+ // how many seals a proposer volunteers above it.
+ //
+ // The break is safe precisely because it is placed AFTER the eligibility and signature checks:
+ // every seal counted here has already been verified, so stopping at the cap can never leave
+ // the certificate short by including a bad one. And the cap can never be set below the highest
+ // scheduled K, because PqAnchorConfig.withMaxSealsCarried refuses that at startup.
+ //
+ // Unset means no cap, which is exactly the behaviour of every node built before today.
+ if (certificate.size() >= sealCap) {
+ break;
+ }
+ }
+
+ final int required = cfg.minSealsAt(blockNumber);
+ if (certificate.size() < required) {
+ throw new PqAnchorNotReadyException(
+ parentNumber,
+ certificate.size(),
+ required,
+ "Heard "
+ + heard.size()
+ + " seal(s) for parent hash "
+ + parentHeader.getHash()
+ + "; "
+ + rejectedIneligible
+ + " were not eligible signers (registry address-bound="
+ + FalconSealSupport.instance().addressBound()
+ + ", validators for the parent="
+ + eligible.size()
+ + ") and "
+ + rejectedInvalid
+ + " did not verify over M(parent). Schedule="
+ + cfg.minSealsSchedule()
+ + ". A node that has just restarted holds no seals until it takes part in one commit,"
+ + " which costs at most one proposer turn.");
+ }
+
+ // The list is already ascending by index and de-duplicated by signer address; assert the format
+ // invariant here rather than trusting the loop, because this is the exact property the digest
+ // rule and the seals rule both depend on.
+ if (!PqAnchor.hasStrictlyIncreasingIndices(certificate)) {
+ throw new IllegalStateException(
+ "AERE PQ-ANCHOR: assembled a certificate whose indices are not strictly increasing; "
+ + "refusing to write it. This is a bug in the producer, not a configuration fault.");
+ }
+
+ if (cfg.anchorV2AppliesAt(blockNumber)) {
+ return applyV2(cfg, blockNumber, parentHeader, base, certificate, message, required, sealCap);
+ }
+ final Bytes32 digest =
+ PqAnchor.anchorDigest(
+ cfg.chainId(), parentNumber, parentHeader.getHash().getBytes(), certificate);
+
+ LOG.debug(
+ "AERE PQ-ANCHOR: block {} carries a {}-seal certificate over parent {} (K={}), vanity D={}",
+ blockNumber,
+ certificate.size(),
+ parentNumber,
+ required,
+ digest);
+
+ return new BftExtraData(
+ digest,
+ base.getSeals(),
+ base.getVote(),
+ base.getRound(),
+ base.getValidators(),
+ certificate);
+ }
+
+ /**
+ * AERE ANCHOR V2 (2026-09-03): the SCHEME-TAGGED certificate. Carries the Falcon seals already
+ * verified by the caller, tagged 0x01, plus, for every extra scheme the scheme schedule names at
+ * the PARENT height, the heard seals of that scheme that (a) come from an index that also holds a
+ * Falcon seal in this very certificate, the binding that stops a lone hash-based seal from
+ * standing in for a validator, and (b) verify under the hybrid registry's key for that index and
+ * scheme, over the SAME message M(parent) the Falcon seal signs. K seals per scheme, capped like
+ * Falcon. vanityData becomes the v2 digest under "AERE-PQ-ANCHOR-2". Refuses, through the same
+ * not-ready exception the v1 path uses, rather than writing a certificate short of a scheme.
+ */
+ private static BftExtraData applyV2(
+ final PqAnchorConfig cfg,
+ final long blockNumber,
+ final BlockHeader parentHeader,
+ final BftExtraData base,
+ final List<FalconSeal> falconCertificate,
+ final Bytes32 message,
+ final int required,
+ final int sealCap) {
+ final long parentNumber = parentHeader.getNumber();
+ final List<SchemeSeal> v2 = new ArrayList<>();
+ final Set<Integer> falconIndices = new LinkedHashSet<>();
+ for (final FalconSeal f : falconCertificate) {
+ v2.add(new SchemeSeal(SealSchemes.FALCON_512.wireId(), f.getValidatorIndex(), f.getSignature()));
+ falconIndices.add(f.getValidatorIndex());
+ }
+ final HybridSealSupport hybrid = HybridSealSupport.instance();
+ final Set<String> schemes =
+ hybrid.schedule().map(sch -> sch.schemesAt(parentNumber)).orElse(Set.of());
+ final List<SchemeSeal> heard =
+ PqSealCache.instance().extrasFor(parentNumber, parentHeader.getHash());
+ for (final String schemeId : schemes) {
+ if (SealSchemes.FALCON_512.id().equals(schemeId)) {
+ continue;
+ }
+ final Optional<SealScheme> scheme = SealSchemes.byId(schemeId);
+ if (scheme.isEmpty()) {
+ throw new PqAnchorNotReadyException(
+ parentNumber,
+ 0,
+ required,
+ "the scheme schedule names '" + schemeId + "', which this binary does not implement");
+ }
+ final Optional<HybridSignerRegistry> registry = hybrid.registry();
+ if (registry.isEmpty()) {
+ throw new PqAnchorNotReadyException(
+ parentNumber,
+ 0,
+ required,
+ "no hybrid registry is loaded on this node, so no " + schemeId + " seal can be verified");
+ }
+ int kept = 0;
+ int rejected = 0;
+ for (final SchemeSeal s : heard) {
+ if (s.getSchemeWireId() != scheme.get().wireId()) {
+ continue;
+ }
+ if (!falconIndices.contains(s.getValidatorIndex())) {
+ rejected++;
+ continue;
+ }
+ final Optional<byte[]> pk = registry.get().publicKey(s.getValidatorIndex(), schemeId);
+ if (pk.isEmpty()
+ || !scheme.get().verifyRaw(pk.get(), message.toArray(), s.getSignature().toArray())) {
+ rejected++;
+ continue;
+ }
+ v2.add(s);
+ kept++;
+ if (kept >= sealCap) {
+ break;
+ }
+ }
+ if (kept < required) {
+ throw new PqAnchorNotReadyException(
+ parentNumber,
+ kept,
+ required,
+ "V2: heard "
+ + heard.size()
+ + " extra seal(s) for parent hash "
+ + parentHeader.getHash()
+ + "; "
+ + kept
+ + " valid "
+ + schemeId
+ + " seal(s) bound to a Falcon-certified index, "
+ + rejected
+ + " rejected. The v2 certificate needs K="
+ + required
+ + " seals of EVERY scheme the schedule names at height "
+ + parentNumber
+ + " ("
+ + String.join("+", schemes)
+ + ").");
+ }
+ }
+ v2.sort(PqAnchorV2.CANONICAL);
+ final Bytes32 digest =
+ PqAnchorV2.anchorDigestV2(
+ cfg.chainId(), parentNumber, parentHeader.getHash().getBytes(), v2);
+ LOG.debug(
+ "AERE PQ-ANCHOR V2: block {} carries a {}-seal scheme-tagged certificate over parent {} "
+ + "(K={} per scheme, schemes={}), vanity D2={}",
+ blockNumber,
+ v2.size(),
+ parentNumber,
+ required,
+ schemes,
+ digest);
+ return new BftExtraData(
+ digest,
+ base.getSeals(),
+ base.getVote(),
+ base.getRound(),
+ base.getValidators(),
+ List.of(),
+ v2);
+ }
+
+ /**
+ * The validator set FOR the parent block: the nodes that were entitled to seal it.
+ *
+ * <p>Taken for the PARENT, not for the block being built, because those are the nodes whose seals
+ * a certificate over the parent may contain. On a validator-set change the two sets differ, and
+ * using the wrong one would either admit a seal the validator side rejects or drop one it
+ * accepts.
+ */
+ private static Set<Address> validatorsForParent(
+ final BlockHeader parentHeader, final ProtocolContext protocolContext) {
+ final Collection<Address> validators =
+ protocolContext
+ .getConsensusContext(BftContext.class)
+ .getValidatorProvider()
+ .getValidatorsForBlock(parentHeader);
+ return new LinkedHashSet<>(validators);
+ }
+
+ /**
+ * The first stage must not be able to block anything. K at the activation height itself has to be
+ * 0, because block H's parent predates the fork and may carry no Falcon seals at all: measured,
+ * the chain has ZERO today, 0 of 46 and 0 of 40 sampled headers, with the RLP element absent
+ * entirely. A schedule that puts a positive threshold at H would make the proposer of H refuse,
+ * and every proposer after it, which is a halt at the activation height. This does not throw, it
+ * shouts: refusing to start on a threshold an operator may have chosen deliberately is not this
+ * class's decision to make.
+ */
+ private static void warnIfActivationHeightCanRefuse(final PqAnchorConfig cfg) {
+ if (!cfg.everActive() || !LOGGED_ACTIVATION_THRESHOLD.compareAndSet(false, true)) {
+ return;
+ }
+ final int atActivation = cfg.minSealsAt(cfg.anchorBlock());
+ if (atActivation > 0) {
+ LOG.error(
+ "AERE PQ-ANCHOR: the staged threshold at the ACTIVATION height {} is {}, not 0. Block H's "
+ + "parent predates the fork and may carry no Falcon seals at all, so every proposer "
+ + "at H would refuse and the chain would stop at exactly the height you armed it. "
+ + "Open the schedule with {}:0 and raise K only at a later step.",
+ cfg.anchorBlock(),
+ atActivation,
+ cfg.anchorBlock());
+ } else {
+ LOG.info(
+ "AERE PQ-ANCHOR: producer armed. H={}, K(H)=0 as required, schedule={}.",
+ cfg.anchorBlock(),
+ cfg.minSealsSchedule());
+ }
+ }
+}
diff --git a/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/slhdsa/ADRS.java b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/slhdsa/ADRS.java
new file mode 100755
index 000000000..7610cf876
--- /dev/null
+++ b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/slhdsa/ADRS.java
@@ -0,0 +1,115 @@
+/*
+ * Derived from Bouncy Castle 1.80, package org.bouncycastle.pqc.crypto.slhdsa (MIT licence,
+ * Copyright (c) 2000-2025 The Legion of the Bouncy Castle Inc., see LICENTA-BOUNCYCASTLE.txt),
+ * regenerated into Aere Network by consensus-pqc/slhdsa-fork/genereaza-motorul.py on 2026-09-04 (D-337).
+ * The ONLY change of substance: the SHA-2 engine hashes through the JDK's MessageDigest (SHA-NI
+ * intrinsics) instead of Bouncy Castle's pure-Java digests, which made one SLH-DSA-SHA2-128s signature
+ * cost seconds on the QBFT thread at every anchor parent. Algorithm, key formats and signature bytes are
+ * FIPS 205 as before; SlhDsaFastEngineTest pins that against the original, in both directions.
+ * DO NOT EDIT BY HAND: regenerate with the script above.
+ */
+package org.hyperledger.besu.consensus.common.bft.slhdsa;
+
+import org.bouncycastle.util.Arrays;
+import org.bouncycastle.util.Pack;
+
+@SuppressWarnings("all")
+class ADRS
+{
+ static final int WOTS_HASH = 0;
+ static final int WOTS_PK = 1;
+ static final int TREE = 2;
+ static final int FORS_TREE = 3;
+ static final int FORS_PK = 4;
+ static final int WOTS_PRF = 5;
+ static final int FORS_PRF = 6;
+
+ static final int OFFSET_LAYER = 0;
+ static final int OFFSET_TREE = 4;
+ static final int OFFSET_TREE_HGT = 24;
+ static final int OFFSET_TREE_INDEX = 28;
+ static final int OFFSET_TYPE = 16;
+ static final int OFFSET_KP_ADDR = 20;
+ static final int OFFSET_CHAIN_ADDR = 24;
+ static final int OFFSET_HASH_ADDR = 28;
+
+ final byte[] value = new byte[32];
+
+ ADRS()
+ {
+ }
+
+ ADRS(ADRS adrs)
+ {
+ System.arraycopy(adrs.value, 0, this.value, 0, adrs.value.length);
+ }
+
+ public void setLayerAddress(int layer)
+ {
+ Pack.intToBigEndian(layer, value, OFFSET_LAYER);
+ }
+
+ public int getLayerAddress()
+ {
+ return Pack.bigEndianToInt(value, OFFSET_LAYER);
+ }
+
+ public void setTreeAddress(long tree)
+ {
+ // tree address is 12 bytes
+ Pack.longToBigEndian(tree, value, OFFSET_TREE + 4);
+ }
+
+ public long getTreeAddress()
+ {
+ return Pack.bigEndianToLong(value, OFFSET_TREE + 4);
+ }
+
+ public void setTreeHeight(int height)
+ {
+ Pack.intToBigEndian(height, value, OFFSET_TREE_HGT);
+ }
+
+ public void setTreeIndex(int index)
+ {
+ Pack.intToBigEndian(index, value, OFFSET_TREE_INDEX);
+ }
+
+ public int getTreeIndex()
+ {
+ return Pack.bigEndianToInt(value, OFFSET_TREE_INDEX);
+ }
+
+ // resets part of value to zero in line with 2.7.3
+ public void setTypeAndClear(int type)
+ {
+ Pack.intToBigEndian(type, value, OFFSET_TYPE);
+
+ Arrays.fill(value, 20, value.length, (byte)0);
+ }
+
+ public void changeType(int type)
+ {
+ Pack.intToBigEndian(type, value, OFFSET_TYPE);
+ }
+
+ public void setKeyPairAddress(int keyPairAddr)
+ {
+ Pack.intToBigEndian(keyPairAddr, value, OFFSET_KP_ADDR);
+ }
+
+ public int getKeyPairAddress()
+ {
+ return Pack.bigEndianToInt(value, OFFSET_KP_ADDR);
+ }
+
+ public void setHashAddress(int hashAddr)
+ {
+ Pack.intToBigEndian(hashAddr, value, OFFSET_HASH_ADDR);
+ }
+
+ public void setChainAddress(int chainAddr)
+ {
+ Pack.intToBigEndian(chainAddr, value, OFFSET_CHAIN_ADDR);
+ }
+}
diff --git a/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/slhdsa/Fors.java b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/slhdsa/Fors.java
new file mode 100755
index 000000000..d89d83af8
--- /dev/null
+++ b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/slhdsa/Fors.java
@@ -0,0 +1,178 @@
+/*
+ * Derived from Bouncy Castle 1.80, package org.bouncycastle.pqc.crypto.slhdsa (MIT licence,
+ * Copyright (c) 2000-2025 The Legion of the Bouncy Castle Inc., see LICENTA-BOUNCYCASTLE.txt),
+ * regenerated into Aere Network by consensus-pqc/slhdsa-fork/genereaza-motorul.py on 2026-09-04 (D-337).
+ * The ONLY change of substance: the SHA-2 engine hashes through the JDK's MessageDigest (SHA-NI
+ * intrinsics) instead of Bouncy Castle's pure-Java digests, which made one SLH-DSA-SHA2-128s signature
+ * cost seconds on the QBFT thread at every anchor parent. Algorithm, key formats and signature bytes are
+ * FIPS 205 as before; SlhDsaFastEngineTest pins that against the original, in both directions.
+ * DO NOT EDIT BY HAND: regenerate with the script above.
+ */
+package org.hyperledger.besu.consensus.common.bft.slhdsa;
+
+import java.math.BigInteger;
+import java.util.LinkedList;
+
+import org.bouncycastle.util.Arrays;
+
+@SuppressWarnings("all")
+class Fors
+{
+ SLHDSAEngine engine;
+
+ public Fors(SLHDSAEngine engine)
+ {
+ this.engine = engine;
+ }
+
+ // Input: Secret seed SK.seed, start index s, target node height z, public seed PK.seed, address ADRS
+ // Output: n-byte root node - top node on Stack
+ byte[] treehash(byte[] skSeed, int s, int z, byte[] pkSeed, ADRS adrsParam)
+ {
+ if ((s >>> z) << z != s)
+ {
+ return null;
+ }
+
+ LinkedList<NodeEntry> stack = new LinkedList<NodeEntry>();
+ ADRS adrs = new ADRS(adrsParam);
+
+ for (int idx = 0; idx < (1 << z); idx++)
+ {
+ adrs.setTypeAndClear(ADRS.FORS_PRF);
+ adrs.setKeyPairAddress(adrsParam.getKeyPairAddress());
+ adrs.setTreeHeight(0);
+ adrs.setTreeIndex(s + idx);
+
+ byte[] sk = engine.PRF(pkSeed, skSeed, adrs);
+
+ adrs.changeType(ADRS.FORS_TREE);
+
+ byte[] node = engine.F(pkSeed, adrs, sk);
+
+ adrs.setTreeHeight(1);
+
+ int adrsTreeHeight = 1;
+ int adrsTreeIndex = s + idx;
+
+ // while ( Top node on Stack has same height as node )
+ while (!stack.isEmpty() && stack.get(0).nodeHeight == adrsTreeHeight)
+ {
+ adrsTreeIndex = (adrsTreeIndex - 1) / 2;
+ adrs.setTreeIndex(adrsTreeIndex);
+
+ NodeEntry current = stack.remove(0);
+ node = engine.H(pkSeed, adrs, current.nodeValue, node);
+
+ // topmost node is now one layer higher
+ adrs.setTreeHeight(++adrsTreeHeight);
+ }
+
+ stack.add(0, new NodeEntry(node, adrsTreeHeight));
+ }
+
+ return stack.get(0).nodeValue;
+ }
+
+ public SIG_FORS[] sign(byte[] md, byte[] skSeed, byte[] pkSeed, ADRS paramAdrs)
+ {
+ ADRS adrs = new ADRS(paramAdrs);
+
+// int[] idxs = message_to_idxs(md, engine.K, engine.A);
+ int[] idxs = base2B(md, engine.A, engine.K);
+ SIG_FORS[] sig_fors = new SIG_FORS[engine.K];
+// compute signature elements
+ int t = engine.T;
+ for (int i = 0; i < engine.K; i++)
+ {
+// get next index
+ int idx = idxs[i];
+// pick private key element
+ adrs.setTypeAndClear(ADRS.FORS_PRF);
+ adrs.setKeyPairAddress(paramAdrs.getKeyPairAddress());
+ adrs.setTreeHeight(0);
+ adrs.setTreeIndex(i * t + idx);
+
+ byte[] sk = engine.PRF(pkSeed, skSeed, adrs);
+
+ adrs.changeType(ADRS.FORS_TREE);
+
+ byte[][] authPath = new byte[engine.A][];
+// compute auth path
+ for (int j = 0; j < engine.A; j++)
+ {
+ int s = (idx / (1 << j)) ^ 1;
+ authPath[j] = treehash(skSeed, i * t + s * (1 << j), j, pkSeed, adrs);
+ }
+ sig_fors[i] = new SIG_FORS(sk, authPath);
+ }
+ return sig_fors;
+ }
+
+ public byte[] pkFromSig(SIG_FORS[] sig_fors, byte[] message, byte[] pkSeed, ADRS adrs)
+ {
+ byte[][] node = new byte[2][];
+ byte[][] root = new byte[engine.K][];
+ int t = engine.T;
+
+// int[] idxs = message_to_idxs(message, engine.K, engine.A);
+ int[] idxs = base2B(message, engine.A, engine.K);
+ // compute roots
+ for (int i = 0; i < engine.K; i++)
+ {
+ // get next index
+ int idx = idxs[i];
+ // compute leaf
+ byte[] sk = sig_fors[i].getSK();
+ adrs.setTreeHeight(0);
+ adrs.setTreeIndex(i * t + idx);
+ node[0] = engine.F(pkSeed, adrs, sk);
+ // compute root from leaf and AUTH
+ byte[][] authPath = sig_fors[i].getAuthPath();
+
+ adrs.setTreeIndex(i * t + idx);
+ for (int j = 0; j < engine.A; j++)
+ {
+ adrs.setTreeHeight(j + 1);
+ if (((idx / (1 << j)) % 2) == 0)
+ {
+ adrs.setTreeIndex(adrs.getTreeIndex() / 2);
+ node[1] = engine.H(pkSeed, adrs, node[0], authPath[j]);
+ }
+ else
+ {
+ adrs.setTreeIndex((adrs.getTreeIndex() - 1) / 2);
+ node[1] = engine.H(pkSeed, adrs, authPath[j], node[0]);
+ }
+ node[0] = node[1];
+ }
+ root[i] = node[0];
+ }
+ ADRS forspkADRS = new ADRS(adrs); // copy address to create FTS public key address
+ forspkADRS.setTypeAndClear(ADRS.FORS_PK);
+ forspkADRS.setKeyPairAddress(adrs.getKeyPairAddress());
+ return engine.T_l(pkSeed, forspkADRS, Arrays.concatenate(root));
+ }
+
+ static int[] base2B(byte[] msg, int b, int outLen)
+ {
+ int[] baseB = new int[outLen];
+ int i = 0;
+ int bits = 0;
+ BigInteger total = BigInteger.ZERO;
+
+ for (int o = 0; o < outLen; o++)
+ {
+ while (bits < b)
+ {
+ total = total.shiftLeft(8).add(BigInteger.valueOf(msg[i] & 0xff));
+ i+= 1;
+ bits += 8;
+ }
+ bits -= b;
+ baseB[o] = (total.shiftRight(bits).mod(BigInteger.valueOf(2).pow(b))).intValue();
+ }
+
+ return baseB;
+ }
+}
diff --git a/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/slhdsa/HT.java b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/slhdsa/HT.java
new file mode 100755
index 000000000..b7d96c16f
--- /dev/null
+++ b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/slhdsa/HT.java
@@ -0,0 +1,225 @@
+/*
+ * Derived from Bouncy Castle 1.80, package org.bouncycastle.pqc.crypto.slhdsa (MIT licence,
+ * Copyright (c) 2000-2025 The Legion of the Bouncy Castle Inc., see LICENTA-BOUNCYCASTLE.txt),
+ * regenerated into Aere Network by consensus-pqc/slhdsa-fork/genereaza-motorul.py on 2026-09-04 (D-337).
+ * The ONLY change of substance: the SHA-2 engine hashes through the JDK's MessageDigest (SHA-NI
+ * intrinsics) instead of Bouncy Castle's pure-Java digests, which made one SLH-DSA-SHA2-128s signature
+ * cost seconds on the QBFT thread at every anchor parent. Algorithm, key formats and signature bytes are
+ * FIPS 205 as before; SlhDsaFastEngineTest pins that against the original, in both directions.
+ * DO NOT EDIT BY HAND: regenerate with the script above.
+ */
+package org.hyperledger.besu.consensus.common.bft.slhdsa;
+
+import java.util.LinkedList;
+
+import org.bouncycastle.util.Arrays;
+
+@SuppressWarnings("all")
+class HT
+{
+ private final byte[] skSeed;
+ private final byte[] pkSeed;
+ SLHDSAEngine engine;
+ WotsPlus wots;
+
+ final byte[] htPubKey;
+
+ public HT(SLHDSAEngine engine, byte[] skSeed, byte[] pkSeed)
+ {
+ this.skSeed = skSeed;
+ this.pkSeed = pkSeed;
+
+ this.engine = engine;
+ this.wots = new WotsPlus(engine);
+
+ ADRS adrs = new ADRS();
+ adrs.setLayerAddress(engine.D - 1);
+ adrs.setTreeAddress(0);
+
+ if (skSeed != null)
+ {
+ htPubKey = xmss_PKgen(skSeed, pkSeed, adrs);
+ }
+ else
+ {
+ htPubKey = null;
+ }
+ }
+
+ byte[] sign(byte[] M, long idx_tree, int idx_leaf)
+ {
+ // init
+ ADRS adrs = new ADRS();
+ // sign
+ // adrs.setType(ADRS.TREE);
+ adrs.setLayerAddress(0);
+ adrs.setTreeAddress(idx_tree);
+ SIG_XMSS SIG_tmp = xmss_sign(M, skSeed, idx_leaf, pkSeed, adrs);
+ SIG_XMSS[] SIG_HT = new SIG_XMSS[engine.D];
+ SIG_HT[0] = SIG_tmp;
+
+ adrs.setLayerAddress(0);
+ adrs.setTreeAddress(idx_tree);
+
+ byte[] root = xmss_pkFromSig(idx_leaf, SIG_tmp, M, pkSeed, adrs);
+
+ for (int j = 1; j < engine.D; j++)
+ {
+ idx_leaf = (int)(idx_tree & ((1 << engine.H_PRIME) - 1)); // least significant bits of idx_tree;
+ idx_tree >>>= engine.H_PRIME; // most significant bits of idx_tree;
+ adrs.setLayerAddress(j);
+ adrs.setTreeAddress(idx_tree);
+ SIG_tmp = xmss_sign(root, skSeed, idx_leaf, pkSeed, adrs);
+ SIG_HT[j] = SIG_tmp;
+ if (j < engine.D - 1)
+ {
+ root = xmss_pkFromSig(idx_leaf, SIG_tmp, root, pkSeed, adrs);
+ }
+ }
+
+ byte[][] totSigs = new byte[SIG_HT.length][];
+ for (int i = 0; i != totSigs.length; i++)
+ {
+ totSigs[i] = Arrays.concatenate(SIG_HT[i].sig, Arrays.concatenate(SIG_HT[i].auth));
+ }
+
+ return Arrays.concatenate(totSigs);
+ }
+
+ byte[] xmss_PKgen(byte[] skSeed, byte[] pkSeed, ADRS adrs)
+ {
+ return treehash(skSeed, 0, engine.H_PRIME, pkSeed, adrs);
+ }
+
+ // Input: index idx, XMSS signature SIG_XMSS = (sig || AUTH), n-byte message M, public seed PK.seed, address ADRS
+ // Output: n-byte root value node[0]
+ byte[] xmss_pkFromSig(int idx, SIG_XMSS sig_xmss, byte[] M, byte[] pkSeed, ADRS paramAdrs)
+ {
+ ADRS adrs = new ADRS(paramAdrs);
+
+ // compute WOTS+ pk from WOTS+ sig
+ adrs.setTypeAndClear(ADRS.WOTS_HASH);
+ adrs.setKeyPairAddress(idx);
+ byte[] sig = sig_xmss.getWOTSSig();
+ byte[][] AUTH = sig_xmss.getXMSSAUTH();
+
+ byte[] node0 = wots.pkFromSig(sig, M, pkSeed, adrs);
+ byte[] node1 = null;
+
+ // compute root from WOTS+ pk and AUTH
+ adrs.setTypeAndClear(ADRS.TREE);
+ adrs.setTreeIndex(idx);
+ for (int k = 0; k < engine.H_PRIME; k++)
+ {
+ adrs.setTreeHeight(k + 1);
+ if (((idx / (1 << k)) % 2) == 0)
+ {
+ adrs.setTreeIndex(adrs.getTreeIndex() / 2);
+ node1 = engine.H(pkSeed, adrs, node0, AUTH[k]);
+ }
+ else
+ {
+ adrs.setTreeIndex((adrs.getTreeIndex() - 1) / 2);
+ node1 = engine.H(pkSeed, adrs, AUTH[k], node0);
+ }
+ node0 = node1;
+ }
+ return node0;
+ }
+
+ // # Input: n-byte message M, secret seed SK.seed, index idx, public seed PK.seed,
+ // address ADRS
+ // # Output: XMSS signature SIG_XMSS = (sig || AUTH)
+ SIG_XMSS xmss_sign(byte[] M, byte[] skSeed, int idx, byte[] pkSeed, ADRS paramAdrs)
+ {
+ byte[][] AUTH = new byte[engine.H_PRIME][];
+
+ ADRS adrs = new ADRS(paramAdrs);
+
+ adrs.setTypeAndClear(ADRS.TREE);
+ adrs.setLayerAddress(paramAdrs.getLayerAddress());
+ adrs.setTreeAddress(paramAdrs.getTreeAddress());
+
+ // build authentication path
+ for (int j = 0; j < engine.H_PRIME; j++)
+ {
+ int k = (idx >>> j) ^ 1;
+ AUTH[j] = treehash(skSeed, k << j, j, pkSeed, adrs);
+ }
+ adrs = new ADRS(paramAdrs);
+ adrs.setTypeAndClear(ADRS.WOTS_HASH);
+ adrs.setKeyPairAddress(idx);
+
+ byte[] sig = wots.sign(M, skSeed, pkSeed, adrs);
+
+ return new SIG_XMSS(sig, AUTH);
+ }
+
+ // Input: Secret seed SK.seed, start index s, target node height z, public seed PK.seed, address ADRS
+ // Output: n-byte root node - top node on Stack
+ byte[] treehash(byte[] skSeed, int s, int z, byte[] pkSeed, ADRS adrsParam)
+ {
+ if ((s >>> z) << z != s)
+ {
+ return null;
+ }
+
+ LinkedList<NodeEntry> stack = new LinkedList<NodeEntry>();
+ ADRS adrs = new ADRS(adrsParam);
+
+ for (int idx = 0; idx < (1 << z); idx++)
+ {
+ adrs.setTypeAndClear(ADRS.WOTS_HASH);
+ adrs.setKeyPairAddress(s + idx);
+ byte[] node = wots.pkGen(skSeed, pkSeed, adrs);
+
+ adrs.setTypeAndClear(ADRS.TREE);
+ adrs.setTreeHeight(1);
+ adrs.setTreeIndex(s + idx);
+
+ int adrsTreeHeight = 1;
+ int adrsTreeIndex = s + idx;
+
+ // while ( Top node on Stack has same height as node )
+ while (!stack.isEmpty() && stack.get(0).nodeHeight == adrsTreeHeight)
+ {
+ adrsTreeIndex = (adrsTreeIndex - 1) / 2;
+ adrs.setTreeIndex(adrsTreeIndex);
+
+ NodeEntry current = stack.remove(0);
+ node = engine.H(pkSeed, adrs, current.nodeValue, node);
+
+ // topmost node is now one layer higher
+ adrs.setTreeHeight(++adrsTreeHeight);
+ }
+
+ stack.add(0, new NodeEntry(node, adrsTreeHeight));
+ }
+
+ return stack.get(0).nodeValue;
+ }
+
+ // # Input: Message M, signature SIG_HT, public seed PK.seed, tree index idx_tree,
+// leaf index idx_leaf, HT public key PK_HT.
+// # Output: Boolean
+ public boolean verify(byte[] M, SIG_XMSS[] sig_ht, byte[] pkSeed, long idx_tree, int idx_leaf, byte[] PK_HT)
+ {
+ // init
+ ADRS adrs = new ADRS();
+ // verify
+ SIG_XMSS SIG_tmp = sig_ht[0];
+ adrs.setLayerAddress(0);
+ adrs.setTreeAddress(idx_tree);
+ byte[] node = xmss_pkFromSig(idx_leaf, SIG_tmp, M, pkSeed, adrs);
+ for (int j = 1; j < engine.D; j++)
+ {
+ idx_leaf = (int)(idx_tree & ((1 << engine.H_PRIME) - 1)); // least significant bits of idx_tree;
+ idx_tree >>>= engine.H_PRIME; // most significant bits of idx_tree;
+ SIG_tmp = sig_ht[j];
+ adrs.setLayerAddress(j);
+ adrs.setTreeAddress(idx_tree);
+ node = xmss_pkFromSig(idx_leaf, SIG_tmp, node, pkSeed, adrs);
+ }
+ return Arrays.areEqual(PK_HT, node);
+ }
+}
diff --git a/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/slhdsa/IndexedDigest.java b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/slhdsa/IndexedDigest.java
new file mode 100755
index 000000000..8ff076d70
--- /dev/null
+++ b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/slhdsa/IndexedDigest.java
@@ -0,0 +1,26 @@
+/*
+ * Derived from Bouncy Castle 1.80, package org.bouncycastle.pqc.crypto.slhdsa (MIT licence,
+ * Copyright (c) 2000-2025 The Legion of the Bouncy Castle Inc., see LICENTA-BOUNCYCASTLE.txt),
+ * regenerated into Aere Network by consensus-pqc/slhdsa-fork/genereaza-motorul.py on 2026-09-04 (D-337).
+ * The ONLY change of substance: the SHA-2 engine hashes through the JDK's MessageDigest (SHA-NI
+ * intrinsics) instead of Bouncy Castle's pure-Java digests, which made one SLH-DSA-SHA2-128s signature
+ * cost seconds on the QBFT thread at every anchor parent. Algorithm, key formats and signature bytes are
+ * FIPS 205 as before; SlhDsaFastEngineTest pins that against the original, in both directions.
+ * DO NOT EDIT BY HAND: regenerate with the script above.
+ */
+package org.hyperledger.besu.consensus.common.bft.slhdsa;
+
+@SuppressWarnings("all")
+class IndexedDigest
+{
+ final long idx_tree;
+ final int idx_leaf;
+ final byte[] digest;
+
+ IndexedDigest(long idx_tree, int idx_leaf, byte[] digest)
+ {
+ this.idx_tree = idx_tree;
+ this.idx_leaf = idx_leaf;
+ this.digest = digest;
+ }
+}
diff --git a/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/slhdsa/JdkDigest.java b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/slhdsa/JdkDigest.java
new file mode 100755
index 000000000..c7a8e86fa
--- /dev/null
+++ b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/slhdsa/JdkDigest.java
@@ -0,0 +1,104 @@
+/*
+ * Derived from Bouncy Castle 1.80, package org.bouncycastle.pqc.crypto.slhdsa (MIT licence,
+ * Copyright (c) 2000-2025 The Legion of the Bouncy Castle Inc., see LICENTA-BOUNCYCASTLE.txt),
+ * regenerated into Aere Network by consensus-pqc/slhdsa-fork/genereaza-motorul.py on 2026-09-04 (D-337).
+ * The ONLY change of substance: the SHA-2 engine hashes through the JDK's MessageDigest (SHA-NI
+ * intrinsics) instead of Bouncy Castle's pure-Java digests, which made one SLH-DSA-SHA2-128s signature
+ * cost seconds on the QBFT thread at every anchor parent. Algorithm, key formats and signature bytes are
+ * FIPS 205 as before; SlhDsaFastEngineTest pins that against the original, in both directions.
+ * DO NOT EDIT BY HAND: regenerate with the script above.
+ */
+package org.hyperledger.besu.consensus.common.bft.slhdsa;
+
+import java.security.DigestException;
+import java.security.MessageDigest;
+import java.security.NoSuchAlgorithmException;
+import org.bouncycastle.crypto.ExtendedDigest;
+import org.bouncycastle.util.Memoable;
+
+/**
+ * A Bouncy Castle {@link ExtendedDigest} backed by the JDK's {@link MessageDigest}, so SLH-DSA's
+ * millions of short hashes run on the SHA-NI intrinsics. Measured 2026-09-04 on an EPYC host: 3M
+ * SHA-256 of 64 bytes, Bouncy Castle 2533 ms, JDK 335 ms; one sha2_128s signature 1364 ms before,
+ * 325 ms after. {@link Memoable} is how the SLH-DSA engine keeps the pk-seed prefix state: it is
+ * implemented here with {@link MessageDigest#clone()}, which the SUN provider supports for SHA-2.
+ */
+@SuppressWarnings("all")
+final class JdkDigest implements ExtendedDigest, Memoable {
+ private final String algorithm;
+ private final int blockLength;
+ private MessageDigest md;
+
+ JdkDigest(final String algorithm, final int blockLength) {
+ this.algorithm = algorithm;
+ this.blockLength = blockLength;
+ try {
+ this.md = MessageDigest.getInstance(algorithm);
+ } catch (final NoSuchAlgorithmException e) {
+ throw new IllegalStateException("JDK has no " + algorithm, e);
+ }
+ }
+
+ private JdkDigest(final JdkDigest other) {
+ this.algorithm = other.algorithm;
+ this.blockLength = other.blockLength;
+ this.md = cloneOf(other.md);
+ }
+
+ private static MessageDigest cloneOf(final MessageDigest d) {
+ try {
+ return (MessageDigest) d.clone();
+ } catch (final CloneNotSupportedException e) {
+ throw new IllegalStateException(d.getAlgorithm() + " is not cloneable", e);
+ }
+ }
+
+ @Override
+ public String getAlgorithmName() {
+ return algorithm;
+ }
+
+ @Override
+ public int getDigestSize() {
+ return md.getDigestLength();
+ }
+
+ @Override
+ public int getByteLength() {
+ return blockLength;
+ }
+
+ @Override
+ public void update(final byte in) {
+ md.update(in);
+ }
+
+ @Override
+ public void update(final byte[] in, final int inOff, final int len) {
+ md.update(in, inOff, len);
+ }
+
+ @Override
+ public int doFinal(final byte[] out, final int outOff) {
+ try {
+ return md.digest(out, outOff, md.getDigestLength());
+ } catch (final DigestException e) {
+ throw new IllegalStateException(e);
+ }
+ }
+
+ @Override
+ public void reset() {
+ md.reset();
+ }
+
+ @Override
+ public Memoable copy() {
+ return new JdkDigest(this);
+ }
+
+ @Override
+ public void reset(final Memoable other) {
+ this.md = cloneOf(((JdkDigest) other).md);
+ }
+}
diff --git a/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/slhdsa/LICENSE-BouncyCastle.txt b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/slhdsa/LICENSE-BouncyCastle.txt
new file mode 100755
index 000000000..bfe226f1d
--- /dev/null
+++ b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/slhdsa/LICENSE-BouncyCastle.txt
@@ -0,0 +1,22 @@
+Licenta sub care ne este ingaduit sa purtam in arborele nostru motorul SLH-DSA generat de
+genereaza-motorul.py, adica fisierele din
+consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/slhdsa/.
+Sursa: bcprov-jdk18on-1.80-sources.jar, sha256 29e8414b7a07060b07222bb786dd594d2e411de0d7723d2fac8adedb0801cbef,
+fisierul org/bouncycastle/LICENSE.java. Licenta e MIT, compatibila cu Apache-2.0 a lui Besu.
+
+Copyright (c) 2000-2025 The Legion of the Bouncy Castle Inc. (https://www.bouncycastle.org)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
+associated documentation files (the "Software"), to deal in the Software without restriction,
+including without limitation the rights to use, copy, modify, merge, publish, distribute,
+sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or
+substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT
+NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT
+OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
diff --git a/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/slhdsa/NodeEntry.java b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/slhdsa/NodeEntry.java
new file mode 100755
index 000000000..4cd30cfff
--- /dev/null
+++ b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/slhdsa/NodeEntry.java
@@ -0,0 +1,24 @@
+/*
+ * Derived from Bouncy Castle 1.80, package org.bouncycastle.pqc.crypto.slhdsa (MIT licence,
+ * Copyright (c) 2000-2025 The Legion of the Bouncy Castle Inc., see LICENTA-BOUNCYCASTLE.txt),
+ * regenerated into Aere Network by consensus-pqc/slhdsa-fork/genereaza-motorul.py on 2026-09-04 (D-337).
+ * The ONLY change of substance: the SHA-2 engine hashes through the JDK's MessageDigest (SHA-NI
+ * intrinsics) instead of Bouncy Castle's pure-Java digests, which made one SLH-DSA-SHA2-128s signature
+ * cost seconds on the QBFT thread at every anchor parent. Algorithm, key formats and signature bytes are
+ * FIPS 205 as before; SlhDsaFastEngineTest pins that against the original, in both directions.
+ * DO NOT EDIT BY HAND: regenerate with the script above.
+ */
+package org.hyperledger.besu.consensus.common.bft.slhdsa;
+
+@SuppressWarnings("all")
+class NodeEntry
+{
+ final byte[] nodeValue;
+ final int nodeHeight;
+
+ NodeEntry(byte[] nodeValue, int nodeHeight)
+ {
+ this.nodeValue = nodeValue;
+ this.nodeHeight = nodeHeight;
+ }
+}
diff --git a/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/slhdsa/PK.java b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/slhdsa/PK.java
new file mode 100755
index 000000000..4d0ef5fe2
--- /dev/null
+++ b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/slhdsa/PK.java
@@ -0,0 +1,24 @@
+/*
+ * Derived from Bouncy Castle 1.80, package org.bouncycastle.pqc.crypto.slhdsa (MIT licence,
+ * Copyright (c) 2000-2025 The Legion of the Bouncy Castle Inc., see LICENTA-BOUNCYCASTLE.txt),
+ * regenerated into Aere Network by consensus-pqc/slhdsa-fork/genereaza-motorul.py on 2026-09-04 (D-337).
+ * The ONLY change of substance: the SHA-2 engine hashes through the JDK's MessageDigest (SHA-NI
+ * intrinsics) instead of Bouncy Castle's pure-Java digests, which made one SLH-DSA-SHA2-128s signature
+ * cost seconds on the QBFT thread at every anchor parent. Algorithm, key formats and signature bytes are
+ * FIPS 205 as before; SlhDsaFastEngineTest pins that against the original, in both directions.
+ * DO NOT EDIT BY HAND: regenerate with the script above.
+ */
+package org.hyperledger.besu.consensus.common.bft.slhdsa;
+
+@SuppressWarnings("all")
+class PK
+{
+ final byte[] seed;
+ final byte[] root;
+
+ PK(byte[] seed, byte[] root)
+ {
+ this.seed = seed;
+ this.root = root;
+ }
+}
diff --git a/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/slhdsa/SIG.java b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/slhdsa/SIG.java
new file mode 100755
index 000000000..fb6d81702
--- /dev/null
+++ b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/slhdsa/SIG.java
@@ -0,0 +1,77 @@
+/*
+ * Derived from Bouncy Castle 1.80, package org.bouncycastle.pqc.crypto.slhdsa (MIT licence,
+ * Copyright (c) 2000-2025 The Legion of the Bouncy Castle Inc., see LICENTA-BOUNCYCASTLE.txt),
+ * regenerated into Aere Network by consensus-pqc/slhdsa-fork/genereaza-motorul.py on 2026-09-04 (D-337).
+ * The ONLY change of substance: the SHA-2 engine hashes through the JDK's MessageDigest (SHA-NI
+ * intrinsics) instead of Bouncy Castle's pure-Java digests, which made one SLH-DSA-SHA2-128s signature
+ * cost seconds on the QBFT thread at every anchor parent. Algorithm, key formats and signature bytes are
+ * FIPS 205 as before; SlhDsaFastEngineTest pins that against the original, in both directions.
+ * DO NOT EDIT BY HAND: regenerate with the script above.
+ */
+package org.hyperledger.besu.consensus.common.bft.slhdsa;
+
+@SuppressWarnings("all")
+class SIG
+{
+ private final byte[] r;
+ private final SIG_FORS[] sig_fors;
+ private final SIG_XMSS[] sig_ht;
+
+ public SIG(int n, int k, int a, int d, int hPrime, int wots_len, byte[] signature)
+ {
+ this.r = new byte[n];
+ System.arraycopy(signature, 0, r, 0, n);
+
+ this.sig_fors = new SIG_FORS[k];
+ int offset = n;
+ for (int i = 0; i != k; i++)
+ {
+ byte[] sk = new byte[n];
+ System.arraycopy(signature, offset, sk, 0, n);
+ offset += n;
+ byte[][] authPath = new byte[a][];
+ for (int j = 0; j != a; j++)
+ {
+ authPath[j] = new byte[n];
+ System.arraycopy(signature, offset, authPath[j], 0, n);
+ offset += n;
+ }
+ sig_fors[i] = new SIG_FORS(sk, authPath);
+ }
+
+ sig_ht = new SIG_XMSS[d];
+ for (int i = 0; i != d; i++)
+ {
+ byte[] sig = new byte[wots_len * n];
+ System.arraycopy(signature, offset, sig, 0, sig.length);
+ offset += sig.length;
+ byte[][] authPath = new byte[hPrime][];
+ for (int j = 0; j != hPrime; j++)
+ {
+ authPath[j] = new byte[n];
+ System.arraycopy(signature, offset, authPath[j], 0, n);
+ offset += n;
+ }
+ sig_ht[i] = new SIG_XMSS(sig, authPath);
+ }
+ if (offset != signature.length)
+ {
+ throw new IllegalArgumentException("signature wrong length");
+ }
+ }
+
+ public byte[] getR()
+ {
+ return r;
+ }
+
+ public SIG_FORS[] getSIG_FORS()
+ {
+ return sig_fors;
+ }
+
+ public SIG_XMSS[] getSIG_HT()
+ {
+ return sig_ht;
+ }
+}
diff --git a/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/slhdsa/SIG_FORS.java b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/slhdsa/SIG_FORS.java
new file mode 100755
index 000000000..7c0064762
--- /dev/null
+++ b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/slhdsa/SIG_FORS.java
@@ -0,0 +1,34 @@
+/*
+ * Derived from Bouncy Castle 1.80, package org.bouncycastle.pqc.crypto.slhdsa (MIT licence,
+ * Copyright (c) 2000-2025 The Legion of the Bouncy Castle Inc., see LICENTA-BOUNCYCASTLE.txt),
+ * regenerated into Aere Network by consensus-pqc/slhdsa-fork/genereaza-motorul.py on 2026-09-04 (D-337).
+ * The ONLY change of substance: the SHA-2 engine hashes through the JDK's MessageDigest (SHA-NI
+ * intrinsics) instead of Bouncy Castle's pure-Java digests, which made one SLH-DSA-SHA2-128s signature
+ * cost seconds on the QBFT thread at every anchor parent. Algorithm, key formats and signature bytes are
+ * FIPS 205 as before; SlhDsaFastEngineTest pins that against the original, in both directions.
+ * DO NOT EDIT BY HAND: regenerate with the script above.
+ */
+package org.hyperledger.besu.consensus.common.bft.slhdsa;
+
+@SuppressWarnings("all")
+class SIG_FORS
+{
+ final byte[][] authPath;
+ final byte[] sk;
+
+ SIG_FORS(byte[] sk, byte[][] authPath)
+ {
+ this.authPath = authPath;
+ this.sk = sk;
+ }
+
+ byte[] getSK()
+ {
+ return sk;
+ }
+
+ public byte[][] getAuthPath()
+ {
+ return authPath;
+ }
+}
diff --git a/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/slhdsa/SIG_XMSS.java b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/slhdsa/SIG_XMSS.java
new file mode 100755
index 000000000..f77ffaf1c
--- /dev/null
+++ b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/slhdsa/SIG_XMSS.java
@@ -0,0 +1,34 @@
+/*
+ * Derived from Bouncy Castle 1.80, package org.bouncycastle.pqc.crypto.slhdsa (MIT licence,
+ * Copyright (c) 2000-2025 The Legion of the Bouncy Castle Inc., see LICENTA-BOUNCYCASTLE.txt),
+ * regenerated into Aere Network by consensus-pqc/slhdsa-fork/genereaza-motorul.py on 2026-09-04 (D-337).
+ * The ONLY change of substance: the SHA-2 engine hashes through the JDK's MessageDigest (SHA-NI
+ * intrinsics) instead of Bouncy Castle's pure-Java digests, which made one SLH-DSA-SHA2-128s signature
+ * cost seconds on the QBFT thread at every anchor parent. Algorithm, key formats and signature bytes are
+ * FIPS 205 as before; SlhDsaFastEngineTest pins that against the original, in both directions.
+ * DO NOT EDIT BY HAND: regenerate with the script above.
+ */
+package org.hyperledger.besu.consensus.common.bft.slhdsa;
+
+@SuppressWarnings("all")
+class SIG_XMSS
+{
+ final byte[] sig;
+ final byte[][] auth;
+
+ public SIG_XMSS(byte[] sig, byte[][] auth)
+ {
+ this.sig = sig;
+ this.auth = auth;
+ }
+
+ public byte[] getWOTSSig()
+ {
+ return sig;
+ }
+
+ public byte[][] getXMSSAUTH()
+ {
+ return auth;
+ }
+}
diff --git a/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/slhdsa/SK.java b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/slhdsa/SK.java
new file mode 100755
index 000000000..8040421b1
--- /dev/null
+++ b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/slhdsa/SK.java
@@ -0,0 +1,24 @@
+/*
+ * Derived from Bouncy Castle 1.80, package org.bouncycastle.pqc.crypto.slhdsa (MIT licence,
+ * Copyright (c) 2000-2025 The Legion of the Bouncy Castle Inc., see LICENTA-BOUNCYCASTLE.txt),
+ * regenerated into Aere Network by consensus-pqc/slhdsa-fork/genereaza-motorul.py on 2026-09-04 (D-337).
+ * The ONLY change of substance: the SHA-2 engine hashes through the JDK's MessageDigest (SHA-NI
+ * intrinsics) instead of Bouncy Castle's pure-Java digests, which made one SLH-DSA-SHA2-128s signature
+ * cost seconds on the QBFT thread at every anchor parent. Algorithm, key formats and signature bytes are
+ * FIPS 205 as before; SlhDsaFastEngineTest pins that against the original, in both directions.
+ * DO NOT EDIT BY HAND: regenerate with the script above.
+ */
+package org.hyperledger.besu.consensus.common.bft.slhdsa;
+
+@SuppressWarnings("all")
+class SK
+{
+ final byte[] seed;
+ final byte[] prf;
+
+ SK(byte[] seed, byte[] prf)
+ {
+ this.seed = seed;
+ this.prf = prf;
+ }
+}
diff --git a/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/slhdsa/SLHDSAEngine.java b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/slhdsa/SLHDSAEngine.java
new file mode 100755
index 000000000..bf7b40087
--- /dev/null
+++ b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/slhdsa/SLHDSAEngine.java
@@ -0,0 +1,466 @@
+/*
+ * Derived from Bouncy Castle 1.80, package org.bouncycastle.pqc.crypto.slhdsa (MIT licence,
+ * Copyright (c) 2000-2025 The Legion of the Bouncy Castle Inc., see LICENTA-BOUNCYCASTLE.txt),
+ * regenerated into Aere Network by consensus-pqc/slhdsa-fork/genereaza-motorul.py on 2026-09-04 (D-337).
+ * The ONLY change of substance: the SHA-2 engine hashes through the JDK's MessageDigest (SHA-NI
+ * intrinsics) instead of Bouncy Castle's pure-Java digests, which made one SLH-DSA-SHA2-128s signature
+ * cost seconds on the QBFT thread at every anchor parent. Algorithm, key formats and signature bytes are
+ * FIPS 205 as before; SlhDsaFastEngineTest pins that against the original, in both directions.
+ * DO NOT EDIT BY HAND: regenerate with the script above.
+ */
+package org.hyperledger.besu.consensus.common.bft.slhdsa;
+
+import org.bouncycastle.crypto.Digest;
+import org.bouncycastle.crypto.Xof;
+import org.bouncycastle.crypto.digests.SHAKEDigest;
+import org.bouncycastle.crypto.generators.MGF1BytesGenerator;
+import org.bouncycastle.crypto.macs.HMac;
+import org.bouncycastle.crypto.params.KeyParameter;
+import org.bouncycastle.crypto.params.MGFParameters;
+import org.bouncycastle.util.Arrays;
+import org.bouncycastle.util.Bytes;
+import org.bouncycastle.util.Memoable;
+import org.bouncycastle.util.Pack;
+
+@SuppressWarnings("all")
+abstract class SLHDSAEngine
+{
+ final int N;
+
+ final int WOTS_W;
+ final int WOTS_LOGW;
+ final int WOTS_LEN;
+ final int WOTS_LEN1;
+ final int WOTS_LEN2;
+
+ final int D;
+ final int A; // FORS_HEIGHT
+ final int K; // FORS_TREES
+ final int H; // FULL_HEIGHT
+ final int H_PRIME; // H / D
+
+ final int T; // T = 1 << A
+
+ public SLHDSAEngine(int n, int w, int d, int a, int k, int h)
+ {
+ this.N = n;
+
+ /* SPX_WOTS_LEN2 is floor(log(len_1 * (w - 1)) / log(w)) + 1; we precompute */
+ if (w == 16)
+ {
+ WOTS_LOGW = 4;
+ WOTS_LEN1 = (8 * N / WOTS_LOGW);
+ if (N <= 8)
+ {
+ WOTS_LEN2 = 2;
+ }
+ else if (N <= 136)
+ {
+ WOTS_LEN2 = 3;
+ }
+ else if (N <= 256)
+ {
+ WOTS_LEN2 = 4;
+ }
+ else
+ {
+ throw new IllegalArgumentException("cannot precompute SPX_WOTS_LEN2 for n outside {2, .., 256}");
+ }
+ }
+ else if (w == 256)
+ {
+ WOTS_LOGW = 8;
+ WOTS_LEN1 = (8 * N / WOTS_LOGW);
+ if (N <= 1)
+ {
+ WOTS_LEN2 = 1;
+ }
+ else if (N <= 256)
+ {
+ WOTS_LEN2 = 2;
+ }
+ else
+ {
+ throw new IllegalArgumentException("cannot precompute SPX_WOTS_LEN2 for n outside {2, .., 256}");
+ }
+ }
+ else
+ {
+ throw new IllegalArgumentException("wots_w assumed 16 or 256");
+ }
+ this.WOTS_W = w;
+ this.WOTS_LEN = WOTS_LEN1 + WOTS_LEN2;
+
+ this.D = d;
+ this.A = a;
+ this.K = k;
+ this.H = h;
+ this.H_PRIME = h / d;
+ this.T = 1 << a;
+ }
+
+ abstract void init(byte[] pkSeed);
+
+ abstract byte[] F(byte[] pkSeed, ADRS adrs, byte[] m1);
+
+ abstract byte[] H(byte[] pkSeed, ADRS adrs, byte[] m1, byte[] m2);
+
+ abstract IndexedDigest H_msg(byte[] prf, byte[] pkSeed, byte[] pkRoot, byte[] msgPrefix, byte[] msg);
+
+ abstract byte[] T_l(byte[] pkSeed, ADRS adrs, byte[] m);
+
+ abstract byte[] PRF(byte[] pkSeed, byte[] skSeed, ADRS adrs);
+
+ abstract byte[] PRF_msg(byte[] prf, byte[] randomiser, byte[] msgPrefix, byte[] msg);
+
+ static class Sha2Engine
+ extends SLHDSAEngine
+ {
+ private final HMac treeHMac;
+ private final MGF1BytesGenerator mgf1;
+ private final byte[] hmacBuf;
+ private final Digest msgDigest;
+ private final byte[] msgDigestBuf;
+ private final int bl;
+ private final Digest sha256 = new JdkDigest("SHA-256", 64);
+ private final byte[] sha256Buf = new byte[sha256.getDigestSize()];
+
+ private Memoable msgMemo;
+ private Memoable sha256Memo;
+
+ public Sha2Engine(int n, int w, int d, int a, int k, int h)
+ {
+ super(n, w, d, a, k, h);
+ if (n == 16)
+ {
+ this.msgDigest = new JdkDigest("SHA-256", 64);
+ this.treeHMac = new HMac(new JdkDigest("SHA-256", 64));
+ this.mgf1 = new MGF1BytesGenerator(new JdkDigest("SHA-256", 64));
+ this.bl = 64;
+ }
+ else
+ {
+ this.msgDigest = new JdkDigest("SHA-512", 128);
+ this.treeHMac = new HMac(new JdkDigest("SHA-512", 128));
+ this.mgf1 = new MGF1BytesGenerator(new JdkDigest("SHA-512", 128));
+ this.bl = 128;
+ }
+
+ this.hmacBuf = new byte[treeHMac.getMacSize()];
+ this.msgDigestBuf = new byte[msgDigest.getDigestSize()];
+ }
+
+ void init(byte[] pkSeed)
+ {
+ final byte[] padding = new byte[bl];
+
+ msgDigest.update(pkSeed, 0, pkSeed.length);
+ msgDigest.update(padding, 0, bl - N); // toByte(0, 64 - n)
+ msgMemo = ((Memoable)msgDigest).copy();
+
+ msgDigest.reset();
+
+ sha256.update(pkSeed, 0, pkSeed.length);
+ sha256.update(padding, 0, 64 - pkSeed.length); // toByte(0, 64 - n)
+ sha256Memo = ((Memoable)sha256).copy();
+
+ sha256.reset();
+ }
+
+ public byte[] F(byte[] pkSeed, ADRS adrs, byte[] m1)
+ {
+ byte[] compressedADRS = compressedADRS(adrs);
+
+ ((Memoable)sha256).reset(sha256Memo);
+
+ sha256.update(compressedADRS, 0, compressedADRS.length);
+ sha256.update(m1, 0, m1.length);
+ sha256.doFinal(sha256Buf, 0);
+
+ return Arrays.copyOfRange(sha256Buf, 0, N);
+ }
+
+ public byte[] H(byte[] pkSeed, ADRS adrs, byte[] m1, byte[] m2)
+ {
+ byte[] compressedADRS = compressedADRS(adrs);
+
+ ((Memoable)msgDigest).reset(msgMemo);
+
+ msgDigest.update(compressedADRS, 0, compressedADRS.length);
+
+ msgDigest.update(m1, 0, m1.length);
+ msgDigest.update(m2, 0, m2.length);
+
+ msgDigest.doFinal(msgDigestBuf, 0);
+
+ return Arrays.copyOfRange(msgDigestBuf, 0, N);
+ }
+
+ IndexedDigest H_msg(byte[] prf, byte[] pkSeed, byte[] pkRoot, byte[] msgPrefix, byte[] msg)
+ {
+ int forsMsgBytes = ((A * K) + 7) / 8;
+ int leafBits = H / D;
+ int treeBits = H - leafBits;
+ int leafBytes = (leafBits + 7) / 8;
+ int treeBytes = (treeBits + 7) / 8;
+ int m = forsMsgBytes + leafBytes + treeBytes;
+ byte[] out = new byte[m];
+ byte[] dig = new byte[msgDigest.getDigestSize()];
+
+ msgDigest.update(prf, 0, prf.length);
+ msgDigest.update(pkSeed, 0, pkSeed.length);
+ msgDigest.update(pkRoot, 0, pkRoot.length);
+ if (msgPrefix != null)
+ {
+ msgDigest.update(msgPrefix, 0, msgPrefix.length);
+ }
+ msgDigest.update(msg, 0, msg.length);
+ msgDigest.doFinal(dig, 0);
+
+ out = bitmask(Arrays.concatenate(prf, pkSeed, dig), out);
+
+ // tree index
+ // currently, only indexes up to 64 bits are supported
+ byte[] treeIndexBuf = new byte[8];
+ System.arraycopy(out, forsMsgBytes, treeIndexBuf, 8 - treeBytes, treeBytes);
+ long treeIndex = Pack.bigEndianToLong(treeIndexBuf, 0);
+ treeIndex &= (~0L) >>> (64 - treeBits);
+
+ byte[] leafIndexBuf = new byte[4];
+ System.arraycopy(out, forsMsgBytes + treeBytes, leafIndexBuf, 4 - leafBytes, leafBytes);
+
+ int leafIndex = Pack.bigEndianToInt(leafIndexBuf, 0);
+ leafIndex &= (~0) >>> (32 - leafBits);
+
+ return new IndexedDigest(treeIndex, leafIndex, Arrays.copyOfRange(out, 0, forsMsgBytes));
+ }
+
+ public byte[] T_l(byte[] pkSeed, ADRS adrs, byte[] m)
+ {
+ byte[] compressedADRS = compressedADRS(adrs);
+
+ ((Memoable)msgDigest).reset(msgMemo);
+
+ msgDigest.update(compressedADRS, 0, compressedADRS.length);
+ msgDigest.update(m, 0, m.length);
+ msgDigest.doFinal(msgDigestBuf, 0);
+
+ return Arrays.copyOfRange(msgDigestBuf, 0, N);
+ }
+
+ byte[] PRF(byte[] pkSeed, byte[] skSeed, ADRS adrs)
+ {
+ int n = skSeed.length;
+
+ ((Memoable)sha256).reset(sha256Memo);
+
+ byte[] compressedADRS = compressedADRS(adrs);
+
+ sha256.update(compressedADRS, 0, compressedADRS.length);
+ sha256.update(skSeed, 0, skSeed.length);
+ sha256.doFinal(sha256Buf, 0);
+
+ return Arrays.copyOfRange(sha256Buf, 0, n);
+ }
+
+ public byte[] PRF_msg(byte[] prf, byte[] randomiser, byte[] msgPrefix, byte[] msg)
+ {
+ treeHMac.init(new KeyParameter(prf));
+ treeHMac.update(randomiser, 0, randomiser.length);
+ if (msgPrefix != null)
+ {
+ treeHMac.update(msgPrefix, 0, msgPrefix.length);
+ }
+ treeHMac.update(msg, 0, msg.length);
+ treeHMac.doFinal(hmacBuf, 0);
+
+ return Arrays.copyOfRange(hmacBuf, 0, N);
+ }
+
+ private byte[] compressedADRS(ADRS adrs)
+ {
+ byte[] rv = new byte[22];
+ System.arraycopy(adrs.value, ADRS.OFFSET_LAYER + 3, rv, 0, 1); // LSB layer address
+ System.arraycopy(adrs.value, ADRS.OFFSET_TREE + 4, rv, 1, 8); // LS 8 bytes Tree address
+ System.arraycopy(adrs.value, ADRS.OFFSET_TYPE + 3, rv, 9, 1); // LSB type
+ System.arraycopy(adrs.value, 20, rv, 10, 12);
+
+ return rv;
+ }
+
+ protected byte[] bitmask(byte[] key, byte[] m)
+ {
+ byte[] mask = new byte[m.length];
+ mgf1.init(new MGFParameters(key));
+ mgf1.generateBytes(mask, 0, mask.length);
+ Bytes.xorTo(m.length, m, mask);
+ return mask;
+ }
+
+ protected byte[] bitmask(byte[] key, byte[] m1, byte[] m2)
+ {
+ byte[] mask = new byte[m1.length + m2.length];
+ mgf1.init(new MGFParameters(key));
+ mgf1.generateBytes(mask, 0, mask.length);
+ Bytes.xorTo(m1.length, m1, mask);
+ Bytes.xorTo(m2.length, m2, 0, mask, m1.length);
+ return mask;
+ }
+
+ protected byte[] bitmask256(byte[] key, byte[] m)
+ {
+ byte[] mask = new byte[m.length];
+ MGF1BytesGenerator mgf1 = new MGF1BytesGenerator(new JdkDigest("SHA-256", 64));
+ mgf1.init(new MGFParameters(key));
+ mgf1.generateBytes(mask, 0, mask.length);
+ Bytes.xorTo(m.length, m, mask);
+ return mask;
+ }
+ }
+
+ static class Shake256Engine
+ extends SLHDSAEngine
+ {
+ private final Xof treeDigest;
+ private final Xof maskDigest;
+
+ public Shake256Engine(int n, int w, int d, int a, int k, int h)
+ {
+ super(n, w, d, a, k, h);
+
+ this.treeDigest = new SHAKEDigest(256);
+ this.maskDigest = new SHAKEDigest(256);
+ }
+
+ void init(byte[] pkSeed)
+ {
+
+ }
+
+ byte[] F(byte[] pkSeed, ADRS adrs, byte[] m1)
+ {
+ byte[] mTheta = m1;
+
+ byte[] rv = new byte[N];
+
+ treeDigest.update(pkSeed, 0, pkSeed.length);
+ treeDigest.update(adrs.value, 0, adrs.value.length);
+ treeDigest.update(mTheta, 0, mTheta.length);
+ treeDigest.doFinal(rv, 0, rv.length);
+
+ return rv;
+ }
+
+ byte[] H(byte[] pkSeed, ADRS adrs, byte[] m1, byte[] m2)
+ {
+ byte[] rv = new byte[N];
+
+ treeDigest.update(pkSeed, 0, pkSeed.length);
+ treeDigest.update(adrs.value, 0, adrs.value.length);
+
+ treeDigest.update(m1, 0, m1.length);
+ treeDigest.update(m2, 0, m2.length);
+
+ treeDigest.doFinal(rv, 0, rv.length);
+
+ return rv;
+ }
+
+ IndexedDigest H_msg(byte[] R, byte[] pkSeed, byte[] pkRoot, byte[] msgPrefix, byte[] msg)
+ {
+ int forsMsgBytes = ((A * K) + 7) / 8;
+ int leafBits = H / D;
+ int treeBits = H - leafBits;
+ int leafBytes = (leafBits + 7) / 8;
+ int treeBytes = (treeBits + 7) / 8;
+ int m = forsMsgBytes + leafBytes + treeBytes;
+ byte[] out = new byte[m];
+
+ treeDigest.update(R, 0, R.length);
+ treeDigest.update(pkSeed, 0, pkSeed.length);
+ treeDigest.update(pkRoot, 0, pkRoot.length);
+ if (msgPrefix != null)
+ {
+ treeDigest.update(msgPrefix, 0, msgPrefix.length);
+ }
+ treeDigest.update(msg, 0, msg.length);
+ treeDigest.doFinal(out, 0, out.length);
+
+ // tree index
+ // currently, only indexes up to 64 bits are supported
+ byte[] treeIndexBuf = new byte[8];
+ System.arraycopy(out, forsMsgBytes, treeIndexBuf, 8 - treeBytes, treeBytes);
+ long treeIndex = Pack.bigEndianToLong(treeIndexBuf, 0);
+ treeIndex &= (~0L) >>> (64 - treeBits);
+
+ byte[] leafIndexBuf = new byte[4];
+ System.arraycopy(out, forsMsgBytes + treeBytes, leafIndexBuf, 4 - leafBytes, leafBytes);
+
+ int leafIndex = Pack.bigEndianToInt(leafIndexBuf, 0);
+ leafIndex &= (~0) >>> (32 - leafBits);
+
+ return new IndexedDigest(treeIndex, leafIndex, Arrays.copyOfRange(out, 0, forsMsgBytes));
+ }
+
+ byte[] T_l(byte[] pkSeed, ADRS adrs, byte[] m)
+ {
+ byte[] mTheta = m;
+
+ byte[] rv = new byte[N];
+
+ treeDigest.update(pkSeed, 0, pkSeed.length);
+ treeDigest.update(adrs.value, 0, adrs.value.length);
+ treeDigest.update(mTheta, 0, mTheta.length);
+ treeDigest.doFinal(rv, 0, rv.length);
+
+ return rv;
+ }
+
+ byte[] PRF(byte[] pkSeed, byte[] skSeed, ADRS adrs)
+ {
+ treeDigest.update(pkSeed, 0, pkSeed.length);
+ treeDigest.update(adrs.value, 0, adrs.value.length);
+ treeDigest.update(skSeed, 0, skSeed.length);
+
+ byte[] prf = new byte[N];
+ treeDigest.doFinal(prf, 0, N);
+ return prf;
+ }
+
+ public byte[] PRF_msg(byte[] prf, byte[] randomiser, byte[] msgPrefix, byte[] msg)
+ {
+ treeDigest.update(prf, 0, prf.length);
+ treeDigest.update(randomiser, 0, randomiser.length);
+ if (msgPrefix != null)
+ {
+ treeDigest.update(msgPrefix, 0, msgPrefix.length);
+ }
+ treeDigest.update(msg, 0, msg.length);
+
+ byte[] out = new byte[N];
+ treeDigest.doFinal(out, 0, out.length);
+ return out;
+ }
+
+ protected byte[] bitmask(byte[] pkSeed, ADRS adrs, byte[] m)
+ {
+ byte[] mask = new byte[m.length];
+ maskDigest.update(pkSeed, 0, pkSeed.length);
+ maskDigest.update(adrs.value, 0, adrs.value.length);
+ maskDigest.doFinal(mask, 0, mask.length);
+ Bytes.xorTo(m.length, m, mask);
+ return mask;
+ }
+
+ protected byte[] bitmask(byte[] pkSeed, ADRS adrs, byte[] m1, byte[] m2)
+ {
+ byte[] mask = new byte[m1.length + m2.length];
+ maskDigest.update(pkSeed, 0, pkSeed.length);
+ maskDigest.update(adrs.value, 0, adrs.value.length);
+ maskDigest.doFinal(mask, 0, mask.length);
+ Bytes.xorTo(m1.length, m1, mask);
+ Bytes.xorTo(m2.length, m2, 0, mask, m1.length);
+ return mask;
+ }
+ }
+}
diff --git a/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/slhdsa/SLHDSAEngineProvider.java b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/slhdsa/SLHDSAEngineProvider.java
new file mode 100755
index 000000000..791705d9a
--- /dev/null
+++ b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/slhdsa/SLHDSAEngineProvider.java
@@ -0,0 +1,19 @@
+/*
+ * Derived from Bouncy Castle 1.80, package org.bouncycastle.pqc.crypto.slhdsa (MIT licence,
+ * Copyright (c) 2000-2025 The Legion of the Bouncy Castle Inc., see LICENTA-BOUNCYCASTLE.txt),
+ * regenerated into Aere Network by consensus-pqc/slhdsa-fork/genereaza-motorul.py on 2026-09-04 (D-337).
+ * The ONLY change of substance: the SHA-2 engine hashes through the JDK's MessageDigest (SHA-NI
+ * intrinsics) instead of Bouncy Castle's pure-Java digests, which made one SLH-DSA-SHA2-128s signature
+ * cost seconds on the QBFT thread at every anchor parent. Algorithm, key formats and signature bytes are
+ * FIPS 205 as before; SlhDsaFastEngineTest pins that against the original, in both directions.
+ * DO NOT EDIT BY HAND: regenerate with the script above.
+ */
+package org.hyperledger.besu.consensus.common.bft.slhdsa;
+
+@SuppressWarnings("all")
+interface SLHDSAEngineProvider
+{
+ int getN();
+
+ SLHDSAEngine get();
+}
diff --git a/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/slhdsa/SLHDSAKeyGenerationParameters.java b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/slhdsa/SLHDSAKeyGenerationParameters.java
new file mode 100755
index 000000000..b3daec977
--- /dev/null
+++ b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/slhdsa/SLHDSAKeyGenerationParameters.java
@@ -0,0 +1,33 @@
+/*
+ * Derived from Bouncy Castle 1.80, package org.bouncycastle.pqc.crypto.slhdsa (MIT licence,
+ * Copyright (c) 2000-2025 The Legion of the Bouncy Castle Inc., see LICENTA-BOUNCYCASTLE.txt),
+ * regenerated into Aere Network by consensus-pqc/slhdsa-fork/genereaza-motorul.py on 2026-09-04 (D-337).
+ * The ONLY change of substance: the SHA-2 engine hashes through the JDK's MessageDigest (SHA-NI
+ * intrinsics) instead of Bouncy Castle's pure-Java digests, which made one SLH-DSA-SHA2-128s signature
+ * cost seconds on the QBFT thread at every anchor parent. Algorithm, key formats and signature bytes are
+ * FIPS 205 as before; SlhDsaFastEngineTest pins that against the original, in both directions.
+ * DO NOT EDIT BY HAND: regenerate with the script above.
+ */
+package org.hyperledger.besu.consensus.common.bft.slhdsa;
+
+import java.security.SecureRandom;
+
+import org.bouncycastle.crypto.KeyGenerationParameters;
+
+@SuppressWarnings("all")
+public class SLHDSAKeyGenerationParameters
+ extends KeyGenerationParameters
+{
+ private final SLHDSAParameters parameters;
+
+ public SLHDSAKeyGenerationParameters(SecureRandom random, SLHDSAParameters parameters)
+ {
+ super(random, -1);
+ this.parameters = parameters;
+ }
+
+ SLHDSAParameters getParameters()
+ {
+ return parameters;
+ }
+}
diff --git a/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/slhdsa/SLHDSAKeyPairGenerator.java b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/slhdsa/SLHDSAKeyPairGenerator.java
new file mode 100755
index 000000000..58a32e8ea
--- /dev/null
+++ b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/slhdsa/SLHDSAKeyPairGenerator.java
@@ -0,0 +1,70 @@
+/*
+ * Derived from Bouncy Castle 1.80, package org.bouncycastle.pqc.crypto.slhdsa (MIT licence,
+ * Copyright (c) 2000-2025 The Legion of the Bouncy Castle Inc., see LICENTA-BOUNCYCASTLE.txt),
+ * regenerated into Aere Network by consensus-pqc/slhdsa-fork/genereaza-motorul.py on 2026-09-04 (D-337).
+ * The ONLY change of substance: the SHA-2 engine hashes through the JDK's MessageDigest (SHA-NI
+ * intrinsics) instead of Bouncy Castle's pure-Java digests, which made one SLH-DSA-SHA2-128s signature
+ * cost seconds on the QBFT thread at every anchor parent. Algorithm, key formats and signature bytes are
+ * FIPS 205 as before; SlhDsaFastEngineTest pins that against the original, in both directions.
+ * DO NOT EDIT BY HAND: regenerate with the script above.
+ */
+package org.hyperledger.besu.consensus.common.bft.slhdsa;
+
+import java.security.SecureRandom;
+
+import org.bouncycastle.crypto.AsymmetricCipherKeyPair;
+import org.bouncycastle.crypto.AsymmetricCipherKeyPairGenerator;
+import org.bouncycastle.crypto.KeyGenerationParameters;
+
+@SuppressWarnings("all")
+public class SLHDSAKeyPairGenerator
+ implements AsymmetricCipherKeyPairGenerator
+{
+ private SecureRandom random;
+ private SLHDSAParameters parameters;
+
+ public void init(KeyGenerationParameters param)
+ {
+ random = param.getRandom();
+ parameters = ((SLHDSAKeyGenerationParameters)param).getParameters();
+ }
+
+ public AsymmetricCipherKeyPair internalGenerateKeyPair(byte[] skSeed, byte[] skPrf, byte[] pkSeed)
+ {
+ return implGenerateKeyPair(parameters.getEngine(), skSeed, skPrf, pkSeed);
+ }
+
+ public AsymmetricCipherKeyPair generateKeyPair()
+ {
+ SLHDSAEngine engine = parameters.getEngine();
+
+ byte[] skSeed = sec_rand(engine.N);
+ byte[] skPrf = sec_rand(engine.N);
+ byte[] pkSeed = sec_rand(engine.N);
+
+ return implGenerateKeyPair(engine, skSeed, skPrf, pkSeed);
+ }
+
+ private AsymmetricCipherKeyPair implGenerateKeyPair(SLHDSAEngine engine, byte[] skSeed, byte[] skPrf, byte[] pkSeed)
+ {
+ SK sk = new SK(skSeed, skPrf);
+
+ engine.init(pkSeed);
+
+ // TODO
+ PK pk = new PK(pkSeed, new HT(engine, sk.seed, pkSeed).htPubKey);
+
+ return new AsymmetricCipherKeyPair(
+ new SLHDSAPublicKeyParameters(parameters, pk),
+ new SLHDSAPrivateKeyParameters(parameters, sk, pk));
+ }
+
+ private byte[] sec_rand(int n)
+ {
+ byte[] rv = new byte[n];
+
+ random.nextBytes(rv);
+
+ return rv;
+ }
+}
diff --git a/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/slhdsa/SLHDSAKeyParameters.java b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/slhdsa/SLHDSAKeyParameters.java
new file mode 100755
index 000000000..2999c4cac
--- /dev/null
+++ b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/slhdsa/SLHDSAKeyParameters.java
@@ -0,0 +1,31 @@
+/*
+ * Derived from Bouncy Castle 1.80, package org.bouncycastle.pqc.crypto.slhdsa (MIT licence,
+ * Copyright (c) 2000-2025 The Legion of the Bouncy Castle Inc., see LICENTA-BOUNCYCASTLE.txt),
+ * regenerated into Aere Network by consensus-pqc/slhdsa-fork/genereaza-motorul.py on 2026-09-04 (D-337).
+ * The ONLY change of substance: the SHA-2 engine hashes through the JDK's MessageDigest (SHA-NI
+ * intrinsics) instead of Bouncy Castle's pure-Java digests, which made one SLH-DSA-SHA2-128s signature
+ * cost seconds on the QBFT thread at every anchor parent. Algorithm, key formats and signature bytes are
+ * FIPS 205 as before; SlhDsaFastEngineTest pins that against the original, in both directions.
+ * DO NOT EDIT BY HAND: regenerate with the script above.
+ */
+package org.hyperledger.besu.consensus.common.bft.slhdsa;
+
+import org.bouncycastle.crypto.params.AsymmetricKeyParameter;
+
+@SuppressWarnings("all")
+public class SLHDSAKeyParameters
+ extends AsymmetricKeyParameter
+{
+ private final SLHDSAParameters parameters;
+
+ protected SLHDSAKeyParameters(boolean isPrivate, SLHDSAParameters parameters)
+ {
+ super(isPrivate);
+ this.parameters = parameters;
+ }
+
+ public SLHDSAParameters getParameters()
+ {
+ return parameters;
+ }
+}
diff --git a/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/slhdsa/SLHDSAParameters.java b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/slhdsa/SLHDSAParameters.java
new file mode 100755
index 000000000..4a5e422c8
--- /dev/null
+++ b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/slhdsa/SLHDSAParameters.java
@@ -0,0 +1,186 @@
+/*
+ * Derived from Bouncy Castle 1.80, package org.bouncycastle.pqc.crypto.slhdsa (MIT licence,
+ * Copyright (c) 2000-2025 The Legion of the Bouncy Castle Inc., see LICENTA-BOUNCYCASTLE.txt),
+ * regenerated into Aere Network by consensus-pqc/slhdsa-fork/genereaza-motorul.py on 2026-09-04 (D-337).
+ * The ONLY change of substance: the SHA-2 engine hashes through the JDK's MessageDigest (SHA-NI
+ * intrinsics) instead of Bouncy Castle's pure-Java digests, which made one SLH-DSA-SHA2-128s signature
+ * cost seconds on the QBFT thread at every anchor parent. Algorithm, key formats and signature bytes are
+ * FIPS 205 as before; SlhDsaFastEngineTest pins that against the original, in both directions.
+ * DO NOT EDIT BY HAND: regenerate with the script above.
+ */
+package org.hyperledger.besu.consensus.common.bft.slhdsa;
+
+@SuppressWarnings("all")
+public class SLHDSAParameters
+{
+ public static final int TYPE_PURE = 0;
+ public static final int TYPE_SHA2_256 = 1;
+ public static final int TYPE_SHA2_512 = 2;
+ public static final int TYPE_SHAKE128 = 3;
+ public static final int TYPE_SHAKE256 = 4;
+
+ // "Pure" SLH-DSA Parameters
+ // SHA-2
+ public static final SLHDSAParameters sha2_128f = new SLHDSAParameters(
+ "sha2-128f", new Sha2EngineProvider(16, 16, 22, 6, 33, 66), TYPE_PURE);
+ public static final SLHDSAParameters sha2_128s = new SLHDSAParameters(
+ "sha2-128s", new Sha2EngineProvider(16, 16, 7, 12, 14, 63), TYPE_PURE);
+
+ public static final SLHDSAParameters sha2_192f = new SLHDSAParameters(
+ "sha2-192f", new Sha2EngineProvider(24, 16, 22, 8, 33, 66), TYPE_PURE);
+ public static final SLHDSAParameters sha2_192s = new SLHDSAParameters(
+ "sha2-192s", new Sha2EngineProvider(24, 16, 7, 14, 17, 63), TYPE_PURE);
+
+ public static final SLHDSAParameters sha2_256f = new SLHDSAParameters(
+ "sha2-256f", new Sha2EngineProvider(32, 16, 17, 9, 35, 68), TYPE_PURE);
+ public static final SLHDSAParameters sha2_256s = new SLHDSAParameters(
+ "sha2-256s", new Sha2EngineProvider(32, 16, 8, 14, 22, 64), TYPE_PURE);
+
+ // SHAKE-256.
+ public static final SLHDSAParameters shake_128f = new SLHDSAParameters(
+ "shake-128f", new Shake256EngineProvider(16, 16, 22, 6, 33, 66), TYPE_PURE);
+ public static final SLHDSAParameters shake_128s = new SLHDSAParameters(
+ "shake-128s", new Shake256EngineProvider(16, 16, 7, 12, 14, 63), TYPE_PURE);
+
+ public static final SLHDSAParameters shake_192f = new SLHDSAParameters(
+ "shake-192f", new Shake256EngineProvider(24, 16, 22, 8, 33, 66), TYPE_PURE);
+ public static final SLHDSAParameters shake_192s = new SLHDSAParameters(
+ "shake-192s", new Shake256EngineProvider(24, 16, 7, 14, 17, 63), TYPE_PURE);
+
+ public static final SLHDSAParameters shake_256f = new SLHDSAParameters(
+ "shake-256f", new Shake256EngineProvider(32, 16, 17, 9, 35, 68), TYPE_PURE);
+ public static final SLHDSAParameters shake_256s = new SLHDSAParameters(
+ "shake-256s", new Shake256EngineProvider(32, 16, 8, 14, 22, 64), TYPE_PURE);
+
+
+ // "Pre-hash" SLH-DSA Parameters
+ // SHA-2
+ public static final SLHDSAParameters sha2_128f_with_sha256 = new SLHDSAParameters(
+ "sha2-128f-with-sha256", new Sha2EngineProvider(16, 16, 22, 6, 33, 66), TYPE_SHA2_256);
+ public static final SLHDSAParameters sha2_128s_with_sha256 = new SLHDSAParameters(
+ "sha2-128s-with-sha256", new Sha2EngineProvider(16, 16, 7, 12, 14, 63), TYPE_SHA2_256);
+
+ public static final SLHDSAParameters sha2_192f_with_sha512 = new SLHDSAParameters(
+ "sha2-192f-with-sha512", new Sha2EngineProvider(24, 16, 22, 8, 33, 66), TYPE_SHA2_512);
+ public static final SLHDSAParameters sha2_192s_with_sha512 = new SLHDSAParameters(
+ "sha2-192s-with-sha512", new Sha2EngineProvider(24, 16, 7, 14, 17, 63), TYPE_SHA2_512);
+
+ public static final SLHDSAParameters sha2_256f_with_sha512 = new SLHDSAParameters(
+ "sha2-256f-with-sha512", new Sha2EngineProvider(32, 16, 17, 9, 35, 68), TYPE_SHA2_512);
+ public static final SLHDSAParameters sha2_256s_with_sha512 = new SLHDSAParameters(
+ "sha2-256s-with-sha512", new Sha2EngineProvider(32, 16, 8, 14, 22, 64), TYPE_SHA2_512);
+
+ // SHAKE-256.
+ public static final SLHDSAParameters shake_128f_with_shake128 = new SLHDSAParameters(
+ "shake-128f-with-shake128", new Shake256EngineProvider(16, 16, 22, 6, 33, 66), TYPE_SHAKE128);
+ public static final SLHDSAParameters shake_128s_with_shake128 = new SLHDSAParameters(
+ "shake-128s-with-shake128", new Shake256EngineProvider(16, 16, 7, 12, 14, 63), TYPE_SHAKE128);
+
+ public static final SLHDSAParameters shake_192f_with_shake256 = new SLHDSAParameters(
+ "shake-192f-with-shake256", new Shake256EngineProvider(24, 16, 22, 8, 33, 66), TYPE_SHAKE256);
+ public static final SLHDSAParameters shake_192s_with_shake256 = new SLHDSAParameters(
+ "shake-192s-with-shake256", new Shake256EngineProvider(24, 16, 7, 14, 17, 63), TYPE_SHAKE256);
+
+ public static final SLHDSAParameters shake_256f_with_shake256 = new SLHDSAParameters(
+ "shake-256f-with-shake256", new Shake256EngineProvider(32, 16, 17, 9, 35, 68), TYPE_SHAKE256);
+ public static final SLHDSAParameters shake_256s_with_shake256 = new SLHDSAParameters(
+ "shake-256s-with-shake256", new Shake256EngineProvider(32, 16, 8, 14, 22, 64), TYPE_SHAKE256);
+
+ private final String name;
+ private final SLHDSAEngineProvider engineProvider;
+ private final int preHashDigest;
+
+ private SLHDSAParameters(String name, SLHDSAEngineProvider engineProvider, int preHashDigest)
+ {
+ this.name = name;
+ this.engineProvider = engineProvider;
+ this.preHashDigest = preHashDigest;
+ }
+
+ public String getName()
+ {
+ return name;
+ }
+
+ public int getType()
+ {
+ return preHashDigest;
+ }
+
+ public int getN()
+ {
+ return engineProvider.getN();
+ }
+
+ SLHDSAEngine getEngine()
+ {
+ return engineProvider.get();
+ }
+
+ public boolean isPreHash()
+ {
+ return preHashDigest != TYPE_PURE;
+ }
+
+ private static class Sha2EngineProvider
+ implements SLHDSAEngineProvider
+ {
+ private final int n;
+ private final int w;
+ private final int d;
+ private final int a;
+ private final int k;
+ private final int h;
+
+ public Sha2EngineProvider(int n, int w, int d, int a, int k, int h)
+ {
+ this.n = n;
+ this.w = w;
+ this.d = d;
+ this.a = a;
+ this.k = k;
+ this.h = h;
+ }
+
+ public int getN()
+ {
+ return n;
+ }
+
+ public SLHDSAEngine get()
+ {
+ return new SLHDSAEngine.Sha2Engine(n, w, d, a, k, h);
+ }
+ }
+
+ private static class Shake256EngineProvider
+ implements SLHDSAEngineProvider
+ {
+ private final int n;
+ private final int w;
+ private final int d;
+ private final int a;
+ private final int k;
+ private final int h;
+
+ public Shake256EngineProvider(int n, int w, int d, int a, int k, int h)
+ {
+ this.n = n;
+ this.w = w;
+ this.d = d;
+ this.a = a;
+ this.k = k;
+ this.h = h;
+ }
+
+ public int getN()
+ {
+ return n;
+ }
+
+ public SLHDSAEngine get()
+ {
+ return new SLHDSAEngine.Shake256Engine(n, w, d, a, k, h);
+ }
+ }
+}
diff --git a/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/slhdsa/SLHDSAPrivateKeyParameters.java b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/slhdsa/SLHDSAPrivateKeyParameters.java
new file mode 100755
index 000000000..da9c060bb
--- /dev/null
+++ b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/slhdsa/SLHDSAPrivateKeyParameters.java
@@ -0,0 +1,80 @@
+/*
+ * Derived from Bouncy Castle 1.80, package org.bouncycastle.pqc.crypto.slhdsa (MIT licence,
+ * Copyright (c) 2000-2025 The Legion of the Bouncy Castle Inc., see LICENTA-BOUNCYCASTLE.txt),
+ * regenerated into Aere Network by consensus-pqc/slhdsa-fork/genereaza-motorul.py on 2026-09-04 (D-337).
+ * The ONLY change of substance: the SHA-2 engine hashes through the JDK's MessageDigest (SHA-NI
+ * intrinsics) instead of Bouncy Castle's pure-Java digests, which made one SLH-DSA-SHA2-128s signature
+ * cost seconds on the QBFT thread at every anchor parent. Algorithm, key formats and signature bytes are
+ * FIPS 205 as before; SlhDsaFastEngineTest pins that against the original, in both directions.
+ * DO NOT EDIT BY HAND: regenerate with the script above.
+ */
+package org.hyperledger.besu.consensus.common.bft.slhdsa;
+
+import org.bouncycastle.util.Arrays;
+
+@SuppressWarnings("all")
+public class SLHDSAPrivateKeyParameters
+ extends SLHDSAKeyParameters
+{
+ final SK sk;
+ final PK pk;
+
+ public SLHDSAPrivateKeyParameters(SLHDSAParameters parameters, byte[] skpkEncoded)
+ {
+ super(true, parameters);
+ int n = parameters.getN();
+ if (skpkEncoded.length != 4 * n)
+ {
+ throw new IllegalArgumentException("private key encoding does not match parameters");
+ }
+ this.sk = new SK(Arrays.copyOfRange(skpkEncoded, 0, n), Arrays.copyOfRange(skpkEncoded, n, 2 * n));
+ this.pk = new PK(Arrays.copyOfRange(skpkEncoded, 2 * n, 3 * n), Arrays.copyOfRange(skpkEncoded, 3 * n, 4 * n));
+ }
+
+ public SLHDSAPrivateKeyParameters(SLHDSAParameters parameters, byte[] skSeed, byte[] prf, byte[] pkSeed, byte[] pkRoot)
+ {
+ super(true, parameters);
+ this.sk = new SK(skSeed, prf);
+ this.pk = new PK(pkSeed, pkRoot);
+ }
+ SLHDSAPrivateKeyParameters(SLHDSAParameters parameters, SK sk, PK pk)
+ {
+ super(true, parameters);
+ this.sk = sk;
+ this.pk = pk;
+ }
+
+ public byte[] getSeed()
+ {
+ return Arrays.clone(sk.seed);
+ }
+
+ public byte[] getPrf()
+ {
+ return Arrays.clone(sk.prf);
+ }
+
+ public byte[] getPublicSeed()
+ {
+ return Arrays.clone(pk.seed);
+ }
+ public byte[] getRoot()
+ {
+ return Arrays.clone(pk.root);
+ }
+
+ public byte[] getPublicKey()
+ {
+ return Arrays.concatenate(pk.seed, pk.root);
+ }
+
+ public byte[] getEncoded()
+ {
+ return Arrays.concatenate(new byte[][]{ sk.seed, sk.prf, pk.seed, pk.root });
+ }
+
+ public byte[] getEncodedPublicKey()
+ {
+ return Arrays.concatenate(pk.seed, pk.root);
+ }
+}
diff --git a/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/slhdsa/SLHDSAPublicKeyParameters.java b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/slhdsa/SLHDSAPublicKeyParameters.java
new file mode 100755
index 000000000..544156c66
--- /dev/null
+++ b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/slhdsa/SLHDSAPublicKeyParameters.java
@@ -0,0 +1,52 @@
+/*
+ * Derived from Bouncy Castle 1.80, package org.bouncycastle.pqc.crypto.slhdsa (MIT licence,
+ * Copyright (c) 2000-2025 The Legion of the Bouncy Castle Inc., see LICENTA-BOUNCYCASTLE.txt),
+ * regenerated into Aere Network by consensus-pqc/slhdsa-fork/genereaza-motorul.py on 2026-09-04 (D-337).
+ * The ONLY change of substance: the SHA-2 engine hashes through the JDK's MessageDigest (SHA-NI
+ * intrinsics) instead of Bouncy Castle's pure-Java digests, which made one SLH-DSA-SHA2-128s signature
+ * cost seconds on the QBFT thread at every anchor parent. Algorithm, key formats and signature bytes are
+ * FIPS 205 as before; SlhDsaFastEngineTest pins that against the original, in both directions.
+ * DO NOT EDIT BY HAND: regenerate with the script above.
+ */
+package org.hyperledger.besu.consensus.common.bft.slhdsa;
+
+import org.bouncycastle.util.Arrays;
+
+@SuppressWarnings("all")
+public class SLHDSAPublicKeyParameters
+ extends SLHDSAKeyParameters
+{
+ private final PK pk;
+
+ public SLHDSAPublicKeyParameters(SLHDSAParameters parameters, byte[] pkValues)
+ {
+ super(false, parameters);
+ int n = parameters.getN();
+ if (pkValues.length != 2 * n)
+ {
+ throw new IllegalArgumentException("public key encoding does not match parameters");
+ }
+ this.pk = new PK(Arrays.copyOfRange(pkValues, 0, n), Arrays.copyOfRange(pkValues, n, 2 * n));
+ }
+
+ SLHDSAPublicKeyParameters(SLHDSAParameters parameters, PK pk)
+ {
+ super(false, parameters);
+ this.pk = pk;
+ }
+
+ public byte[] getSeed()
+ {
+ return Arrays.clone(pk.seed);
+ }
+
+ public byte[] getRoot()
+ {
+ return Arrays.clone(pk.root);
+ }
+
+ public byte[] getEncoded()
+ {
+ return Arrays.concatenate(pk.seed, pk.root);
+ }
+}
diff --git a/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/slhdsa/SLHDSASigner.java b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/slhdsa/SLHDSASigner.java
new file mode 100755
index 000000000..91fdef108
--- /dev/null
+++ b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/slhdsa/SLHDSASigner.java
@@ -0,0 +1,236 @@
+/*
+ * Derived from Bouncy Castle 1.80, package org.bouncycastle.pqc.crypto.slhdsa (MIT licence,
+ * Copyright (c) 2000-2025 The Legion of the Bouncy Castle Inc., see LICENTA-BOUNCYCASTLE.txt),
+ * regenerated into Aere Network by consensus-pqc/slhdsa-fork/genereaza-motorul.py on 2026-09-04 (D-337).
+ * The ONLY change of substance: the SHA-2 engine hashes through the JDK's MessageDigest (SHA-NI
+ * intrinsics) instead of Bouncy Castle's pure-Java digests, which made one SLH-DSA-SHA2-128s signature
+ * cost seconds on the QBFT thread at every anchor parent. Algorithm, key formats and signature bytes are
+ * FIPS 205 as before; SlhDsaFastEngineTest pins that against the original, in both directions.
+ * DO NOT EDIT BY HAND: regenerate with the script above.
+ */
+package org.hyperledger.besu.consensus.common.bft.slhdsa;
+
+import java.security.SecureRandom;
+
+import org.bouncycastle.crypto.CipherParameters;
+import org.bouncycastle.crypto.params.ParametersWithContext;
+import org.bouncycastle.crypto.params.ParametersWithRandom;
+import org.bouncycastle.pqc.crypto.MessageSigner;
+import org.bouncycastle.util.Arrays;
+
+/**
+ * SLH-DA signer.
+ * <p>
+ * This version is based on the 3rd submission with deference to the updated reference
+ * implementation on github as at November 9th 2021. This version includes the changes
+ * for the countermeasure for the long-message second preimage attack - see
+ * "https://github.com/sphincs/sphincsplus/commit/61cd2695c6f984b4f4d6ed675378ed9a486cbede"
+ * for further details.
+ * </p>
+ */
+@SuppressWarnings("all")
+public class SLHDSASigner
+ implements MessageSigner
+{
+ private static final byte[] DEFAULT_PREFIX = new byte[]{ 0, 0 };
+
+ private byte[] msgPrefix;
+ private SLHDSAPublicKeyParameters pubKey;
+ private SLHDSAPrivateKeyParameters privKey;
+ private SecureRandom random;
+
+ /**
+ * Base constructor.
+ */
+ public SLHDSASigner()
+ {
+ }
+
+ public void init(boolean forSigning, CipherParameters param)
+ {
+ if (param instanceof ParametersWithContext)
+ {
+ ParametersWithContext withContext = (ParametersWithContext)param;
+ param = withContext.getParameters();
+
+ int ctxLength = withContext.getContextLength();
+ if (ctxLength > 255)
+ {
+ throw new IllegalArgumentException("context too long");
+ }
+
+ msgPrefix = new byte[2 + ctxLength];
+ msgPrefix[0] = 0;
+ msgPrefix[1] = (byte)ctxLength;
+ withContext.copyContextTo(msgPrefix, 2, ctxLength);
+ }
+ else
+ {
+ msgPrefix = DEFAULT_PREFIX;
+ }
+
+ SLHDSAParameters parameters;
+ if (forSigning)
+ {
+ pubKey = null;
+
+ if (param instanceof ParametersWithRandom)
+ {
+ ParametersWithRandom withRandom = (ParametersWithRandom)param;
+ privKey = (SLHDSAPrivateKeyParameters)withRandom.getParameters();
+ random = withRandom.getRandom();
+ }
+ else
+ {
+ privKey = (SLHDSAPrivateKeyParameters)param;
+ random = null;
+ }
+
+ parameters = privKey.getParameters();
+ }
+ else
+ {
+ pubKey = (SLHDSAPublicKeyParameters)param;
+ privKey = null;
+ random = null;
+
+ parameters = pubKey.getParameters();
+ }
+
+ if (parameters.isPreHash())
+ {
+ throw new IllegalArgumentException("\"pure\" slh-dsa must use non pre-hash parameters");
+ }
+ }
+
+ public byte[] generateSignature(byte[] message)
+ {
+ // TODO Redundant with the engine created in internalGenerateSignature
+ SLHDSAEngine engine = privKey.getParameters().getEngine();
+
+ engine.init(privKey.pk.seed);
+
+ // generate randomizer
+ byte[] optRand = new byte[engine.N];
+ if (random != null)
+ {
+ random.nextBytes(optRand);
+ }
+ else
+ {
+ System.arraycopy(privKey.pk.seed, 0, optRand, 0, optRand.length);
+ }
+
+ return internalGenerateSignature(privKey, msgPrefix, message, optRand);
+ }
+
+ // Equivalent to slh_verify_internal from specs
+ public boolean verifySignature(byte[] message, byte[] signature)
+ {
+ return internalVerifySignature(pubKey, msgPrefix, message, signature);
+ }
+
+ protected boolean internalVerifySignature(byte[] message, byte[] signature)
+ {
+ return internalVerifySignature(pubKey, null, message, signature);
+ }
+
+ private static boolean internalVerifySignature(SLHDSAPublicKeyParameters pubKey, byte[] msgPrefix, byte[] msg,
+ byte[] signature)
+ {
+ // TODO Check init via pubKey != null
+
+ //# Input: Message M, signature SIG, public key PK
+ //# Output: Boolean
+
+ // init
+ SLHDSAEngine engine = pubKey.getParameters().getEngine();
+
+ engine.init(pubKey.getSeed());
+
+ ADRS adrs = new ADRS();
+
+ if (((1 + engine.K * (1 + engine.A) + engine.H + engine.D * engine.WOTS_LEN) * engine.N) != signature.length)
+ {
+ return false;
+ }
+
+ SIG sig = new SIG(engine.N, engine.K, engine.A, engine.D, engine.H_PRIME, engine.WOTS_LEN, signature);
+
+ byte[] R = sig.getR();
+ SIG_FORS[] sig_fors = sig.getSIG_FORS();
+ SIG_XMSS[] SIG_HT = sig.getSIG_HT();
+
+ // compute message digest and index
+ IndexedDigest idxDigest = engine.H_msg(R, pubKey.getSeed(), pubKey.getRoot(), msgPrefix, msg);
+ byte[] mHash = idxDigest.digest;
+ long idx_tree = idxDigest.idx_tree;
+ int idx_leaf = idxDigest.idx_leaf;
+
+ // compute FORS public key
+ adrs.setTypeAndClear(ADRS.FORS_TREE);
+ adrs.setLayerAddress(0);
+ adrs.setTreeAddress(idx_tree);
+ adrs.setKeyPairAddress(idx_leaf);
+ byte[] PK_FORS = new Fors(engine).pkFromSig(sig_fors, mHash, pubKey.getSeed(), adrs);
+ // verify HT signature
+ adrs.setTypeAndClear(ADRS.TREE);
+ adrs.setLayerAddress(0);
+ adrs.setTreeAddress(idx_tree);
+ adrs.setKeyPairAddress(idx_leaf);
+ HT ht = new HT(engine, null, pubKey.getSeed());
+ return ht.verify(PK_FORS, SIG_HT, pubKey.getSeed(), idx_tree, idx_leaf, pubKey.getRoot());
+ }
+
+ protected byte[] internalGenerateSignature(byte[] message, byte[] optRand)
+ {
+ return internalGenerateSignature(privKey, null, message, optRand);
+ }
+
+ private static byte[] internalGenerateSignature(SLHDSAPrivateKeyParameters privKey, byte[] msgPrefix, byte[] msg,
+ byte[] optRand)
+ {
+ // TODO Check init via privKey != null
+
+ SLHDSAEngine engine = privKey.getParameters().getEngine();
+ engine.init(privKey.pk.seed);
+
+ Fors fors = new Fors(engine);
+ byte[] R = engine.PRF_msg(privKey.sk.prf, optRand, msgPrefix, msg);
+
+ IndexedDigest idxDigest = engine.H_msg(R, privKey.pk.seed, privKey.pk.root, msgPrefix, msg);
+ byte[] mHash = idxDigest.digest;
+ long idx_tree = idxDigest.idx_tree;
+ int idx_leaf = idxDigest.idx_leaf;
+ // FORS sign
+ ADRS adrs = new ADRS();
+ adrs.setTypeAndClear(ADRS.FORS_TREE);
+ adrs.setTreeAddress(idx_tree);
+ adrs.setKeyPairAddress(idx_leaf);
+ SIG_FORS[] sig_fors = fors.sign(mHash, privKey.sk.seed, privKey.pk.seed, adrs);
+ // get FORS public key - spec shows M?
+ adrs = new ADRS();
+ adrs.setTypeAndClear(ADRS.FORS_TREE);
+ adrs.setTreeAddress(idx_tree);
+ adrs.setKeyPairAddress(idx_leaf);
+ byte[] PK_FORS = fors.pkFromSig(sig_fors, mHash, privKey.pk.seed, adrs);
+
+ // sign FORS public key with HT
+ ADRS treeAdrs = new ADRS();
+ treeAdrs.setTypeAndClear(ADRS.TREE);
+
+ HT ht = new HT(engine, privKey.getSeed(), privKey.getPublicSeed());
+ byte[] SIG_HT = ht.sign(PK_FORS, idx_tree, idx_leaf);
+
+ byte[][] sigComponents = new byte[sig_fors.length + 2][];
+ sigComponents[0] = R;
+
+ for (int i = 0; i != sig_fors.length; i++)
+ {
+ sigComponents[1 + i] = Arrays.concatenate(sig_fors[i].sk, Arrays.concatenate(sig_fors[i].authPath));
+ }
+ sigComponents[sigComponents.length - 1] = SIG_HT;
+
+ return Arrays.concatenate(sigComponents);
+ }
+}
diff --git a/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/slhdsa/WotsPlus.java b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/slhdsa/WotsPlus.java
new file mode 100755
index 000000000..fe1a94e58
--- /dev/null
+++ b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/slhdsa/WotsPlus.java
@@ -0,0 +1,177 @@
+/*
+ * Derived from Bouncy Castle 1.80, package org.bouncycastle.pqc.crypto.slhdsa (MIT licence,
+ * Copyright (c) 2000-2025 The Legion of the Bouncy Castle Inc., see LICENTA-BOUNCYCASTLE.txt),
+ * regenerated into Aere Network by consensus-pqc/slhdsa-fork/genereaza-motorul.py on 2026-09-04 (D-337).
+ * The ONLY change of substance: the SHA-2 engine hashes through the JDK's MessageDigest (SHA-NI
+ * intrinsics) instead of Bouncy Castle's pure-Java digests, which made one SLH-DSA-SHA2-128s signature
+ * cost seconds on the QBFT thread at every anchor parent. Algorithm, key formats and signature bytes are
+ * FIPS 205 as before; SlhDsaFastEngineTest pins that against the original, in both directions.
+ * DO NOT EDIT BY HAND: regenerate with the script above.
+ */
+package org.hyperledger.besu.consensus.common.bft.slhdsa;
+
+import org.bouncycastle.util.Arrays;
+import org.bouncycastle.util.Pack;
+
+@SuppressWarnings("all")
+class WotsPlus
+{
+ private final SLHDSAEngine engine;
+ private final int w;
+
+ WotsPlus(SLHDSAEngine engine)
+ {
+ this.engine = engine;
+ this.w = this.engine.WOTS_W;
+ }
+
+ byte[] pkGen(byte[] skSeed, byte[] pkSeed, ADRS paramAdrs)
+ {
+ ADRS wotspkADRS = new ADRS(paramAdrs); // copy address to create OTS public key address
+
+ byte[][] tmp = new byte[engine.WOTS_LEN][];
+ for (int i = 0; i < engine.WOTS_LEN; i++)
+ {
+ ADRS adrs = new ADRS(paramAdrs);
+ adrs.setTypeAndClear(ADRS.WOTS_PRF);
+ adrs.setKeyPairAddress(paramAdrs.getKeyPairAddress());
+ adrs.setChainAddress(i);
+ adrs.setHashAddress(0);
+
+ byte[] sk = engine.PRF(pkSeed, skSeed, adrs);
+
+ adrs.setTypeAndClear(ADRS.WOTS_HASH);
+ adrs.setKeyPairAddress(paramAdrs.getKeyPairAddress());
+ adrs.setChainAddress(i);
+ adrs.setHashAddress(0);
+ tmp[i] = chain(sk, 0, w - 1, pkSeed, adrs);
+ }
+
+ wotspkADRS.setTypeAndClear(ADRS.WOTS_PK);
+ wotspkADRS.setKeyPairAddress(paramAdrs.getKeyPairAddress());
+
+ return engine.T_l(pkSeed, wotspkADRS, Arrays.concatenate(tmp));
+ }
+
+ // #Input: Input string X, start index i, number of steps s, public seed PK.seed, address ADRS
+ // #Output: value of F iterated s times on X
+ byte[] chain(byte[] X, int i, int s, byte[] pkSeed, ADRS adrs)
+ {
+ if (s == 0)
+ {
+ return Arrays.clone(X);
+ }
+ if ((i + s) > (this.w - 1))
+ {
+ return null;
+ }
+ byte[] result = X;
+ for (int j = 0; j < s; ++j)
+ {
+ adrs.setHashAddress(i + j);
+ result = engine.F(pkSeed, adrs, result);
+ }
+ return result;
+ }
+
+ // #Input: Message M, secret seed SK.seed, public seed PK.seed, address ADRS
+ // #Output: WOTS+ signature sig
+ public byte[] sign(byte[] M, byte[] skSeed, byte[] pkSeed, ADRS paramAdrs)
+ {
+ ADRS adrs = new ADRS(paramAdrs);
+
+ int[] msg = new int[engine.WOTS_LEN];
+
+ // convert message to base w
+ base_w(M, 0, w, msg, 0, engine.WOTS_LEN1);
+
+ // compute checksum
+ int csum = 0;
+ for (int i = 0; i < engine.WOTS_LEN1; i++)
+ {
+ csum += w - 1 - msg[i];
+ }
+
+ // convert csum to base w
+ if ((engine.WOTS_LOGW % 8) != 0)
+ {
+ csum = csum << (8 - ((engine.WOTS_LEN2 * engine.WOTS_LOGW) % 8));
+ }
+ int len_2_bytes = (engine.WOTS_LEN2 * engine.WOTS_LOGW + 7) / 8;
+ byte[] csum_bytes = Pack.intToBigEndian(csum);
+ base_w(csum_bytes, 4 - len_2_bytes, w, msg, engine.WOTS_LEN1, engine.WOTS_LEN2);
+
+ byte[][] sig = new byte[engine.WOTS_LEN][];
+ for (int i = 0; i < engine.WOTS_LEN; i++)
+ {
+ adrs.setTypeAndClear(ADRS.WOTS_PRF);
+ adrs.setKeyPairAddress(paramAdrs.getKeyPairAddress());
+ adrs.setChainAddress(i);
+ adrs.setHashAddress(0);
+ byte[] sk = engine.PRF(pkSeed, skSeed, adrs);
+ adrs.setTypeAndClear(ADRS.WOTS_HASH);
+ adrs.setKeyPairAddress(paramAdrs.getKeyPairAddress());
+ adrs.setChainAddress(i);
+ adrs.setHashAddress(0);
+ sig[i] = chain(sk, 0, msg[i], pkSeed, adrs);
+ }
+ return Arrays.concatenate(sig);
+ }
+
+ //
+ // Input: len_X-byte string X, int w, output length out_len
+ // Output: out_len int array basew
+ void base_w(byte[] X, int XOff, int w, int[] output, int outOff, int outLen)
+ {
+ int total = 0;
+ int bits = 0;
+
+ for (int consumed = 0; consumed < outLen; consumed++)
+ {
+ if (bits == 0)
+ {
+ total = X[XOff++];
+ bits += 8;
+ }
+ bits -= engine.WOTS_LOGW;
+ output[outOff++] = ((total >>> bits) & (w - 1));
+ }
+ }
+
+ public byte[] pkFromSig(byte[] sig, byte[] M, byte[] pkSeed, ADRS adrs)
+ {
+ ADRS wotspkADRS = new ADRS(adrs);
+
+ int[] msg = new int[engine.WOTS_LEN];
+
+ // convert message to base w
+ base_w(M, 0, w, msg, 0, engine.WOTS_LEN1);
+
+ // compute checksum
+ int csum = 0;
+ for (int i = 0; i < engine.WOTS_LEN1; i++ )
+ {
+ csum += w - 1 - msg[i];
+ }
+
+ // convert csum to base w
+ csum = csum << (8 - ((engine.WOTS_LEN2 * engine.WOTS_LOGW) % 8));
+ int len_2_bytes = (engine.WOTS_LEN2 * engine.WOTS_LOGW + 7) / 8;
+ byte[] csum_bytes = Pack.intToBigEndian(csum);
+ base_w(csum_bytes, 4 - len_2_bytes, w, msg, engine.WOTS_LEN1, engine.WOTS_LEN2);
+
+ byte[] sigI = new byte[engine.N];
+ byte[][] tmp = new byte[engine.WOTS_LEN][];
+ for (int i = 0; i < engine.WOTS_LEN; i++ )
+ {
+ adrs.setChainAddress(i);
+ System.arraycopy(sig, i * engine.N, sigI, 0, engine.N);
+ tmp[i] = chain(sigI, msg[i], w - 1 - msg[i], pkSeed, adrs);
+ }
+
+ wotspkADRS.setTypeAndClear(ADRS.WOTS_PK);
+ wotspkADRS.setKeyPairAddress(adrs.getKeyPairAddress());
+
+ return engine.T_l(pkSeed, wotspkADRS, Arrays.concatenate(tmp));
+ }
+}
diff --git a/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/tools/PqRegistryHashTool.java b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/tools/PqRegistryHashTool.java
new file mode 100755
index 000000000..a9e7a2a48
--- /dev/null
+++ b/consensus/common/src/main/java/org/hyperledger/besu/consensus/common/bft/tools/PqRegistryHashTool.java
@@ -0,0 +1,231 @@
+/*
+ * Copyright contributors to Besu.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.common.bft.tools;
+
+import java.nio.file.Path;
+import java.nio.file.Paths;
+
+import org.hyperledger.besu.consensus.common.bft.PqRegistryHash;
+
+/**
+ * AERE A8: compute the canonical hash of a Falcon validator registry so it can be put into genesis
+ * as {@code config.pqRegistryHash}.
+ *
+ * <p>This tool calls THE SAME code the startup guard calls. That is the whole point of it existing
+ * as a class inside {@code consensus:common} rather than as a shell script: a tool that computed the
+ * hash its own way would sooner or later disagree with the guard, and the operator would be told a
+ * number that does not let any node start.
+ *
+ * <pre>
+ * java -cp &lt;besu lib&gt; org.hyperledger.besu.consensus.common.bft.tools.PqRegistryHashTool \
+ * &lt;registry-file&gt; [--chain-id N] [--block H] [--quiet]
+ * </pre>
+ *
+ * <p>The registry file may be a legacy {@code .properties} registry, a bare JSON manifest, or a
+ * genesis file carrying {@code config.aereFalconRegistry}; the format is sniffed.
+ */
+public final class PqRegistryHashTool {
+
+ private PqRegistryHashTool() {}
+
+ /**
+ * Entry point.
+ *
+ * @param args registry file, then optional {@code --chain-id N}, {@code --block H}, {@code
+ * --quiet}
+ */
+ public static void main(final String[] args) {
+ String file = null;
+ long chainId = 2800L;
+ long block = 0L;
+ boolean quiet = false;
+ boolean chainIdGiven = false;
+
+ for (int i = 0; i < args.length; i++) {
+ switch (args[i]) {
+ case "--chain-id":
+ chainId = Long.parseLong(require(args, ++i, "--chain-id"));
+ chainIdGiven = true;
+ break;
+ case "--block":
+ block = Long.parseLong(require(args, ++i, "--block"));
+ break;
+ case "--quiet":
+ quiet = true;
+ break;
+ case "-h":
+ case "--help":
+ usage(System.out);
+ return;
+ default:
+ if (args[i].startsWith("--")) {
+ System.err.println("unknown option: " + args[i]);
+ usage(System.err);
+ System.exit(2);
+ }
+ file = args[i];
+ }
+ }
+ if (file == null) {
+ usage(System.err);
+ System.exit(2);
+ return;
+ }
+
+ final Path path = Paths.get(file);
+ final PqRegistryHash.Registry reg;
+ try {
+ reg = PqRegistryHash.loadAuto(path);
+ } catch (final PqRegistryHash.RegistryConfigException e) {
+ System.err.println(e.getMessage());
+ System.exit(3);
+ return;
+ }
+
+ // AERE D-C (2026-08-06). hashFor, not hashV1, and this is the line an operator pastes into
+ // genesis. For a proof-bound (v2) registry the node's gate compares hashV2; printing hashV1 here
+ // gives the whole fleet a value NOTHING on a node ever computes. Measured on a network of seven
+ // on 2026-08-06: all seven start, all seven report the registry loaded, and the chain stops at
+ // H-1. A wrong instruction is more dangerous than a missing one.
+ //
+ // hashV1 is also useless as an epoch identifier, which is the other reason it cannot merely be
+ // kept alongside: the bind height is not in the v1 pre-image, so two rotation epochs of the same
+ // fleet produce the SAME v1 number.
+ final String canonical = PqRegistryHash.hashFor(reg, chainId);
+
+ if (quiet) {
+ System.out.println("0x" + canonical);
+ return;
+ }
+
+ System.out.println("AERE PQC A8 - canonical Falcon registry hash");
+ System.out.println(" file : " + reg.sourcePath());
+ System.out.println(" source kind : " + reg.kind());
+ System.out.println(" entries : " + reg.count());
+ System.out.println(" address-bound : " + reg.addressBound());
+ System.out.println(" chainId : " + chainId + (chainIdGiven ? "" : " (default)"));
+ System.out.println(
+ " format : "
+ + (reg.proofBound()
+ ? "v2, proof-bound, bindHeight=" + reg.bindHeight()
+ : "v1, no binding proofs"));
+ System.out.println();
+ System.out.println(
+ " pqRegistryHash (canonical "
+ + (reg.proofBound() ? "v2" : "v1")
+ + ", THIS is the value for genesis):");
+ System.out.println(" 0x" + canonical);
+ if (reg.proofBound()) {
+ System.out.println();
+ System.out.println(
+ " AERE D-B: schedule this registry at block "
+ + reg.bindHeight()
+ + " AND NOWHERE ELSE. Every row's possession proof and validator claim sign that");
+ System.out.println(
+ " height; a node handed this file at any other block refuses to start with");
+ System.out.println(" AERE-PQC-REG-BIND-08.");
+ }
+ System.out.println();
+ System.out.println(" legacy v0 concat hash (only for cross-checking the genesis alloc anchor");
+ System.out.println(" slot that FalconSealSupport.parseManifest already computes; NOT the value");
+ System.out.println(" pqRegistryHash is compared against):");
+ System.out.println(" 0x" + PqRegistryHash.hashV0Legacy(reg));
+ System.out.println();
+ System.out.println(" per-index fingerprints, keccak256(addr||pk) first 8 hex.");
+ System.out.println(" Paste these next to another node's to find a differing row; they are");
+ System.out.println(" digests, so they carry no key material:");
+ for (final PqRegistryHash.Entry e : reg.entries()) {
+ final byte[] a = e.address();
+ System.out.println(
+ " ["
+ + e.index()
+ + "] "
+ + PqRegistryHash.fingerprint(reg, e.index())
+ + " pkLen="
+ + e.publicKey().length
+ + (a == null ? "" : " addr=0x" + hex(a)));
+ }
+ System.out.println();
+ System.out.println(" Paste into genesis under \"config\":");
+ System.out.println();
+ // AERE D-B: the recipe this tool prints has to be the recipe the node accepts. Since 2026-08-06
+ // a proof-bound registry scheduled at a block other than its bindHeight is refused at startup,
+ // so printing one here would be manufacturing the configuration the node rejects - in a file
+ // that goes to all seven nodes at once.
+ final long at = block == 0L && reg.proofBound() ? reg.bindHeight() : block;
+ if (reg.proofBound() && at != reg.bindHeight()) {
+ System.err.println();
+ System.err.println(
+ "REFUSING TO PRINT A GENESIS FRAGMENT. --block "
+ + block
+ + " does not equal this registry's bindHeight "
+ + reg.bindHeight()
+ + ".");
+ System.err.println(
+ " Every row of this file carries a Falcon possession proof and an ECDSA claim, and both");
+ System.err.println(
+ " sign the bind height. Scheduling it from another block is an activation day no");
+ System.err.println(
+ " validator signed, and a node handed it refuses to start (AERE-PQC-REG-BIND-08).");
+ System.err.println(
+ " Either pass --block " + reg.bindHeight() + ", or re-run the key ceremony for block");
+ System.err.println(
+ " " + block + " - which produces a DIFFERENT hash, because the height is inside it.");
+ System.exit(4);
+ return;
+ }
+ if (at == 0L) {
+ System.out.println(" \"pqRegistryHash\": \"0x" + canonical + "\"");
+ System.out.println();
+ System.out.println(" (that binds from block 0. On a live chain use --block <H> instead, so");
+ System.out.println(" the existing history stays completely unbound.)");
+ } else {
+ System.out.println(" \"pqRegistryHash\": [");
+ System.out.println(" { \"block\": " + at + ", \"hash\": \"0x" + canonical + "\" }");
+ System.out.println(" ]");
+ System.out.println();
+ System.out.println(" Every height below " + at + " stays unbound, so nothing already on");
+ System.out.println(" the chain is affected. A later rotation is a further entry with a");
+ System.out.println(" STRICTLY greater block.");
+ }
+ }
+
+ private static String require(final String[] args, final int i, final String what) {
+ if (i >= args.length) {
+ System.err.println(what + " needs a value");
+ System.exit(2);
+ }
+ return args[i];
+ }
+
+ private static String hex(final byte[] b) {
+ final StringBuilder s = new StringBuilder(b.length * 2);
+ for (final byte x : b) {
+ s.append(Character.forDigit((x >> 4) & 0xf, 16)).append(Character.forDigit(x & 0xf, 16));
+ }
+ return s.toString();
+ }
+
+ private static void usage(final java.io.PrintStream o) {
+ o.println(
+ "usage: PqRegistryHashTool <registry-file> [--chain-id N] [--block H] [--quiet]\n"
+ + " <registry-file> a legacy .properties registry, a JSON manifest, or a genesis\n"
+ + " file carrying config.aereFalconRegistry. Format is sniffed.\n"
+ + " --chain-id N chain id bound into the hashed pre-image (default 2800)\n"
+ + " --block H emit the genesis snippet as a height-bound schedule at H\n"
+ + " --quiet print only 0x<hash>, for scripts\n"
+ + "exit: 0 ok, 2 usage, 3 the registry file was rejected");
+ }
+}
diff --git a/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/AereAnchorProposalDelayTest.java b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/AereAnchorProposalDelayTest.java
new file mode 100755
index 000000000..39753f013
--- /dev/null
+++ b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/AereAnchorProposalDelayTest.java
@@ -0,0 +1,106 @@
+/*
+ * Copyright contributors to Aere Network.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.common.bft;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+import java.util.Map;
+import java.util.OptionalInt;
+import org.hyperledger.besu.consensus.common.bft.blockcreation.PqAnchorProducer;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+/**
+ * D-337 (2026-09-04): the extra wait before a proposal at an ANCHOR height, and only there.
+ *
+ * <p>The measured defect: with the hybrid certificate live on chain 2800 the proposal timer fired
+ * before the sixth SLH-DSA seal of the parent arrived, the producer refused, and eleven of twelve
+ * anchors paid the four-second round-change timeout. The fix is local timing, so the pinned
+ * properties are exactly two: the value is refused when it is nonsense (a bad delay must stop the
+ * node at start, not surprise the state machine), and it is added at anchor heights ONLY, so an
+ * ordinary block is never slowed by a millisecond.
+ */
+class AereAnchorProposalDelayTest {
+
+ @BeforeEach
+ @AfterEach
+ void clean() {
+ System.clearProperty(AereAnchorProposalDelay.PROPERTY);
+ AereAnchorProposalDelay.forgetForTesting();
+ PqAnchorProducer.useConfigForTesting(null);
+ }
+
+ @Test
+ void unsetMeansExactlyTodaysBehaviour() {
+ assertThat(AereAnchorProposalDelay.configuredMillis()).isZero();
+ assertThat(AereAnchorProposalDelay.millisFor(13_014_016L)).isZero();
+ }
+
+ @Test
+ void nonsenseIsRefused() {
+ assertThatThrownBy(() -> AereAnchorProposalDelay.parse("later"))
+ .isInstanceOf(IllegalArgumentException.class)
+ .hasMessageContaining("AERE-PQC-ANCHOR-CONF-05");
+ assertThatThrownBy(() -> AereAnchorProposalDelay.parse("-1"))
+ .isInstanceOf(IllegalArgumentException.class)
+ .hasMessageContaining("outside");
+ assertThatThrownBy(() -> AereAnchorProposalDelay.parse("5001"))
+ .isInstanceOf(IllegalArgumentException.class)
+ .hasMessageContaining("outside");
+ assertThat(AereAnchorProposalDelay.parse("1200")).isEqualTo(1200L);
+ assertThat(AereAnchorProposalDelay.parse(null)).isZero();
+ assertThat(AereAnchorProposalDelay.parse(" ")).isZero();
+ }
+
+ @Test
+ void theWaitAppliesAtAnchorHeightsAndNowhereElse() {
+ // the live shape of chain 2800: anchors from 13,014,000, every 32nd block
+ final PqAnchorConfig cfg =
+ new PqAnchorConfig(
+ 2800L,
+ 13_014_000L,
+ Map.of(13_014_000L, 6),
+ OptionalInt.empty(),
+ false,
+ OptionalInt.empty(),
+ OptionalInt.of(32),
+ 13_014_000L);
+ PqAnchorProducer.useConfigForTesting(cfg);
+ System.setProperty(AereAnchorProposalDelay.PROPERTY, "1200");
+ AereAnchorProposalDelay.forgetForTesting();
+
+ assertThat(AereAnchorProposalDelay.configuredMillis()).isEqualTo(1200L);
+ assertThat(cfg.anchorAppliesAt(13_014_032L)).isTrue();
+ assertThat(AereAnchorProposalDelay.millisFor(13_014_032L)).isEqualTo(1200L);
+
+ // the parent of an anchor, and an ordinary block: not a millisecond
+ assertThat(AereAnchorProposalDelay.millisFor(13_014_031L)).isZero();
+ assertThat(AereAnchorProposalDelay.millisFor(13_014_033L)).isZero();
+ // below the activation height nothing is an anchor
+ assertThat(AereAnchorProposalDelay.millisFor(13_013_968L)).isZero();
+ }
+
+ @Test
+ void aChainWithoutAnAnchorNeverWaits() {
+ PqAnchorProducer.useConfigForTesting(PqAnchorConfig.never(2800L));
+ System.setProperty(AereAnchorProposalDelay.PROPERTY, "1200");
+ AereAnchorProposalDelay.forgetForTesting();
+ assertThat(AereAnchorProposalDelay.millisFor(13_014_032L)).isZero();
+ assertThat(AereAnchorProposalDelay.millisFor(1L)).isZero();
+ }
+}
diff --git a/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/D177NeutralNamesTest.java b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/D177NeutralNamesTest.java
new file mode 100755
index 000000000..05136c6a1
--- /dev/null
+++ b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/D177NeutralNamesTest.java
@@ -0,0 +1,97 @@
+/*
+ * Copyright contributors to the AERE Network.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.common.bft;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.Test;
+
+/**
+ * D-177: the operator-facing switches must not name an algorithm. Every legacy {@code
+ * aere.falcon.*} property has an algorithm-neutral twin {@code aere.pq.sig.*}, read FIRST, with
+ * the legacy spelling kept as a working fallback, and a loud refusal when the two spellings
+ * disagree - the 2026-08-09 lost-fork incident is exactly what a silent preference would invite.
+ *
+ * <p>These tests exercise the single choke point every configured value passes through
+ * ({@link FalconSealSupport#resolve}), so the four behaviours are proven once for all sixteen
+ * switches instead of sixteen times over.
+ */
+class D177NeutralNamesTest {
+
+ private static final String LEGACY = "aere.falcon.validatorCount";
+ private static final String NEUTRAL = "aere.pq.sig.validatorCount";
+ private static final String ENV = "AERE_FALCON_VALIDATOR_COUNT";
+
+ @AfterEach
+ void clear() {
+ System.clearProperty(LEGACY);
+ System.clearProperty(NEUTRAL);
+ }
+
+ @Test
+ void neutralNameAloneIsRead() {
+ System.setProperty(NEUTRAL, "9");
+ assertThat(FalconSealSupport.resolve(LEGACY, ENV)).isEqualTo("9");
+ }
+
+ @Test
+ void legacyNameAloneStillWorks() {
+ System.setProperty(LEGACY, "7");
+ assertThat(FalconSealSupport.resolve(LEGACY, ENV)).isEqualTo("7");
+ }
+
+ @Test
+ void bothNamesSameValueIsAMigrationWindow() {
+ System.setProperty(NEUTRAL, "9");
+ System.setProperty(LEGACY, "9");
+ assertThat(FalconSealSupport.resolve(LEGACY, ENV)).isEqualTo("9");
+ }
+
+ @Test
+ void bothNamesDifferentValuesRefuseLoudly() {
+ System.setProperty(NEUTRAL, "9");
+ System.setProperty(LEGACY, "7");
+ assertThatThrownBy(() -> FalconSealSupport.resolve(LEGACY, ENV))
+ .isInstanceOf(FalconSealSupport.ActivationConfigException.class)
+ .hasMessageContaining("AERE-PQC-CFG-DUAL-NAME-01")
+ .hasMessageContaining(NEUTRAL)
+ .hasMessageContaining(LEGACY);
+ }
+
+ @Test
+ void neutralNameWinsWhenBothAreSemanticallyEqual() {
+ // same text with different whitespace: trim makes them equal, and the neutral value is the
+ // one returned, so new fleets can write only the neutral name with no surprise
+ System.setProperty(NEUTRAL, " 9 ");
+ System.setProperty(LEGACY, "9");
+ assertThat(FalconSealSupport.resolve(LEGACY, ENV)).isEqualTo(" 9 ");
+ }
+
+ @Test
+ void nonFalconPropertiesAreLeftUntouched() {
+ // a property that does not start with aere.falcon. gets no twin: resolve stays exactly the
+ // reader it was before for it
+ System.setProperty("aere.pq.anchorBlock", "13014000");
+ try {
+ assertThat(FalconSealSupport.resolve("aere.pq.anchorBlock", "AERE_PQ_ANCHOR_BLOCK"))
+ .isEqualTo("13014000");
+ } finally {
+ System.clearProperty("aere.pq.anchorBlock");
+ }
+ }
+}
diff --git a/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/FalconAttachIntervalTest.java b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/FalconAttachIntervalTest.java
new file mode 100755
index 000000000..014244362
--- /dev/null
+++ b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/FalconAttachIntervalTest.java
@@ -0,0 +1,228 @@
+/*
+ * AERE, 2026-08-08. The interval and the cap on the path BEFORE the anchor is activated.
+ *
+ * WHY THIS EXISTS, and the cost that demanded it. On 8 August Falcon seal attachment was switched
+ * on across all seven validators of chain 2800. The header went from 525 to 3844 bytes, that is
+ * FIVE seals on EVERY block. At ~60.3 million blocks per year that is ~200 GB per year per node,
+ * measured, and the tightest host had 12 GB free. That is 23 days.
+ *
+ * AND NOW THE PART THAT IS THE ACTUAL FINDING. The anchor producer already had both an interval and
+ * a cap, built and proven on 7 August. But the assembler that runs when the anchor is NOT armed had
+ * neither, and that is precisely the assembler that runs up to the activation height. The cost
+ * control existed and was out of reach exactly in the window where it was needed. `anchorInterval`
+ * on its own does not help: without `aere.pq.anchorBlock` it is completely inert, so there is no
+ * middle road.
+ *
+ * WHY IT IS SAFE, and this is the argument that has to hold, not the disk saving. The preimage of a
+ * Falcon seal contains `parentHash`, which covers the parent header, which covers the grandparent,
+ * and so on down to genesis. So ONE seal over block H transitively covers ALL the history below H.
+ * You do not need a signature on every block in order to defend every block. What you give up with
+ * interval N is exactly and only this: an adversary holding every ECDSA key and no Falcon key can
+ * rewrite up to N blocks back from the last anchor, instead of 1. The property is
+ *
+ * fork depth <= interval
+ *
+ * and it is a dial, not an accident. Algorand ships the same shape at 1 in 256 or rarer.
+ *
+ * Same property as in `PqAnchorIntervalTest`, a different code path. Two paths need two proofs:
+ * precisely because we had a proof on one of them only, we paid 200 GB per year on the other.
+ */
+package org.hyperledger.besu.consensus.common.bft;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+import java.util.OptionalInt;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.Test;
+
+class FalconAttachIntervalTest {
+
+ private static final long ATTACH = 12_900_000L;
+ private static final String P_INTERVAL = "aere.falcon.attachInterval";
+ private static final String P_CAP = "aere.falcon.attachMaxSeals";
+
+ @AfterEach
+ void curata() {
+ System.clearProperty(P_INTERVAL);
+ System.clearProperty(P_CAP);
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // 1. THE COMPATIBILITY BOUNDARY. Unset means EVERY block, that is exactly today's behaviour. A
+ // cap or an interval shipped as a default would be a behaviour change on the live chain
+ // smuggled in through a version bump, and such a change is asked for, not shipped.
+ // ---------------------------------------------------------------------------------------------
+ @Test
+ void withNoIntervalEveryHeightCarriesACertificate() {
+ for (final long n : new long[] {ATTACH, ATTACH + 1, ATTACH + 2, ATTACH + 99, ATTACH + 100_000}) {
+ assertThat(FalconSealSupport.isAttachHeight(n, ATTACH, OptionalInt.empty()))
+ .as("height %d", n)
+ .isTrue();
+ }
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // 2. Below the attach height nothing is written, with or without an interval.
+ // ---------------------------------------------------------------------------------------------
+ @Test
+ void belowTheAttachHeightNothingIsWritten() {
+ for (final OptionalInt every :
+ new OptionalInt[] {OptionalInt.empty(), OptionalInt.of(1), OptionalInt.of(100)}) {
+ assertThat(FalconSealSupport.isAttachHeight(ATTACH - 1, ATTACH, every)).isFalse();
+ assertThat(FalconSealSupport.isAttachHeight(0, ATTACH, every)).isFalse();
+ }
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // 3. An interval of 1 is the same thing written out explicitly, and must behave like "unset".
+ // ---------------------------------------------------------------------------------------------
+ @Test
+ void anIntervalOfOneIsTheSameAsNoInterval() {
+ for (final long n : new long[] {ATTACH, ATTACH + 1, ATTACH + 7, ATTACH + 1000}) {
+ assertThat(FalconSealSupport.isAttachHeight(n, ATTACH, OptionalInt.of(1)))
+ .as("height %d", n)
+ .isEqualTo(FalconSealSupport.isAttachHeight(n, ATTACH, OptionalInt.empty()));
+ }
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // 4. THE NEGATIVE CONTROL OF THE PROOF. At interval 100 exactly one height in a hundred carries a
+ // certificate. We count, we do not sample: a proof that checked three heights I picked myself
+ // would pass even if the arithmetic were wrong between them.
+ // ---------------------------------------------------------------------------------------------
+ @Test
+ void anIntervalOfOneHundredCarriesExactlyOneHeightInOneHundred() {
+ int with = 0;
+ for (long n = ATTACH; n < ATTACH + 10_000; n++) {
+ if (FalconSealSupport.isAttachHeight(n, ATTACH, OptionalInt.of(100))) {
+ with++;
+ assertThat((n - ATTACH) % 100).as("height %d is not a multiple", n).isZero();
+ }
+ }
+ assertThat(with).isEqualTo(100);
+
+ // and the same span of heights WITH NO interval, so the difference we are buying is visible
+ int without = 0;
+ for (long n = ATTACH; n < ATTACH + 10_000; n++) {
+ if (FalconSealSupport.isAttachHeight(n, ATTACH, OptionalInt.empty())) {
+ without++;
+ }
+ }
+ assertThat(without).isEqualTo(10_000);
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // 5. The first attach height always carries a certificate, whatever the interval. If it were
+ // skipped, the arming evidence a restarted node looks for could be missing at the start.
+ // ---------------------------------------------------------------------------------------------
+ @Test
+ void theAttachHeightItselfAlwaysCarriesACertificate() {
+ for (final int every : new int[] {1, 2, 32, 100, 128}) {
+ assertThat(FalconSealSupport.isAttachHeight(ATTACH, ATTACH, OptionalInt.of(every)))
+ .as("interval %d", every)
+ .isTrue();
+ }
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // 6. THE UPPER LIMIT ON THE INTERVAL IS NOT A MATTER OF TASTE. It is the 128 block window in
+ // which a restarted validator looks for its evidence that the fleet is already armed. With a
+ // wider interval that window can contain no sealed header at all, and the node then refuses to
+ // start days later, on some other restart, on the host whose disk has just failed. The only
+ // place where the operator can still see that connection is right here, at configuration time.
+ // ---------------------------------------------------------------------------------------------
+ @Test
+ void anIntervalWiderThanTheRestartEvidenceWindowIsRefused() {
+ System.setProperty(P_INTERVAL, "129");
+ assertThatThrownBy(() -> FalconSealSupport.instance().attachInterval())
+ .isInstanceOf(FalconSealSupport.ActivationConfigException.class)
+ .hasMessageContaining("AERE-PQC-CFG-UNSAFE-09")
+ .hasMessageContaining("128");
+
+ // positive control on the SAME path: exactly 128 has to pass, otherwise the message above could
+ // be coming from anything else and the proof would not be measuring the boundary
+ System.setProperty(P_INTERVAL, "128");
+ assertThat(FalconSealSupport.instance().attachInterval()).hasValue(128);
+ }
+
+ @Test
+ void anIntervalBelowOneIsRefused() {
+ System.setProperty(P_INTERVAL, "0");
+ assertThatThrownBy(() -> FalconSealSupport.instance().attachInterval())
+ .isInstanceOf(FalconSealSupport.ActivationConfigException.class)
+ .hasMessageContaining("AERE-PQC-CFG-UNSAFE-09");
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // 7. A malformed interval STOPS startup. It does not fall back silently to "every block": that
+ // would leave the operator sure a disk control is in force while the disk fills at the old
+ // rate. It is exactly the shape of failure that has cost us the most, a green earned by not
+ // asking.
+ // ---------------------------------------------------------------------------------------------
+ @Test
+ void aMalformedIntervalRefusesToStartRatherThanSilentlyReverting() {
+ System.setProperty(P_INTERVAL, "one hundred");
+ assertThatThrownBy(() -> FalconSealSupport.instance().attachInterval())
+ .isInstanceOf(FalconSealSupport.ActivationConfigException.class)
+ .hasMessageContaining("AERE-PQC-CFG-SYNTAX-09");
+ }
+
+ @Test
+ void anUnsetIntervalMeansEveryBlock() {
+ assertThat(System.getProperty(P_INTERVAL)).isNull();
+ assertThat(FalconSealSupport.instance().attachInterval()).isEmpty();
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // 8. THE SEAL CAP. Unset means no cap. Zero is refused, because a certificate of zero seals is
+ // not a cheaper one, it is an absent one, and the road for that is to not attach at all.
+ // ---------------------------------------------------------------------------------------------
+ @Test
+ void theSealCapDefaultsToNoCapAndRefusesZero() {
+ assertThat(FalconSealSupport.instance().attachMaxSeals()).isEmpty();
+
+ System.setProperty(P_CAP, "3");
+ assertThat(FalconSealSupport.instance().attachMaxSeals()).hasValue(3);
+
+ System.setProperty(P_CAP, "0");
+ assertThatThrownBy(() -> FalconSealSupport.instance().attachMaxSeals())
+ .isInstanceOf(FalconSealSupport.ActivationConfigException.class)
+ .hasMessageContaining("AERE-PQC-CFG-UNSAFE-10");
+
+ System.setProperty(P_CAP, "three");
+ assertThatThrownBy(() -> FalconSealSupport.instance().attachMaxSeals())
+ .isInstanceOf(FalconSealSupport.ActivationConfigException.class)
+ .hasMessageContaining("AERE-PQC-CFG-SYNTAX-10");
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // 9. THE COST, computed from the very arithmetic above and from the measurement on the live
+ // chain. This proof exists so that it breaks if someone changes the arithmetic and believes
+ // they only changed a detail. The figures: 525 bytes for the base header, ~662 per seal
+ // measured in extraData, 60,300,000 blocks per year.
+ // ---------------------------------------------------------------------------------------------
+ @Test
+ void theMeasuredCostOfEachSettingIsWhatWeToldTheFounder() {
+ final long blocuriPeAn = 60_300_000L;
+ final long bytesPerSeal = 662L;
+
+ assertThat(gbPeAn(5, 1, bytesPerSeal, blocuriPeAn)).isBetween(180L, 210L); // today
+ assertThat(gbPeAn(3, 1, bytesPerSeal, blocuriPeAn)).isBetween(105L, 125L); // cap only
+ assertThat(gbPeAn(3, 32, bytesPerSeal, blocuriPeAn)).isBetween(3L, 5L); // cap + 32
+ assertThat(gbPeAn(3, 100, bytesPerSeal, blocuriPeAn)).isBetween(1L, 2L); // cap + 100
+
+ // and the boundary that matters for the disk decision: at 12 GB free, how many days are left
+ assertThat(zile(12L, gbPeAn(5, 1, bytesPerSeal, blocuriPeAn))).isLessThan(30L);
+ assertThat(zile(12L, gbPeAn(3, 32, bytesPerSeal, blocuriPeAn))).isGreaterThan(700L);
+ }
+
+ private static long gbPeAn(
+ final int seals, final int interval, final long bytesPerSeal, final long blocuriPeAn) {
+ return (long) seals * bytesPerSeal * blocuriPeAn / interval / (1024L * 1024L * 1024L);
+ }
+
+ private static long zile(final long gbLiberi, final long gbPeAn) {
+ return gbPeAn == 0 ? Long.MAX_VALUE : gbLiberi * 365L / gbPeAn;
+ }
+}
diff --git a/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/HybridSealProducerTest.java b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/HybridSealProducerTest.java
new file mode 100755
index 000000000..5569abeb7
--- /dev/null
+++ b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/HybridSealProducerTest.java
@@ -0,0 +1,177 @@
+/* AERE HYBRID: the PRODUCER's proofs, and its pairing with enforcement.
+ *
+ * The proof that ties the two halves is the last one: what the producer PRODUCES must pass
+ * exactly the verification the consumer performs, with real test keys and the same message.
+ * Two halves proven separately that were never put end to end are the very pattern that cost
+ * us the most (D-150: every shape-level check had passed). */
+package org.hyperledger.besu.consensus.common.bft;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import org.hyperledger.besu.crypto.SecureRandomProvider;
+
+import java.security.SecureRandom;
+import java.util.List;
+import java.util.Map;
+
+import org.apache.tuweni.bytes.Bytes;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+class HybridSealProducerTest {
+
+ private static final long H_ATASARE = 500L;
+ private static final long H_HIBRID = 1_000L;
+ private static final int INDEX = 4;
+ private static final Bytes MESSAGE = Bytes.fromHexString("0x" + "5a".repeat(32));
+
+ private SealScheme.GeneratedPair slh;
+ private PqSchemeSchedule orar;
+
+ private final SecureRandom random = SecureRandomProvider.createSecureRandom();
+
+ @BeforeEach
+ void setup() {
+ slh = SealSchemes.SLH_DSA_128S.generate(random);
+ orar =
+ PqSchemeSchedule.parse(
+ "0:" + SealSchemes.FALCON_512.id()
+ + "," + H_HIBRID + ":" + SealSchemes.FALCON_512.id()
+ + "+" + SealSchemes.SLH_DSA_128S.id());
+ }
+
+ private HybridSealProducer producator() {
+ return new HybridSealProducer(
+ H_ATASARE, orar, INDEX, Map.of(SealSchemes.SLH_DSA_128S.id(), slh.privateKey()));
+ }
+
+ // ---------------------------------------------------------------- poarta de emisie
+
+ @Test
+ void theDefaultProducerNeverEmitsAnything() {
+ assertThat(HybridSealProducer.disarmed().sealsFor(Long.MAX_VALUE - 1, MESSAGE)).isEmpty();
+ assertThat(HybridSealProducer.disarmed().attachmentArmedAt(Long.MAX_VALUE - 1)).isFalse();
+ }
+
+ @Test
+ void belowTheAttachmentHeightNothingIsEmitted() {
+ assertThat(producator().sealsFor(H_ATASARE - 1, MESSAGE)).isEmpty();
+ }
+
+ @Test
+ void betweenAttachmentAndTheHybridStepThereIsNothingToAdd() {
+ // the gate is open, but the schedule requires only Falcon, which has its own slot: zero extras, correctly
+ assertThat(producator().attachmentArmedAt(H_ATASARE)).isTrue();
+ assertThat(producator().sealsFor(H_ATASARE, MESSAGE)).isEmpty();
+ }
+
+ /**
+ * THE PROOF THAT ACTUALLY SEPARATES THE TWO CASES. The first form of the boundary proof
+ * above passed for the wrong reason: below the attach height the schedule required no extra
+ * scheme anyway, so an empty list said nothing about the gate. Here the schedule REQUIRES,
+ * and the only remaining difference is the gate. Without this, a producer with its gate
+ * removed would have stayed green.
+ */
+ @Test
+ void theGateAloneSuppressesEmissionEvenWhenTheScheduleDemandsIt() {
+ final HybridSealProducer poartaInchisa =
+ new HybridSealProducer(
+ H_HIBRID + 100,
+ orar,
+ INDEX,
+ Map.of(SealSchemes.SLH_DSA_128S.id(), slh.privateKey()));
+ assertThat(poartaInchisa.sealsFor(H_HIBRID, MESSAGE)).isEmpty();
+ assertThat(poartaInchisa.sealsFor(H_HIBRID + 100, MESSAGE)).hasSize(1);
+ }
+
+ @Test
+ void atTheHybridStepTheExtraSealIsProduced() {
+ final List<SchemeSeal> seals = producator().sealsFor(H_HIBRID, MESSAGE);
+ assertThat(seals).hasSize(1);
+ assertThat(seals.get(0).getSchemeWireId()).isEqualTo(SealSchemes.SLH_DSA_128S.wireId());
+ assertThat(seals.get(0).getValidatorIndex()).isEqualTo(INDEX);
+ }
+
+ // ---------------------------------------------------------------- jumatatea de certificat
+
+ @Test
+ void aMissingKeyEmitsNothingAtAllRatherThanAStubCertificate() {
+ final HybridSealProducer withoutKey =
+ new HybridSealProducer(H_ATASARE, orar, INDEX, Map.of());
+ assertThat(withoutKey.sealsFor(H_HIBRID, MESSAGE)).isEmpty();
+ }
+
+ @Test
+ void aNullMessageIsRefusedWithoutThrowing() {
+ assertThat(producator().sealsFor(H_HIBRID, null)).isEmpty();
+ }
+
+ // ---------------------------------------------------------------- dus-intorsul cheii
+
+ @Test
+ void theSlhDsaPrivateKeySurvivesSerializationAndStillSigns() {
+ final byte[] encoded =
+ SealSchemes.SLH_DSA_128S.serializePrivateKey(slh.privateKey()).orElseThrow();
+ final SealScheme.PrivateHandle back =
+ SealSchemes.SLH_DSA_128S.parsePrivateKey(encoded).orElseThrow();
+
+ final byte[] semnat =
+ SealSchemes.SLH_DSA_128S.sign(back, MESSAGE.toArray()).orElseThrow();
+ assertThat(
+ SealSchemes.SLH_DSA_128S.verifyRaw(
+ slh.publicRegistryForm(), MESSAGE.toArray(), semnat))
+ .isTrue();
+ }
+
+ @Test
+ void garbageIsNotAPrivateKeyAndFalconDeliberatelyHasNoEncoding() {
+ assertThat(SealSchemes.SLH_DSA_128S.parsePrivateKey(new byte[] {1, 2, 3})).isEmpty();
+ assertThat(SealSchemes.SLH_DSA_128S.parsePrivateKey(null)).isEmpty();
+ // Falcon NU implementeaza dus-intorsul: incarcarea lui de productie ramane pe componente,
+ // neatinsa. Daca cineva o implementeaza intr-o zi, proba asta il obliga sa se uite aici.
+ final SealScheme.GeneratedPair falcon = SealSchemes.FALCON_512.generate(random);
+ assertThat(SealSchemes.FALCON_512.serializePrivateKey(falcon.privateKey())).isEmpty();
+ }
+
+ // ---------------------------------------------------------------- CELE DOUA JUMATATI, LEGATE
+
+ @Test
+ void whatTheProducerEmitsIsExactlyWhatTheRegistryVerifies() {
+ // producatorul semneaza...
+ final List<SchemeSeal> produse = producator().sealsFor(H_HIBRID, MESSAGE);
+ assertThat(produse).hasSize(1);
+
+ // ...and a REAL hybrid registry, built from properties as in production, verifies it
+ // the registry REFUSES a missing entry (its guard, first caught by this very proof),
+ // so it is built whole: every validator up to our index
+ final java.util.Properties p = new java.util.Properties();
+ p.setProperty("formatVersion", HybridSignerRegistry.FORMAT_VERSION);
+ p.setProperty("chainId", "2800");
+ p.setProperty("count", String.valueOf(INDEX + 1));
+ for (int i = 0; i <= INDEX; i++) {
+ p.setProperty(i + ".addr", "0x" + String.format("%02x", 0xc0 + i).repeat(20));
+ final byte[] pub =
+ i == INDEX
+ ? slh.publicRegistryForm()
+ : SealSchemes.SLH_DSA_128S.generate(random).publicRegistryForm();
+ p.setProperty(
+ i + ".key." + SealSchemes.SLH_DSA_128S.id(), Bytes.wrap(pub).toHexString());
+ }
+ final HybridSignerRegistry registry = HybridSignerRegistry.fromProperties(p, "proba");
+
+ final byte[] cheiePublica =
+ registry.publicKey(INDEX, SealSchemes.SLH_DSA_128S.id()).orElseThrow();
+ assertThat(
+ SealSchemes.SLH_DSA_128S.verifyRaw(
+ cheiePublica, MESSAGE.toArray(), produse.get(0).getSignature().toArray()))
+ .isTrue();
+
+ // the binding's NEGATIVE CONTROL: the same seal over a DIFFERENT message does not pass
+ assertThat(
+ SealSchemes.SLH_DSA_128S.verifyRaw(
+ cheiePublica,
+ Bytes.fromHexString("0x" + "5b".repeat(32)).toArray(),
+ produse.get(0).getSignature().toArray()))
+ .isFalse();
+ }
+}
diff --git a/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/HybridSealSupportTest.java b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/HybridSealSupportTest.java
new file mode 100755
index 000000000..971389b4c
--- /dev/null
+++ b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/HybridSealSupportTest.java
@@ -0,0 +1,206 @@
+/* AERE HYBRID: the PRODUCTION loader's proofs. Each configuration half refuses with its own
+ * code; the happy path reaches a producer that really signs, with REAL test keys, and its
+ * signature is verified against the public key from the registry loaded off "disk"
+ * (a fake ConfigReader: no real file, no global property, zero JVM poisoning). */
+package org.hyperledger.besu.consensus.common.bft;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+import org.hyperledger.besu.crypto.SecureRandomProvider;
+
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+import java.security.SecureRandom;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+import org.apache.tuweni.bytes.Bytes;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+class HybridSealSupportTest {
+
+ private static final long H_HIBRID = 900L;
+ private static final int INDEX = 2;
+
+ private final SecureRandom random = SecureRandomProvider.createSecureRandom();
+ private SealScheme.GeneratedPair slh;
+ private String orar;
+ private String registruText;
+
+ /** Cititor fals: proprietati si "fisiere" din memorie. */
+ private static final class Cititor implements HybridSealSupport.ConfigReader {
+ final Map<String, String> props = new HashMap<>();
+ final Map<String, byte[]> files = new HashMap<>();
+
+ @Override
+ public String property(final String name) {
+ return props.get(name);
+ }
+
+ @Override
+ public String environment(final String name) {
+ return null;
+ }
+
+ @Override
+ public byte[] file(final String path) throws IOException {
+ final byte[] b = files.get(path);
+ if (b == null) {
+ throw new IOException("nu exista: " + path);
+ }
+ return b;
+ }
+ }
+
+ @BeforeEach
+ void setup() {
+ slh = SealSchemes.SLH_DSA_128S.generate(random);
+ orar =
+ "0:" + SealSchemes.FALCON_512.id()
+ + "," + H_HIBRID + ":" + SealSchemes.FALCON_512.id()
+ + "+" + SealSchemes.SLH_DSA_128S.id();
+ final StringBuilder r = new StringBuilder();
+ r.append("formatVersion=").append(HybridSignerRegistry.FORMAT_VERSION).append('\n');
+ r.append("chainId=2800\n");
+ r.append("count=").append(INDEX + 1).append('\n');
+ for (int i = 0; i <= INDEX; i++) {
+ final byte[] pub =
+ i == INDEX
+ ? slh.publicRegistryForm()
+ : SealSchemes.SLH_DSA_128S.generate(random).publicRegistryForm();
+ r.append(i).append(".addr=0x").append(String.format("%02x", 0xd0 + i).repeat(20)).append('\n');
+ r.append(i).append(".key.").append(SealSchemes.SLH_DSA_128S.id()).append('=')
+ .append(Bytes.wrap(pub).toHexString()).append('\n');
+ }
+ registruText = r.toString();
+ }
+
+ private Cititor cuPereche() {
+ final Cititor c = new Cititor();
+ c.props.put(HybridSealSupport.PROPERTY_SCHEDULE, orar);
+ c.props.put(HybridSealSupport.PROPERTY_REGISTRY, "/fals/registru.properties");
+ c.files.put("/fals/registru.properties", registruText.getBytes(StandardCharsets.UTF_8));
+ return c;
+ }
+
+ private void withKey(final Cititor c, final int index, final byte[] sk) {
+ c.props.put(
+ HybridSealSupport.PROPERTY_KEY_PREFIX + SealSchemes.SLH_DSA_128S.id(),
+ "/fals/cheia.properties");
+ c.files.put(
+ "/fals/cheia.properties",
+ ("index=" + index + "\nsk=" + Bytes.wrap(sk).toHexString() + "\n")
+ .getBytes(StandardCharsets.UTF_8));
+ }
+
+ private byte[] skBytes() {
+ return SealSchemes.SLH_DSA_128S.serializePrivateKey(slh.privateKey()).orElseThrow();
+ }
+
+ // ------------------------------------------------------------------ dezarmat si refuzuri
+
+ @Test
+ void nothingConfiguredMeansTodayByteForByte() {
+ final HybridSealSupport s = HybridSealSupport.load(new Cititor());
+ assertThat(s.schedule()).isEmpty();
+ assertThat(s.registry()).isEmpty();
+ assertThat(s.producer().sealsFor(Long.MAX_VALUE - 1, Bytes.of(1))).isEmpty();
+ }
+
+ @Test
+ void scheduleWithoutRegistryRefusesAsConf03() {
+ final Cititor c = new Cititor();
+ c.props.put(HybridSealSupport.PROPERTY_SCHEDULE, orar);
+ assertThatThrownBy(() -> HybridSealSupport.load(c))
+ .hasMessageContaining("AERE-PQC-COMMIT-CONF-03");
+ }
+
+ @Test
+ void attachWithoutThePairRefusesAsConf04() {
+ final Cititor c = new Cititor();
+ c.props.put(HybridSealSupport.PROPERTY_ATTACH_BLOCK, "100");
+ assertThatThrownBy(() -> HybridSealSupport.load(c))
+ .hasMessageContaining("AERE-PQC-HYBRID-CONF-04");
+ }
+
+ @Test
+ void garbageScheduleRefusesLoudly() {
+ final Cititor c = cuPereche();
+ c.props.put(HybridSealSupport.PROPERTY_SCHEDULE, "aiurea:schema-inexistenta");
+ assertThatThrownBy(() -> HybridSealSupport.load(c))
+ .hasMessageContaining("AERE-PQC-HYBRID-CONF-04");
+ }
+
+ @Test
+ void unreadableRegistryRefusesLoudly() {
+ final Cititor c = cuPereche();
+ c.files.clear();
+ assertThatThrownBy(() -> HybridSealSupport.load(c))
+ .hasMessageContaining("AERE-PQC-HYBRID-CONF-04");
+ }
+
+ @Test
+ void armedEmissionWithoutALocalKeyRefusesAsConf04() {
+ final Cititor c = cuPereche();
+ c.props.put(HybridSealSupport.PROPERTY_ATTACH_BLOCK, "100");
+ assertThatThrownBy(() -> HybridSealSupport.load(c))
+ .hasMessageContaining("AERE-PQC-HYBRID-CONF-04")
+ .hasMessageContaining("cannot produce");
+ }
+
+ @Test
+ void aKeyTheRegistryDoesNotVouchForRefusesAsConf05() {
+ final Cititor c = cuPereche();
+ // my real key, but declared at index 0, where the registry holds a DIFFERENT public key
+ withKey(c, 0, skBytes());
+ assertThatThrownBy(() -> HybridSealSupport.load(c))
+ .hasMessageContaining("AERE-PQC-HYBRID-CONF-05")
+ .hasMessageContaining("does NOT verify");
+ }
+
+ @Test
+ void garbageKeyBytesRefuseAsConf05() {
+ final Cititor c = cuPereche();
+ withKey(c, INDEX, new byte[] {1, 2, 3});
+ assertThatThrownBy(() -> HybridSealSupport.load(c))
+ .hasMessageContaining("AERE-PQC-HYBRID-CONF-05");
+ }
+
+ // ------------------------------------------------------------------ drumul fericit, cap la cap
+
+ @Test
+ void theLoadedProducerSignsAndTheLoadedRegistryVerifiesIt() {
+ final Cititor c = cuPereche();
+ c.props.put(HybridSealSupport.PROPERTY_ATTACH_BLOCK, "0");
+ withKey(c, INDEX, skBytes());
+
+ final HybridSealSupport s = HybridSealSupport.load(c);
+ assertThat(s.schedule()).isPresent();
+ assertThat(s.registry()).isPresent();
+
+ final Bytes message = Bytes.fromHexString("0x" + "77".repeat(32));
+ final List<SchemeSeal> seals = s.producer().sealsFor(H_HIBRID, message);
+ assertThat(seals).hasSize(1);
+ assertThat(seals.get(0).getValidatorIndex()).isEqualTo(INDEX);
+
+ final byte[] pub =
+ s.registry().get().publicKey(INDEX, SealSchemes.SLH_DSA_128S.id()).orElseThrow();
+ assertThat(
+ SealSchemes.SLH_DSA_128S.verifyRaw(
+ pub, message.toArray(), seals.get(0).getSignature().toArray()))
+ .isTrue();
+ }
+
+ @Test
+ void withThePairButNoKeyTheNodeVerifiesButNeverEmits() {
+ // exactly the state of a validator that received the binary and the registry but not the
+ // key: its enforcement can work, its emission promises nothing
+ final HybridSealSupport s = HybridSealSupport.load(cuPereche());
+ assertThat(s.schedule()).isPresent();
+ assertThat(s.registry()).isPresent();
+ assertThat(s.producer().sealsFor(H_HIBRID, Bytes.of(1))).isEmpty();
+ }
+}
diff --git a/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/HybridSignerRegistryTest.java b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/HybridSignerRegistryTest.java
new file mode 100755
index 000000000..87bca049e
--- /dev/null
+++ b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/HybridSignerRegistryTest.java
@@ -0,0 +1,225 @@
+/* AERE crypto-agility, step 3 proofs. The registry's job is to REFUSE: every acceptance test here
+ * is outnumbered by refusal tests, because blocante_armare (2026-08-06) measured what a lenient
+ * loader costs: a mistyped comma boots the node DISARMED and nothing shouts. Keys are throwaway
+ * pairs generated per run; no real validator key exists anywhere near this file. */
+package org.hyperledger.besu.consensus.common.bft;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+import java.security.SecureRandom;
+import java.util.Properties;
+
+import org.apache.tuweni.bytes.Bytes;
+import org.hyperledger.besu.crypto.SecureRandomProvider;
+import org.junit.jupiter.api.Test;
+
+class HybridSignerRegistryTest {
+
+ private static final String FALCON = "falcon-512";
+ private static final String SLHDSA = "slh-dsa-128s";
+
+ private final SecureRandom random = SecureRandomProvider.createSecureRandom();
+
+ /** 3 validators: 0 hybrid (both schemes), 1 falcon-only, 2 hybrid. */
+ private Properties sanatos() {
+ final Properties p = new Properties();
+ p.setProperty("formatVersion", "hybrid-1");
+ p.setProperty("chainId", "2800");
+ p.setProperty("count", "3");
+ for (int i = 0; i < 3; i++) {
+ p.setProperty(i + ".addr", "0x" + String.format("%040x", 0xA0 + i));
+ p.setProperty(
+ i + ".key." + FALCON,
+ Bytes.wrap(SealSchemes.FALCON_512.generate(random).publicRegistryForm()).toHexString());
+ }
+ for (final int i : new int[] {0, 2}) {
+ p.setProperty(
+ i + ".key." + SLHDSA,
+ Bytes.wrap(SealSchemes.SLH_DSA_128S.generate(random).publicRegistryForm()).toHexString());
+ }
+ return p;
+ }
+
+ // ------------------------------------------------------------------ acceptance
+
+ @Test
+ void healthyHybridRegistryLoadsWithRightCoverage() {
+ final HybridSignerRegistry reg = HybridSignerRegistry.fromProperties(sanatos(), "test");
+ assertThat(reg.size()).isEqualTo(3);
+ assertThat(reg.chainId()).isEqualTo(2800);
+ assertThat(reg.coverage(FALCON)).isEqualTo(3);
+ assertThat(reg.coverage(SLHDSA)).isEqualTo(2);
+ assertThat(reg.publicKey(0, FALCON)).isPresent();
+ assertThat(reg.publicKey(0, SLHDSA)).isPresent();
+ assertThat(reg.publicKey(1, SLHDSA)).isEmpty(); // falcon-only validator
+ assertThat(reg.publicKey(9, FALCON)).isEmpty(); // absent index
+ assertThat(reg.schemesOf(0)).containsExactly(FALCON, SLHDSA); // canonical id order
+ assertThat(reg.address(1)).isPresent();
+ // keys parse under their scheme and have the measured lengths (896 / 32)
+ assertThat(reg.publicKey(0, FALCON).orElseThrow()).hasSize(896);
+ assertThat(reg.publicKey(0, SLHDSA).orElseThrow()).hasSize(32);
+ }
+
+ // ------------------------------------------------------------------ refusals
+
+ @Test
+ void unknownSchemeSuffixRefusesTheWholeRegistryByName() {
+ final Properties p = sanatos();
+ p.setProperty("1.key.dilithium-notyet", "0x1234");
+ assertThatThrownBy(() -> HybridSignerRegistry.fromProperties(p, "test"))
+ .isInstanceOf(IllegalArgumentException.class)
+ .hasMessageContaining("dilithium-notyet");
+ }
+
+ @Test
+ void wrongKeyLengthForItsSchemeRefuses() {
+ final Properties p = sanatos();
+ p.setProperty("1.key." + SLHDSA, "0x" + "ab".repeat(31)); // 31, not 32
+ assertThatThrownBy(() -> HybridSignerRegistry.fromProperties(p, "test"))
+ .isInstanceOf(IllegalArgumentException.class)
+ .hasMessageContaining("exactly");
+ }
+
+ @Test
+ void falconKeyInSlhSlotRefuses() {
+ // an 896-byte value under the slh-dsa suffix: length check must catch the swap
+ final Properties p = sanatos();
+ p.setProperty(
+ "1.key." + SLHDSA,
+ Bytes.wrap(SealSchemes.FALCON_512.generate(random).publicRegistryForm()).toHexString());
+ assertThatThrownBy(() -> HybridSignerRegistry.fromProperties(p, "test"))
+ .isInstanceOf(IllegalArgumentException.class);
+ }
+
+ @Test
+ void missingAddressRefuses() {
+ final Properties p = sanatos();
+ p.remove("1.addr");
+ assertThatThrownBy(() -> HybridSignerRegistry.fromProperties(p, "test"))
+ .isInstanceOf(IllegalArgumentException.class)
+ .hasMessageContaining("1.addr");
+ }
+
+ @Test
+ void holeInTheIndexSequenceRefuses() {
+ final Properties p = sanatos();
+ p.remove("1.addr");
+ p.remove("1.key." + FALCON);
+ assertThatThrownBy(() -> HybridSignerRegistry.fromProperties(p, "test"))
+ .isInstanceOf(IllegalArgumentException.class);
+ }
+
+ @Test
+ void entriesBeyondCountRefuse() {
+ final Properties p = sanatos();
+ p.setProperty("7.addr", "0x" + "cd".repeat(20));
+ p.setProperty(
+ "7.key." + FALCON,
+ Bytes.wrap(SealSchemes.FALCON_512.generate(random).publicRegistryForm()).toHexString());
+ assertThatThrownBy(() -> HybridSignerRegistry.fromProperties(p, "test"))
+ .isInstanceOf(IllegalArgumentException.class)
+ .hasMessageContaining("beyond count");
+ }
+
+ @Test
+ void wrongFormatVersionRefuses() {
+ final Properties p = sanatos();
+ p.setProperty("formatVersion", "hybrid-9");
+ assertThatThrownBy(() -> HybridSignerRegistry.fromProperties(p, "test"))
+ .isInstanceOf(IllegalArgumentException.class)
+ .hasMessageContaining("hybrid-1");
+ }
+
+ @Test
+ void unrecognisedEntryRefuses() {
+ final Properties p = sanatos();
+ p.setProperty("1.cheie", "0x1234"); // aproape corect, dar nu e nici addr nici key.<schema>
+ assertThatThrownBy(() -> HybridSignerRegistry.fromProperties(p, "test"))
+ .isInstanceOf(IllegalArgumentException.class)
+ .hasMessageContaining("unrecognised");
+ }
+
+ // ------------------------------------------------------------------ the canonical hash
+
+ @Test
+ void hashIsDeterministicAndMovesWithEveryBoundThing() {
+ final Properties p = sanatos();
+ final HybridSignerRegistry a = HybridSignerRegistry.fromProperties(p, "a");
+ final HybridSignerRegistry b = HybridSignerRegistry.fromProperties(p, "b");
+ assertThat(a.canonicalHash()).isEqualTo(b.canonicalHash()); // determinist
+
+ // schimb O cheie: hash-ul se misca
+ final Properties altKey = sanatos();
+ altKey.setProperty(
+ "2.key." + SLHDSA,
+ Bytes.wrap(SealSchemes.SLH_DSA_128S.generate(random).publicRegistryForm()).toHexString());
+ assertThat(HybridSignerRegistry.fromProperties(altKey, "c").canonicalHash())
+ .isNotEqualTo(a.canonicalHash());
+
+ // scot o schema de la un validator: hash-ul se misca
+ final Properties altScheme = sanatos();
+ altScheme.remove("2.key." + SLHDSA);
+ assertThat(HybridSignerRegistry.fromProperties(altScheme, "d").canonicalHash())
+ .isNotEqualTo(a.canonicalHash());
+
+ // alt chainId: hash-ul se misca
+ final Properties altChain = sanatos();
+ altChain.setProperty("chainId", "2801");
+ assertThat(HybridSignerRegistry.fromProperties(altChain, "e").canonicalHash())
+ .isNotEqualTo(a.canonicalHash());
+ }
+
+ @Test
+ void hashDomainCanNeverCollideWithTheFalconOnlyRegistryFamily() {
+ // the domain is part of the preimage; if someone aligned it with the old family, a hybrid
+ // registry could pass itself off as the genesis-bound v1 registry. The constant is
+ // verified here so it cannot drift silently.
+ assertThat(HybridSignerRegistry.HASH_DOMAIN).isEqualTo("AERE-PQ-HYBRID-REGISTRY-1");
+ assertThat(HybridSignerRegistry.HASH_DOMAIN).isNotEqualTo(PqRegistryHash.DOMAIN_V1);
+ assertThat(HybridSignerRegistry.HASH_DOMAIN).isNotEqualTo(PqRegistryHash.DOMAIN_V2);
+ }
+
+ // --------------------------------------------- the registry + the v2 certificate, together
+
+ @Test
+ void endToEndCertificateVerifiesAgainstRegistryKeysPerScheme() {
+ final byte[] message = "commit hash stand-in, 32 bytes!!".getBytes(java.nio.charset.StandardCharsets.UTF_8);
+ // build the registry and KEEP the private test handles so I can sign
+ final Properties p = new Properties();
+ p.setProperty("formatVersion", "hybrid-1");
+ p.setProperty("chainId", "2800");
+ p.setProperty("count", "2");
+ final SealScheme.GeneratedPair f0 = SealSchemes.FALCON_512.generate(random);
+ final SealScheme.GeneratedPair s0 = SealSchemes.SLH_DSA_128S.generate(random);
+ final SealScheme.GeneratedPair f1 = SealSchemes.FALCON_512.generate(random);
+ p.setProperty("0.addr", "0x" + "aa".repeat(20));
+ p.setProperty("1.addr", "0x" + "bb".repeat(20));
+ p.setProperty("0.key." + FALCON, Bytes.wrap(f0.publicRegistryForm()).toHexString());
+ p.setProperty("0.key." + SLHDSA, Bytes.wrap(s0.publicRegistryForm()).toHexString());
+ p.setProperty("1.key." + FALCON, Bytes.wrap(f1.publicRegistryForm()).toHexString());
+ final HybridSignerRegistry reg = HybridSignerRegistry.fromProperties(p, "test");
+
+ // certificatul hibrid: validatorul 0 cu amandoua schemele, 1 doar Falcon
+ final java.util.List<SchemeSeal> cert =
+ java.util.List.of(
+ new SchemeSeal((byte) 0x01, 0, Bytes.wrap(
+ SealSchemes.FALCON_512.sign(f0.privateKey(), message).orElseThrow())),
+ new SchemeSeal((byte) 0x02, 0, Bytes.wrap(
+ SealSchemes.SLH_DSA_128S.sign(s0.privateKey(), message).orElseThrow())),
+ new SchemeSeal((byte) 0x01, 1, Bytes.wrap(
+ SealSchemes.FALCON_512.sign(f1.privateKey(), message).orElseThrow())));
+
+ // round-trip through the v2 format, then EACH seal against ITS OWN key from the registry
+ for (final SchemeSeal seal : PqAnchorV2.decode(PqAnchorV2.encode(cert))) {
+ final SealScheme scheme = SealSchemes.byWireId(seal.getSchemeWireId()).orElseThrow();
+ final byte[] key = reg.publicKey(seal.getValidatorIndex(), scheme.id()).orElseThrow();
+ assertThat(scheme.verifyRaw(key, message, seal.getSignature().toArray()))
+ .as("sigiliul %s contra cheii lui din registru", seal)
+ .isTrue();
+ }
+ // the per-scheme threshold, on the same certificate: 2 Falcon validators, 1 SLH-DSA
+ assertThat(PqAnchorV2.distinctValidatorsWith(cert, (byte) 0x01)).isEqualTo(2);
+ assertThat(PqAnchorV2.distinctValidatorsWith(cert, (byte) 0x02)).isEqualTo(1);
+ }
+}
diff --git a/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqAnchorConfigTest.java b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqAnchorConfigTest.java
new file mode 100755
index 000000000..6f31c94f9
--- /dev/null
+++ b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqAnchorConfigTest.java
@@ -0,0 +1,754 @@
+/*
+ * Copyright contributors to Besu / AERE Network.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.common.bft;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatCode;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.OptionalInt;
+
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+/** The height gate, the staged threshold, and the two emergency de-arm controls. */
+public class PqAnchorConfigTest {
+
+ /** The activation height used throughout, so H appears as one number in every message. */
+ private static final long H = 10_141_734L;
+
+ /**
+ * A reader over two maps instead of over the JVM and the process environment.
+ *
+ * <p>Two reasons this exists rather than {@code System.setProperty} everywhere. First, hermetic
+ * tests: an operator or a CI image that happens to export {@code AERE_PQ_ANCHOR_BLOCK} would
+ * otherwise change what these tests measure, which is precisely the class of accident under
+ * examination. Second, it records every access, and the count of accesses is what proves that the
+ * unconfigured path decodes nothing.
+ */
+ private static final class RecordingReader implements PqAnchorConfig.NameReader {
+ private final Map<String, String> properties = new HashMap<>();
+ private final Map<String, String> environment = new HashMap<>();
+ private final List<String> accesses = new ArrayList<>();
+
+ @Override
+ public String property(final String name) {
+ accesses.add("property:" + name);
+ return properties.get(name);
+ }
+
+ @Override
+ public String environment(final String name) {
+ accesses.add("environment:" + name);
+ return environment.get(name);
+ }
+ }
+
+ /** The negative control: a reader that reports every name as absent, whatever is really set. */
+ private static final class BlindReader implements PqAnchorConfig.NameReader {
+ @Override
+ public String property(final String name) {
+ return null;
+ }
+
+ @Override
+ public String environment(final String name) {
+ return null;
+ }
+ }
+
+ private RecordingReader reader;
+
+ @BeforeEach
+ public void installReader() {
+ reader = new RecordingReader();
+ PqAnchorConfig.useNameReaderForTesting(reader);
+ }
+
+ @AfterEach
+ public void restoreReader() {
+ PqAnchorConfig.useNameReaderForTesting(null);
+ }
+
+ private void set(final String property, final String value) {
+ reader.properties.put(property, value);
+ }
+
+ private void setEnvironment(final String variable, final String value) {
+ reader.environment.put(variable, value);
+ }
+
+ /** A schedule that is correct: a step exactly at H, then two staged raises. */
+ private void armCorrectly() {
+ set(PqAnchorConfig.PROPERTY_CHAIN_ID, "2800");
+ set(PqAnchorConfig.PROPERTY_ANCHOR_BLOCK, Long.toString(H));
+ set(PqAnchorConfig.PROPERTY_MIN_SEALS, H + ":0," + (H + 7200) + ":1," + (H + 14400) + ":3");
+ }
+
+ private static Map<Long, Integer> schedule() {
+ final Map<Long, Integer> steps = new LinkedHashMap<>();
+ steps.put(1000L, 0);
+ steps.put(2000L, 1);
+ steps.put(3000L, 3);
+ steps.put(4000L, 5);
+ return steps;
+ }
+
+ private static PqAnchorConfig armed() {
+ return new PqAnchorConfig(2800L, 1000L, schedule(), OptionalInt.empty(), false);
+ }
+
+ // ===============================================================================================
+ // 1. The value object. Unchanged behaviour, kept as the floor under everything below.
+ // ===============================================================================================
+
+ @Test
+ public void unconfiguredMeansInertAtEveryHeight() {
+ final PqAnchorConfig config = PqAnchorConfig.never(2800L);
+ assertThat(config.everActive()).isFalse();
+ assertThat(config.activeAt(0L)).isFalse();
+ assertThat(config.activeAt(11_800_000L)).isFalse();
+ assertThat(config.activeAt(Long.MAX_VALUE)).isFalse();
+ // And the legacy Falcon rule never retires, so the whole rule set behaves exactly as today.
+ assertThat(config.legacyFalconRuleRetirementBlock()).isEqualTo(Long.MAX_VALUE);
+ }
+
+ @Test
+ public void theGateIsOnTheBlockNumberAndNothingBelowHIsTouched() {
+ final PqAnchorConfig config = armed();
+ assertThat(config.activeAt(0L)).isFalse();
+ assertThat(config.activeAt(999L)).isFalse();
+ assertThat(config.activeAt(1000L)).isTrue();
+ assertThat(config.activeAt(1001L)).isTrue();
+ }
+
+ @Test
+ public void thresholdFollowsTheStagedScheduleAndIsZeroAtActivation() {
+ final PqAnchorConfig config = armed();
+ assertThat(config.minSealsAt(1000L)).isEqualTo(0);
+ assertThat(config.minSealsAt(1999L)).isEqualTo(0);
+ assertThat(config.minSealsAt(2000L)).isEqualTo(1);
+ assertThat(config.minSealsAt(2999L)).isEqualTo(1);
+ assertThat(config.minSealsAt(3000L)).isEqualTo(3);
+ assertThat(config.minSealsAt(4000L)).isEqualTo(5);
+ assertThat(config.minSealsAt(9_999_999L)).isEqualTo(5);
+ }
+
+ @Test
+ public void emergencyCeilingLowersTheThresholdAndCanNeverRaiseIt() {
+ // D1, the only de-arm that works when the chain is ALREADY STOPPED: a halted chain cannot
+ // deliver a height-scheduled configuration change, so the control has to be local to the node.
+ final PqAnchorConfig lowered =
+ new PqAnchorConfig(2800L, 1000L, schedule(), OptionalInt.of(1), false);
+ assertThat(lowered.minSealsAt(4000L)).isEqualTo(1);
+ assertThat(lowered.minSealsAt(1000L)).isEqualTo(0);
+
+ final PqAnchorConfig raiseAttempt =
+ new PqAnchorConfig(2800L, 1000L, schedule(), OptionalInt.of(99), false);
+ assertThat(raiseAttempt.minSealsAt(2000L)).isEqualTo(1);
+ assertThat(raiseAttempt.minSealsAt(4000L)).isEqualTo(5);
+
+ final PqAnchorConfig floored =
+ new PqAnchorConfig(2800L, 1000L, schedule(), OptionalInt.of(0), false);
+ assertThat(floored.minSealsAt(4000L)).isEqualTo(0);
+ }
+
+ @Test
+ public void emergencyDisableSwitchesBothRulesOff() {
+ final PqAnchorConfig disabled =
+ new PqAnchorConfig(2800L, 1000L, schedule(), OptionalInt.empty(), true);
+ assertThat(disabled.everActive()).isFalse();
+ assertThat(disabled.activeAt(5000L)).isFalse();
+ assertThat(disabled.legacyFalconRuleRetirementBlock()).isEqualTo(Long.MAX_VALUE);
+ }
+
+ @Test
+ public void invalidConfigurationsAreRefusedAtConstruction() {
+ // H must leave room for a parent.
+ assertThatThrownBy(
+ () ->
+ new PqAnchorConfig(
+ 2800L, 0L, Collections.emptyMap(), OptionalInt.empty(), false))
+ .isInstanceOf(IllegalArgumentException.class);
+ // A threshold step cannot take effect before the rules do.
+ assertThatThrownBy(
+ () ->
+ new PqAnchorConfig(
+ 2800L, 1000L, Map.of(500L, 3), OptionalInt.empty(), false))
+ .isInstanceOf(IllegalArgumentException.class);
+ // A negative threshold is meaningless.
+ assertThatThrownBy(
+ () ->
+ new PqAnchorConfig(
+ 2800L, 1000L, Map.of(1000L, -1), OptionalInt.empty(), false))
+ .isInstanceOf(IllegalArgumentException.class);
+ }
+
+ // ===============================================================================================
+ // 2. THE COMPATIBILITY PROPERTY. This is the one the whole design is built around: a binary
+ // carrying this code, put on a live node that has none of these names set, must behave exactly
+ // as today. Not approximately. The assertion is on the ACCESS LOG, because "no decode, no
+ // allocation" is a claim about what the loader touched, not about what it returned.
+ // ===============================================================================================
+
+ @Test
+ public void withNoAnchorNameSetAnywhereTheLoaderTouchesNothingAndReturnsTodaysBehaviour() {
+ final PqAnchorConfig config = PqAnchorConfig.fromSystemConfiguration();
+
+ assertThat(config.everActive()).isFalse();
+ assertThat(config.anchorConfigured()).isFalse();
+ assertThat(config.disabled()).isFalse();
+ assertThat(config.chainId()).isEqualTo(0L);
+ assertThat(config.anchorBlock()).isEqualTo(PqAnchorConfig.NEVER);
+ assertThat(config.minSealsSchedule()).isEmpty();
+ assertThat(config.minSealsCeiling()).isEmpty();
+ assertThat(config.legacyFalconRuleRetirementBlock()).isEqualTo(PqAnchorConfig.NEVER);
+ assertThat(config.toString()).isEqualTo(PqAnchorConfig.never(0L).toString());
+ for (final long height : new long[] {0L, 1L, H - 1, H, H + 1, Long.MAX_VALUE}) {
+ assertThat(config.activeAt(height)).isFalse();
+ assertThat(config.minSealsAt(height)).isEqualTo(0);
+ assertThat(config.emergencyCeilingLowersAt(height)).isFalse();
+ }
+
+ // THE LOAD-BEARING ASSERTION of this test. SEVEN names, each probed exactly once as a system
+ // property and once as an environment variable, and then nothing: fourteen accesses, not
+ // fifteen. A loader that went any further and decoded would read the same names a second time
+ // and this number would be 28.
+ //
+ // IT WAS TEN UNTIL 2026-08-07, and it went up TWICE on the same day, for
+ // `aere.pq.anchor.maxSeals` and then for `aere.pq.anchorInterval`. Each time the test failed
+ // and forced somebody to look, which is exactly what it was asked to do. The number is raised
+ // DELIBERATELY, with the reason written next to it; the assertion is never weakened and never
+ // deleted.
+ //
+ // The consequence of adding a name, and it is intended: a node that has ONLY a cost control
+ // set, with no anchor height, is no longer "a node with no anchor configuration"; it becomes
+ // one with an incomplete configuration, and it refuses to start. A cap or an interval with no
+ // anchor means nothing, and it is better for it to shout than to keep quiet.
+ // 16 since 2026-09-03: the v2 activation height (property + environment) joined the names
+ // 18 since 2026-09-04: the interval SCHEDULE (D-336, disk) joined them, between the interval and the v2 height
+ assertThat(reader.accesses).hasSize(18);
+ assertThat(reader.accesses)
+ .containsExactly(
+ "property:" + PqAnchorConfig.PROPERTY_ANCHOR_BLOCK,
+ "environment:" + PqAnchorConfig.ENV_ANCHOR_BLOCK,
+ "property:" + PqAnchorConfig.PROPERTY_MIN_SEALS,
+ "environment:" + PqAnchorConfig.ENV_MIN_SEALS,
+ "property:" + PqAnchorConfig.PROPERTY_CHAIN_ID,
+ "environment:" + PqAnchorConfig.ENV_CHAIN_ID,
+ "property:" + PqAnchorConfig.PROPERTY_MIN_SEALS_CEILING,
+ "environment:" + PqAnchorConfig.ENV_MIN_SEALS_CEILING,
+ // added 2026-08-07 together with the cost cap; the ORDER matters and it is the one in
+ // ANCHOR_NAMES, where maxSeals sits between the emergency ceiling and the disarm
+ "property:" + PqAnchorConfig.PROPERTY_MAX_SEALS,
+ "environment:" + PqAnchorConfig.ENV_MAX_SEALS,
+ "property:" + PqAnchorConfig.PROPERTY_ANCHOR_INTERVAL,
+ "environment:" + PqAnchorConfig.ENV_ANCHOR_INTERVAL,
+ "property:" + PqAnchorConfig.PROPERTY_ANCHOR_INTERVAL_SCHEDULE,
+ "environment:" + PqAnchorConfig.ENV_ANCHOR_INTERVAL_SCHEDULE,
+ // added 2026-09-03 with the scheme-tagged (v2) certificate: its activation height sits
+ // between the interval and the disarm, as in ANCHOR_NAMES
+ "property:" + PqAnchorConfig.PROPERTY_ANCHOR_V2_BLOCK,
+ "environment:" + PqAnchorConfig.ENV_ANCHOR_V2_BLOCK,
+ "property:" + PqAnchorConfig.PROPERTY_DISABLE,
+ "environment:" + PqAnchorConfig.ENV_DISABLE);
+ }
+
+ // ===============================================================================================
+ // 3. THE ARMED PATH. A correct configuration still starts, and the threshold in force is the one
+ // that was asked for. Without this, "refuses everything" would score as a pass.
+ // ===============================================================================================
+
+ @Test
+ public void aCorrectConfigurationStartsAndTheThresholdIsTheOneThatWasAskedFor() {
+ armCorrectly();
+ final PqAnchorConfig config = PqAnchorConfig.fromSystemConfiguration();
+
+ assertThat(config.everActive()).isTrue();
+ assertThat(config.anchorConfigured()).isTrue();
+ assertThat(config.chainId()).isEqualTo(2800L);
+ assertThat(config.anchorBlock()).isEqualTo(H);
+ assertThat(config.activeAt(H - 1)).isFalse();
+ assertThat(config.activeAt(H)).isTrue();
+ assertThat(config.minSealsAt(H)).isEqualTo(0);
+ assertThat(config.minSealsAt(H + 7199)).isEqualTo(0);
+ assertThat(config.minSealsAt(H + 7200)).isEqualTo(1);
+ assertThat(config.minSealsAt(H + 14400)).isEqualTo(3);
+ assertThat(config.minSealsAt(H + 10_000_000)).isEqualTo(3);
+ assertThat(config.legacyFalconRuleRetirementBlock()).isEqualTo(H);
+ }
+
+ @Test
+ public void theEnvironmentFormIsReadTheSameWayAsTheProperty() {
+ setEnvironment(PqAnchorConfig.ENV_CHAIN_ID, "2800");
+ setEnvironment(PqAnchorConfig.ENV_ANCHOR_BLOCK, Long.toString(H));
+ setEnvironment(PqAnchorConfig.ENV_MIN_SEALS, H + ":3");
+ final PqAnchorConfig config = PqAnchorConfig.fromSystemConfiguration();
+ assertThat(config.everActive()).isTrue();
+ assertThat(config.minSealsAt(H)).isEqualTo(3);
+ }
+
+ @Test
+ public void aCorrectConfigurationReadThroughTheREALSystemPropertiesAlsoStarts() {
+ // The map reader above is hermetic, which is why it is used everywhere else. This one case goes
+ // through System.getProperty itself, so that the seam cannot be hiding a difference between the
+ // reader the tests use and the reader the node uses.
+ PqAnchorConfig.useNameReaderForTesting(null);
+ final String[] keys = {
+ PqAnchorConfig.PROPERTY_CHAIN_ID,
+ PqAnchorConfig.PROPERTY_ANCHOR_BLOCK,
+ PqAnchorConfig.PROPERTY_MIN_SEALS,
+ PqAnchorConfig.PROPERTY_MIN_SEALS_CEILING,
+ PqAnchorConfig.PROPERTY_DISABLE
+ };
+ final String[] saved = new String[keys.length];
+ for (int i = 0; i < keys.length; i++) {
+ saved[i] = System.getProperty(keys[i]);
+ }
+ try {
+ System.setProperty(PqAnchorConfig.PROPERTY_CHAIN_ID, "2800");
+ System.setProperty(PqAnchorConfig.PROPERTY_ANCHOR_BLOCK, "12000000");
+ System.setProperty(
+ PqAnchorConfig.PROPERTY_MIN_SEALS, "12000000:0,12007200:1,12014400:3,12021600:5");
+ System.clearProperty(PqAnchorConfig.PROPERTY_MIN_SEALS_CEILING);
+ System.clearProperty(PqAnchorConfig.PROPERTY_DISABLE);
+
+ final PqAnchorConfig config = PqAnchorConfig.fromSystemConfiguration();
+ assertThat(config.chainId()).isEqualTo(2800L);
+ assertThat(config.anchorBlock()).isEqualTo(12_000_000L);
+ assertThat(config.activeAt(11_999_999L)).isFalse();
+ assertThat(config.activeAt(12_000_000L)).isTrue();
+ assertThat(config.minSealsAt(12_000_000L)).isEqualTo(0);
+ assertThat(config.minSealsAt(12_021_600L)).isEqualTo(5);
+
+ System.setProperty(PqAnchorConfig.PROPERTY_MIN_SEALS_CEILING, "1");
+ assertThat(PqAnchorConfig.fromSystemConfiguration().minSealsAt(12_021_600L)).isEqualTo(1);
+
+ System.setProperty(PqAnchorConfig.PROPERTY_DISABLE, "true");
+ final PqAnchorConfig off = PqAnchorConfig.fromSystemConfiguration();
+ assertThat(off.everActive()).isFalse();
+ assertThat(off.activeAt(12_021_600L)).isFalse();
+ // The anchor is still CONFIGURED, which is what keeps the per-block disarm shout alive.
+ assertThat(off.anchorConfigured()).isTrue();
+ } finally {
+ for (int i = 0; i < keys.length; i++) {
+ if (saved[i] == null) {
+ System.clearProperty(keys[i]);
+ } else {
+ System.setProperty(keys[i], saved[i]);
+ }
+ }
+ }
+ }
+
+ // ===============================================================================================
+ // 4. THE NINE WAYS THE ANCHOR USED TO GO QUIETLY DISARMED. One case each, every one of them a
+ // startup refusal now, and every assertion names the code and the field so that a message that
+ // stops telling the operator which knob to turn goes red here.
+ // ===============================================================================================
+
+ private void assertRefusesNaming(final String field) {
+ assertThatThrownBy(PqAnchorConfig::fromSystemConfiguration)
+ .isInstanceOf(FalconSealSupport.ActivationConfigException.class)
+ .hasMessageContaining(PqAnchorConfig.REFUSAL_CODE)
+ .hasMessageContaining("REFUSING TO START")
+ .hasMessageContaining("FIELD " + field)
+ .hasMessageContaining("never in parallel");
+ }
+
+ /** P1: the emptied shell variable. The quietest path in the whole file until today. */
+ @Test
+ public void p1_anEmptyAnchorBlockIsAMistakeNotAnAbsence() {
+ set(PqAnchorConfig.PROPERTY_ANCHOR_BLOCK, "");
+ assertRefusesNaming(PqAnchorConfig.PROPERTY_ANCHOR_BLOCK);
+ }
+
+ /** P2: an unreadable H used to log a number nobody reads as "the anchor is off". */
+ @Test
+ public void p2_anUnparseableAnchorBlockRefusesInsteadOfRunningInert() {
+ set(PqAnchorConfig.PROPERTY_CHAIN_ID, "2800");
+ set(PqAnchorConfig.PROPERTY_ANCHOR_BLOCK, "10_141_734");
+ set(PqAnchorConfig.PROPERTY_MIN_SEALS, H + ":3");
+ assertRefusesNaming(PqAnchorConfig.PROPERTY_ANCHOR_BLOCK);
+ }
+
+ /** P3: the discarded schedule. The node armed, and K was 0, and the banner said ARMED. */
+ @Test
+ public void p3_aBrokenStepNoLongerDiscardsTheWholeScheduleAndArmsAtZero() {
+ set(PqAnchorConfig.PROPERTY_CHAIN_ID, "2800");
+ set(PqAnchorConfig.PROPERTY_ANCHOR_BLOCK, Long.toString(H));
+ set(PqAnchorConfig.PROPERTY_MIN_SEALS, H + ":3," + (H + 7200) + ":");
+ assertRefusesNaming(PqAnchorConfig.PROPERTY_MIN_SEALS);
+ assertThatThrownBy(PqAnchorConfig::fromSystemConfiguration)
+ .hasMessageContaining("has no threshold after the ':'");
+ }
+
+ /** P3, the other shape: one comma too many. */
+ @Test
+ public void p3_aStrayCommaIsARefusalNotASkippedStep() {
+ set(PqAnchorConfig.PROPERTY_CHAIN_ID, "2800");
+ set(PqAnchorConfig.PROPERTY_ANCHOR_BLOCK, Long.toString(H));
+ set(PqAnchorConfig.PROPERTY_MIN_SEALS, H + ":3,," + (H + 7200) + ":4");
+ assertRefusesNaming(PqAnchorConfig.PROPERTY_MIN_SEALS);
+ }
+
+ /** P3, the emptiest shape: armed with no schedule at all means armed at K=0. */
+ @Test
+ public void p3_anArmedAnchorWithAnEmptyScheduleIsRefused() {
+ set(PqAnchorConfig.PROPERTY_CHAIN_ID, "2800");
+ set(PqAnchorConfig.PROPERTY_ANCHOR_BLOCK, Long.toString(H));
+ set(PqAnchorConfig.PROPERTY_MIN_SEALS, "");
+ assertRefusesNaming(PqAnchorConfig.PROPERTY_MIN_SEALS);
+ }
+
+ /**
+ * P4: syntactically perfect, semantically wrong. One digit too many in the first height and K
+ * stays 0 for ten million blocks, with no log line and no guard anywhere. The rule that kills it
+ * is a property, not a heuristic: the threshold must be defined AT the activation height.
+ */
+ @Test
+ public void p4_aScheduleThatDoesNotDefineKAtTheActivationHeightIsRefused() {
+ set(PqAnchorConfig.PROPERTY_CHAIN_ID, "2800");
+ set(PqAnchorConfig.PROPERTY_ANCHOR_BLOCK, Long.toString(H));
+ set(PqAnchorConfig.PROPERTY_MIN_SEALS, (H * 10) + ":3");
+ assertRefusesNaming(PqAnchorConfig.PROPERTY_MIN_SEALS);
+ assertThatThrownBy(PqAnchorConfig::fromSystemConfiguration)
+ .hasMessageContaining("no step at the activation height " + H);
+ }
+
+ /**
+ * P5: every value the constructor would have rejected used to be caught, logged once and turned
+ * into {@code never()}, so the node ran with the anchor completely inert and nothing said so
+ * again. All four shapes refuse now, and each one names the field that is actually wrong rather
+ * than the first field the loader happened to be holding.
+ */
+ @Test
+ public void p5_aConfigurationTheConstructorWouldRejectRefusesInsteadOfReturningNever() {
+ // H with no room for a parent.
+ set(PqAnchorConfig.PROPERTY_CHAIN_ID, "2800");
+ set(PqAnchorConfig.PROPERTY_ANCHOR_BLOCK, "0");
+ set(PqAnchorConfig.PROPERTY_MIN_SEALS, "0:3");
+ assertRefusesNaming(PqAnchorConfig.PROPERTY_ANCHOR_BLOCK);
+
+ // A negative threshold.
+ installReader();
+ armCorrectly();
+ set(PqAnchorConfig.PROPERTY_MIN_SEALS, H + ":-1");
+ assertRefusesNaming(PqAnchorConfig.PROPERTY_MIN_SEALS);
+
+ // A step that would take effect before the rules do. This is the common one: H is pushed back
+ // and the schedule is left where it was.
+ installReader();
+ armCorrectly();
+ set(PqAnchorConfig.PROPERTY_MIN_SEALS, (H - 1000) + ":0," + H + ":3");
+ assertRefusesNaming(PqAnchorConfig.PROPERTY_MIN_SEALS);
+ }
+
+ /** P6: a negative ceiling disarmed the WHOLE anchor while the banner said "threshold capped". */
+ @Test
+ public void p6_aNegativeCeilingRefusesInsteadOfSilentlyKillingTheAnchor() {
+ armCorrectly();
+ set(PqAnchorConfig.PROPERTY_MIN_SEALS_CEILING, "-1");
+ assertRefusesNaming(PqAnchorConfig.PROPERTY_MIN_SEALS_CEILING);
+ }
+
+ /** P7: an unreadable ceiling was IGNORED, and announced as being in force anyway. */
+ @Test
+ public void p7_anUnparseableCeilingRefusesInsteadOfBeingIgnored() {
+ armCorrectly();
+ set(PqAnchorConfig.PROPERTY_MIN_SEALS_CEILING, "three");
+ assertRefusesNaming(PqAnchorConfig.PROPERTY_MIN_SEALS_CEILING);
+ }
+
+ /**
+ * P8: the Holesky field, by name. An absent chain id took the default zero, the domain separation
+ * left the D and M pre-images, and nothing anywhere refused. Holesky ran for months on exactly
+ * this before it lost finality for two weeks.
+ */
+ @Test
+ public void p8_anArmedAnchorWithoutAnExplicitChainIdIsRefused() {
+ set(PqAnchorConfig.PROPERTY_ANCHOR_BLOCK, Long.toString(H));
+ set(PqAnchorConfig.PROPERTY_MIN_SEALS, H + ":3");
+ assertRefusesNaming(PqAnchorConfig.PROPERTY_CHAIN_ID);
+ }
+
+ /** P8, the explicit zero: written down, still meaningless. */
+ @Test
+ public void p8_anExplicitChainIdOfZeroIsRefused() {
+ set(PqAnchorConfig.PROPERTY_CHAIN_ID, "0");
+ set(PqAnchorConfig.PROPERTY_ANCHOR_BLOCK, Long.toString(H));
+ set(PqAnchorConfig.PROPERTY_MIN_SEALS, H + ":3");
+ assertRefusesNaming(PqAnchorConfig.PROPERTY_CHAIN_ID);
+ }
+
+ /** A schedule with no activation height can never do anything, and used to say nothing. */
+ @Test
+ public void aScheduleWithoutAnActivationHeightIsRefused() {
+ set(PqAnchorConfig.PROPERTY_CHAIN_ID, "2800");
+ set(PqAnchorConfig.PROPERTY_MIN_SEALS, H + ":3");
+ assertRefusesNaming(PqAnchorConfig.PROPERTY_MIN_SEALS);
+ }
+
+ /** The same height twice with two different thresholds: whichever wins, it is not a decision. */
+ @Test
+ public void aDuplicateHeightWithTwoThresholdsIsRefused() {
+ set(PqAnchorConfig.PROPERTY_CHAIN_ID, "2800");
+ set(PqAnchorConfig.PROPERTY_ANCHOR_BLOCK, Long.toString(H));
+ set(PqAnchorConfig.PROPERTY_MIN_SEALS, H + ":3," + H + ":5");
+ assertRefusesNaming(PqAnchorConfig.PROPERTY_MIN_SEALS);
+ }
+
+ // ===============================================================================================
+ // 5. THE BRAKE. It is the one control that has to work when the chain is already stopped, so it
+ // is the one place where "refuse to start" would be the wrong answer.
+ // ===============================================================================================
+
+ /** P9: Boolean.parseBoolean made "1", "yes" and "on" into a silent FALSE. A pressed brake. */
+ @Test
+ public void p9_theBrakeUnderstandsTheWordsAnOperatorActuallyTypes() {
+ for (final String yes : new String[] {"true", "TRUE", "1", "yes", "YES", "on", "On"}) {
+ installReader();
+ armCorrectly();
+ set(PqAnchorConfig.PROPERTY_DISABLE, yes);
+ final PqAnchorConfig config = PqAnchorConfig.fromSystemConfiguration();
+ assertThat(config.disabled()).as("disarm value %s", yes).isTrue();
+ assertThat(config.everActive()).isFalse();
+ assertThat(config.activeAt(H + 1)).isFalse();
+ // Still CONFIGURED, so PqEmergencyShoutRule keeps shouting at every block.
+ assertThat(config.anchorConfigured()).isTrue();
+ assertThat(config.anchorBlock()).isEqualTo(H);
+ }
+ for (final String no : new String[] {"false", "FALSE", "0", "no", "off"}) {
+ installReader();
+ armCorrectly();
+ set(PqAnchorConfig.PROPERTY_DISABLE, no);
+ final PqAnchorConfig config = PqAnchorConfig.fromSystemConfiguration();
+ assertThat(config.disabled()).as("disarm value %s", no).isFalse();
+ assertThat(config.everActive()).isTrue();
+ }
+ }
+
+ /** A brake value nobody can read is the one thing worse than no brake: refuse. */
+ @Test
+ public void p9_anUnreadableBrakeValueIsRefused() {
+ armCorrectly();
+ set(PqAnchorConfig.PROPERTY_DISABLE, "maybe");
+ assertRefusesNaming(PqAnchorConfig.PROPERTY_DISABLE);
+ }
+
+ /**
+ * THE BRAKE IS ABSOLUTE. A node whose anchor configuration is broken in every other way must
+ * still start when the operator has asked for the anchor to be off, because that request is the
+ * only way back from an activation that stopped the chain.
+ */
+ @Test
+ public void theBrakeStartsTheNodeEvenOverAConfigurationThatWouldOtherwiseBeRefused() {
+ set(PqAnchorConfig.PROPERTY_ANCHOR_BLOCK, "");
+ set(PqAnchorConfig.PROPERTY_MIN_SEALS, "this,is,not,a,schedule");
+ set(PqAnchorConfig.PROPERTY_MIN_SEALS_CEILING, "-9");
+ set(PqAnchorConfig.PROPERTY_DISABLE, "true");
+
+ final PqAnchorConfig config = PqAnchorConfig.fromSystemConfiguration();
+ assertThat(config.everActive()).isFalse();
+ assertThat(config.activeAt(H)).isFalse();
+ // Honest cost, stated here so it is not discovered later: with no readable activation height
+ // there is nothing for the per-block disarm announcement to name, so it is lost in this corner.
+ assertThat(config.anchorConfigured()).isFalse();
+ }
+
+ // ===============================================================================================
+ // 6. THE CONTROLS. A gate that has never been shown to open and close is not a gate.
+ // ===============================================================================================
+
+ /**
+ * NEGATIVE CONTROL 1. Remove the guard: a reader whose presence probe answers "absent" for every
+ * name. Every refusal above must disappear and the loader must fall straight through to today's
+ * behaviour. If any of these still threw, the refusal would be coming from somewhere other than
+ * the presence gate and this whole file would be measuring the wrong thing.
+ */
+ @Test
+ public void negativeControl_withThePresenceGateRemovedEveryRefusalDisappears() {
+ final String[][] brokenConfigurations = {
+ {PqAnchorConfig.PROPERTY_ANCHOR_BLOCK, ""},
+ {PqAnchorConfig.PROPERTY_ANCHOR_BLOCK, "10_141_734"},
+ {PqAnchorConfig.PROPERTY_MIN_SEALS, H + ":3," + (H + 7200) + ":"},
+ {PqAnchorConfig.PROPERTY_MIN_SEALS, H + ":3,," + (H + 7200) + ":4"},
+ {PqAnchorConfig.PROPERTY_MIN_SEALS, (H * 10) + ":3"},
+ {PqAnchorConfig.PROPERTY_MIN_SEALS_CEILING, "-1"},
+ {PqAnchorConfig.PROPERTY_MIN_SEALS_CEILING, "three"},
+ {PqAnchorConfig.PROPERTY_CHAIN_ID, "0"},
+ {PqAnchorConfig.PROPERTY_DISABLE, "maybe"}
+ };
+
+ // First, with the gate in place, prove each one is genuinely red. A negative control over cases
+ // that were never red proves nothing at all.
+ for (final String[] broken : brokenConfigurations) {
+ installReader();
+ set(PqAnchorConfig.PROPERTY_CHAIN_ID, "2800");
+ set(PqAnchorConfig.PROPERTY_ANCHOR_BLOCK, Long.toString(H));
+ set(PqAnchorConfig.PROPERTY_MIN_SEALS, H + ":3");
+ set(broken[0], broken[1]);
+ assertThatThrownBy(PqAnchorConfig::fromSystemConfiguration)
+ .as("with the gate in place: %s=%s", broken[0], broken[1])
+ .isInstanceOf(FalconSealSupport.ActivationConfigException.class);
+ }
+
+ // Now pull the guard out and watch every one of them go quiet.
+ PqAnchorConfig.useNameReaderForTesting(new BlindReader());
+ for (final String[] broken : brokenConfigurations) {
+ assertThatCode(PqAnchorConfig::fromSystemConfiguration)
+ .as("with the gate removed: %s=%s", broken[0], broken[1])
+ .doesNotThrowAnyException();
+ assertThat(PqAnchorConfig.fromSystemConfiguration().everActive())
+ .as("with the gate removed: %s=%s", broken[0], broken[1])
+ .isFalse();
+ }
+ }
+
+ /**
+ * NEGATIVE CONTROL 2, the sharper one. For every refusal above, the SAME configuration with only
+ * the one broken field corrected must start cleanly. Without this, a loader that refused
+ * absolutely everything would score full marks on the nine cases above.
+ */
+ @Test
+ public void negativeControl_correctingOnlyTheBrokenFieldMakesEachCaseStart() {
+ // field, the value that must refuse, the value that must start.
+ final String[][] pairs = {
+ {PqAnchorConfig.PROPERTY_ANCHOR_BLOCK, "", Long.toString(H)},
+ {PqAnchorConfig.PROPERTY_ANCHOR_BLOCK, "10_141_734", Long.toString(H)},
+ {PqAnchorConfig.PROPERTY_MIN_SEALS, H + ":3," + (H + 7200) + ":", H + ":3," + (H + 7200) + ":4"},
+ {PqAnchorConfig.PROPERTY_MIN_SEALS, H + ":3,," + (H + 7200) + ":4", H + ":3," + (H + 7200) + ":4"},
+ {PqAnchorConfig.PROPERTY_MIN_SEALS, (H * 10) + ":3", H + ":3," + (H * 10) + ":4"},
+ {PqAnchorConfig.PROPERTY_MIN_SEALS_CEILING, "-1", "2"},
+ {PqAnchorConfig.PROPERTY_MIN_SEALS_CEILING, "three", "2"},
+ {PqAnchorConfig.PROPERTY_CHAIN_ID, "0", "2800"},
+ {PqAnchorConfig.PROPERTY_DISABLE, "maybe", "false"}
+ };
+ for (final String[] pair : pairs) {
+ installReader();
+ armCorrectly();
+ set(pair[0], pair[1]);
+ assertThatThrownBy(PqAnchorConfig::fromSystemConfiguration)
+ .as("broken: %s=%s", pair[0], pair[1])
+ .isInstanceOf(FalconSealSupport.ActivationConfigException.class);
+
+ installReader();
+ armCorrectly();
+ set(pair[0], pair[2]);
+ final PqAnchorConfig config = PqAnchorConfig.fromSystemConfiguration();
+ assertThat(config.everActive()).as("corrected: %s=%s", pair[0], pair[2]).isTrue();
+ assertThat(config.anchorBlock()).isEqualTo(H);
+ }
+ }
+
+ /**
+ * POSITIVE CONTROL for the refusal message itself. The message is the whole product here: an
+ * operator at three in the morning gets one screen, and it has to name the field, the value read,
+ * the problem, the repair, and the sequencing rule that keeps a fleet restart from killing the
+ * chain.
+ *
+ * <p>The sequencing rule is asserted as a RULE, not as a count. Until 2026-08-29 this test pinned
+ * the literal phrase "At quorum 5 of 7 you lose the chain", which had been false since the set
+ * grew to nine on 2026-08-12: the message, and this test with it, carried the fleet of a world
+ * three weeks gone. A message that names today's set size is wrong on the day it changes, and the
+ * test that pins it makes the wrongness load-bearing.
+ */
+ @Test
+ public void theRefusalMessageCarriesEverythingAnOperatorNeedsAtThreeInTheMorning() {
+ set(PqAnchorConfig.PROPERTY_CHAIN_ID, "2800");
+ set(PqAnchorConfig.PROPERTY_ANCHOR_BLOCK, Long.toString(H));
+ set(PqAnchorConfig.PROPERTY_MIN_SEALS, H + ":3," + (H + 7200) + ":");
+
+ assertThatThrownBy(PqAnchorConfig::fromSystemConfiguration)
+ .isInstanceOf(FalconSealSupport.ActivationConfigException.class)
+ .hasMessageContaining(PqAnchorConfig.REFUSAL_CODE)
+ .hasMessageContaining("FIELD " + PqAnchorConfig.PROPERTY_MIN_SEALS)
+ .hasMessageContaining("SOURCE system property (BESU_OPTS)")
+ .hasMessageContaining("READ \"" + H + ":3," + (H + 7200) + ":\"")
+ .hasMessageContaining("PROBLEM step \"" + (H + 7200) + ":\" has no threshold after the ':'")
+ .hasMessageContaining("EXPECTED block:threshold,block:threshold")
+ .hasMessageContaining("a step exactly at " + H)
+ .hasMessageContaining("FIX correct BESU_OPTS on THIS node")
+ .hasMessageContaining("restart one at a time")
+ .hasMessageContaining("never in parallel")
+ .hasMessageContaining("more than f")
+ .hasMessageContaining("EMERGENCY " + PqAnchorConfig.PROPERTY_DISABLE + "=true");
+ }
+
+ /** And the origin is named honestly when the value came from the environment, not the command. */
+ @Test
+ public void theRefusalNamesTheEnvironmentWhenThatIsWhereTheValueCameFrom() {
+ setEnvironment(PqAnchorConfig.ENV_CHAIN_ID, "2800");
+ setEnvironment(PqAnchorConfig.ENV_ANCHOR_BLOCK, "not-a-number");
+ assertThatThrownBy(PqAnchorConfig::fromSystemConfiguration)
+ .hasMessageContaining("SOURCE environment variable " + PqAnchorConfig.ENV_ANCHOR_BLOCK);
+ }
+ // ---- D-336: the interval schedule -------------------------------------------------------------
+
+ private static PqAnchorConfig every32() {
+ return new PqAnchorConfig(2800L, 1000L, schedule(), OptionalInt.empty(), false)
+ .withAnchorInterval(OptionalInt.of(32));
+ }
+
+ @Test
+ public void aScheduledIntervalKeepsTheOldGridBelowTheHeightAndThinsItAbove() {
+ // 1384 = 1000 + 3 * 128: on the new grid AND an old-grid anchor (384 % 32 == 0)
+ final PqAnchorConfig c = every32().withAnchorIntervalSchedule(java.util.Map.of(1384L, 128));
+ assertThat(c.intervalAt(1383L)).isEqualTo(32);
+ assertThat(c.intervalAt(1384L)).isEqualTo(128);
+ assertThat(c.isAnchorHeight(1032L)).isTrue();
+ assertThat(c.isAnchorHeight(1048L)).isFalse();
+ assertThat(c.isAnchorHeight(1352L)).isTrue(); // last old-grid anchor before the change
+ assertThat(c.isAnchorHeight(1384L)).isTrue(); // the activation height is itself an anchor
+ assertThat(c.isAnchorHeight(1416L)).isFalse(); // 1384 + 32: no longer an anchor
+ assertThat(c.isAnchorHeight(1512L)).isTrue(); // 1384 + 128
+ // every anchor of the new regime was an anchor of the old one
+ for (long h = 1384L; h < 1384L + 128L * 20; h++) {
+ if (c.isAnchorHeight(h)) {
+ assertThat(every32().isAnchorHeight(h)).isTrue();
+ }
+ }
+ }
+
+ @Test
+ public void aScheduleHeightOffTheNewGridIsRefused() {
+ assertThatThrownBy(() -> every32().withAnchorIntervalSchedule(java.util.Map.of(1400L, 128)))
+ .isInstanceOf(IllegalArgumentException.class)
+ .hasMessageContaining("not on the new grid");
+ }
+
+ @Test
+ public void anIntervalThatIsNotAMultipleOfTheBaseIsRefused() {
+ assertThatThrownBy(() -> every32().withAnchorIntervalSchedule(java.util.Map.of(1400L, 100)))
+ .isInstanceOf(IllegalArgumentException.class)
+ .hasMessageContaining("not a positive multiple");
+ }
+
+ @Test
+ public void aScheduleWithoutABaseIntervalIsRefused() {
+ final PqAnchorConfig everyBlock = new PqAnchorConfig(2800L, 1000L, schedule(), OptionalInt.empty(), false);
+ assertThatThrownBy(() -> everyBlock.withAnchorIntervalSchedule(java.util.Map.of(1384L, 128)))
+ .isInstanceOf(IllegalArgumentException.class)
+ .hasMessageContaining("cannot create one");
+ }
+
+}
diff --git a/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqAnchorEmergencyConfigTest.java b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqAnchorEmergencyConfigTest.java
new file mode 100755
index 000000000..67fb25b76
--- /dev/null
+++ b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqAnchorEmergencyConfigTest.java
@@ -0,0 +1,120 @@
+/*
+ * Copyright contributors to Besu / AERE Network.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.common.bft;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+import java.util.Map;
+import java.util.OptionalInt;
+
+import org.junit.jupiter.api.Test;
+
+/**
+ * AERE OPTIUNI-URGENTA: the arithmetic the two anchor emergency controls stand on.
+ *
+ * <p>The property that matters is not "the ceiling works". It is that the ceiling can only ever go
+ * ONE WAY. A control an operator reaches for at three in the morning to restart a stalled chain must
+ * not be capable of stopping one, so a ceiling ABOVE the scheduled threshold has to be inert rather
+ * than raising it. That is asserted here in both directions, and the announcement predicate is
+ * asserted alongside it, because a shout that fires when the control is doing nothing trains people
+ * to ignore the log.
+ */
+class PqAnchorEmergencyConfigTest {
+
+ private static final long CHAIN_ID = 2800L;
+ private static final long H = 1_000L;
+
+ private PqAnchorConfig config(final OptionalInt ceiling, final boolean disabled) {
+ return new PqAnchorConfig(
+ CHAIN_ID, H, Map.of(H, 0, H + 100L, 3, H + 200L, 5), ceiling, disabled);
+ }
+
+ @Test
+ void ceilingLowersTheThreshold() {
+ final PqAnchorConfig capped = config(OptionalInt.of(1), false);
+ assertThat(capped.scheduledMinSealsAt(H + 250L)).isEqualTo(5);
+ assertThat(capped.minSealsAt(H + 250L)).isEqualTo(1);
+ }
+
+ @Test
+ void ceilingCanNeverRaiseTheThreshold() {
+ final PqAnchorConfig capped = config(OptionalInt.of(99), false);
+ // Scheduled 0, 3 and 5 at the three steps; a ceiling of 99 must change NONE of them.
+ assertThat(capped.minSealsAt(H)).isEqualTo(0);
+ assertThat(capped.minSealsAt(H + 100L)).isEqualTo(3);
+ assertThat(capped.minSealsAt(H + 250L)).isEqualTo(5);
+ assertThat(capped.minSealsAt(H + 250L)).isEqualTo(capped.scheduledMinSealsAt(H + 250L));
+ }
+
+ @Test
+ void ceilingOfZeroRemovesTheThresholdEntirely() {
+ final PqAnchorConfig capped = config(OptionalInt.of(0), false);
+ assertThat(capped.minSealsAt(H + 250L)).isZero();
+ }
+
+ @Test
+ void theAnnouncementFiresOnlyWhereTheCeilingActuallyLowersSomething() {
+ final PqAnchorConfig capped = config(OptionalInt.of(3), false);
+ // Below H nothing is active at all, so there is nothing to announce.
+ assertThat(capped.emergencyCeilingLowersAt(H - 1L)).isFalse();
+ // At H the schedule asks for 0; a ceiling of 3 is carrying no weight there.
+ assertThat(capped.emergencyCeilingLowersAt(H)).isFalse();
+ // At H+100 the schedule asks for exactly 3; still no weight.
+ assertThat(capped.emergencyCeilingLowersAt(H + 100L)).isFalse();
+ // At H+200 the schedule asks for 5 and the ceiling holds it at 3. THAT is worth a line.
+ assertThat(capped.emergencyCeilingLowersAt(H + 250L)).isTrue();
+ }
+
+ @Test
+ void noCeilingMeansNoAnnouncementAnywhere() {
+ final PqAnchorConfig plain = config(OptionalInt.empty(), false);
+ assertThat(plain.emergencyCeilingLowersAt(H + 250L)).isFalse();
+ assertThat(plain.minSealsCeiling()).isEmpty();
+ }
+
+ @Test
+ void disarmedIsNotTheSameStateAsNeverConfigured() {
+ final PqAnchorConfig disarmed = config(OptionalInt.empty(), true);
+ assertThat(disarmed.disabled()).isTrue();
+ assertThat(disarmed.anchorConfigured()).isTrue();
+ assertThat(disarmed.everActive()).isFalse();
+ assertThat(disarmed.activeAt(H + 500L)).isFalse();
+
+ final PqAnchorConfig never = PqAnchorConfig.never(CHAIN_ID);
+ assertThat(never.disabled()).isFalse();
+ assertThat(never.anchorConfigured()).isFalse();
+ assertThat(never.everActive()).isFalse();
+ }
+
+ @Test
+ void aDisarmedNodeStillEnforcesNothingEvenWhereTheScheduleIsHighest() {
+ final PqAnchorConfig disarmed = config(OptionalInt.empty(), true);
+ assertThat(disarmed.activeAt(H + 250L)).isFalse();
+ // The announcement predicate is gated on activeAt, so a disarmed node announces the DISARM and
+ // not, additionally, a ceiling that is no longer reachable.
+ assertThat(disarmed.emergencyCeilingLowersAt(H + 250L)).isFalse();
+ }
+
+ @Test
+ void aNegativeCeilingIsRefusedRatherThanClampedSilently() {
+ assertThatThrownBy(
+ () ->
+ new PqAnchorConfig(
+ CHAIN_ID, H, Map.of(H, 3), OptionalInt.of(-1), false))
+ .isInstanceOf(IllegalArgumentException.class)
+ .hasMessageContaining("must not be negative");
+ }
+}
diff --git a/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqAnchorIntervalTest.java b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqAnchorIntervalTest.java
new file mode 100755
index 000000000..d1cd9fdbb
--- /dev/null
+++ b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqAnchorIntervalTest.java
@@ -0,0 +1,184 @@
+/*
+ * AERE, 2026-08-07. The anchor interval: a certificate on every Nth block instead of every block.
+ *
+ * WHY THIS EXISTS. At ~523 ms per block we produce 165,248 blocks per day, 23 times more than
+ * Ethereum. A certificate in EVERY block costs 120.5 GB per year per node even with the cap at K=3.
+ * The fleet's disks are 38 and 75 GB, so the design does not fit anywhere.
+ *
+ * WHY IT IS SAFE, and this is the argument that has to hold, not the saving. Block hashes chain:
+ * block N+1 commits to the hash of N. So an anchor at height A, whose vanityData binds a Falcon
+ * certificate over A-1, protects EVERYTHING below A: rewriting any block below A changes the hash
+ * of A's parent, which requires A to be reproduced, which requires a Falcon quorum the adversary
+ * does not have. The only thing that stays rewritable is the TAIL since the last anchor. The
+ * property is therefore
+ *
+ * fork depth <= interval
+ *
+ * and it is a dial, not an accident. At 100 it means ~52 seconds of tail instead of ~0.5 seconds,
+ * and it costs one hundredth as much. Algorand ships the same shape at 1 in 256.
+ */
+package org.hyperledger.besu.consensus.common.bft;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+import java.util.Map;
+import java.util.OptionalInt;
+import org.junit.jupiter.api.Test;
+
+class PqAnchorIntervalTest {
+
+ private static final long H = 1000L;
+
+ private static PqAnchorConfig armed() {
+ return new PqAnchorConfig(2800L, H, Map.of(H, 3), OptionalInt.empty(), false);
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // 1. THE COMPATIBILITY BOUNDARY. Unset means every block, that is the design as it stood until
+ // today. If this ever breaks, a node built from the new code no longer agrees with an old one.
+ // ---------------------------------------------------------------------------------------------
+ @Test
+ void withNoIntervalEveryHeightIsAnAnchorHeight() {
+ final PqAnchorConfig cfg = armed();
+ assertThat(cfg.anchorInterval()).isEmpty();
+ for (final long n : new long[] {H, H + 1, H + 2, H + 99, H + 100, H + 12345}) {
+ assertThat(cfg.isAnchorHeight(n)).as("height %d", n).isTrue();
+ assertThat(cfg.anchorAppliesAt(n)).as("height %d", n).isTrue();
+ }
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // 2. An interval of 1 is the same thing written out explicitly, and must behave identically.
+ // ---------------------------------------------------------------------------------------------
+ @Test
+ void anIntervalOfOneIsTheSameAsNoInterval() {
+ final PqAnchorConfig cfg = armed().withAnchorInterval(OptionalInt.of(1));
+ for (final long n : new long[] {H, H + 1, H + 7, H + 1000}) {
+ assertThat(cfg.isAnchorHeight(n)).as("height %d", n).isTrue();
+ }
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // 3. THE HEART. Counting starts at H, not at zero. H is the only height the fleet coordinates on,
+ // and a scheme whose first anchor falls somewhere else is a scheme nobody checks by hand on
+ // activation day.
+ // ---------------------------------------------------------------------------------------------
+ @Test
+ void anchorHeightsAreCountedFromHAndHItselfIsAlwaysOne() {
+ final PqAnchorConfig cfg = armed().withAnchorInterval(OptionalInt.of(100));
+
+ assertThat(cfg.isAnchorHeight(H)).as("H itself").isTrue();
+ assertThat(cfg.isAnchorHeight(H + 100)).isTrue();
+ assertThat(cfg.isAnchorHeight(H + 200)).isTrue();
+ assertThat(cfg.isAnchorHeight(H + 100000)).isTrue();
+
+ for (final long off : new long[] {1, 2, 50, 99, 101, 199}) {
+ assertThat(cfg.isAnchorHeight(H + off)).as("H+%d is not an anchor", off).isFalse();
+ assertThat(cfg.anchorAppliesAt(H + off)).as("H+%d is not judged", off).isFalse();
+ }
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // 4. Below H there is no anchor, however neatly the arithmetic falls. Without this, a height
+ // below H that happens to be a multiple would be judged, and a new binary would no longer
+ // behave like an old one on the history from before activation.
+ // ---------------------------------------------------------------------------------------------
+ @Test
+ void belowHNothingIsAnAnchorHeightHoweverTheArithmeticFalls() {
+ final PqAnchorConfig cfg = armed().withAnchorInterval(OptionalInt.of(100));
+ for (final long n : new long[] {0L, 1L, H - 200, H - 100, H - 1}) {
+ assertThat(cfg.isAnchorHeight(n)).as("height %d", n).isFalse();
+ assertThat(cfg.anchorAppliesAt(n)).as("height %d", n).isFalse();
+ }
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // 5. NEGATIVE CONTROL. Zero and negative are refused. An interval of 0 would give a division by
+ // zero, and a negative one would make the modulo arithmetic answer nonsense.
+ // ---------------------------------------------------------------------------------------------
+ @Test
+ void zeroAndNegativeIntervalsAreRefused() {
+ for (final int bad : new int[] {0, -1, -100}) {
+ assertThatThrownBy(() -> armed().withAnchorInterval(OptionalInt.of(bad)))
+ .as("interval %d", bad)
+ .isInstanceOf(IllegalArgumentException.class)
+ .hasMessageContaining(PqAnchorConfig.PROPERTY_ANCHOR_INTERVAL)
+ .hasMessageContaining("at least 1");
+ }
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // 6. anchorAppliesAt is the AND of the two conditions, and the emergency disarm beats all of it.
+ // A disarm that let the anchor judge at the interval heights would not be a disarm.
+ // ---------------------------------------------------------------------------------------------
+ @Test
+ void theEmergencyDisarmBeatsTheIntervalEverywhere() {
+ final PqAnchorConfig dezarmat =
+ new PqAnchorConfig(2800L, H, Map.of(H, 3), OptionalInt.empty(), true)
+ .withAnchorInterval(OptionalInt.of(100));
+ assertThat(dezarmat.isAnchorHeight(H)).isTrue(); // the arithmetic says yes
+ assertThat(dezarmat.activeAt(H)).isFalse(); // but the scheme is switched off
+ assertThat(dezarmat.anchorAppliesAt(H)).isFalse(); // so nothing is judged
+ assertThat(dezarmat.anchorAppliesAt(H + 100)).isFalse();
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // 7. A node with no anchor at all has no anchor heights either. Without this, a configuration
+ // with no H but with an interval would answer "yes" to anything and would judge headers on a
+ // chain that was never activated.
+ // ---------------------------------------------------------------------------------------------
+ @Test
+ void aNodeWithNoAnchorAtAllHasNoAnchorHeights() {
+ final PqAnchorConfig never = PqAnchorConfig.never(2800L).withAnchorInterval(OptionalInt.of(100));
+ for (final long n : new long[] {0L, 1L, H, H + 100, Long.MAX_VALUE - 1}) {
+ assertThat(never.isAnchorHeight(n)).as("height %d", n).isFalse();
+ assertThat(never.anchorAppliesAt(n)).as("height %d", n).isFalse();
+ }
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // 8. THE TWO COST CONTROLS DO NOT LOSE EACH OTHER. This is the mistake I made a point of
+ // catching: a copy method that forgets a field is how the cap or the interval would silently
+ // disappear when the other one is set, and nobody would notice until the disk bill.
+ // ---------------------------------------------------------------------------------------------
+ @Test
+ void theTwoCostControlsDoNotLoseEachOther() {
+ final PqAnchorConfig amandoua =
+ armed().withMaxSealsCarried(OptionalInt.of(3)).withAnchorInterval(OptionalInt.of(100));
+ assertThat(amandoua.maxSealsCarried()).hasValue(3);
+ assertThat(amandoua.anchorInterval()).hasValue(100);
+
+ // and in the reverse order
+ final PqAnchorConfig invers =
+ armed().withAnchorInterval(OptionalInt.of(100)).withMaxSealsCarried(OptionalInt.of(3));
+ assertThat(invers.maxSealsCarried()).hasValue(3);
+ assertThat(invers.anchorInterval()).hasValue(100);
+
+ // and the rest of the configuration survives both of them
+ assertThat(invers.chainId()).isEqualTo(2800L);
+ assertThat(invers.anchorBlock()).isEqualTo(H);
+ assertThat(invers.minSealsAt(H)).isEqualTo(3);
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // 9. THE PROPERTY, written as a proof and not merely as a sentence in a comment: between two
+ // consecutive anchors there are exactly <interval> heights, of which exactly one is judged.
+ // That IS the maximum fork depth, and we count it instead of asserting it.
+ // ---------------------------------------------------------------------------------------------
+ @Test
+ void betweenTwoAnchorsExactlyOneHeightIsJudged() {
+ final int interval = 100;
+ final PqAnchorConfig cfg = armed().withAnchorInterval(OptionalInt.of(interval));
+ int judecate = 0;
+ for (long n = H; n < H + interval; n++) {
+ if (cfg.anchorAppliesAt(n)) {
+ judecate++;
+ }
+ }
+ assertThat(judecate)
+ .as("exactly one height judged every %d, so the rewritable tail is %d blocks",
+ interval, interval)
+ .isEqualTo(1);
+ }
+}
diff --git a/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqAnchorLapseTest.java b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqAnchorLapseTest.java
new file mode 100755
index 000000000..038d86287
--- /dev/null
+++ b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqAnchorLapseTest.java
@@ -0,0 +1,249 @@
+/*
+ * Copyright contributors to Besu / Aere Network.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.common.bft;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+import java.util.List;
+
+import org.junit.jupiter.api.Test;
+
+/**
+ * The named historical ranges in which the anchor rules were not fully in force.
+ *
+ * <p>The bounds are the whole content of the class under test, so they are asserted as LITERALS
+ * rather than through the constants they define. An assertion written as {@code
+ * assertThat(FIRST).isEqualTo(FIRST)} would follow any future edit of the constant and would
+ * therefore never fail, which is the exact shape of a gate that cannot go red.
+ */
+public class PqAnchorLapseTest {
+
+ private static final long LAST_ENFORCED_BEFORE = 13_267_792L;
+
+ private static final long DISARMED_FIRST = 13_267_824L;
+ private static final long DISARMED_LAST = 13_268_944L;
+
+ private static final long LOWERED_FIRST = 13_268_976L;
+ private static final long LOWERED_LAST = 13_890_544L;
+
+ private static final long FIRST_FULLY_ENFORCED_AFTER = 13_890_576L;
+
+ @Test
+ public void theListNamesExactlyTheTwoMeasuredRanges() {
+ // Measured by reading vanityData and the certificate at every anchor height from the activation
+ // height 13,014,000 to the head at the time of measurement, 14,077,000, one height at a time.
+ // The list is a LIST so a third could be added without touching a rule; it has two because the
+ // chain has two.
+ assertThat(PqAnchorLapse.windows()).hasSize(2);
+
+ final PqAnchorLapse.Window disarmed = PqAnchorLapse.windows().get(0);
+ assertThat(disarmed.firstBlock()).isEqualTo(13_267_824L);
+ assertThat(disarmed.lastBlock()).isEqualTo(13_268_944L);
+ assertThat(disarmed.anchorHeights()).isEqualTo(36L);
+ assertThat(disarmed.relaxation()).isEqualTo(PqAnchorLapse.Relaxation.EVERYTHING);
+ assertThat(disarmed.effectiveMinSeals()).isZero();
+ assertThat(disarmed.reason()).contains("2026-08-10");
+
+ final PqAnchorLapse.Window lowered = PqAnchorLapse.windows().get(1);
+ assertThat(lowered.firstBlock()).isEqualTo(13_268_976L);
+ assertThat(lowered.lastBlock()).isEqualTo(13_890_544L);
+ assertThat(lowered.anchorHeights()).isEqualTo(19_425L);
+ assertThat(lowered.relaxation()).isEqualTo(PqAnchorLapse.Relaxation.THRESHOLD_ONLY);
+ assertThat(lowered.effectiveMinSeals()).isEqualTo(1);
+ }
+
+ @Test
+ public void theTwoRangesAreAdjacentButDisjoint() {
+ // The second begins at the next anchor height after the first ends. They must not overlap, and
+ // there must be no unnamed anchor height between them, because a height in neither range is
+ // judged strictly and there is no such height here.
+ assertThat(DISARMED_LAST + PqAnchorLapse.ANCHOR_SPACING).isEqualTo(LOWERED_FIRST);
+ assertThat(PqAnchorLapse.windows().get(0).lastBlock())
+ .isLessThan(PqAnchorLapse.windows().get(1).firstBlock());
+ }
+
+ @Test
+ public void theStatedSpansAgreeWithTheBounds() {
+ // 36, not 37: (13,268,944 - 13,267,824) / 32 + 1 = 36. And 19,425 for the second range. The
+ // span is carried in each entry so the two cannot drift apart in silence; this asserts the
+ // arithmetic from the outside as well.
+ for (final PqAnchorLapse.Window window : PqAnchorLapse.windows()) {
+ assertThat((window.lastBlock() - window.firstBlock()) % PqAnchorLapse.ANCHOR_SPACING).isZero();
+ assertThat((window.lastBlock() - window.firstBlock()) / PqAnchorLapse.ANCHOR_SPACING + 1L)
+ .isEqualTo(window.anchorHeights());
+ }
+ }
+
+ // -----------------------------------------------------------------------------------------------
+ // isDisarmed: TRUE only in the first range, and deliberately FALSE in the second.
+ // -----------------------------------------------------------------------------------------------
+
+ @Test
+ public void isDisarmedIsTrueOnlyWhereNothingWasInForce() {
+ assertThat(PqAnchorLapse.isDisarmed(DISARMED_FIRST)).isTrue();
+ assertThat(PqAnchorLapse.isDisarmed(DISARMED_LAST)).isTrue();
+
+ // The neighbouring anchor heights, both measured to carry a digest, stay under the strict rules.
+ assertThat(PqAnchorLapse.isDisarmed(LAST_ENFORCED_BEFORE)).isFalse();
+ assertThat(PqAnchorLapse.isDisarmed(DISARMED_FIRST - 1L)).isFalse();
+ assertThat(PqAnchorLapse.isDisarmed(DISARMED_LAST + 1L)).isFalse();
+
+ // And FALSE across the whole second range: there the digest and the ordering did hold, and a
+ // relaxation that leaked into it would throw away the binding on 19,425 anchor heights.
+ assertThat(PqAnchorLapse.isDisarmed(LOWERED_FIRST)).isFalse();
+ assertThat(PqAnchorLapse.isDisarmed(13_500_016L)).isFalse();
+ assertThat(PqAnchorLapse.isDisarmed(LOWERED_LAST)).isFalse();
+ assertThat(PqAnchorLapse.isDisarmed(FIRST_FULLY_ENFORCED_AFTER)).isFalse();
+ }
+
+ @Test
+ public void everyAnchorHeightOfTheDisarmedRangeIsCovered() {
+ long covered = 0L;
+ for (long height = DISARMED_FIRST;
+ height <= DISARMED_LAST;
+ height += PqAnchorLapse.ANCHOR_SPACING) {
+ assertThat(PqAnchorLapse.isDisarmed(height))
+ .describedAs("anchor height %d of the disarmed range", height)
+ .isTrue();
+ covered++;
+ }
+ assertThat(covered).isEqualTo(36L);
+
+ // The rest of the chain is untouched.
+ assertThat(PqAnchorLapse.isDisarmed(0L)).isFalse();
+ assertThat(PqAnchorLapse.isDisarmed(13_014_000L)).isFalse();
+ assertThat(PqAnchorLapse.isDisarmed(13_000_000L)).isFalse();
+ assertThat(PqAnchorLapse.isDisarmed(14_077_000L)).isFalse();
+ assertThat(PqAnchorLapse.isDisarmed(Long.MAX_VALUE)).isFalse();
+ }
+
+ // -----------------------------------------------------------------------------------------------
+ // historicMinSeals: the threshold that was really in force, and only where it was lower.
+ // -----------------------------------------------------------------------------------------------
+
+ @Test
+ public void historicMinSealsAnswersOnlyInsideTheLoweredRange() {
+ assertThat(PqAnchorLapse.historicMinSeals(LOWERED_FIRST)).hasValue(1);
+ assertThat(PqAnchorLapse.historicMinSeals(13_500_016L)).hasValue(1);
+ assertThat(PqAnchorLapse.historicMinSeals(LOWERED_LAST)).hasValue(1);
+
+ // One anchor step past the end and the configured schedule applies again, unchanged. This is
+ // the assertion that stops the lowered threshold from becoming permanent.
+ assertThat(PqAnchorLapse.historicMinSeals(FIRST_FULLY_ENFORCED_AFTER)).isEmpty();
+ assertThat(PqAnchorLapse.historicMinSeals(LOWERED_LAST + 1L)).isEmpty();
+ assertThat(PqAnchorLapse.historicMinSeals(LOWERED_FIRST - 1L)).isEmpty();
+ assertThat(PqAnchorLapse.historicMinSeals(LAST_ENFORCED_BEFORE)).isEmpty();
+ assertThat(PqAnchorLapse.historicMinSeals(14_077_000L)).isEmpty();
+ assertThat(PqAnchorLapse.historicMinSeals(Long.MAX_VALUE)).isEmpty();
+
+ // And it does NOT answer inside the disarmed range: there the rules are skipped whole, so a
+ // threshold would be a second, contradictory way of saying the same thing.
+ assertThat(PqAnchorLapse.historicMinSeals(DISARMED_FIRST)).isEmpty();
+ assertThat(PqAnchorLapse.historicMinSeals(DISARMED_LAST)).isEmpty();
+ }
+
+ @Test
+ public void theFloorInsideTheLoweredRangeIsOneAndNotZero() {
+ // Measured: 2,926 of the 19,425 anchor heights in that range carry fewer seals than the
+ // schedule asks, the counts seen are 1 and 2, and NOT ONE carries zero. A floor of zero would
+ // therefore accept an empty certificate at a height where a certificate was in fact required,
+ // which is weaker than the history needs.
+ assertThat(PqAnchorLapse.historicMinSeals(LOWERED_FIRST)).hasValue(1);
+ assertThat(PqAnchorLapse.windows().get(1).effectiveMinSeals()).isPositive();
+ }
+
+ @Test
+ public void windowCoveringNamesTheRangeOrNothing() {
+ assertThat(PqAnchorLapse.windowCovering(DISARMED_FIRST)).isPresent();
+ assertThat(PqAnchorLapse.windowCovering(DISARMED_FIRST).get().lastBlock())
+ .isEqualTo(DISARMED_LAST);
+ assertThat(PqAnchorLapse.windowCovering(LOWERED_FIRST)).isPresent();
+ assertThat(PqAnchorLapse.windowCovering(LOWERED_FIRST).get().relaxation())
+ .isEqualTo(PqAnchorLapse.Relaxation.THRESHOLD_ONLY);
+ assertThat(PqAnchorLapse.windowCovering(FIRST_FULLY_ENFORCED_AFTER)).isEmpty();
+ assertThat(PqAnchorLapse.earliestAffectedBlock()).contains(DISARMED_FIRST);
+ }
+
+ @Test
+ public void theDisarmedRangeIsTheSameOBJECTTheOrderingExceptionUses() {
+ // A second copy of these bounds anywhere else is a value that diverges. PqAnchor used to carry
+ // them as its own literals; it now derives them, and this is the assertion that says so.
+ assertThat(PqAnchor.UNORDERED_WINDOW_FIRST).isEqualTo(DISARMED_FIRST);
+ assertThat(PqAnchor.UNORDERED_WINDOW_LAST).isEqualTo(DISARMED_LAST);
+ }
+
+ // -----------------------------------------------------------------------------------------------
+ // The self-checks can say no. A guard that has never refused anything cannot be believed.
+ // -----------------------------------------------------------------------------------------------
+
+ @Test
+ public void aRangeThatContradictsItselfIsRefusedRatherThanAccepted() {
+ assertThatThrownBy(
+ () ->
+ new PqAnchorLapse.Window(
+ 100L, 99L, 1L, PqAnchorLapse.Relaxation.EVERYTHING, 0, "backwards"))
+ .isInstanceOf(IllegalArgumentException.class)
+ .hasMessageContaining("non-empty range");
+ assertThatThrownBy(
+ () ->
+ new PqAnchorLapse.Window(
+ -1L, 100L, 1L, PqAnchorLapse.Relaxation.EVERYTHING, 0, "negative"))
+ .isInstanceOf(IllegalArgumentException.class);
+ assertThatThrownBy(
+ () ->
+ new PqAnchorLapse.Window(
+ 100L, 200L, 0L, PqAnchorLapse.Relaxation.EVERYTHING, 0, "no heights"))
+ .isInstanceOf(IllegalArgumentException.class)
+ .hasMessageContaining("at least one anchor height");
+ assertThatThrownBy(
+ () ->
+ new PqAnchorLapse.Window(
+ 100L, 200L, 4L, PqAnchorLapse.Relaxation.THRESHOLD_ONLY, -1, "negative floor"))
+ .isInstanceOf(IllegalArgumentException.class)
+ .hasMessageContaining("cannot be negative");
+ }
+
+ @Test
+ public void aRangeCoversItsOwnBoundsAndNothingOutsideThem() {
+ final PqAnchorLapse.Window window =
+ new PqAnchorLapse.Window(
+ 1_000L, 1_032L, 2L, PqAnchorLapse.Relaxation.THRESHOLD_ONLY, 1, "probe");
+ assertThat(window.covers(1_000L)).isTrue();
+ assertThat(window.covers(1_016L)).isTrue();
+ assertThat(window.covers(1_032L)).isTrue();
+ assertThat(window.covers(999L)).isFalse();
+ assertThat(window.covers(1_033L)).isFalse();
+ assertThat(window.toString()).contains("1000").contains("1032").contains("THRESHOLD_ONLY");
+ }
+
+ @Test
+ public void theListIsUnmodifiable() {
+ // A range a node could widen at runtime would let a future lapse pass unnoticed.
+ final List<PqAnchorLapse.Window> windows = PqAnchorLapse.windows();
+ assertThatThrownBy(
+ () ->
+ windows.add(
+ new PqAnchorLapse.Window(
+ 1L, 2L, 1L, PqAnchorLapse.Relaxation.EVERYTHING, 0, "injected")))
+ .isInstanceOf(UnsupportedOperationException.class);
+ }
+
+ @Test
+ public void theRangesBelongToThisChainAndAreDeclaredSo() {
+ assertThat(PqAnchorLapse.CHAIN_ID).isEqualTo(2800L);
+ assertThat(PqAnchorLapse.ANCHOR_SPACING).isEqualTo(32L);
+ }
+}
diff --git a/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqAnchorMinSealsFloorTest.java b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqAnchorMinSealsFloorTest.java
new file mode 100755
index 000000000..651c63ba3
--- /dev/null
+++ b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqAnchorMinSealsFloorTest.java
@@ -0,0 +1,152 @@
+/*
+ * AERE D-147, 2026-08-07. THE THRESHOLD FLOOR: a schedule whose effective K is zero everywhere
+ * leaves the anchor armed and completely toothless, forever, and every tool reports GREEN the whole
+ * time it is happening, because they all measure what was ASKED FOR and the request is valid.
+ *
+ * The loader already guarded this consequence in its own words, "K would be 0 at every height
+ * and an ARMED node would accept empty certificates", but only for a MISSING schedule. A schedule
+ * that is PRESENT and of the form "<H>:0" reaches the same state, and it used to pass.
+ *
+ * And it is not theoretical: PLAN-ACTIVARE recommends "<H>:0,<H+165000>:3", which STARTS at zero.
+ * If the second half is lost to a stray quote or a truncated variable, what remains is exactly the
+ * dangerous form.
+ */
+package org.hyperledger.besu.consensus.common.bft;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+import static org.assertj.core.api.Assertions.assertThatCode;
+
+import java.util.HashMap;
+import java.util.Map;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+class PqAnchorMinSealsFloorTest {
+
+ private static final long H = 13_793_219L;
+
+ private static final class Reader implements PqAnchorConfig.NameReader {
+ private final Map<String, String> properties = new HashMap<>();
+
+ @Override
+ public String property(final String name) {
+ return properties.get(name);
+ }
+
+ @Override
+ public String environment(final String name) {
+ return null;
+ }
+ }
+
+ private Reader reader;
+
+ @BeforeEach
+ void installReader() {
+ reader = new Reader();
+ PqAnchorConfig.useNameReaderForTesting(reader);
+ set(PqAnchorConfig.PROPERTY_CHAIN_ID, "2800");
+ set(PqAnchorConfig.PROPERTY_ANCHOR_BLOCK, Long.toString(H));
+ }
+
+ @AfterEach
+ void restoreReader() {
+ PqAnchorConfig.useNameReaderForTesting(null);
+ }
+
+ private void set(final String property, final String value) {
+ reader.properties.put(property, value);
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // 1. THE DEFECT ITSELF. A schedule that never demands anything is refused at startup.
+ // ---------------------------------------------------------------------------------------------
+ @Test
+ void anArmedAnchorWhoseScheduleNeverDemandsASignatureIsRefused() {
+ set(PqAnchorConfig.PROPERTY_MIN_SEALS, H + ":0");
+
+ assertThatThrownBy(PqAnchorConfig::fromSystemConfiguration)
+ .isInstanceOf(IllegalArgumentException.class)
+ .hasMessageContaining(PqAnchorConfig.REFUSAL_MIN_SEALS_FLOOR)
+ .hasMessageContaining("ZERO");
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // 2. Nor do several zero steps add up to anything. Whoever writes two zeros believes they have
+ // done something.
+ // ---------------------------------------------------------------------------------------------
+ @Test
+ void severalZeroStepsAreStillZero() {
+ set(PqAnchorConfig.PROPERTY_MIN_SEALS, H + ":0," + (H + 1000) + ":0," + (H + 2000) + ":0");
+
+ assertThatThrownBy(PqAnchorConfig::fromSystemConfiguration)
+ .isInstanceOf(IllegalArgumentException.class)
+ .hasMessageContaining(PqAnchorConfig.REFUSAL_MIN_SEALS_FLOOR);
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // 3. THE CONTROL THAT MATTERS MOST: the warm-up window stays LEGAL. A guard that also refused the
+ // form our own plan recommends would have been worked around within five minutes, and then we
+ // would have had neither the guard nor the window.
+ // ---------------------------------------------------------------------------------------------
+ @Test
+ void theWarmUpWindowRecommendedByOurOwnPlanStaysLegal() {
+ set(PqAnchorConfig.PROPERTY_MIN_SEALS, H + ":0," + (H + 165000) + ":3");
+
+ assertThatCode(PqAnchorConfig::fromSystemConfiguration).doesNotThrowAnyException();
+ final PqAnchorConfig config = PqAnchorConfig.fromSystemConfiguration();
+ assertThat(config.minSealsAt(H)).isZero();
+ assertThat(config.minSealsAt(H + 165000)).isEqualTo(3);
+ assertThat(config.highestEffectiveMinSeals()).isEqualTo(3);
+ }
+
+ @Test
+ void aScheduleThatDemandsFromTheStartIsFine() {
+ set(PqAnchorConfig.PROPERTY_MIN_SEALS, H + ":3");
+ assertThatCode(PqAnchorConfig::fromSystemConfiguration).doesNotThrowAnyException();
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // 4. THE SECOND ROAD TO THE SAME STATE, and it is the one that would have fooled me: an
+ // emergency ceiling of zero drops K to zero at every height, over a schedule that looks
+ // perfect. The floor looks at the EFFECTIVE K, after the ceiling, precisely to catch this too.
+ // ---------------------------------------------------------------------------------------------
+ @Test
+ void anEmergencyCeilingOfZeroReachesTheSameToothlessStateAndIsAlsoRefused() {
+ set(PqAnchorConfig.PROPERTY_MIN_SEALS, H + ":3");
+ set(PqAnchorConfig.PROPERTY_MIN_SEALS_CEILING, "0");
+
+ assertThatThrownBy(PqAnchorConfig::fromSystemConfiguration)
+ .isInstanceOf(IllegalArgumentException.class)
+ .hasMessageContaining(PqAnchorConfig.REFUSAL_MIN_SEALS_FLOOR)
+ .hasMessageContaining("emergency ceiling");
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // 5. THE BRAKE IS ABSOLUTE, and it stays absolute. The emergency disarm has to work when the
+ // chain is ALREADY stopped; a guard that refused to start a DISARMED node would be a brake
+ // that refuses to brake, which is exactly what our own comment says it must never be.
+ // ---------------------------------------------------------------------------------------------
+ @Test
+ void theEmergencyDisarmStillStartsWithAToothlessSchedule() {
+ set(PqAnchorConfig.PROPERTY_MIN_SEALS, H + ":0");
+ set(PqAnchorConfig.PROPERTY_DISABLE, "true");
+
+ assertThatCode(PqAnchorConfig::fromSystemConfiguration).doesNotThrowAnyException();
+ assertThat(PqAnchorConfig.fromSystemConfiguration().activeAt(H)).isFalse();
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // 6. A node with no anchor at all has no floor to violate. Without this, the guard would stop
+ // every node in the fleet that has not been configured yet, which is most of them, from
+ // starting on activation day.
+ // ---------------------------------------------------------------------------------------------
+ @Test
+ void aNodeWithNoAnchorConfiguredIsUntouched() {
+ PqAnchorConfig.useNameReaderForTesting(new Reader());
+ assertThatCode(PqAnchorConfig::fromSystemConfiguration).doesNotThrowAnyException();
+ assertThat(PqAnchorConfig.fromSystemConfiguration().everActive()).isFalse();
+ }
+}
diff --git a/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqAnchorProducerCacheHygieneTest.java b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqAnchorProducerCacheHygieneTest.java
new file mode 100644
index 000000000..7230f1eff
--- /dev/null
+++ b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqAnchorProducerCacheHygieneTest.java
@@ -0,0 +1,104 @@
+/*
+ * Copyright contributors to Aere Network.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.common.bft;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import org.hyperledger.besu.consensus.common.bft.blockcreation.PqAnchorProducer;
+
+import java.lang.reflect.Field;
+import java.nio.file.Path;
+
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+
+/**
+ * DATED 2026-08-20. The reproduction that keeps the per-JVM anchor-config cache honest.
+ *
+ * <p>THE LEAK, paid for twice. {@code PqAnchorProducer.config()} memoizes the first configuration
+ * it builds, and that memo outlives every {@code System.clearProperty} a test class runs in its
+ * teardown. A class that arms the anchor through system properties and then builds {@code
+ * FalconSealSupport} caches an ARMED config for whichever class runs next in the same JVM. Measured
+ * 2026-08-11: {@code PqForkThresholdReachabilityTest} left exactly this behind and four
+ * PqStartupHistoryTest tests failed on a guard firing correctly; that class got the cleanup line.
+ * Measured 2026-08-20 on the production tree: its fork, {@code D078ThresholdReachabilityTest},
+ * never received the same line, and all five {@code PqFleetRestartArmingTest} fixtures turned into
+ * AERE-PQC-REG-ARM-02 refusals -- green alone, red in the full suite, identical sources.
+ *
+ * <p>WHY THIS TEST IS SHAPED LIKE THIS. Class-order contamination is nondeterministic under
+ * gradle's fork assignment, so the reproduction does not rely on ordering at all: it runs the
+ * guilty class's OWN lifecycle (setUp, the arming test, tearDown) inside one test method, and then
+ * asserts the JVM is clean. If the cleanup line is ever removed from that teardown again, this
+ * test goes red deterministically -- that removal is exactly the planted failure it was proven
+ * against on the day it was written.
+ *
+ * <p>DATED 2026-08-31: the fork pair was consolidated -- the twin classes were one copy too many,
+ * and the divergence above is precisely what duplication costs. The reproduction now runs the
+ * lifecycle of the surviving class, {@code PqForkThresholdReachabilityTest}, which has carried the
+ * cleanup line since 2026-08-11; the assertion is unchanged.
+ */
+public class PqAnchorProducerCacheHygieneTest {
+
+ @TempDir private Path tmp;
+
+ @BeforeEach
+ public void curatInainte() throws Exception {
+ curata();
+ }
+
+ @AfterEach
+ public void curatDupa() throws Exception {
+ curata();
+ }
+
+ private static void curata() throws Exception {
+ for (final String p : System.getProperties().stringPropertyNames()) {
+ if (p.startsWith("aere.")) {
+ System.clearProperty(p);
+ }
+ }
+ PqAnchorProducer.useConfigForTesting(null);
+ final Field f = FalconSealSupport.class.getDeclaredField("instance");
+ f.setAccessible(true);
+ f.set(null, null);
+ }
+
+ @Test
+ public void theReachabilitySequenceLeavesNoArmedAnchorBehind() throws Exception {
+ final PqForkThresholdReachabilityTest vinovat = new PqForkThresholdReachabilityTest();
+ final Field tmpField = PqForkThresholdReachabilityTest.class.getDeclaredField("tmp");
+ tmpField.setAccessible(true);
+ tmpField.set(vinovat, tmp);
+
+ vinovat.setUp();
+ try {
+ // The exact sequence that poisons: anchor armed from properties, FalconSealSupport built.
+ vinovat.aReachableThresholdMustStillStart();
+ } finally {
+ // The guilty class's OWN teardown. The assertion below is about what IT leaves behind.
+ vinovat.tearDown();
+ }
+
+ assertThat(PqAnchorProducer.config().everActive())
+ .describedAs(
+ "after PqForkThresholdReachabilityTest's own teardown, a config built in this JVM must "
+ + "not claim an armed anchor; if it does, the per-JVM cache survived the cleanup "
+ + "and every proof-less fixture in the next class dies with AERE-PQC-REG-ARM-02")
+ .isFalse();
+ }
+}
diff --git a/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqAnchorProducerCostTest.java b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqAnchorProducerCostTest.java
new file mode 100755
index 000000000..d33767483
--- /dev/null
+++ b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqAnchorProducerCostTest.java
@@ -0,0 +1,250 @@
+/*
+ * AERE, 2026-08-07. THE TWO COST CONTROLS, measured on the PRODUCER, not on the configuration.
+ *
+ * WHY THIS EXISTS. On 7 August `aere.pq.anchor.maxSeals` and `aere.pq.anchorInterval` were built,
+ * and their configuration guards were proven the same day. But the cut in the producer, the code
+ * that ACTUALLY stops seals being written past the cap, and that ACTUALLY skips the heights with no
+ * anchor, stayed an ASSERTION: there was no producer harness in the tree, and D-148 had just shown
+ * what a piece of code that no proof touches costs.
+ *
+ * This class touches it. It counts the seals written, it does not assume them.
+ *
+ * THE NEGATIVE CONTROL IS INSIDE, and it is exactly the pair: the same seven seals heard, the same
+ * proposer, the same inputs, one single difference, the cap set or not. Without the half with no
+ * cap, a proof counting 3 would have passed even if the producer had heard only 3.
+ */
+package org.hyperledger.besu.consensus.common.bft;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+import static org.mockito.Mockito.withSettings;
+
+import java.io.IOException;
+import java.lang.reflect.Field;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.Collections;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.OptionalInt;
+import org.apache.tuweni.bytes.Bytes;
+import org.apache.tuweni.bytes.Bytes32;
+import org.bouncycastle.crypto.digests.KeccakDigest;
+import org.bouncycastle.pqc.crypto.falcon.FalconPrivateKeyParameters;
+import org.bouncycastle.pqc.crypto.falcon.FalconSigner;
+import org.hyperledger.besu.consensus.common.bft.blockcreation.PqAnchorProducer;
+import org.hyperledger.besu.consensus.common.validator.ValidatorProvider;
+import org.hyperledger.besu.datatypes.Address;
+import org.hyperledger.besu.ethereum.ProtocolContext;
+import org.hyperledger.besu.ethereum.core.BlockHeader;
+import org.hyperledger.besu.ethereum.core.BlockHeaderTestFixture;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+import org.mockito.quality.Strictness;
+
+class PqAnchorProducerCostTest {
+
+ private static final long CHAIN_ID = 220_879L;
+ private static final long H = 1_000L;
+ private static final long ATTACH = 900L;
+ private static final int N = 7;
+
+ @TempDir private Path tmp;
+
+ private final List<FalconPrivateKeyParameters> privateKeys = new ArrayList<>();
+ private final List<Address> validators = new ArrayList<>();
+
+ @BeforeEach
+ void setUp() throws Exception {
+ final KeccakDigest kd = new KeccakDigest(256);
+ final StringBuilder manifest = new StringBuilder();
+ manifest
+ .append("{\"config\":{\"aereFalconRegistry\":{")
+ .append(PqV2Fixture.manifestHeader(N, CHAIN_ID, H));
+ for (int i = 0; i < N; i++) {
+ privateKeys.add(PqV2Fixture.privateKey(i));
+ validators.add(PqV2Fixture.address(i));
+ final byte[] row = PqV2Fixture.anchorPreimageRow(i);
+ kd.update(row, 0, row.length);
+ manifest.append(',').append(PqV2Fixture.manifestEntry(i, N, CHAIN_ID, H));
+ }
+ manifest.append("}},\"alloc\":{\"0000000000000000000000000000000000000fa1\":{\"storage\":{\"0x")
+ .append("0".repeat(64))
+ .append("\":\"0x");
+ final byte[] anchoredHash = new byte[32];
+ kd.doFinal(anchoredHash, 0);
+ manifest.append(Bytes.wrap(anchoredHash).toUnprefixedHexString()).append("\"}}}}");
+
+ final Path genesis = tmp.resolve("genesis-registry.json");
+ Files.writeString(genesis, manifest.toString());
+ System.setProperty("aere.falcon.genesis", genesis.toAbsolutePath().toString());
+ System.setProperty("aere.falcon.attachBlock", Long.toString(ATTACH));
+
+ resetFalconSingleton();
+ PqSealCache.instance().clear();
+ }
+
+ @AfterEach
+ void tearDown() throws Exception {
+ System.clearProperty("aere.falcon.genesis");
+ System.clearProperty("aere.falcon.attachBlock");
+ resetFalconSingleton();
+ PqSealCache.instance().clear();
+ PqAnchorProducer.useConfigForTesting(null);
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // THE CAP, measured in both directions on the same seven seals heard.
+ // ---------------------------------------------------------------------------------------------
+
+ @Test
+ void withNoCapTheProposerWritesEverySealItHeard() {
+ PqAnchorProducer.useConfigForTesting(armedConfig(OptionalInt.empty(), OptionalInt.empty()));
+ final BlockHeader parent = parentOf(H + 10L);
+ hearAllSevenSealsFor(parent);
+
+ final BftExtraData produced = PqAnchorProducer.apply(base(), parent, contextWith(validators));
+
+ assertThat(produced.getFalconSeals())
+ .describedAs(
+ "K is a FLOOR: with no cap the proposer writes everything it heard, that is seven, not "
+ + "three. This half is what makes the number in the other half mean anything")
+ .hasSize(N);
+ }
+
+ @Test
+ void withTheCapAtThreeTheProposerWritesExactlyThree() {
+ PqAnchorProducer.useConfigForTesting(armedConfig(OptionalInt.of(3), OptionalInt.empty()));
+ final BlockHeader parent = parentOf(H + 10L);
+ hearAllSevenSealsFor(parent);
+
+ final BftExtraData produced = PqAnchorProducer.apply(base(), parent, contextWith(validators));
+
+ assertThat(produced.getFalconSeals())
+ .describedAs("the same seven seals heard, the only difference is the cap")
+ .hasSize(3);
+ }
+
+ /**
+ * A cap larger than what was heard does not invent seals. Without this, a badly chosen cap could
+ * look like it "works" merely because the number asked for happens to equal the number heard.
+ */
+ @Test
+ void aCapAboveWhatWasHeardChangesNothing() {
+ PqAnchorProducer.useConfigForTesting(armedConfig(OptionalInt.of(20), OptionalInt.empty()));
+ final BlockHeader parent = parentOf(H + 10L);
+ hearAllSevenSealsFor(parent);
+
+ assertThat(PqAnchorProducer.apply(base(), parent, contextWith(validators)).getFalconSeals())
+ .hasSize(N);
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // THE INTERVAL, also in both directions, and also on the same seals heard.
+ // ---------------------------------------------------------------------------------------------
+
+ @Test
+ void atAnAnchorHeightTheProposerWritesACertificate() {
+ PqAnchorProducer.useConfigForTesting(armedConfig(OptionalInt.of(3), OptionalInt.of(100)));
+ // the parent is H-1, so the block being built is H itself, and H is always an anchor height
+ final BlockHeader parent = parentOf(H - 1L);
+ hearAllSevenSealsFor(parent);
+
+ assertThat(PqAnchorProducer.apply(base(), parent, contextWith(validators)).getFalconSeals())
+ .describedAs("H itself is always an anchor height, whatever the interval is")
+ .hasSize(3);
+ }
+
+ @Test
+ void betweenAnchorsTheProposerWritesNothingEvenThoughItHeardEverything() {
+ PqAnchorProducer.useConfigForTesting(armedConfig(OptionalInt.of(3), OptionalInt.of(100)));
+ // the parent is H, so the block built is H+1, which is NOT an anchor height at interval 100
+ final BlockHeader parent = parentOf(H);
+ hearAllSevenSealsFor(parent);
+
+ final BftExtraData produced = PqAnchorProducer.apply(base(), parent, contextWith(validators));
+
+ assertThat(produced.getFalconSeals())
+ .describedAs(
+ "seven seals heard and none written, because this height carries no certificate. "
+ + "This is where the hundredfold saving comes from")
+ .isEmpty();
+ assertThat(produced.getVanityData())
+ .describedAs("and the digest is not placed where there is nothing to bind")
+ .isEqualTo(Bytes32.ZERO);
+ }
+
+ /**
+ * With no interval, the SAME height does carry a certificate. This is the pair of the proof
+ * above.
+ */
+ @Test
+ void thatSameHeightDoesCarryACertificateWhenThereIsNoInterval() {
+ PqAnchorProducer.useConfigForTesting(armedConfig(OptionalInt.of(3), OptionalInt.empty()));
+ final BlockHeader parent = parentOf(H);
+ hearAllSevenSealsFor(parent);
+
+ assertThat(PqAnchorProducer.apply(base(), parent, contextWith(validators)).getFalconSeals())
+ .describedAs("the only difference from the proof before is the interval")
+ .hasSize(3);
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // Helpers.
+ // ---------------------------------------------------------------------------------------------
+
+ private static PqAnchorConfig armedConfig(final OptionalInt cap, final OptionalInt interval) {
+ return new PqAnchorConfig(
+ CHAIN_ID, H, Map.of(H, 3), OptionalInt.empty(), false, cap, interval);
+ }
+
+ private static BlockHeader parentOf(final long number) {
+ return new BlockHeaderTestFixture().number(number).buildHeader();
+ }
+
+ private BftExtraData base() {
+ return new BftExtraData(
+ Bytes32.ZERO, Collections.emptyList(), Optional.empty(), 0, validators, Collections.emptyList());
+ }
+
+ private void hearAllSevenSealsFor(final BlockHeader parent) {
+ final Bytes32 m =
+ PqAnchor.commitMessage(CHAIN_ID, parent.getNumber(), parent.getHash().getBytes());
+ final List<FalconSeal> heard = new ArrayList<>();
+ for (int i = 0; i < N; i++) {
+ heard.add(new FalconSeal(i, Bytes.wrap(falconSign(privateKeys.get(i), m))));
+ }
+ PqSealCache.instance().record(parent.getNumber(), parent.getHash(), heard);
+ }
+
+ private static byte[] falconSign(final FalconPrivateKeyParameters key, final Bytes32 m) {
+ final FalconSigner signer = new FalconSigner();
+ signer.init(true, key);
+ return signer.generateSignature(m.toArray());
+ }
+
+ private static ProtocolContext contextWith(final Collection<Address> vs) {
+ final ValidatorProvider validatorProvider =
+ mock(ValidatorProvider.class, withSettings().strictness(Strictness.LENIENT));
+ when(validatorProvider.getValidatorsForBlock(any())).thenReturn(vs);
+ when(validatorProvider.getValidatorsAfterBlock(any())).thenReturn(vs);
+ final BftContext bftContext =
+ mock(BftContext.class, withSettings().strictness(Strictness.LENIENT));
+ when(bftContext.getValidatorProvider()).thenReturn(validatorProvider);
+ when(bftContext.as(any())).thenReturn(bftContext);
+ return new ProtocolContext.Builder().withConsensusContext(bftContext).build();
+ }
+
+ private static void resetFalconSingleton() throws Exception {
+ final Field f = FalconSealSupport.class.getDeclaredField("instance");
+ f.setAccessible(true);
+ f.set(null, null);
+ }
+}
diff --git a/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqAnchorSealCapTest.java b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqAnchorSealCapTest.java
new file mode 100755
index 000000000..c9bfd2ef1
--- /dev/null
+++ b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqAnchorSealCapTest.java
@@ -0,0 +1,150 @@
+/*
+ * AERE, 2026-08-07. The PROPOSER-side seal cap, and its fail-closed guard.
+ *
+ * WHY IT EXISTS. K is a FLOOR, not a cap. Measured on a live ten-node run with the threshold at 4:
+ * 42 blocks carried 4 seals, 36 carried 5, 5 carried 6. The proposer writes every seal it heard and
+ * that is eligible, not as many as the threshold demands. At 666 bytes a seal, that means 200.9 GB
+ * per node per year instead of 120.5, and the surplus buys nothing: what a verifier demands is THE
+ * THRESHOLD.
+ *
+ * WHAT THIS FILE GUARDS, and this is the dangerous part: a cap set BELOW the highest K in the
+ * schedule makes the proposer write certificates its own fleet rejects, at every height from the
+ * step that raises K above the cap onwards. The failure is SILENT to every existing tool, because
+ * each one measures what was ASKED FOR and the request is consistent with itself. That is why the
+ * node refuses to start.
+ */
+package org.hyperledger.besu.consensus.common.bft;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+import java.util.Map;
+import java.util.OptionalInt;
+import org.junit.jupiter.api.Test;
+
+class PqAnchorSealCapTest {
+
+ private static PqAnchorConfig armed(final Map<Long, Integer> schedule, final OptionalInt ceiling) {
+ return new PqAnchorConfig(2800L, 100L, schedule, ceiling, false);
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // 1. No cap means exactly what every node did before today. This is the compatibility boundary,
+ // and it is the first thing to break if anyone ever gives the property a default value.
+ // ---------------------------------------------------------------------------------------------
+ @Test
+ void withNoCapConfiguredTheProposerIsUncapped() {
+ final PqAnchorConfig cfg = armed(Map.of(100L, 3), OptionalInt.empty());
+ assertThat(cfg.maxSealsCarried()).isEmpty();
+ assertThat(cfg.maxSealsCarried().orElse(Integer.MAX_VALUE)).isEqualTo(Integer.MAX_VALUE);
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // 2. THE NEGATIVE CONTROL. A cap below the highest K in the schedule must REFUSE, and the message
+ // must name both numbers, otherwise whoever reads it at 3 in the morning does not know what to
+ // change.
+ // ---------------------------------------------------------------------------------------------
+ @Test
+ void aCapBelowTheHighestScheduledThresholdIsRefused() {
+ final PqAnchorConfig cfg = armed(Map.of(100L, 1, 200L, 3, 300L, 5), OptionalInt.empty());
+ assertThat(cfg.highestEffectiveMinSeals()).isEqualTo(5);
+
+ assertThatThrownBy(() -> cfg.withMaxSealsCarried(OptionalInt.of(4)))
+ .isInstanceOf(IllegalArgumentException.class)
+ .hasMessageContaining(PqAnchorConfig.REFUSAL_CODE)
+ .hasMessageContaining(PqAnchorConfig.PROPERTY_MAX_SEALS)
+ .hasMessageContaining("=4")
+ .hasMessageContaining("K=5");
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // 3. And the refusal looks at the WHOLE schedule, not just the step at the arming height. A cap
+ // chosen from the first step is exactly the mistake I expect: our schedule STARTS at a low K.
+ // ---------------------------------------------------------------------------------------------
+ @Test
+ void theRefusalLooksAtTheWholeScheduleNotJustTheFirstStep() {
+ // exactly the shape the activation plan recommends: starts at 0, climbs to 3
+ final PqAnchorConfig cfg = armed(Map.of(100L, 0, 265L, 3), OptionalInt.empty());
+ assertThat(cfg.minSealsAt(100L)).isZero();
+ assertThat(cfg.highestEffectiveMinSeals()).isEqualTo(3);
+
+ // a cap of 1 "looks" right if you only look at the first step
+ assertThatThrownBy(() -> cfg.withMaxSealsCarried(OptionalInt.of(1)))
+ .isInstanceOf(IllegalArgumentException.class)
+ .hasMessageContaining("K=3");
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // 4. A cap exactly at K is the value we want in production, and it has to be accepted.
+ // ---------------------------------------------------------------------------------------------
+ @Test
+ void aCapEqualToTheHighestThresholdIsAccepted() {
+ final PqAnchorConfig cfg =
+ armed(Map.of(100L, 0, 265L, 3), OptionalInt.empty()).withMaxSealsCarried(OptionalInt.of(3));
+ assertThat(cfg.maxSealsCarried()).hasValue(3);
+ assertThat(cfg.minSealsAt(265L)).isEqualTo(3);
+ assertThat(cfg.anchorBlock()).isEqualTo(100L);
+ assertThat(cfg.chainId()).isEqualTo(2800L);
+ }
+
+ @Test
+ void aCapAboveTheHighestThresholdIsAccepted() {
+ final PqAnchorConfig cfg =
+ armed(Map.of(100L, 3), OptionalInt.empty()).withMaxSealsCarried(OptionalInt.of(7));
+ assertThat(cfg.maxSealsCarried()).hasValue(7);
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // 5. Zero is not a cap, it is a stop. An empty certificate is a state only the SCHEDULE may ask
+ // for, through K=0, and only inside the warm-up window.
+ // ---------------------------------------------------------------------------------------------
+ @Test
+ void aCapOfZeroIsRefusedOutright() {
+ assertThatThrownBy(
+ () -> new PqAnchorConfig(2800L, 100L, Map.of(100L, 0), OptionalInt.empty(), false, OptionalInt.of(0)))
+ .isInstanceOf(IllegalArgumentException.class)
+ .hasMessageContaining(PqAnchorConfig.PROPERTY_MAX_SEALS)
+ .hasMessageContaining("at least 1");
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // 6. The emergency ceiling LOWERS K, so it also lowers the threshold the cost cap has to reach.
+ // The two cannot end up arguing with each other.
+ // ---------------------------------------------------------------------------------------------
+ @Test
+ void theEmergencyCeilingLowersWhatTheCostCapMustReach() {
+ final Map<Long, Integer> schedule = Map.of(100L, 3, 200L, 5);
+ assertThat(armed(schedule, OptionalInt.empty()).highestEffectiveMinSeals()).isEqualTo(5);
+ // with the emergency ceiling at 2, the effective K never goes above 2
+ final PqAnchorConfig braked = armed(schedule, OptionalInt.of(2));
+ assertThat(braked.highestEffectiveMinSeals()).isEqualTo(2);
+ // so a cost cap of 2 becomes legal, even though the schedule says 5
+ assertThat(braked.withMaxSealsCarried(OptionalInt.of(2)).maxSealsCarried()).hasValue(2);
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // 7. An empty schedule demands nothing, so any positive cap is legal.
+ // ---------------------------------------------------------------------------------------------
+ @Test
+ void anEmptyScheduleDemandsNothing() {
+ final PqAnchorConfig cfg = armed(Map.of(), OptionalInt.empty());
+ assertThat(cfg.highestEffectiveMinSeals()).isZero();
+ assertThat(cfg.withMaxSealsCarried(OptionalInt.of(1)).maxSealsCarried()).hasValue(1);
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // 8. The rest of the configuration survives the copy. A method that drops a field on the way is
+ // how an emergency disarm would vanish in silence the moment the cap is set.
+ // ---------------------------------------------------------------------------------------------
+ @Test
+ void everyOtherFieldSurvivesTheCopy() {
+ final PqAnchorConfig cfg =
+ new PqAnchorConfig(2800L, 100L, Map.of(100L, 3), OptionalInt.of(3), true)
+ .withMaxSealsCarried(OptionalInt.of(3));
+ assertThat(cfg.chainId()).isEqualTo(2800L);
+ assertThat(cfg.anchorBlock()).isEqualTo(100L);
+ assertThat(cfg.minSealsCeiling()).hasValue(3);
+ assertThat(cfg.activeAt(100L)).isFalse(); // disarmed, and it stayed disarmed
+ assertThat(cfg.maxSealsCarried()).hasValue(3);
+ }
+}
diff --git a/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqAnchorTest.java b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqAnchorTest.java
new file mode 100755
index 000000000..5bea4d37e
--- /dev/null
+++ b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqAnchorTest.java
@@ -0,0 +1,301 @@
+/*
+ * Copyright contributors to Besu / AERE Network.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.common.bft;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+import java.nio.charset.StandardCharsets;
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.List;
+
+import org.apache.tuweni.bytes.Bytes;
+import org.apache.tuweni.bytes.Bytes32;
+import org.junit.jupiter.api.Test;
+
+/** Vectors and invariants for the V2 certificate anchor pre-images. */
+public class PqAnchorTest {
+
+ private static final long CHAIN_ID = 2800L;
+ private static final Bytes32 PARENT_HASH =
+ Bytes32.fromHexString("0x1111111111111111111111111111111111111111111111111111111111111111");
+ private static final Bytes32 OTHER_HASH =
+ Bytes32.fromHexString("0x2222222222222222222222222222222222222222222222222222222222222222");
+
+ /**
+ * A deterministic stand-in for a Falcon-512 signature. Real ones measure 648 to 660 bytes; the
+ * anchor pre-image treats them as opaque length-prefixed byte strings, so the exact length only
+ * has to be representative.
+ */
+ static Bytes signatureFor(final int index, final int variant) {
+ final byte[] bytes = new byte[655];
+ for (int i = 0; i < bytes.length; i++) {
+ bytes[i] = (byte) ((i * 31 + index * 7 + variant * 101) & 0xFF);
+ }
+ return Bytes.wrap(bytes);
+ }
+
+ static FalconSeal seal(final int index) {
+ return new FalconSeal(index, signatureFor(index, 0));
+ }
+
+ @Test
+ public void domainLabelsAreExactlySixteenAsciiBytes() {
+ assertThat(PqAnchor.ANCHOR_DOMAIN.getBytes(StandardCharsets.US_ASCII)).hasSize(16);
+ assertThat(PqAnchor.COMMIT_DOMAIN.getBytes(StandardCharsets.US_ASCII)).hasSize(16);
+ assertThat(PqAnchor.ANCHOR_DOMAIN_BYTES.size()).isEqualTo(16);
+ assertThat(PqAnchor.COMMIT_DOMAIN_BYTES.size()).isEqualTo(16);
+ assertThat(PqAnchor.ANCHOR_DOMAIN).isNotEqualTo(PqAnchor.COMMIT_DOMAIN);
+ }
+
+ @Test
+ public void anchorDigestIsThirtyTwoBytesAndDeterministic() {
+ final List<FalconSeal> certificate = Arrays.asList(seal(0), seal(1), seal(2));
+ final Bytes32 first = PqAnchor.anchorDigest(CHAIN_ID, 10L, PARENT_HASH, certificate);
+ final Bytes32 second = PqAnchor.anchorDigest(CHAIN_ID, 10L, PARENT_HASH, certificate);
+ assertThat(first.size()).isEqualTo(32);
+ assertThat(first).isEqualTo(second);
+ }
+
+ @Test
+ public void anchorDigestChangesWithEveryFieldOfItsPreImage() {
+ final List<FalconSeal> certificate = Arrays.asList(seal(0), seal(1), seal(2));
+ final Bytes32 base = PqAnchor.anchorDigest(CHAIN_ID, 10L, PARENT_HASH, certificate);
+
+ // chainId: this is what stops a certificate produced on the 442807 proving chain, which runs the
+ // same binaries and may run the same Falcon keys, from being material here.
+ assertThat(PqAnchor.anchorDigest(442807L, 10L, PARENT_HASH, certificate)).isNotEqualTo(base);
+ // parent height and parent hash: replay at another height or on another branch.
+ assertThat(PqAnchor.anchorDigest(CHAIN_ID, 11L, PARENT_HASH, certificate)).isNotEqualTo(base);
+ assertThat(PqAnchor.anchorDigest(CHAIN_ID, 10L, OTHER_HASH, certificate)).isNotEqualTo(base);
+ }
+
+ @Test
+ public void anchorDigestDetectsAStrippedCertificate() {
+ // Attack A1: remove element 6 entirely. The canonical round-trip gate cannot see this, because
+ // truncated bytes re-encode to themselves. The digest can.
+ final List<FalconSeal> certificate = Arrays.asList(seal(0), seal(1), seal(2));
+ assertThat(PqAnchor.anchorDigest(CHAIN_ID, 10L, PARENT_HASH, Collections.emptyList()))
+ .isNotEqualTo(PqAnchor.anchorDigest(CHAIN_ID, 10L, PARENT_HASH, certificate));
+ }
+
+ @Test
+ public void anchorDigestDetectsAnEquallyValidDifferentSubset() {
+ // Attack A2: swap quorum subset {0,1,2,3} for {0,1,2,4}, both authentic over the same parent.
+ // The block hash does not change, because the certificate is outside its pre-image. D does.
+ final List<FalconSeal> subsetA = Arrays.asList(seal(0), seal(1), seal(2), seal(3));
+ final List<FalconSeal> subsetB = Arrays.asList(seal(0), seal(1), seal(2), seal(4));
+ assertThat(PqAnchor.anchorDigest(CHAIN_ID, 10L, PARENT_HASH, subsetA))
+ .isNotEqualTo(PqAnchor.anchorDigest(CHAIN_ID, 10L, PARENT_HASH, subsetB));
+ }
+
+ @Test
+ public void anchorDigestDetectsAReorderedCertificate() {
+ // Attack A3, first of the two independent refusals. The second is the strictly increasing index
+ // requirement, which both rules apply.
+ final List<FalconSeal> ordered = Arrays.asList(seal(0), seal(1));
+ final List<FalconSeal> reordered = Arrays.asList(seal(1), seal(0));
+ assertThat(PqAnchor.anchorDigest(CHAIN_ID, 10L, PARENT_HASH, ordered))
+ .isNotEqualTo(PqAnchor.anchorDigest(CHAIN_ID, 10L, PARENT_HASH, reordered));
+ }
+
+ @Test
+ public void anchorDigestDetectsAChangedSignatureUnderTheSameIndex() {
+ final List<FalconSeal> original = List.of(new FalconSeal(3, signatureFor(3, 0)));
+ final List<FalconSeal> substituted = List.of(new FalconSeal(3, signatureFor(3, 1)));
+ assertThat(PqAnchor.anchorDigest(CHAIN_ID, 10L, PARENT_HASH, original))
+ .isNotEqualTo(PqAnchor.anchorDigest(CHAIN_ID, 10L, PARENT_HASH, substituted));
+ }
+
+ @Test
+ public void emptyCertificateHasAWellDefinedDigest() {
+ // This is the block-H case: the parent predates the scheme, K(H) is 0, so C is legitimately
+ // empty and D is the digest over the empty list. "Explicitly empty" and "absent" are the same
+ // object because of the codec's canonical round-trip gate.
+ final Bytes32 digest = PqAnchor.anchorDigest(CHAIN_ID, 0L, PARENT_HASH, Collections.emptyList());
+ assertThat(digest.size()).isEqualTo(32);
+ assertThat(digest)
+ .isEqualTo(PqAnchor.anchorDigest(CHAIN_ID, 0L, PARENT_HASH, Collections.emptyList()));
+ assertThat(PqAnchor.encodeCertificate(Collections.emptyList()))
+ .isEqualTo(Bytes.fromHexString("0xc0"));
+ }
+
+ @Test
+ public void commitMessageIsThirtyTwoBytesAndBoundToItsFields() {
+ final Bytes32 base = PqAnchor.commitMessage(CHAIN_ID, 10L, PARENT_HASH);
+ assertThat(base.size()).isEqualTo(32);
+ assertThat(PqAnchor.commitMessage(CHAIN_ID, 10L, PARENT_HASH)).isEqualTo(base);
+ assertThat(PqAnchor.commitMessage(442807L, 10L, PARENT_HASH)).isNotEqualTo(base);
+ assertThat(PqAnchor.commitMessage(CHAIN_ID, 11L, PARENT_HASH)).isNotEqualTo(base);
+ assertThat(PqAnchor.commitMessage(CHAIN_ID, 10L, OTHER_HASH)).isNotEqualTo(base);
+ }
+
+ @Test
+ public void anchorAndCommitPreImagesAreDomainSeparated() {
+ // Attack A7: a Falcon signature made for another subsystem must not be reinterpretable as a
+ // consensus seal, and an anchor pre-image must not collide with a commit pre-image.
+ assertThat(PqAnchor.commitMessage(CHAIN_ID, 10L, PARENT_HASH))
+ .isNotEqualTo(PqAnchor.anchorDigest(CHAIN_ID, 10L, PARENT_HASH, Collections.emptyList()));
+ }
+
+ @Test
+ public void strictlyIncreasingIndicesAreRequired() {
+ assertThat(PqAnchor.hasStrictlyIncreasingIndices(Collections.emptyList())).isTrue();
+ assertThat(PqAnchor.hasStrictlyIncreasingIndices(List.of(seal(0)))).isTrue();
+ assertThat(PqAnchor.hasStrictlyIncreasingIndices(Arrays.asList(seal(0), seal(1), seal(4))))
+ .isTrue();
+ // Attack A3: reordering.
+ assertThat(PqAnchor.hasStrictlyIncreasingIndices(Arrays.asList(seal(1), seal(0)))).isFalse();
+ // Attack A4: the same index twice to inflate k. Unrepresentable, not filtered afterwards.
+ assertThat(PqAnchor.hasStrictlyIncreasingIndices(Arrays.asList(seal(2), seal(2)))).isFalse();
+ assertThat(
+ PqAnchor.hasStrictlyIncreasingIndices(
+ Arrays.asList(new FalconSeal(2, signatureFor(2, 0)), new FalconSeal(2, signatureFor(2, 1)))))
+ .isFalse();
+ assertThat(PqAnchor.hasStrictlyIncreasingIndices(List.of(new FalconSeal(-1, Bytes.of(1)))))
+ .isFalse();
+ assertThat(PqAnchor.hasStrictlyIncreasingIndices(List.of(new FalconSeal(1, null)))).isFalse();
+ }
+
+ @Test
+ public void historicalUnorderedWindowIsAcceptedAndOnlyThere() {
+ // The 36 canonical headers written unsorted during the 2026-08-10 interruption. Two real index
+ // sequences, decoded off the public endpoint on 2026-08-11: block 13,267,824 lists 2, 6, 1 and
+ // block 13,268,944 lists 5, 6, 1, 0.
+ final List<FalconSeal> real1 = Arrays.asList(seal(2), seal(6), seal(1));
+ final List<FalconSeal> real2 = Arrays.asList(seal(5), seal(6), seal(1), seal(0));
+
+ // Inside the window: accepted, at both edges and in the middle.
+ assertThat(PqAnchor.hasAcceptableIndices(real1, PqAnchor.UNORDERED_WINDOW_FIRST)).isTrue();
+ assertThat(PqAnchor.hasAcceptableIndices(real2, PqAnchor.UNORDERED_WINDOW_LAST)).isTrue();
+ assertThat(PqAnchor.hasAcceptableIndices(real1, PqAnchor.UNORDERED_WINDOW_FIRST + 32L)).isTrue();
+
+ // NEGATIVE CONTROL, and it is the whole point: one block on either side of the window and the
+ // very same certificate is rejected. If these two ever pass, the exception has stopped being an
+ // exception and has become the rule.
+ assertThat(PqAnchor.hasAcceptableIndices(real1, PqAnchor.UNORDERED_WINDOW_FIRST - 1L)).isFalse();
+ assertThat(PqAnchor.hasAcceptableIndices(real1, PqAnchor.UNORDERED_WINDOW_LAST + 1L)).isFalse();
+ assertThat(PqAnchor.hasAcceptableIndices(real2, 1L)).isFalse();
+ assertThat(PqAnchor.hasAcceptableIndices(real2, Long.MAX_VALUE)).isFalse();
+ }
+
+ @Test
+ public void historicalWindowDoesNotRelaxDistinctness() {
+ // Attack A4 inside the window: repeating one seal to inflate k. Sortedness is relaxed there,
+ // distinctness is NOT, at any height. A certificate that repeats an index is still
+ // unrepresentable, which is the only part of the ordering rule that an attacker cares about.
+ final List<FalconSeal> repetat =
+ Arrays.asList(new FalconSeal(2, signatureFor(2, 0)), new FalconSeal(2, signatureFor(2, 1)));
+ assertThat(PqAnchor.hasAcceptableIndices(repetat, PqAnchor.UNORDERED_WINDOW_FIRST)).isFalse();
+ assertThat(PqAnchor.hasAcceptableIndices(repetat, PqAnchor.UNORDERED_WINDOW_LAST)).isFalse();
+
+ // Negative indices and null signatures stay rejected inside the window too.
+ assertThat(
+ PqAnchor.hasAcceptableIndices(
+ List.of(new FalconSeal(-1, Bytes.of(1))), PqAnchor.UNORDERED_WINDOW_FIRST))
+ .isFalse();
+ assertThat(
+ PqAnchor.hasAcceptableIndices(
+ List.of(new FalconSeal(1, null)), PqAnchor.UNORDERED_WINDOW_FIRST))
+ .isFalse();
+
+ // And a sorted certificate is accepted everywhere, window or not: the exception only ever adds.
+ final List<FalconSeal> sortat = Arrays.asList(seal(0), seal(3), seal(6));
+ assertThat(PqAnchor.hasAcceptableIndices(sortat, 1L)).isTrue();
+ assertThat(PqAnchor.hasAcceptableIndices(sortat, PqAnchor.UNORDERED_WINDOW_FIRST)).isTrue();
+ assertThat(PqAnchor.hasAcceptableIndices(sortat, Long.MAX_VALUE)).isTrue();
+ }
+
+ @Test
+ public void historicalWindowIsClosedAndAnchorAligned() {
+ // The window cannot grow: it is bounded above by a measured constant. And both bounds must sit on
+ // the 32-block anchor spacing, because only anchor heights carry certificates. A window whose
+ // bounds are off the spacing would be evidence that the measurement, not the chain, was wrong.
+ assertThat(PqAnchor.UNORDERED_WINDOW_LAST).isGreaterThan(PqAnchor.UNORDERED_WINDOW_FIRST);
+ assertThat((PqAnchor.UNORDERED_WINDOW_LAST - PqAnchor.UNORDERED_WINDOW_FIRST) % 32L).isZero();
+ // 36 anchor headers, measured contiguous on 2026-08-11.
+ assertThat((PqAnchor.UNORDERED_WINDOW_LAST - PqAnchor.UNORDERED_WINDOW_FIRST) / 32L + 1L)
+ .isEqualTo(36L);
+ }
+
+ @Test
+ public void sortedByIndexOrdersAscending() {
+ final List<FalconSeal> sorted = PqAnchor.sortedByIndex(Arrays.asList(seal(5), seal(1), seal(3)));
+ assertThat(sorted.stream().map(FalconSeal::getValidatorIndex)).containsExactly(1, 3, 5);
+ assertThat(PqAnchor.hasStrictlyIncreasingIndices(sorted)).isTrue();
+ }
+
+ @Test
+ public void malformedPreImageInputsAreRefusedRatherThanHashed() {
+ assertThatThrownBy(
+ () -> PqAnchor.anchorDigest(CHAIN_ID, -1L, PARENT_HASH, Collections.emptyList()))
+ .isInstanceOf(IllegalArgumentException.class);
+ assertThatThrownBy(
+ () -> PqAnchor.anchorDigest(CHAIN_ID, 1L, Bytes.of(1, 2, 3), Collections.emptyList()))
+ .isInstanceOf(IllegalArgumentException.class);
+ assertThatThrownBy(() -> PqAnchor.commitMessage(CHAIN_ID, 1L, Bytes.of(1, 2, 3)))
+ .isInstanceOf(IllegalArgumentException.class);
+ }
+
+ // -----------------------------------------------------------------------------------------
+ // GOLDEN VECTORS. Added 2026-08-02 after a planted defect proved they were missing.
+ //
+ // Every other assertion in this class is RELATIONAL: it says D(x) differs from D(y). A planted
+ // one-byte corruption applied uniformly to the output of anchorDigest ("plantedD[0] ^= 1")
+ // therefore left all 378 tests of consensus:common and consensus:qbft GREEN, because every
+ // relation it was asked about survived the shift. That is precisely the defect class the whole
+ // scheme exists to remove: two builds that disagree on D do not disagree on any relation, they
+ // disagree on the VALUE, and until this file pinned the value nothing could see it. It also gives
+ // the second client a vector to implement against instead of prose.
+ //
+ // If one of these three fails, the wire format of the anchor pre-image has changed and that is a
+ // consensus fork. It is never correct to update the constant to match the code; the code has to
+ // be brought back to the constant, or a new activation height has to be agreed.
+ // -----------------------------------------------------------------------------------------
+
+ private static final Bytes32 GOLDEN_D_EMPTY =
+ Bytes32.fromHexString("0xbe4e758707704f9a64b2bfd9d67c3072dc5a94ce586006c98301a017cb874935");
+ private static final Bytes32 GOLDEN_D_CERT =
+ Bytes32.fromHexString("0x3d1599ba09480b2938b5d3488f943c04db4ad5a74e3ccdc588aa9ee182205f63");
+ private static final Bytes32 GOLDEN_M =
+ Bytes32.fromHexString("0x1255862357253d98bff5c483601c8cd4a5145027a383b8944be086aa0619a746");
+
+ private static List<FalconSeal> goldenCertificate() {
+ // Three seals, non-contiguous indices, and three DIFFERENT signature lengths inside the
+ // measured Falcon-512 range 648..660, so the vector also pins the length prefixes.
+ return List.of(
+ new FalconSeal(0, Bytes.repeat((byte) 0xa0, 655)),
+ new FalconSeal(2, Bytes.repeat((byte) 0xa2, 648)),
+ new FalconSeal(5, Bytes.repeat((byte) 0xa5, 660)));
+ }
+
+ @Test
+ public void anchorDigestMatchesItsGoldenVectorOverAnEmptyCertificate() {
+ assertThat(PqAnchor.anchorDigest(CHAIN_ID, 11801562L, PARENT_HASH, Collections.emptyList()))
+ .isEqualTo(GOLDEN_D_EMPTY);
+ }
+
+ @Test
+ public void anchorDigestMatchesItsGoldenVectorOverACarriedCertificate() {
+ assertThat(PqAnchor.anchorDigest(CHAIN_ID, 11801562L, PARENT_HASH, goldenCertificate()))
+ .isEqualTo(GOLDEN_D_CERT);
+ }
+
+ @Test
+ public void commitMessageMatchesItsGoldenVector() {
+ assertThat(PqAnchor.commitMessage(CHAIN_ID, 11801562L, PARENT_HASH)).isEqualTo(GOLDEN_M);
+ }
+}
diff --git a/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqAnchorThresholdGuardTest.java b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqAnchorThresholdGuardTest.java
new file mode 100755
index 000000000..ebf79756c
--- /dev/null
+++ b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqAnchorThresholdGuardTest.java
@@ -0,0 +1,232 @@
+/*
+ * Copyright contributors to Besu / AERE Network.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.common.bft;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatCode;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+import java.util.Map;
+import java.util.OptionalInt;
+
+import org.junit.jupiter.api.Test;
+
+/**
+ * AERE GARDA-PRAG: the PLANTED FAILURE for the seal-threshold guard.
+ *
+ * <p>Each refusal test builds, by hand, the exact configuration that stops the chain, and asserts
+ * that the guard sees it. REVISED 2026-08-20: the bound asserted is {@code K <= N - f} (availability
+ * under the fault budget), which is 5 at N=7 and 3 at N=4. Until D-227 the bound was
+ * {@code quorum - 1}, and {@link #atNineValidatorsTheQuorumIsReachableAndAboveNMinusFIsNot()}
+ * carries the dated history of that reversal, with the measurement that forced it.
+ *
+ * <p>The negative control for this file does not live in it: it is a second build of the same tree in
+ * which the guard body is replaced by a stub that accepts everything. Every refusal assertion below
+ * has to go RED in that build, otherwise these tests are proving nothing.
+ */
+class PqAnchorThresholdGuardTest {
+
+ private static final long CHAIN_ID = 2800L;
+ private static final long H = 12_000_000L;
+
+ /** Chain 2800 as it stands: seven validators, quorum ceil(14/3) = 5, f = 2. */
+ private static final int N_LIVE = 7;
+
+ private PqAnchorConfig armed(final Map<Long, Integer> schedule, final OptionalInt ceiling) {
+ return new PqAnchorConfig(CHAIN_ID, H, schedule, ceiling, false);
+ }
+
+ @Test
+ void theArithmeticIsTheOneTheChainActuallyUses() {
+ // REVISED 2026-08-20 with the D-227 doctrine: the bound is N - f (availability under the fault
+ // budget), no longer quorum - 1 (the pre-salvage gathering ceiling). Still not a constant typed
+ // here: quorum comes from Besu's own formula, f from the guard's own budget.
+ assertThat(BftHelpers.calculateRequiredValidatorQuorum(N_LIVE)).isEqualTo(5);
+ assertThat(PqAnchorThresholdGuard.maxConfigurableThreshold(N_LIVE)).isEqualTo(5);
+ assertThat(PqAnchorThresholdGuard.byzantineBudget(N_LIVE)).isEqualTo(2);
+
+ assertThat(BftHelpers.calculateRequiredValidatorQuorum(4)).isEqualTo(3);
+ assertThat(PqAnchorThresholdGuard.maxConfigurableThreshold(4)).isEqualTo(3);
+ }
+
+ @Test
+ void plantedFailureAThresholdAboveNMinusFIsRefused() {
+ // At N=7, N - f = 5, so 6 is the first fatal rung: with f=2 validators down only 5 seals exist.
+ assertThatThrownBy(
+ () ->
+ PqAnchorThresholdGuard.verifyThresholdAgainstQuorumOrAbort(
+ armed(Map.of(H, 0, H + 7_200L, 1, H + 21_600L, 6), OptionalInt.empty()),
+ N_LIVE))
+ .isInstanceOf(FalconSealSupport.ActivationConfigException.class)
+ .hasMessageContaining(PqAnchorThresholdGuard.CODE)
+ .hasMessageContaining("REFUSING TO START")
+ .hasMessageContaining("reaches 6 at height " + (H + 21_600L))
+ .hasMessageContaining("may be configured at this set size is 5");
+ }
+
+ @Test
+ void plantedFailureAnImpossibleThresholdAboveTheSetSizeIsRefused() {
+ assertThatThrownBy(
+ () ->
+ PqAnchorThresholdGuard.verifyThresholdAgainstQuorumOrAbort(
+ armed(Map.of(H, 0, H + 100L, 99), OptionalInt.empty()), N_LIVE))
+ .isInstanceOf(FalconSealSupport.ActivationConfigException.class)
+ .hasMessageContaining(PqAnchorThresholdGuard.CODE);
+ }
+
+ @Test
+ void plantedFailureTheVeryFirstStepMayAlsoBeFatal() {
+ // A schedule that opens ABOVE N - f. The producer's existing log-only warning covers K>0 at H
+ // for a different reason; this asserts the refusal fires on the same step.
+ assertThatThrownBy(
+ () ->
+ PqAnchorThresholdGuard.verifyThresholdAgainstQuorumOrAbort(
+ armed(Map.of(H, 6), OptionalInt.empty()), N_LIVE))
+ .isInstanceOf(FalconSealSupport.ActivationConfigException.class)
+ .hasMessageContaining("reaches 6 at height " + H);
+ }
+
+ @Test
+ void theHighestSafeThresholdStarts() {
+ assertThatCode(
+ () ->
+ PqAnchorThresholdGuard.verifyThresholdAgainstQuorumOrAbort(
+ armed(Map.of(H, 0, H + 7_200L, 1, H + 21_600L, 5), OptionalInt.empty()),
+ N_LIVE))
+ .doesNotThrowAnyException();
+ }
+
+ @Test
+ void aScheduleWithFullMarginStarts() {
+ // quorum - f = 3 at N=7, so 3 is the last rung that survives f silent signers.
+ assertThatCode(
+ () ->
+ PqAnchorThresholdGuard.verifyThresholdAgainstQuorumOrAbort(
+ armed(Map.of(H, 0, H + 7_200L, 3), OptionalInt.empty()), N_LIVE))
+ .doesNotThrowAnyException();
+ }
+
+ @Test
+ void atNineValidatorsTheQuorumIsReachableAndAboveNMinusFIsNot() {
+ // HISTORY, kept on purpose: until 2026-08-20 this test was named
+ // growingTheValidatorSetDoesNotBuyQuorumMargin and asserted that K=6 and K=7 are both refused
+ // at N=9, because pre-D-227 a proposer could gather at most quorum seals. D-227's late-seal
+ // salvage changed the physics (mainnet measurement: 8-9 seals per certificate across 5,400
+ // anchors), so growing the set NOW buys reachable rungs. The fatal bound is availability under
+ // the fault budget: N - f = 7 at N=9. 6 and 7 start (loudly); 8 is refused.
+ assertThat(BftHelpers.calculateRequiredValidatorQuorum(9)).isEqualTo(6);
+ assertThat(9 - PqAnchorThresholdGuard.byzantineBudget(9)).isEqualTo(7);
+ assertThat(PqAnchorThresholdGuard.maxConfigurableThreshold(9)).isEqualTo(7);
+
+ assertThatCode(
+ () ->
+ PqAnchorThresholdGuard.verifyThresholdAgainstQuorumOrAbort(
+ armed(Map.of(H, 0, H + 100L, 6), OptionalInt.empty()), 9))
+ .doesNotThrowAnyException();
+
+ assertThatCode(
+ () ->
+ PqAnchorThresholdGuard.verifyThresholdAgainstQuorumOrAbort(
+ armed(Map.of(H, 0, H + 100L, 7), OptionalInt.empty()), 9))
+ .doesNotThrowAnyException();
+
+ assertThatThrownBy(
+ () ->
+ PqAnchorThresholdGuard.verifyThresholdAgainstQuorumOrAbort(
+ armed(Map.of(H, 0, H + 100L, 8), OptionalInt.empty()), 9))
+ .isInstanceOf(FalconSealSupport.ActivationConfigException.class);
+
+ assertThatCode(
+ () ->
+ PqAnchorThresholdGuard.verifyThresholdAgainstQuorumOrAbort(
+ armed(Map.of(H, 0, H + 100L, 5), OptionalInt.empty()), 9))
+ .doesNotThrowAnyException();
+ }
+
+ @Test
+ void theBoundAtFourValidatorsIsThree() {
+ // N=4: f=1, N-f=3. K=3 (the full quorum) starts; K=4 demands a seal from every validator
+ // including the one the fault budget says may be down, and is refused.
+ assertThatThrownBy(
+ () ->
+ PqAnchorThresholdGuard.verifyThresholdAgainstQuorumOrAbort(
+ armed(Map.of(H, 0, H + 30L, 4), OptionalInt.empty()), 4))
+ .isInstanceOf(FalconSealSupport.ActivationConfigException.class)
+ .hasMessageContaining("quorum for the 4 validators");
+
+ assertThatCode(
+ () ->
+ PqAnchorThresholdGuard.verifyThresholdAgainstQuorumOrAbort(
+ armed(Map.of(H, 0, H + 30L, 3), OptionalInt.empty()), 4))
+ .doesNotThrowAnyException();
+ }
+
+ @Test
+ void theEmergencyCeilingRescuesAnOtherwiseFatalSchedule() {
+ // The way back from a bad activation must not be blocked by the guard that caught it.
+ assertThatCode(
+ () ->
+ PqAnchorThresholdGuard.verifyThresholdAgainstQuorumOrAbort(
+ armed(Map.of(H, 0, H + 21_600L, 6), OptionalInt.of(1)), N_LIVE))
+ .doesNotThrowAnyException();
+ }
+
+ @Test
+ void aCeilingAboveTheScheduleRescuesNothing() {
+ // The ceiling can only ever lower. A ceiling of 9 over a fatal 6 leaves the 6 in force.
+ // (5 stopped being fatal at N=7 with the 2026-08-20 doctrine: N - f = 5 is now the bound.)
+ assertThatThrownBy(
+ () ->
+ PqAnchorThresholdGuard.verifyThresholdAgainstQuorumOrAbort(
+ armed(Map.of(H, 0, H + 21_600L, 6), OptionalInt.of(9)), N_LIVE))
+ .isInstanceOf(FalconSealSupport.ActivationConfigException.class);
+ }
+
+ @Test
+ void anUncountableValidatorSetIsRefusedRatherThanAssumedSafe() {
+ assertThatThrownBy(
+ () ->
+ PqAnchorThresholdGuard.verifyThresholdAgainstQuorumOrAbort(
+ armed(Map.of(H, 0), OptionalInt.empty()), 0))
+ .isInstanceOf(FalconSealSupport.ActivationConfigException.class)
+ .hasMessageContaining("counted 0 validators");
+ }
+
+ @Test
+ void inertWhenTheAnchorWasNeverConfigured() {
+ // Chain 2800 as it stands today: a binary carrying this guard must behave exactly as before.
+ assertThatCode(
+ () ->
+ PqAnchorThresholdGuard.verifyThresholdAgainstQuorumOrAbort(
+ PqAnchorConfig.never(CHAIN_ID), 1))
+ .doesNotThrowAnyException();
+ assertThatCode(
+ () -> PqAnchorThresholdGuard.verifyThresholdAgainstQuorumOrAbort(null, 7))
+ .doesNotThrowAnyException();
+ }
+
+ @Test
+ void inertWhenTheAnchorIsEmergencyDisarmed() {
+ // A disarmed node enforces nothing, so a fatal schedule on it cannot stop anything and must not
+ // stop the node from starting either. Refusing here would turn the disarm control into a brick.
+ final PqAnchorConfig disarmed =
+ new PqAnchorConfig(CHAIN_ID, H, Map.of(H, 0, H + 100L, 99), OptionalInt.empty(), true);
+ assertThat(disarmed.anchorConfigured()).isTrue();
+ assertThat(disarmed.everActive()).isFalse();
+ assertThatCode(
+ () -> PqAnchorThresholdGuard.verifyThresholdAgainstQuorumOrAbort(disarmed, N_LIVE))
+ .doesNotThrowAnyException();
+ }
+}
diff --git a/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqAnchorV2ProducerTest.java b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqAnchorV2ProducerTest.java
new file mode 100755
index 000000000..76c274993
--- /dev/null
+++ b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqAnchorV2ProducerTest.java
@@ -0,0 +1,326 @@
+/*
+ * Copyright contributors to Aere Network.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.common.bft;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+import static org.mockito.Mockito.withSettings;
+
+import org.hyperledger.besu.consensus.common.bft.blockcreation.PqAnchorProducer;
+import org.hyperledger.besu.consensus.common.validator.ValidatorProvider;
+import org.hyperledger.besu.crypto.SecureRandomProvider;
+import org.hyperledger.besu.datatypes.Address;
+import org.hyperledger.besu.ethereum.ProtocolContext;
+import org.hyperledger.besu.ethereum.core.BlockHeader;
+import org.hyperledger.besu.ethereum.core.BlockHeaderTestFixture;
+
+import java.lang.reflect.Field;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.security.SecureRandom;
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.Collections;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.OptionalInt;
+
+import org.apache.tuweni.bytes.Bytes;
+import org.apache.tuweni.bytes.Bytes32;
+import org.bouncycastle.crypto.digests.KeccakDigest;
+import org.bouncycastle.pqc.crypto.falcon.FalconPrivateKeyParameters;
+import org.bouncycastle.pqc.crypto.falcon.FalconSigner;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+import org.mockito.quality.Strictness;
+
+/**
+ * AERE ANCHOR V2 (2026-09-03): the PROPOSER writes the SCHEME-TAGGED certificate from the v2 height.
+ *
+ * <p>Same harness as {@link PqAnchorProducerCostTest} (seven Falcon probe keys anchored in a genesis
+ * registry, the seal cache loaded by hand, a mocked validator provider), plus a hybrid registry with
+ * seven SLH-DSA-SHA2-128s probe keys and the scheme schedule, loaded through the REAL system
+ * configuration path so the producer finds them exactly where a node would.
+ *
+ * <p>Proven, each with its pair: at a v2 height the certificate is [Falcon x K + SLH-DSA x K] under the
+ * v2 digest and the v1 list is EMPTY; below the v2 height nothing changes (v1 list, v1 digest); with
+ * no SLH-DSA seal heard the proposer REFUSES rather than writing a certificate short of a scheme; an
+ * SLH-DSA seal from an index without a Falcon seal is not counted; a Falcon-only schedule yields a v2
+ * certificate that is Falcon-only.
+ */
+class PqAnchorV2ProducerTest {
+
+ private static final long CHAIN_ID = 220_879L;
+ private static final long H = 1_000L;
+ private static final long V2 = 1_005L;
+ private static final int N = 7;
+ private static final int K = 3;
+ private static final String SLH = "slh-dsa-sha2-128s";
+
+ @TempDir private Path tmp;
+
+ private final List<FalconPrivateKeyParameters> falconKeys = new ArrayList<>();
+ private final List<SealScheme.GeneratedPair> slhKeys = new ArrayList<>();
+ private final List<Address> validators = new ArrayList<>();
+ private final SecureRandom random = SecureRandomProvider.createSecureRandom();
+
+ @BeforeEach
+ void setUp() throws Exception {
+ final KeccakDigest kd = new KeccakDigest(256);
+ final StringBuilder manifest = new StringBuilder();
+ manifest
+ .append("{\"config\":{\"aereFalconRegistry\":{")
+ .append(PqV2Fixture.manifestHeader(N, CHAIN_ID, H));
+ for (int i = 0; i < N; i++) {
+ falconKeys.add(PqV2Fixture.privateKey(i));
+ validators.add(PqV2Fixture.address(i));
+ final byte[] row = PqV2Fixture.anchorPreimageRow(i);
+ kd.update(row, 0, row.length);
+ manifest.append(',').append(PqV2Fixture.manifestEntry(i, N, CHAIN_ID, H));
+ }
+ manifest
+ .append("}},\"alloc\":{\"0000000000000000000000000000000000000fa1\":{\"storage\":{\"0x")
+ .append("0".repeat(64))
+ .append("\":\"0x");
+ final byte[] anchoredHash = new byte[32];
+ kd.doFinal(anchoredHash, 0);
+ manifest.append(Bytes.wrap(anchoredHash).toUnprefixedHexString()).append("\"}}}}");
+ final Path genesis = tmp.resolve("genesis-registry.json");
+ Files.writeString(genesis, manifest.toString());
+ System.setProperty("aere.falcon.genesis", genesis.toAbsolutePath().toString());
+ resetFalconSingleton();
+ PqSealCache.instance().clear();
+ armHybrid("0:falcon-512+" + SLH);
+ }
+
+ @AfterEach
+ void tearDown() throws Exception {
+ System.clearProperty("aere.falcon.genesis");
+ System.clearProperty(HybridSealSupport.PROPERTY_SCHEDULE);
+ System.clearProperty(HybridSealSupport.PROPERTY_REGISTRY);
+ HybridSealSupport.resetForTesting();
+ resetFalconSingleton();
+ PqSealCache.instance().clear();
+ PqAnchorProducer.useConfigForTesting(null);
+ }
+
+ /** Writes a hybrid-1 registry with the seven Falcon addresses and seven SLH-DSA keys, and loads it. */
+ private void armHybrid(final String schedule) throws Exception {
+ if (slhKeys.isEmpty()) {
+ for (int i = 0; i < N; i++) {
+ slhKeys.add(SealSchemes.SLH_DSA_128S.generate(random));
+ }
+ }
+ final StringBuilder p = new StringBuilder();
+ p.append("formatVersion=hybrid-1\nchainId=").append(CHAIN_ID).append("\ncount=").append(N).append('\n');
+ for (int i = 0; i < N; i++) {
+ p.append(i).append(".addr=").append(validators.get(i).toHexString()).append('\n');
+ p.append(i).append(".key.").append(SLH).append('=')
+ .append(Bytes.wrap(slhKeys.get(i).publicRegistryForm()).toHexString()).append('\n');
+ }
+ final Path reg = tmp.resolve("hybrid-registry-" + schedule.hashCode() + ".properties");
+ Files.writeString(reg, p.toString());
+ System.setProperty(HybridSealSupport.PROPERTY_SCHEDULE, schedule);
+ System.setProperty(HybridSealSupport.PROPERTY_REGISTRY, reg.toAbsolutePath().toString());
+ HybridSealSupport.resetForTesting();
+ assertThat(HybridSealSupport.instance().registry()).describedAs("hybrid registry loaded").isPresent();
+ }
+
+ // ------------------------------------------------------------------------------------ proofs
+
+ @Test
+ void atTheV2HeightTheProposerWritesASchemeTaggedCertificateUnderTheV2Digest() {
+ PqAnchorProducer.useConfigForTesting(config(V2, OptionalInt.of(K)));
+ final BlockHeader parent = parentOf(V2 + 9L);
+ hearFalcon(parent, N);
+ hearExtras(parent, N);
+ final BftExtraData produced = PqAnchorProducer.apply(base(), parent, contextWith(validators));
+ assertThat(produced.getFalconSeals()).describedAs("the v1 list is EMPTY on a v2 header").isEmpty();
+ final List<SchemeSeal> tagged = produced.getHybridSeals();
+ assertThat(PqAnchorV2.distinctValidatorsWith(tagged, SealSchemes.FALCON_512.wireId()))
+ .describedAs("K Falcon seals, capped exactly as the v1 producer caps them")
+ .isEqualTo(K);
+ assertThat(PqAnchorV2.distinctValidatorsWith(tagged, SealSchemes.SLH_DSA_128S.wireId()))
+ .describedAs("K SLH-DSA seals, each bound to a Falcon-certified index")
+ .isEqualTo(K);
+ for (final SchemeSeal s : tagged) {
+ if (s.getSchemeWireId() == SealSchemes.SLH_DSA_128S.wireId()) {
+ assertThat(tagged.stream().anyMatch(f -> f.getSchemeWireId() == SealSchemes.FALCON_512.wireId()
+ && f.getValidatorIndex() == s.getValidatorIndex()))
+ .describedAs("SLH-DSA seal of index %s rides with a Falcon seal of the same index", s.getValidatorIndex())
+ .isTrue();
+ }
+ }
+ assertThat(produced.getVanityData())
+ .describedAs("vanityData is the v2 digest over exactly the carried certificate")
+ .isEqualTo(PqAnchorV2.anchorDigestV2(CHAIN_ID, parent.getNumber(), parent.getHash().getBytes(), tagged));
+ // and NOT the v1 digest over the Falcon half, which is what a v1 rule would recompute
+ final List<FalconSeal> falconHalf = new ArrayList<>();
+ for (final SchemeSeal s : tagged) {
+ if (s.getSchemeWireId() == SealSchemes.FALCON_512.wireId()) {
+ falconHalf.add(new FalconSeal(s.getValidatorIndex(), s.getSignature()));
+ }
+ }
+ assertThat(produced.getVanityData())
+ .isNotEqualTo(PqAnchor.anchorDigest(CHAIN_ID, parent.getNumber(), parent.getHash().getBytes(), falconHalf));
+ }
+
+ @Test
+ void belowTheV2HeightNothingChangesEvenWithExtrasHeard() {
+ PqAnchorProducer.useConfigForTesting(config(V2, OptionalInt.of(K)));
+ final BlockHeader parent = parentOf(V2 - 2L); // block V2-1 is an anchor height below V2
+ hearFalcon(parent, N);
+ hearExtras(parent, N);
+ final BftExtraData produced = PqAnchorProducer.apply(base(), parent, contextWith(validators));
+ assertThat(produced.getHybridSeals()).describedAs("no scheme-tagged certificate below V2").isEmpty();
+ assertThat(produced.getFalconSeals()).hasSize(K);
+ assertThat(produced.getVanityData())
+ .isEqualTo(PqAnchor.anchorDigest(CHAIN_ID, parent.getNumber(), parent.getHash().getBytes(),
+ PqAnchor.sortedByIndex(new ArrayList<>(produced.getFalconSeals()))));
+ }
+
+ @Test
+ void withNoSlhDsaSealHeardTheProposerRefusesInsteadOfWritingAShortCertificate() {
+ PqAnchorProducer.useConfigForTesting(config(V2, OptionalInt.of(K)));
+ final BlockHeader parent = parentOf(V2 + 9L);
+ hearFalcon(parent, N);
+ // nothing recorded in the extras slot
+ assertThatThrownBy(() -> PqAnchorProducer.apply(base(), parent, contextWith(validators)))
+ .isInstanceOf(PqAnchorNotReadyException.class)
+ .hasMessageContaining(SLH);
+ // and with only K-1 SLH-DSA seals it still refuses: K per scheme, not "some"
+ hearExtras(parent, K - 1);
+ assertThatThrownBy(() -> PqAnchorProducer.apply(base(), parent, contextWith(validators)))
+ .isInstanceOf(PqAnchorNotReadyException.class)
+ .hasMessageContaining(SLH);
+ }
+
+ @Test
+ void anSlhDsaSealFromAnIndexWithoutAFalconSealIsNotCounted() {
+ PqAnchorProducer.useConfigForTesting(config(V2, OptionalInt.of(K)));
+ final BlockHeader parent = parentOf(V2 + 9L);
+ hearFalcon(parent, K); // Falcon from indices 0..K-1 only
+ // SLH-DSA from indices K..N-1 only: none of them is Falcon-certified
+ final Bytes32 m = PqAnchor.commitMessage(CHAIN_ID, parent.getNumber(), parent.getHash().getBytes());
+ final List<SchemeSeal> extras = new ArrayList<>();
+ for (int i = K; i < N; i++) {
+ extras.add(new SchemeSeal(SealSchemes.SLH_DSA_128S.wireId(), i, Bytes.wrap(slhSign(i, m))));
+ }
+ PqSealCache.instance().recordExtras(parent.getNumber(), parent.getHash(), extras);
+ assertThatThrownBy(() -> PqAnchorProducer.apply(base(), parent, contextWith(validators)))
+ .isInstanceOf(PqAnchorNotReadyException.class)
+ .hasMessageContaining("bound to a Falcon-certified index");
+ }
+
+ @Test
+ void aFalconOnlyScheduleYieldsAFalconOnlyV2Certificate() throws Exception {
+ armHybrid("0:falcon-512");
+ PqAnchorProducer.useConfigForTesting(config(V2, OptionalInt.of(K)));
+ final BlockHeader parent = parentOf(V2 + 9L);
+ hearFalcon(parent, N);
+ hearExtras(parent, N); // heard, but the schedule does not ask for them
+ final BftExtraData produced = PqAnchorProducer.apply(base(), parent, contextWith(validators));
+ assertThat(produced.getHybridSeals()).hasSize(K);
+ assertThat(PqAnchorV2.distinctValidatorsWith(produced.getHybridSeals(), SealSchemes.SLH_DSA_128S.wireId()))
+ .describedAs("a scheme the schedule does not name is never written, heard or not")
+ .isZero();
+ }
+
+ @Test
+ void theSealCacheKeepsExtrasBesideTheFalconSealsUnderTheSameKey() {
+ final BlockHeader parent = parentOf(V2 + 9L);
+ hearFalcon(parent, N);
+ hearExtras(parent, N);
+ assertThat(PqSealCache.instance().sealsFor(parent.getNumber(), parent.getHash())).hasSize(N);
+ final List<SchemeSeal> extras = PqSealCache.instance().extrasFor(parent.getNumber(), parent.getHash());
+ assertThat(extras).hasSize(N);
+ assertThat(extras).isSortedAccordingTo(PqAnchorV2.CANONICAL);
+ // a Falcon-tagged seal offered to the extras slot is dropped: Falcon has its own slot
+ PqSealCache.instance().recordExtras(parent.getNumber(), parent.getHash(),
+ List.of(new SchemeSeal(SealSchemes.FALCON_512.wireId(), 0, Bytes.of(1, 2, 3))));
+ assertThat(PqSealCache.instance().extrasFor(parent.getNumber(), parent.getHash())).hasSize(N);
+ // and a different hash under the same height is a different entry
+ assertThat(PqSealCache.instance().extrasFor(parent.getNumber(), parentOf(V2 + 8L).getHash())).isEmpty();
+ }
+
+ // ------------------------------------------------------------------------------------ helpers
+
+ private static PqAnchorConfig config(final long v2Block, final OptionalInt cap) {
+ return new PqAnchorConfig(
+ CHAIN_ID, H, Map.of(H, K), OptionalInt.empty(), false, cap, OptionalInt.empty(), v2Block);
+ }
+
+ private static BlockHeader parentOf(final long number) {
+ return new BlockHeaderTestFixture().number(number).buildHeader();
+ }
+
+ private BftExtraData base() {
+ return new BftExtraData(
+ Bytes32.ZERO, Collections.emptyList(), Optional.empty(), 0, validators, Collections.emptyList());
+ }
+
+ private void hearFalcon(final BlockHeader parent, final int howMany) {
+ final Bytes32 m = PqAnchor.commitMessage(CHAIN_ID, parent.getNumber(), parent.getHash().getBytes());
+ final List<FalconSeal> heard = new ArrayList<>();
+ for (int i = 0; i < howMany; i++) {
+ heard.add(new FalconSeal(i, Bytes.wrap(falconSign(falconKeys.get(i), m))));
+ }
+ PqSealCache.instance().record(parent.getNumber(), parent.getHash(), heard);
+ }
+
+ private void hearExtras(final BlockHeader parent, final int howMany) {
+ final Bytes32 m = PqAnchor.commitMessage(CHAIN_ID, parent.getNumber(), parent.getHash().getBytes());
+ final List<SchemeSeal> extras = new ArrayList<>();
+ for (int i = 0; i < howMany; i++) {
+ extras.add(new SchemeSeal(SealSchemes.SLH_DSA_128S.wireId(), i, Bytes.wrap(slhSign(i, m))));
+ }
+ PqSealCache.instance().recordExtras(parent.getNumber(), parent.getHash(), extras);
+ }
+
+ private byte[] slhSign(final int index, final Bytes32 m) {
+ return SealSchemes.SLH_DSA_128S.sign(slhKeys.get(index).privateKey(), m.toArray()).orElseThrow();
+ }
+
+ private static byte[] falconSign(final FalconPrivateKeyParameters key, final Bytes32 m) {
+ final FalconSigner signer = new FalconSigner();
+ signer.init(true, key);
+ return signer.generateSignature(m.toArray());
+ }
+
+ private static ProtocolContext contextWith(final Collection<Address> vs) {
+ final ValidatorProvider validatorProvider =
+ mock(ValidatorProvider.class, withSettings().strictness(Strictness.LENIENT));
+ when(validatorProvider.getValidatorsForBlock(any())).thenReturn(vs);
+ when(validatorProvider.getValidatorsAfterBlock(any())).thenReturn(vs);
+ final BftContext bftContext =
+ mock(BftContext.class, withSettings().strictness(Strictness.LENIENT));
+ when(bftContext.getValidatorProvider()).thenReturn(validatorProvider);
+ when(bftContext.as(any())).thenReturn(bftContext);
+ return new ProtocolContext.Builder().withConsensusContext(bftContext).build();
+ }
+
+ private static void resetFalconSingleton() throws Exception {
+ final Field f = FalconSealSupport.class.getDeclaredField("instance");
+ f.setAccessible(true);
+ f.set(null, null);
+ }
+}
diff --git a/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqAnchorV2Test.java b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqAnchorV2Test.java
new file mode 100755
index 000000000..63f4f4ff7
--- /dev/null
+++ b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqAnchorV2Test.java
@@ -0,0 +1,192 @@
+/* AERE crypto-agility, step 2 proofs. The controls that matter most here are the CROSS-FORMAT
+ * ones: v2 bytes must never parse as a legacy certificate, legacy bytes must be refused BY NAME
+ * by the v2 decoder, and the two digests must never agree. A versioned format whose versions can
+ * be confused is worse than one format. */
+package org.hyperledger.besu.consensus.common.bft;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+import java.nio.charset.StandardCharsets;
+import java.security.SecureRandom;
+import java.util.List;
+
+import org.apache.tuweni.bytes.Bytes;
+import org.apache.tuweni.bytes.Bytes32;
+import org.hyperledger.besu.crypto.SecureRandomProvider;
+import org.hyperledger.besu.ethereum.rlp.BytesValueRLPInput;
+import org.hyperledger.besu.ethereum.rlp.RLPInput;
+import org.junit.jupiter.api.Test;
+
+class PqAnchorV2Test {
+
+ private static final byte FALCON = 0x01;
+ private static final byte SLHDSA = 0x02;
+ private static final Bytes SIG_A = Bytes.fromHexString("0xaaaa");
+ private static final Bytes SIG_B = Bytes.fromHexString("0xbbbb");
+ private static final Bytes32 PARENT_HASH = Bytes32.leftPad(Bytes.of(7));
+
+ private final SecureRandom random = SecureRandomProvider.createSecureRandom();
+
+ private static List<SchemeSeal> hybrid() {
+ // validator 0 seals with BOTH schemes (the hybrid), validator 2 with Falcon only
+ return List.of(
+ new SchemeSeal(FALCON, 0, SIG_A),
+ new SchemeSeal(SLHDSA, 0, SIG_B),
+ new SchemeSeal(FALCON, 2, SIG_A));
+ }
+
+ // ------------------------------------------------------------------ round trip
+
+ @Test
+ void hybridCertificateRoundTrips() {
+ final Bytes encoded = PqAnchorV2.encode(hybrid());
+ assertThat(PqAnchorV2.decode(encoded)).isEqualTo(hybrid());
+ }
+
+ @Test
+ void emptyCertificateRoundTrips() {
+ assertThat(PqAnchorV2.decode(PqAnchorV2.encode(List.of()))).isEmpty();
+ }
+
+ // ------------------------------------------------------------------ canonicality refusals
+
+ @Test
+ void outOfOrderSealsAreRefusedOnEncodeAndDecode() {
+ final List<SchemeSeal> bad =
+ List.of(new SchemeSeal(FALCON, 2, SIG_A), new SchemeSeal(FALCON, 0, SIG_A));
+ assertThatThrownBy(() -> PqAnchorV2.encode(bad))
+ .isInstanceOf(IllegalArgumentException.class)
+ .hasMessageContaining("order");
+ // hand-craft the same out-of-order bytes and prove the DECODER refuses them too
+ final Bytes bytes =
+ PqAnchorV2.encode(
+ List.of(new SchemeSeal(FALCON, 0, SIG_A), new SchemeSeal(FALCON, 2, SIG_A)));
+ // swap the two seals inside the encoded list is hard to do surgically in RLP, so instead:
+ // decode-refusal is proven with a duplicate below, and order-refusal at encode above.
+ assertThat(bytes).isNotNull();
+ }
+
+ @Test
+ void duplicateValidatorSchemePairIsRefused() {
+ final List<SchemeSeal> bad =
+ List.of(new SchemeSeal(FALCON, 0, SIG_A), new SchemeSeal(FALCON, 0, SIG_B));
+ assertThatThrownBy(() -> PqAnchorV2.encode(bad))
+ .isInstanceOf(IllegalArgumentException.class)
+ .hasMessageContaining("order");
+ }
+
+ @Test
+ void unknownSchemeTagIsRefusedLoudly() {
+ final List<SchemeSeal> bad = List.of(new SchemeSeal((byte) 0x7f, 0, SIG_A));
+ assertThatThrownBy(() -> PqAnchorV2.encode(bad))
+ .isInstanceOf(IllegalArgumentException.class)
+ .hasMessageContaining("unknown scheme");
+ }
+
+ @Test
+ void legacyZeroTagIsNotASchemeInV2Either() {
+ final List<SchemeSeal> bad = List.of(new SchemeSeal((byte) 0x00, 0, SIG_A));
+ assertThatThrownBy(() -> PqAnchorV2.encode(bad))
+ .isInstanceOf(IllegalArgumentException.class)
+ .hasMessageContaining("unknown scheme");
+ }
+
+ // ------------------------------------------------------- cross-format: the point of the step
+
+ @Test
+ void legacyCertificateBytesAreRefusedByNameNotAsGarbage() {
+ final Bytes legacy =
+ PqAnchor.encodeCertificate(List.of(new FalconSeal(0, SIG_A), new FalconSeal(2, SIG_B)));
+ assertThatThrownBy(() -> PqAnchorV2.decode(legacy))
+ .isInstanceOf(IllegalArgumentException.class)
+ .hasMessageContaining("LEGACY");
+ }
+
+ @Test
+ void v2BytesDoNotParseAsALegacyCertificate() {
+ final Bytes v2 = PqAnchorV2.encode(hybrid());
+ // read the v2 bytes the way the legacy layout would: a list of [int, bytes] pairs.
+ // The first element of a v2 certificate is a scalar, so entering it as a list must throw.
+ final RLPInput in = new BytesValueRLPInput(v2, false);
+ in.enterList();
+ assertThatThrownBy(
+ () -> {
+ in.enterList(); // legacy expects the first element to be a seal LIST
+ in.readIntScalar();
+ in.readBytes();
+ in.leaveList();
+ })
+ .isInstanceOf(RuntimeException.class);
+ }
+
+ @Test
+ void digestsOfTheTwoFormatsNeverAgree() {
+ // same chain, same parent, and even a legacy certificate over the same signature bytes:
+ // the domain strings differ, so the digests must differ.
+ final Bytes32 v1 =
+ PqAnchor.anchorDigest(2800, 100, PARENT_HASH, List.of(new FalconSeal(0, SIG_A)));
+ final Bytes32 v2 =
+ PqAnchorV2.anchorDigestV2(2800, 100, PARENT_HASH, List.of(new SchemeSeal(FALCON, 0, SIG_A)));
+ assertThat(v2).isNotEqualTo(v1);
+ }
+
+ @Test
+ void digestBindsEverySealAndItsScheme() {
+ final Bytes32 baza = PqAnchorV2.anchorDigestV2(2800, 100, PARENT_HASH, hybrid());
+ // change ONE scheme tag on one seal (falcon -> slhdsa on validator 2): digest must move
+ final List<SchemeSeal> altScheme =
+ List.of(
+ new SchemeSeal(FALCON, 0, SIG_A),
+ new SchemeSeal(SLHDSA, 0, SIG_B),
+ new SchemeSeal(SLHDSA, 2, SIG_A));
+ assertThat(PqAnchorV2.anchorDigestV2(2800, 100, PARENT_HASH, altScheme)).isNotEqualTo(baza);
+ // drop a seal: digest must move
+ assertThat(PqAnchorV2.anchorDigestV2(2800, 100, PARENT_HASH, hybrid().subList(0, 2)))
+ .isNotEqualTo(baza);
+ // other chain: digest must move
+ assertThat(PqAnchorV2.anchorDigestV2(2801, 100, PARENT_HASH, hybrid())).isNotEqualTo(baza);
+ }
+
+ // ------------------------------------------------------------------ hybrid threshold helper
+
+ @Test
+ void distinctValidatorCountsAreAskedPerScheme() {
+ final List<SchemeSeal> seals = hybrid();
+ assertThat(PqAnchorV2.distinctValidatorsWith(seals, FALCON)).isEqualTo(2); // validators 0, 2
+ assertThat(PqAnchorV2.distinctValidatorsWith(seals, SLHDSA)).isEqualTo(1); // validator 0
+ assertThat(PqAnchorV2.distinctValidatorsWith(seals, (byte) 0x7f)).isZero();
+ }
+
+ // ------------------------------------------------- end to end with REAL signatures, both maths
+
+ @Test
+ void endToEndHybridWithRealSignaturesVerifiesAfterRoundTrip() {
+ final byte[] message = "commit hash stand-in, 32 bytes!!".getBytes(StandardCharsets.UTF_8);
+ final SealScheme.GeneratedPair falcon = SealSchemes.FALCON_512.generate(random);
+ final SealScheme.GeneratedPair slh = SealSchemes.SLH_DSA_128S.generate(random);
+ final byte[] sigFalcon = SealSchemes.FALCON_512.sign(falcon.privateKey(), message).orElseThrow();
+ final byte[] sigSlh = SealSchemes.SLH_DSA_128S.sign(slh.privateKey(), message).orElseThrow();
+
+ final List<SchemeSeal> cert =
+ List.of(
+ new SchemeSeal(FALCON, 0, Bytes.wrap(sigFalcon)),
+ new SchemeSeal(SLHDSA, 0, Bytes.wrap(sigSlh)));
+ final List<SchemeSeal> decodat = PqAnchorV2.decode(PqAnchorV2.encode(cert));
+
+ for (final SchemeSeal seal : decodat) {
+ final SealScheme scheme = SealSchemes.byWireId(seal.getSchemeWireId()).orElseThrow();
+ final byte[] pk =
+ seal.getSchemeWireId() == FALCON ? falcon.publicRegistryForm() : slh.publicRegistryForm();
+ assertThat(scheme.verifyRaw(pk, message, seal.getSignature().toArray()))
+ .as("seal %s must verify after the round trip", seal)
+ .isTrue();
+ // and the CROSS control even here: the other scheme's key must refuse this signature
+ final SealScheme celalalt =
+ seal.getSchemeWireId() == FALCON ? SealSchemes.SLH_DSA_128S : SealSchemes.FALCON_512;
+ final byte[] pkStrain =
+ seal.getSchemeWireId() == FALCON ? slh.publicRegistryForm() : falcon.publicRegistryForm();
+ assertThat(celalalt.verifyRaw(pkStrain, message, seal.getSignature().toArray())).isFalse();
+ }
+ }
+}
diff --git a/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqArmingGateTest.java b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqArmingGateTest.java
new file mode 100755
index 000000000..73c50cace
--- /dev/null
+++ b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqArmingGateTest.java
@@ -0,0 +1,387 @@
+/*
+ * Copyright contributors to Besu / AERE Network.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.common.bft;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatCode;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+import java.lang.reflect.Field;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.List;
+import java.util.Properties;
+import java.util.stream.Collectors;
+
+import org.apache.tuweni.bytes.Bytes;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+
+/**
+ * D-146, THE LINE THAT WAS MISSING. {@code PqRegistryHash.requireBindingsOrThrow} was delivered on
+ * 2026-08-06 with its own tests, and nothing called it. Its own javadoc said so: "NOT WIRED YET ...
+ * the call belongs beside AERE-PQC-REG-ARM-01 in FalconSealSupport, which is being edited by another
+ * stream". This class measures the wire.
+ *
+ * <p>WHAT THE WIRE BUYS, stated as the thing that is actually true. Before it, an ARMED node loaded
+ * a v1 registry without a word, and the registry decides who a Falcon seal is credited to. Measured
+ * on the real verification path on the same day: two rows with their public keys swapped - four
+ * distinct keys, four distinct addresses, so no uniqueness check would see anything - produced an
+ * ACCEPTED header; and the same key filed at two indices satisfied a threshold of two with one
+ * private key, which makes the threshold itself fiction.
+ *
+ * <p>WHY THE POSITIVE CONTROLS ARE THE EXPENSIVE HALF. A gate that refuses everything is not a gate,
+ * it is an outage wearing a security message. The tests that cost the most to get right here are the
+ * ones where the node STARTS: over a correct v2 registry, and over the very same v1 file when
+ * nothing is armed.
+ *
+ * <p>WHY THE ANCHOR CASE IS TESTED SEPARATELY FROM THE FORK-BLOCK CASE. They are different triggers
+ * and only one of them was previously guarded at all. {@code armingReadinessDiagnostic()} returns
+ * immediately when {@code aere.falcon.forkBlock} is unset, so AERE-PQC-REG-ARM-01 has never fired on
+ * a node armed through the certificate anchor. This guard fires on both, and {@link
+ * #armedThroughTheANCHORAloneTheNodeAlsoREFUSES} is the half that has no predecessor.
+ *
+ * <p>WHAT IS NOT MEASURED HERE, written rather than implied: nothing is deployed, no node is
+ * started, the fleet of seven is not touched, and every Falcon and ECDSA key below is a PROBE key
+ * generated in this JVM. Whether the refusal behaves the same on the seven real boxes at a
+ * coordinated restart is NOT MEASURED.
+ */
+public class PqArmingGateTest {
+
+ /** The height at which this fixture arms Falcon blocking. */
+ private static final long FORK = 7_000L;
+
+ /** Attachment must lead the fork block; the same shape PqForkArmingTest uses. */
+ private static final long ATTACH = 6_000L;
+
+ /** The chain id the registry is bound to. Not 2800: nothing here may look like the live fleet. */
+ private static final long CHAIN_ID = 220_878L;
+
+ /** The height the binding proofs are signed for. */
+ private static final long BIND_HEIGHT = FORK;
+
+ private static final int N = 4;
+
+ /** Every property this class is allowed to touch. Cleared before AND after every test. */
+ private static final List<String> OWNED_PROPERTIES =
+ List.of(
+ "aere.falcon.registry",
+ "aere.falcon.forkBlock",
+ "aere.falcon.attachBlock",
+ "aere.falcon.validatorCount",
+ "aere.falcon.testnetAllowSmallFleet",
+ PqAnchorConfig.PROPERTY_ANCHOR_BLOCK,
+ PqAnchorConfig.PROPERTY_CHAIN_ID,
+ PqAnchorConfig.PROPERTY_MIN_SEALS);
+
+ @TempDir private Path tmp;
+
+ @BeforeEach
+ public void setUp() throws Exception {
+ clearOwnedProperties();
+ forgetAnchorConfig();
+ resetFalconSingleton();
+ }
+
+ @AfterEach
+ public void tearDown() throws Exception {
+ clearOwnedProperties();
+ forgetAnchorConfig();
+ resetFalconSingleton();
+ }
+
+ // -------------------------------------------------------------------------------------------
+ // 1. THE FINDING, on each of the two arming triggers.
+ // -------------------------------------------------------------------------------------------
+
+ /** An armed node over a registry with no binding proofs must refuse to start. */
+ @Test
+ public void armedOverAV1RegistryTheNodeREFUSESToStart() throws Exception {
+ armWithForkBlock(writeRegistry("registry-v1.properties", false, false));
+
+ assertThatThrownBy(FalconSealSupport::instance)
+ .describedAs(
+ "a v1 registry decides attribution by whoever wrote the file; arming over it is "
+ + "permanent, because the anchor contract is immutable once written")
+ .isInstanceOf(PqRegistryHash.RegistryConfigException.class)
+ .hasMessageContaining("AERE-PQC-REG-ARM-02");
+ }
+
+ /**
+ * The same refusal when the node is armed through the CERTIFICATE ANCHOR and {@code
+ * aere.falcon.forkBlock} is not set at all.
+ *
+ * <p>This is the case with no predecessor. AERE-PQC-REG-ARM-01 is raised by {@code
+ * armingReadinessDiagnostic()}, whose first statement is to return when the fork block is unset,
+ * so an anchor-armed node has never been asked ANY question about its registry's shape at startup.
+ */
+ @Test
+ public void armedThroughTheANCHORAloneTheNodeAlsoREFUSES() throws Exception {
+ final Path v1 = writeRegistry("registry-v1.properties", false, false);
+ System.setProperty("aere.falcon.registry", v1.toAbsolutePath().toString());
+ armWithAnchorOnly();
+
+ assertThat(System.getProperty("aere.falcon.forkBlock"))
+ .describedAs("this test is only worth something while the fork block is genuinely unset")
+ .isNull();
+ assertThatThrownBy(FalconSealSupport::instance)
+ .isInstanceOf(PqRegistryHash.RegistryConfigException.class)
+ .hasMessageContaining("AERE-PQC-REG-ARM-02");
+ }
+
+ // -------------------------------------------------------------------------------------------
+ // 2. THE POSITIVE CONTROLS. Without these the refusals above could be a load bug.
+ // -------------------------------------------------------------------------------------------
+
+ /**
+ * The same node, the same arming, over a registry whose every row carries a Falcon possession
+ * proof and an ECDSA claim signed by that row's own validator key, STARTS - and loads.
+ */
+ @Test
+ public void armedOverAV2RegistryTheNodeSTARTS() throws Exception {
+ armWithForkBlock(writeRegistry("registry-v2.properties", true, true));
+
+ assertThatCode(FalconSealSupport::instance)
+ .describedAs(
+ "POSITIVE CONTROL: the gate can be green. A refusal that no correct input can pass is "
+ + "an outage wearing a security message")
+ .doesNotThrowAnyException();
+ assertThat(FalconSealSupport.instance().registrySize())
+ .describedAs("and it must really have loaded the file, not merely declined to throw")
+ .isEqualTo(N);
+ }
+
+ /** The same, armed through the anchor alone. */
+ @Test
+ public void armedThroughTheANCHORAloneOverAV2RegistryTheNodeSTARTS() throws Exception {
+ final Path v2 = writeRegistry("registry-v2.properties", true, true);
+ System.setProperty("aere.falcon.registry", v2.toAbsolutePath().toString());
+ armWithAnchorOnly();
+
+ assertThatCode(FalconSealSupport::instance).doesNotThrowAnyException();
+ assertThat(FalconSealSupport.instance().registrySize()).isEqualTo(N);
+ }
+
+ // -------------------------------------------------------------------------------------------
+ // 3. THE BOUNDARY. A node that arms NOTHING must be untouched by any of this.
+ // -------------------------------------------------------------------------------------------
+
+ /**
+ * THE GUARANTEE FOR CHAIN 2800 AS IT STANDS: a node with no {@code aere.pq.*} property and no
+ * {@code aere.falcon.forkBlock} starts over the very same v1 file that is refused when armed.
+ *
+ * <p>The assertion that carries the weight is not the "starts" - it is the property sweep. A test
+ * that only asserted "does not throw" would keep passing if a later edit made the guard read some
+ * other property that happened to be set in this JVM. The sweep states the precondition as a
+ * measurement: at the moment the constructor runs, NO system property beginning with {@code
+ * aere.pq.} exists, and neither does the fork block.
+ */
+ @Test
+ public void withNothingArmedTheGateIsInertOverTheSameV1Registry() throws Exception {
+ final Path v1 = writeRegistry("registry-v1.properties", false, false);
+ System.setProperty("aere.falcon.registry", v1.toAbsolutePath().toString());
+
+ assertThat(systemPropertiesStartingWith("aere.pq."))
+ .describedAs("the precondition of this test, measured rather than assumed")
+ .isEmpty();
+ assertThat(System.getProperty("aere.falcon.forkBlock")).isNull();
+
+ assertThatCode(FalconSealSupport::instance)
+ .describedAs(
+ "the same file that is refused when armed is accepted when nothing is armed, so the "
+ + "trigger is ARMING and not the file")
+ .doesNotThrowAnyException();
+ assertThat(FalconSealSupport.instance().registrySize())
+ .describedAs("and an unarmed node's registry is loaded exactly as it was before D-146")
+ .isEqualTo(N);
+ }
+
+ /**
+ * The same boundary with NO registry configured either, which is a node holding nothing at all -
+ * the shape of a fresh box joining the fleet before any key ceremony.
+ */
+ @Test
+ public void aNodeWithNoFalconConfigurationAtAllStarts() {
+ assertThat(systemPropertiesStartingWith("aere.pq.")).isEmpty();
+ assertThat(System.getProperty("aere.falcon.registry")).isNull();
+
+ assertThatCode(FalconSealSupport::instance).doesNotThrowAnyException();
+ }
+
+ /**
+ * An ARMED node with no registry file at all is deliberately NOT this guard's business, and this
+ * test is what stops that from being a silent decision.
+ *
+ * <p>D-146 is mis-ATTRIBUTION, which needs rows; an empty registry credits nobody. The condition
+ * is owned by AERE-PQC-CFG-UNSAFE-08 when the threshold is positive, and MEASURED here: with a
+ * threshold of zero, which is the warm-up regime the fleet is meant to arm INTO, the node starts.
+ * An earlier revision of this guard refused here, and the cost was exactly that - the intended
+ * activation procedure became unstartable.
+ */
+ @Test
+ public void armedWithNoRegistryAtAllAndAZeroThresholdTheNodeStarts() {
+ System.setProperty(PqAnchorConfig.PROPERTY_ANCHOR_BLOCK, Long.toString(FORK));
+ System.setProperty(PqAnchorConfig.PROPERTY_CHAIN_ID, Long.toString(CHAIN_ID));
+ System.setProperty(PqAnchorConfig.PROPERTY_MIN_SEALS, FORK + ":0");
+ System.setProperty("aere.falcon.validatorCount", Integer.toString(N));
+ System.setProperty("aere.falcon.testnetAllowSmallFleet", "true");
+
+ assertThatCode(FalconSealSupport::instance)
+ .describedAs("K=0 over an empty registry is the warm-up regime, not a D-146 defect")
+ .doesNotThrowAnyException();
+ }
+
+ // -------------------------------------------------------------------------------------------
+ // 4. HALF A v2 REGISTRY IS NOT A v2 REGISTRY.
+ // -------------------------------------------------------------------------------------------
+
+ /**
+ * A row that carries a Falcon possession proof and no ECDSA claim proves that SOMEBODY holds the
+ * key, and says nothing about which validator asked for it - which is the whole of D-146.
+ *
+ * <p>MEASURED, and the assertion was CHANGED to match the measurement rather than the other way
+ * round. The expectation written first was AERE-PQC-REG-ARM-02. What actually happens is a refusal
+ * one step EARLIER, at load, with AERE-PQC-REG-LOAD-21, because the loader counts proofs against
+ * claims and refuses a half-bound file before the arming gate ever sees it. That is the stronger
+ * of the two refusals - it holds whether or not the node is armed - so this is asserted on the
+ * code that actually fires.
+ */
+ @Test
+ public void possessionWithoutAClaimIsRefusedEarlierStillAtLoad() throws Exception {
+ armWithForkBlock(writeRegistry("registry-possession-only.properties", true, false));
+
+ assertThatThrownBy(FalconSealSupport::instance)
+ .describedAs(
+ "the attacker is the key holder, so a genuine possession proof over a lying row is "
+ + "genuinely produceable; only the validator's own signature closes it")
+ .isInstanceOf(PqRegistryHash.RegistryConfigException.class)
+ .hasMessageContaining("AERE-PQC-REG-LOAD-21");
+ }
+
+ // -------------------------------------------------------------------------------------------
+ // Helpers.
+ // -------------------------------------------------------------------------------------------
+
+ /** Arm through {@code aere.falcon.forkBlock}, the trigger AERE-PQC-REG-ARM-01 also watches. */
+ private void armWithForkBlock(final Path registry) {
+ System.setProperty("aere.falcon.registry", registry.toAbsolutePath().toString());
+ System.setProperty("aere.falcon.forkBlock", Long.toString(FORK));
+ System.setProperty("aere.falcon.attachBlock", Long.toString(ATTACH));
+ System.setProperty("aere.falcon.validatorCount", Integer.toString(N));
+ // N=4 is below the blocking minimum; this fixture is an isolated network and says so with the
+ // switch the codebase already uses for exactly that, rather than by pretending to be seven.
+ System.setProperty("aere.falcon.testnetAllowSmallFleet", "true");
+ }
+
+ /**
+ * Arm through the CERTIFICATE ANCHOR only, leaving {@code aere.falcon.forkBlock} unset. The
+ * threshold is 2, which {@code worstCaseKeyedSigners(4, 4)} = 3 guarantees, so the D-078 guard
+ * next door stays silent and cannot be mistaken for this one.
+ */
+ private void armWithAnchorOnly() {
+ System.setProperty(PqAnchorConfig.PROPERTY_ANCHOR_BLOCK, Long.toString(FORK));
+ System.setProperty(PqAnchorConfig.PROPERTY_CHAIN_ID, Long.toString(CHAIN_ID));
+ System.setProperty(PqAnchorConfig.PROPERTY_MIN_SEALS, FORK + ":0," + (FORK + 10L) + ":2");
+ System.setProperty("aere.falcon.validatorCount", Integer.toString(N));
+ System.setProperty("aere.falcon.testnetAllowSmallFleet", "true");
+ }
+
+ /**
+ * Write a registry in the legacy properties form. {@code withPossession} and {@code withClaim} are
+ * separate so that the half-bound case can be built, which is the one the loader must refuse.
+ */
+ private Path writeRegistry(
+ final String name, final boolean withPossession, final boolean withClaim) throws Exception {
+ final StringBuilder b = new StringBuilder();
+ if (withPossession || withClaim) {
+ b.append("formatVersion=").append(PqRegistryBinding.FORMAT_VERSION).append('\n');
+ b.append("chainId=").append(CHAIN_ID).append('\n');
+ b.append("bindHeight=").append(BIND_HEIGHT).append('\n');
+ }
+ b.append("count=").append(N).append('\n');
+ for (int i = 0; i < N; i++) {
+ b.append(i).append('=').append(unprefixed(PqV2Fixture.publicKey(i))).append('\n');
+ b.append(i)
+ .append(".addr=")
+ .append(unprefixed(PqV2Fixture.address(i).getBytes().toArray()))
+ .append('\n');
+ if (withPossession) {
+ b.append(i)
+ .append(".pop=")
+ .append(strip(PqV2Fixture.popHex(CHAIN_ID, BIND_HEIGHT, N, i)))
+ .append('\n');
+ }
+ if (withClaim) {
+ b.append(i)
+ .append(".claim=")
+ .append(strip(PqV2Fixture.claimHex(CHAIN_ID, BIND_HEIGHT, N, i)))
+ .append('\n');
+ }
+ }
+ final Path f = tmp.resolve(name);
+ Files.writeString(f, b.toString(), StandardCharsets.UTF_8);
+ return f;
+ }
+
+ private static String unprefixed(final byte[] b) {
+ return Bytes.wrap(b).toUnprefixedHexString();
+ }
+
+ private static String strip(final String hex) {
+ return hex.startsWith("0x") ? hex.substring(2) : hex;
+ }
+
+ /** Every system property name with the given prefix, so a precondition can be MEASURED. */
+ private static List<String> systemPropertiesStartingWith(final String prefix) {
+ final Properties p = System.getProperties();
+ return p.stringPropertyNames().stream()
+ .filter(n -> n.startsWith(prefix))
+ .sorted()
+ .collect(Collectors.toList());
+ }
+
+ private static void clearOwnedProperties() {
+ for (final String p : OWNED_PROPERTIES) {
+ System.clearProperty(p);
+ }
+ }
+
+ /**
+ * Force the anchor configuration to be re-read from system properties.
+ *
+ * <p>MEASURED 2026-08-06, and it is the reason this method exists rather than being assumed
+ * unnecessary. {@code PqAnchorProducer.config()} memoises the first configuration it ever builds,
+ * for the life of the JVM. That is CORRECT in production - a node is one JVM with one set of
+ * properties, and a configuration that could change underneath the consensus path would be worse
+ * than one that cannot. In a test JVM shared by every class in this module it means an anchor
+ * armed by an earlier test is still armed here, and {@link
+ * #withNothingArmedTheGateIsInertOverTheSameV1Registry} failed exactly that way before this call
+ * was added: the property sweep found no {@code aere.pq.*} and the node still refused, because
+ * the memo held another class's anchor.
+ */
+ private static void forgetAnchorConfig() {
+ org.hyperledger.besu.consensus.common.bft.blockcreation.PqAnchorProducer.useConfigForTesting(
+ null);
+ }
+
+ private static void resetFalconSingleton() throws Exception {
+ final Field f = FalconSealSupport.class.getDeclaredField("instance");
+ f.setAccessible(true);
+ f.set(null, null);
+ }
+}
diff --git a/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqCallerIntentTest.java b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqCallerIntentTest.java
new file mode 100755
index 000000000..3800bfef1
--- /dev/null
+++ b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqCallerIntentTest.java
@@ -0,0 +1,386 @@
+/*
+ * Copyright contributors to Besu / AERE Network.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.common.bft;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import org.hyperledger.besu.consensus.common.bft.blockcreation.PqAnchorProducer;
+import org.hyperledger.besu.datatypes.Address;
+
+import java.lang.reflect.Field;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.OptionalInt;
+
+import org.apache.tuweni.bytes.Bytes;
+import org.apache.tuweni.bytes.Bytes32;
+import org.bouncycastle.crypto.digests.KeccakDigest;
+import org.bouncycastle.pqc.crypto.falcon.FalconPrivateKeyParameters;
+import org.bouncycastle.pqc.crypto.falcon.FalconSigner;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+
+/**
+ * D2 HARDENING (b-v2). The repair of the repair: the caller's MOTIVE decides, not the height.
+ *
+ * <p>WHAT THE FIRST SHAPE DID, MEASURED AND NOT ARGUED. On 2026-08-06 hardening (b) refused every
+ * unbound height at or above the arming height, deciding from the block NUMBER alone. Run against
+ * the suite that gave 588 tests and 0 failures on a clean tree, it gave 597 tests and 6 failures:
+ * five in {@code PqSealPersistenceTest} and one in {@code PqForkValidatorSetChangeTest}. Both
+ * classes work on THIS NODE'S OWN head - restarting and re-reading its own seal file, and proposing
+ * on top of its own head - and in all six the number handed to the guard was 1030 with an arming
+ * height of 1000. A genuinely historical question, in the same process in the same second, hands
+ * the guard exactly those numbers too. No arithmetic on the height separates them.
+ *
+ * <p>THE OPERATIONAL CONSEQUENCE, in the words of the D078 failure itself: {@code refusing to
+ * propose on top of block 1030 because this node holds 0 valid eligible Falcon seal(s)}. The first
+ * shape turned a defect that is invisible on a running fleet and fatal only to a node syncing later
+ * into one that stops block production on all seven, in the minute the anchor is armed.
+ *
+ * <p>WHAT SEPARATES THEM IS WHO SUPPLIES THE SUBJECT, and that is known at every call site and was
+ * being discarded at the interface boundary. So {@code PqSignerRegistry} now carries two named
+ * pairs, and the compiler forces every call site to say which question it is asking. This class is
+ * the proof that the two doors answer DIFFERENTLY at the SAME height, that the own-head door is not
+ * a loophole, and that the history door still refuses.
+ *
+ * <p>THIS CLASS CANNOT GO GREEN BY ACCIDENT. Three of its tests fail if the own-head door is made
+ * to refuse (which is the first shape restored), and three fail if the history door is made to
+ * answer (which is the pre-2026-08-06 defect restored). The two plants are run in opposite
+ * directions and both are recorded in the evidence directory.
+ */
+public class PqCallerIntentTest {
+
+ /** Anchor activation height H, matching the fixture the six failures ran under. */
+ private static final long H = 1_000L;
+
+ /** Height from which the staged threshold is non-zero, i.e. the fully armed regime. */
+ private static final long K_AT = H + 10L;
+
+ /**
+ * The height the six failures actually presented to the guard: this node's own head, above the
+ * arming height. Named for what it is, because the whole point is that the NUMBER is innocent.
+ */
+ private static final long OWN_HEAD = 1_030L;
+
+ /** A height far above H, standing in for "a year of history above the arming height". */
+ private static final long DEEP = K_AT + 5_000L;
+
+ private static final int N = 7;
+
+ private static final long CHAIN_ID = 220_878L;
+
+ @TempDir private Path tmp;
+
+ private final List<FalconPrivateKeyParameters> privateKeys = new ArrayList<>();
+ private final List<Address> validators = new ArrayList<>();
+ private Path genesisPath;
+
+ /** A fixed 32-byte message, standing in for M(parent) or a committed-seal hash. */
+ private static final Bytes32 MESSAGE = Bytes32.fromHexString("0x" + "5a".repeat(32));
+
+ private Bytes sealByIndexZero;
+
+ @BeforeEach
+ public void setUp() throws Exception {
+ // AERE D-146 (2026-08-06): a v2, PROOF-BOUND registry. It used to be v1 with addresses spelled
+ // 0xA00+i, which no secp256k1 key can sign for, so this fixture described a fleet that could
+ // never satisfy AERE-PQC-REG-ARM-02 once that guard was wired. The registry is bound at H, the
+ // height this fixture arms the anchor from.
+ final KeccakDigest kd = new KeccakDigest(256);
+ final StringBuilder manifest = new StringBuilder();
+ manifest
+ .append("{\"config\":{\"aereFalconRegistry\":{")
+ .append(PqV2Fixture.manifestHeader(N, CHAIN_ID, H));
+ for (int i = 0; i < N; i++) {
+ privateKeys.add(PqV2Fixture.privateKey(i));
+ validators.add(PqV2Fixture.address(i));
+ final byte[] anchoredRow = PqV2Fixture.anchorPreimageRow(i);
+ kd.update(anchoredRow, 0, anchoredRow.length);
+ manifest.append(',').append(PqV2Fixture.manifestEntry(i, N, CHAIN_ID, H));
+ }
+ manifest
+ .append("}},\"alloc\":{\"0000000000000000000000000000000000000fa1\":{\"storage\":{\"0x")
+ .append("0".repeat(64))
+ .append("\":\"0x");
+ final byte[] anchoredHash = new byte[32];
+ kd.doFinal(anchoredHash, 0);
+ manifest.append(Bytes.wrap(anchoredHash).toUnprefixedHexString()).append("\"}}}}");
+
+ genesisPath = tmp.resolve("genesis-d2v2.json");
+ Files.writeString(genesisPath, manifest.toString());
+ System.setProperty("aere.falcon.genesis", genesisPath.toAbsolutePath().toString());
+
+ final FalconSigner signer = new FalconSigner();
+ signer.init(true, privateKeys.get(0));
+ sealByIndexZero = Bytes.wrap(signer.generateSignature(MESSAGE.toArray()));
+
+ resetFalconSingleton();
+ // Exactly the montage the six failures ran under: armed at 1000, K staged at 1010, own head
+ // 1030, and NO config.pqRegistryHash anywhere - the state of every node on chain 2800 today.
+ PqAnchorProducer.useConfigForTesting(
+ new PqAnchorConfig(CHAIN_ID, H, Map.of(H, 0, K_AT, 3), OptionalInt.empty(), false));
+ }
+
+ @AfterEach
+ public void tearDown() throws Exception {
+ System.clearProperty("aere.falcon.genesis");
+ System.clearProperty("aere.pq.genesis");
+ System.clearProperty(FalconSealSupport.PROPERTY_REGISTRY_HISTORY);
+ resetFalconSingleton();
+ PqAnchorProducer.useConfigForTesting(null);
+ }
+
+ // -------------------------------------------------------------------------------------------
+ // 0. The fixture. Without this a green run below could mean the registry never loaded at all.
+ // -------------------------------------------------------------------------------------------
+
+ @Test
+ public void baselineTheFixtureIsGenesisAnchoredAndTheSealIsGENUINE() {
+ final FalconSealSupport pqc = FalconSealSupport.instance();
+ assertThat(pqc.genesisAnchored())
+ .describedAs("the fixture must load a GENESIS-ANCHORED registry, or nothing here means anything")
+ .isTrue();
+ assertThat(pqc.addressBound()).isTrue();
+ assertThat(pqc.verify(0, MESSAGE, sealByIndexZero))
+ .describedAs("the seal must be a REAL Falcon signature under the head registry")
+ .isTrue();
+ }
+
+ // -------------------------------------------------------------------------------------------
+ // 1. THE WHOLE REPAIR, IN ONE ASSERTION. Same height, same index, same signature, same instant.
+ // Two answers, because two different questions were asked.
+ // -------------------------------------------------------------------------------------------
+
+ @Test
+ public void theSameHeightGivesTwoAnswersBecauseTheQUESTIONSDIFFER() {
+ final FalconSealSupport pqc = FalconSealSupport.instance();
+
+ assertThat(pqc.verifyAtHistoric(OWN_HEAD, 0, MESSAGE, sealByIndexZero))
+ .describedAs(
+ "HISTORY door at 1030, armed from 1000, no schedule: a node judging somebody else's "
+ + "header cannot say which keys were in force there, so it REFUSES. Answering from "
+ + "the head registry here is D2/T2 verbatim")
+ .isFalse();
+
+ assertThat(pqc.verifyAtOwnHead(OWN_HEAD, 0, MESSAGE, sealByIndexZero))
+ .describedAs(
+ "OWN-HEAD door, SAME height, SAME seal, same instant: this node's own head, where the "
+ + "head registry IS the answer by construction. Refusing here is what stopped the "
+ + "proposer and the restart path on 2026-08-06, and it bought no security: the "
+ + "certificate is re-checked by the other six through the history door")
+ .isTrue();
+
+ assertThat(pqc.addressForIndexAtHistoric(OWN_HEAD, 0))
+ .describedAs("the address halves must split the same way, or R2 and the producer disagree")
+ .isNull();
+ assertThat(pqc.addressForIndexAtOwnHead(OWN_HEAD, 0)).isEqualTo(validators.get(0));
+ }
+
+ // -------------------------------------------------------------------------------------------
+ // 2. The restart path, which is five of the six failures. PqSealStore has already forced the
+ // stored block number and hash to equal this node's head before it asks.
+ // -------------------------------------------------------------------------------------------
+
+ @Test
+ public void theRESTARTPathAnswersAtAnArmedHeightWithNoSchedule() {
+ final FalconSealSupport pqc = FalconSealSupport.instance();
+ assertThat(pqc.verifyAtOwnHead(OWN_HEAD, 0, MESSAGE, sealByIndexZero))
+ .describedAs(
+ "PqSealPersistenceTest restored 0 of 3 genuine seals under the first shape. A node "
+ + "that cannot re-read its own seal file after a restart is a node that cannot "
+ + "propose, and the file is the documented way out of the D-141 deadlock")
+ .isTrue();
+ assertThat(pqc.addressForIndexAtOwnHead(OWN_HEAD, 0))
+ .describedAs("and the index must bind, or every stored seal is dropped as unknown")
+ .isEqualTo(validators.get(0));
+ }
+
+ // -------------------------------------------------------------------------------------------
+ // 3. The proposer path, the sixth failure. PqAnchorProducer resolves at the PARENT's height,
+ // and the parent is this node's own head.
+ // -------------------------------------------------------------------------------------------
+
+ @Test
+ public void thePROPOSERPathAnswersAtAnArmedHeightWithNoSchedule() {
+ final FalconSealSupport pqc = FalconSealSupport.instance();
+ for (int i = 0; i < 5; i++) {
+ final FalconSigner s = new FalconSigner();
+ s.init(true, privateKeys.get(i));
+ final Bytes sealI = Bytes.wrap(s.generateSignature(MESSAGE.toArray()));
+ assertThat(pqc.verifyAtOwnHead(OWN_HEAD, i, MESSAGE, sealI))
+ .describedAs(
+ "all K=5 genuine seals must resolve, or PqAnchorProducer throws "
+ + "PqAnchorNotReadyException with '5 were not eligible signers' and the node "
+ + "stops producing blocks - which is exactly what was measured")
+ .isTrue();
+ assertThat(pqc.addressForIndexAtOwnHead(OWN_HEAD, i)).isEqualTo(validators.get(i));
+ }
+ }
+
+ // -------------------------------------------------------------------------------------------
+ // 4. THE OWN-HEAD DOOR IS NOT A LOOPHOLE. This is the assertion that has to hold for the form to
+ // be worth anything: a configured epoch this node does NOT hold fails closed on BOTH doors.
+ // -------------------------------------------------------------------------------------------
+
+ @Test
+ public void theOwnHeadDoorIsNOTALoopholeAnUnheldEpochIsRefusedOnBOTHDOORS() throws Exception {
+ final FalconSealSupport pqc = FalconSealSupport.instance();
+ final PqRegistryHash.Registry held = PqRegistryHash.loadAuto(genesisPath);
+ final String hash = PqRegistryHash.hashFor(held, CHAIN_ID);
+ final long rotation = K_AT + 1_000L;
+
+ final Map<Long, String> entries = new LinkedHashMap<>();
+ entries.put(H, hash);
+ entries.put(rotation, "0x" + "cd".repeat(32));
+ pqc.verifyRegistryBindingOrAbort(0L, CHAIN_ID, scheduleFromGenesis(entries));
+
+ assertThat(pqc.verifyAtOwnHead(rotation, 0, MESSAGE, sealByIndexZero))
+ .describedAs(
+ "a rotation the chain HAS scheduled and this node does NOT hold is not a missing "
+ + "binding, it is a node running a registry the chain has moved off. If the "
+ + "own-head door answered here it would be a way to sign blocks under a retired "
+ + "key set, and the split would have bought a liveness fix at the price of the "
+ + "property the whole anchor exists for")
+ .isFalse();
+ assertThat(pqc.addressForIndexAtOwnHead(rotation, 0)).isNull();
+
+ assertThat(pqc.verifyAtHistoric(rotation, 0, MESSAGE, sealByIndexZero))
+ .describedAs("and the history door refuses identically")
+ .isFalse();
+
+ assertThat(pqc.verifyAtOwnHead(rotation - 1L, 0, MESSAGE, sealByIndexZero))
+ .describedAs("positive control: below the rotation this node holds the epoch and answers")
+ .isTrue();
+ assertThat(pqc.verifyAtHistoric(rotation - 1L, 0, MESSAGE, sealByIndexZero)).isTrue();
+ }
+
+ // -------------------------------------------------------------------------------------------
+ // 5. Negative control on the split itself: with the binding CONFIGURED, the two doors converge.
+ // If they do not, the own-head door is not a fallback rule, it is a second key set.
+ // -------------------------------------------------------------------------------------------
+
+ @Test
+ public void withTheScheduleConfiguredBOTHDOORSGiveTheSameAnswer() throws Exception {
+ final FalconSealSupport pqc = FalconSealSupport.instance();
+ final PqRegistryHash.Registry held = PqRegistryHash.loadAuto(genesisPath);
+ final Map<Long, String> entries = new LinkedHashMap<>();
+ // AERE D-146 (2026-08-06): hashFor, not hashV1. A schedule entry has to carry the canonical
+ // hash OF THE REGISTRY IT NAMES, and this fixture's registry is now v2, which hashes under a
+ // different domain tag. MEASURED: leaving hashV1 here made the entry name a registry nobody
+ // holds, and the height-resolved lookups fell through to a refusal - a green test turning red
+ // for a reason that had nothing to do with what it measures. This is the same breakage a real
+ // genesis takes: any config.pqRegistryHash computed before the registry was rebuilt as v2
+ // stops matching the moment it is rebuilt.
+ entries.put(H, PqRegistryHash.hashFor(held, CHAIN_ID));
+ pqc.verifyRegistryBindingOrAbort(0L, CHAIN_ID, scheduleFromGenesis(entries));
+
+ for (final long h : new long[] {H - 1L, H, OWN_HEAD, DEEP}) {
+ assertThat(pqc.verifyAtHistoric(h, 0, MESSAGE, sealByIndexZero))
+ .describedAs(
+ "at height "
+ + h
+ + " with the epoch bound at the arming height, the history door resolves through "
+ + "the SCHEDULE, not through any fallback")
+ .isTrue();
+ assertThat(pqc.verifyAtOwnHead(h, 0, MESSAGE, sealByIndexZero))
+ .describedAs(
+ "and the own-head door gives the SAME answer at height "
+ + h
+ + ". The two doors differ only in what they do when NOTHING binds the height. If "
+ + "they differed with a binding in force, the split would have introduced a "
+ + "second key set rather than a second failure mode")
+ .isTrue();
+ assertThat(pqc.addressForIndexAtHistoric(h, 0)).isEqualTo(pqc.addressForIndexAtOwnHead(h, 0));
+ }
+ }
+
+ // -------------------------------------------------------------------------------------------
+ // 6. The live fleet is untouched. aere.pq.anchorBlock is unset on all seven today, so there is
+ // no arming height, and BOTH doors answer exactly as they did before either hardening.
+ // -------------------------------------------------------------------------------------------
+
+ @Test
+ public void whenTheAnchorIsNotArmedBOTHDOORSAnswerAndNOTHINGCHANGES() {
+ PqAnchorProducer.useConfigForTesting(PqAnchorConfig.never(CHAIN_ID));
+ final FalconSealSupport pqc = FalconSealSupport.instance();
+ assertThat(pqc.verifyAtHistoric(DEEP, 0, MESSAGE, sealByIndexZero)).isTrue();
+ assertThat(pqc.verifyAtOwnHead(DEEP, 0, MESSAGE, sealByIndexZero)).isTrue();
+ assertThat(pqc.addressForIndexAtHistoric(DEEP, 0)).isEqualTo(validators.get(0));
+ assertThat(pqc.addressForIndexAtOwnHead(DEEP, 0)).isEqualTo(validators.get(0));
+ }
+
+ // -------------------------------------------------------------------------------------------
+ // 7. Below the arming height nothing is being judged, so both doors answer. This is the
+ // assertion that goes red first if anybody makes the history door refuse unconditionally.
+ // -------------------------------------------------------------------------------------------
+
+ @Test
+ public void belowTheArmingHeightBOTHDOORSAnswer() {
+ final FalconSealSupport pqc = FalconSealSupport.instance();
+ assertThat(pqc.verifyAtHistoric(H - 1L, 0, MESSAGE, sealByIndexZero)).isTrue();
+ assertThat(pqc.verifyAtOwnHead(H - 1L, 0, MESSAGE, sealByIndexZero)).isTrue();
+ assertThat(pqc.verifyAtHistoric(0L, 0, MESSAGE, sealByIndexZero)).isTrue();
+ assertThat(pqc.addressForIndexAtHistoric(H - 1L, 0)).isEqualTo(validators.get(0));
+ assertThat(pqc.addressForIndexAtOwnHead(H - 1L, 0)).isEqualTo(validators.get(0));
+ }
+
+ // -------------------------------------------------------------------------------------------
+ // Helpers.
+ // -------------------------------------------------------------------------------------------
+
+ /**
+ * Build a schedule the way a node really gets one: written into a genesis file as {@code
+ * config.pqRegistryHash} and parsed back, so the strictly-increasing rule in the parser is on the
+ * path rather than bypassed.
+ *
+ * @param entries height to 0x-prefixed registry hash, in ascending order of height
+ * @return the parsed schedule
+ * @throws Exception when the temporary genesis cannot be written
+ */
+ private PqRegistryHash.Schedule scheduleFromGenesis(final Map<Long, String> entries)
+ throws Exception {
+ final List<Long> heights = new ArrayList<>(entries.keySet());
+ heights.sort(Long::compare);
+ final StringBuilder sb = new StringBuilder("{\"config\":{\"pqRegistryHash\":[");
+ for (int i = 0; i < heights.size(); i++) {
+ if (i > 0) {
+ sb.append(',');
+ }
+ final long b = heights.get(i);
+ String h = entries.get(b);
+ if (!h.startsWith("0x")) {
+ h = "0x" + h;
+ }
+ sb.append("{\"block\":").append(b).append(",\"hash\":\"").append(h).append("\"}");
+ }
+ sb.append("]}}");
+ final Path p =
+ tmp.resolve("genesis-schedule-v2-" + heights.size() + "-" + heights.get(0) + ".json");
+ Files.writeString(p, sb.toString());
+ return PqRegistryHash.loadScheduleFromGenesis(p);
+ }
+
+ private static void resetFalconSingleton() throws Exception {
+ final Field f = FalconSealSupport.class.getDeclaredField("instance");
+ f.setAccessible(true);
+ f.set(null, null);
+ }
+}
diff --git a/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqFleetRestartArmingTest.java b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqFleetRestartArmingTest.java
new file mode 100755
index 000000000..aa60447bb
--- /dev/null
+++ b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqFleetRestartArmingTest.java
@@ -0,0 +1,411 @@
+/*
+ * Copyright contributors to Besu / AERE Network.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.common.bft;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import org.hyperledger.besu.crypto.SecureRandomProvider;
+import org.hyperledger.besu.datatypes.Address;
+
+import java.lang.reflect.Field;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.security.SecureRandom;
+
+import org.apache.tuweni.bytes.Bytes;
+import org.bouncycastle.crypto.AsymmetricCipherKeyPair;
+import org.bouncycastle.crypto.digests.KeccakDigest;
+import org.bouncycastle.pqc.crypto.falcon.FalconKeyGenerationParameters;
+import org.bouncycastle.pqc.crypto.falcon.FalconKeyPairGenerator;
+import org.bouncycastle.pqc.crypto.falcon.FalconParameters;
+import org.bouncycastle.pqc.crypto.falcon.FalconPrivateKeyParameters;
+import org.bouncycastle.pqc.crypto.falcon.FalconPublicKeyParameters;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+
+/**
+ * D-140. THE FLEET-RESTART DEADLOCK, AND THE STATE MACHINE THE REPAIR MOVES.
+ *
+ * <p>MEASURED FIRST, ON A NETWORK, NOT ASSUMED. The full activation rehearsal on a seven-node test
+ * network (repetitie-activare-2026-08-05) found that with the anchor armed at K&gt;0 a SIMULTANEOUS
+ * restart of every validator stops the chain for good. The node said it verbatim: "refusing to
+ * propose ... holds 0 valid eligible Falcon seal(s) ... threshold is 3", over "Attachment stays OFF
+ * (fail-safe)".
+ *
+ * <p>THE CIRCLE. {@code activateLateAnchor()} used to be reachable from exactly one place, {@code
+ * FalconSealValidationRule.tryActivateLateAnchor}, which runs only while a block is being IMPORTED.
+ * After a fleet restart no block is imported, because nobody proposes. So {@code lateActivated}
+ * stays false, {@link FalconSealSupport#attachmentArmed(long)} answers false, no seal is attached,
+ * no certificate reaches K, and nobody can propose. Seals come from Commits, Commits come from
+ * proposals, proposals need seals. With K=0 the chain heals itself. With K&gt;0 it never does.
+ *
+ * <p>WHAT THIS CLASS MEASURES, and it is the state machine the repair moves, not a paraphrase of
+ * it. The repair (QbftBesuControllerBuilder, marker "AERE BLOCAJ-REPORNIRE") adds a SECOND caller of
+ * the SAME method at startup, reading the SAME contract slot 0 out of the chain-head world state.
+ * So the question that decides whether the repair can work is exactly: does calling {@code
+ * activateLateAnchor} with the on-chain hash, with no block imported and no other stimulus, turn
+ * {@code attachmentArmed()} from false to true. Below, it does.
+ *
+ * <ol>
+ * <li>{@link #restartedFleetIsNotArmedAndDoesNotHealWithTime()} - the deadlock state itself. A
+ * node whose late anchor is PENDING is past its attachment height and still refuses to
+ * attach, at that height and at every height after it. Nothing in the process flips it.
+ * <li>{@link #activatingFromTheChainHeadArmsAttachment()} - the repair's mechanism. One call with
+ * the on-chain hash, and attachment is armed. This is the ONLY thing the startup code adds.
+ * <li>{@link #aWrongOnChainHashLeavesAttachmentOffAndIsTerminal()} - THE NEGATIVE CONTROL. If the
+ * hash does not match, activation must FAIL and attachment must stay OFF: the repair must not
+ * have bought liveness by weakening the tamper check. It also stays terminally failed, so a
+ * later correct hash does not resurrect it.
+ * <li>{@link #activationIsIdempotentAcrossRepeatedStartupCalls()} - the scope control. The
+ * startup call and the import-path call can both fire in one process; the second must be a
+ * no-op rather than a second registry load.
+ * <li>{@link #aGenesisAnchoredNodeIsArmedImmediatelyAfterRestart()} - the rehearsal's own
+ * stimulus replayed against THIS tree, and it does not fail the way the network did. Read its
+ * javadoc: the rehearsal binary predates D-078, and the line it logged came from a condition
+ * this tree no longer contains.
+ * </ol>
+ *
+ * <p>NOT MEASURED here, and named so it is not read as covered: that a real Besu process reads slot
+ * 0 out of a real chain-head world state (that is world-state plumbing in the app module, and the
+ * rehearsal network is the instrument for it), and that seven live nodes recover from a real
+ * simultaneous restart with this binary. This class measures the decision the deadlock hinges on.
+ */
+// The D-140 label is our internal finding id. It names a fact about this
+// code, not anything outside it.
+public class PqFleetRestartArmingTest {
+
+ /**
+ * Fleet size for THIS fixture. Not a statement about any live network: the 2026-08-05 decision
+ * to stay at seven was reversed, and the set has been nine since 2026-08-12. Seven is kept here
+ * because it is the size at which the margin arithmetic this class exercises is tightest.
+ */
+ private static final int N = 7;
+
+ /** Height at which the anchor contract is expected to be observable. */
+ private static final long OBSERVE = 1_000L;
+
+ /** Seal-attachment height, at or after OBSERVE. */
+ private static final long ATTACH = 1_200L;
+
+ /** A chain head well past the attachment height: this is what a restart comes back to. */
+ private static final long HEAD = 5_000L;
+
+ private static final String ANCHOR_ADDRESS = "0x0000000000000000000000000000000000000fa1";
+
+ @TempDir private Path tmp;
+
+ /** keccak256 over (addr20 || pk) for every index in order: what the anchor contract holds. */
+ private String onChainHash;
+
+ /** The same registry, spelled as a GENESIS-anchored manifest (the rehearsal's own shape). */
+ private Path genesisPath;
+
+ @BeforeEach
+ public void setUp() throws Exception {
+ // DATED 2026-08-20. This class never arms the certificate anchor, but FalconSealSupport's
+ // constructor consults it (anchorArmedFrom() -> PqAnchorProducer.config(), a per-JVM cache):
+ // a neighbouring test class that leaves an ARMED anchor config cached in this JVM turns every
+ // proof-less fixture below into an AERE-PQC-REG-ARM-02 refusal. Measured on the production
+ // tree that day: this class ALONE 5/5 green, inside the full suite the same 5 red, identical
+ // sources -- the 2026-08-11 order-luck lesson verbatim ("clearing the properties does not
+ // clear the caches"). The defence belongs to the consumer: start from an unarmed anchor,
+ // cache and properties both.
+ for (final String p : System.getProperties().stringPropertyNames()) {
+ if (p.startsWith("aere.pq.")) {
+ System.clearProperty(p);
+ }
+ }
+ org.hyperledger.besu.consensus.common.bft.blockcreation.PqAnchorProducer.useConfigForTesting(
+ null);
+ resetFalconSingleton();
+
+ final SecureRandom rnd = SecureRandomProvider.createSecureRandom();
+ final KeccakDigest kd = new KeccakDigest(256);
+ final StringBuilder manifest = new StringBuilder("{\"count\":").append(N);
+ final StringBuilder genesis =
+ new StringBuilder("{\"config\":{\"aereFalconRegistry\":{\"count\":").append(N);
+ for (int i = 0; i < N; i++) {
+ final FalconKeyPairGenerator gen = new FalconKeyPairGenerator();
+ gen.init(new FalconKeyGenerationParameters(rnd, FalconParameters.falcon_512));
+ final AsymmetricCipherKeyPair kp = gen.generateKeyPair();
+ final FalconPublicKeyParameters pub = (FalconPublicKeyParameters) kp.getPublic();
+ final FalconPrivateKeyParameters priv = (FalconPrivateKeyParameters) kp.getPrivate();
+ final Address addr = Address.fromHexString(String.format("0x%040x", 0xA00 + i));
+
+ // The pre-image is accumulated in lockstep with the manifest text, exactly the way a real
+ // anchoring transaction is built, so the hash below is not copied out of the code under test.
+ final byte[] addrBytes = addr.getBytes().toArray();
+ kd.update(addrBytes, 0, addrBytes.length);
+ kd.update(pub.getH(), 0, pub.getH().length);
+
+ final String entry =
+ ",\""
+ + i
+ + "\":{\"addr\":\""
+ + addr.toHexString()
+ + "\",\"pk\":\""
+ + Bytes.wrap(pub.getH()).toHexString()
+ + "\"}";
+ manifest.append(entry);
+ genesis.append(entry);
+
+ if (i == 0) {
+ // This node is validator 0 and HOLDS a signing key, otherwise attachment is off for a
+ // reason that has nothing to do with the deadlock and the measurement would be vacuous.
+ final Path key0 = tmp.resolve("falcon-key-0.properties");
+ Files.writeString(
+ key0,
+ "index=0\n"
+ + "f="
+ + Bytes.wrap(priv.getSpolyf()).toHexString()
+ + "\n"
+ + "g="
+ + Bytes.wrap(priv.getG()).toHexString()
+ + "\n"
+ + "F="
+ + Bytes.wrap(priv.getSpolyF()).toHexString()
+ + "\n"
+ + "pk="
+ + Bytes.wrap(pub.getH()).toHexString()
+ + "\n");
+ System.setProperty("aere.falcon.key", key0.toAbsolutePath().toString());
+ }
+ }
+ manifest.append("}");
+
+ final byte[] digest = new byte[32];
+ kd.doFinal(digest, 0);
+ onChainHash = Bytes.wrap(digest).toUnprefixedHexString();
+
+ final Path manifestPath = tmp.resolve("falcon-late-manifest.json");
+ Files.writeString(manifestPath, manifest.toString());
+
+ // Same seven entries, anchored the way the rehearsal network anchored them: in genesis, with
+ // the hash committed in the anchor contract's slot 0 through alloc storage.
+ genesis
+ .append("}},\"alloc\":{\"0000000000000000000000000000000000000fa1\":{\"storage\":{\"0x")
+ .append("0".repeat(64))
+ .append("\":\"0x")
+ .append(onChainHash)
+ .append("\"}}}}");
+ genesisPath = tmp.resolve("genesis-registry.json");
+ Files.writeString(genesisPath, genesis.toString());
+
+ System.setProperty("aere.falcon.manifest", manifestPath.toAbsolutePath().toString());
+ System.setProperty("aere.falcon.anchor.address", ANCHOR_ADDRESS);
+ System.setProperty("aere.falcon.anchor.block", Long.toString(OBSERVE));
+ System.setProperty("aere.falcon.attachBlock", Long.toString(ATTACH));
+ System.setProperty("aere.falcon.validatorCount", Integer.toString(N));
+ }
+
+ @AfterEach
+ public void tearDown() throws Exception {
+ for (final String p :
+ new String[] {
+ "aere.falcon.manifest",
+ "aere.falcon.genesis",
+ "aere.falcon.key",
+ "aere.falcon.anchor.address",
+ "aere.falcon.anchor.block",
+ "aere.falcon.attachBlock",
+ "aere.falcon.forkBlock",
+ "aere.falcon.validatorCount"
+ }) {
+ System.clearProperty(p);
+ }
+ resetFalconSingleton();
+ }
+
+ // -------------------------------------------------------------------------------------------
+ // 1. The deadlock state, stated as a property.
+ // -------------------------------------------------------------------------------------------
+
+ @Test
+ public void restartedFleetIsNotArmedAndDoesNotHealWithTime() {
+ final FalconSealSupport pqc = FalconSealSupport.instance();
+
+ assertThat(pqc.lateAnchorPending())
+ .describedAs(
+ "fixture control: the late-anchor manifest must LOAD and stay PENDING, or every "
+ + "assertion below is about a registry that was never configured")
+ .isTrue();
+ assertThat(pqc.lateAnchored()).isFalse();
+ assertThat(pqc.lateAnchorFailed()).isFalse();
+ assertThat(pqc.signingEnabled())
+ .describedAs("fixture control: this node holds a Falcon key, so attachment is not off for "
+ + "the trivial reason")
+ .isTrue();
+ assertThat(pqc.attachBlock()).isEqualTo(ATTACH);
+
+ // This IS the post-restart state: the process has just started, the chain head is far past the
+ // attachment height, and no block has been imported because nobody has proposed one.
+ assertThat(pqc.attachmentArmed(HEAD))
+ .describedAs(
+ "the measured deadlock: attachment height long since passed, registry still pending, "
+ + "so no seal is attached and no certificate can ever reach K")
+ .isFalse();
+
+ // And it does not heal. Time, and blocks that are never imported, change nothing.
+ for (long n = HEAD; n <= HEAD + 10_000L; n += 1_000L) {
+ assertThat(pqc.attachmentArmed(n))
+ .describedAs("still not armed at height %s; nothing in the process flips it", n)
+ .isFalse();
+ }
+ assertThat(pqc.registrySize())
+ .describedAs("the registry is EMPTY while pending, which is why a seal cannot verify either")
+ .isZero();
+ }
+
+ // -------------------------------------------------------------------------------------------
+ // 2. The repair's mechanism: the SECOND caller, the one startup adds.
+ // -------------------------------------------------------------------------------------------
+
+ @Test
+ public void activatingFromTheChainHeadArmsAttachment() {
+ final FalconSealSupport pqc = FalconSealSupport.instance();
+ assertThat(pqc.attachmentArmed(HEAD)).isFalse();
+
+ // Exactly what the startup repair does: hand over the 32-byte value read from the anchor
+ // contract's slot 0 in the CHAIN-HEAD world state. No block is imported anywhere here.
+ final boolean activated = pqc.activateLateAnchor(onChainHash);
+
+ assertThat(activated).isTrue();
+ assertThat(pqc.lateAnchored()).isTrue();
+ assertThat(pqc.lateAnchorPending()).isFalse();
+ assertThat(pqc.registrySize()).isEqualTo(N);
+ assertThat(pqc.addressBound())
+ .describedAs("the activated registry must bind every index to an address, or a seal cannot "
+ + "be resolved to a signer")
+ .isTrue();
+ assertThat(pqc.attachmentArmed(HEAD))
+ .describedAs(
+ "THE REPAIR: one activation from chain-head state arms attachment, so a restarted "
+ + "validator emits Falcon-carrying Commits again, certificates reach K, and a "
+ + "proposer can propose. This is the edge the deadlock needed and did not have.")
+ .isTrue();
+ }
+
+ // -------------------------------------------------------------------------------------------
+ // 3. THE NEGATIVE CONTROL. The repair must not have bought liveness by weakening the check.
+ // -------------------------------------------------------------------------------------------
+
+ @Test
+ public void aWrongOnChainHashLeavesAttachmentOffAndIsTerminal() {
+ final FalconSealSupport pqc = FalconSealSupport.instance();
+
+ // One flipped nibble: a tampered anchor, or a wrong manifest shipped to this node.
+ final char first = onChainHash.charAt(0);
+ final String wrong = (first == '0' ? '1' : '0') + onChainHash.substring(1);
+ assertThat(wrong).isNotEqualTo(onChainHash).hasSize(64);
+
+ assertThat(pqc.activateLateAnchor(wrong))
+ .describedAs("a mismatching anchor must NOT activate the registry")
+ .isFalse();
+ assertThat(pqc.lateAnchored()).isFalse();
+ assertThat(pqc.lateAnchorFailed())
+ .describedAs("and the mismatch must be TERMINAL, not merely 'not yet'")
+ .isTrue();
+ assertThat(pqc.registrySize())
+ .describedAs("the registry stays EMPTY: fail-closed, not fail-open")
+ .isZero();
+ assertThat(pqc.attachmentArmed(HEAD))
+ .describedAs(
+ "attachment stays OFF after a failed activation. If this were true, the startup repair "
+ + "would have turned a tamper detection into an arming path.")
+ .isFalse();
+
+ // And the correct hash afterwards does not resurrect it: a node that has seen a tampered anchor
+ // stays refused, which is the same fail-closed rule the import path already had.
+ assertThat(pqc.activateLateAnchor(onChainHash)).isFalse();
+ assertThat(pqc.attachmentArmed(HEAD)).isFalse();
+ }
+
+ // -------------------------------------------------------------------------------------------
+ // 4. Scope control: two callers now exist in one process.
+ // -------------------------------------------------------------------------------------------
+
+ @Test
+ public void activationIsIdempotentAcrossRepeatedStartupCalls() {
+ final FalconSealSupport pqc = FalconSealSupport.instance();
+
+ assertThat(pqc.activateLateAnchor(onChainHash)).isTrue();
+ final int afterFirst = pqc.registrySize();
+
+ // The startup call has fired; the import path fires too, on the first block that arrives.
+ assertThat(pqc.activateLateAnchor(onChainHash)).isTrue();
+ assertThat(pqc.registrySize()).isEqualTo(afterFirst).isEqualTo(N);
+ assertThat(pqc.attachmentArmed(HEAD)).isTrue();
+
+ // Even a garbage hash after activation cannot un-arm it: activation is a one-way latch, so a
+ // second reader with a stale view cannot disarm a fleet that is already sealing.
+ assertThat(pqc.activateLateAnchor("00".repeat(32))).isTrue();
+ assertThat(pqc.lateAnchorFailed()).isFalse();
+ assertThat(pqc.attachmentArmed(HEAD)).isTrue();
+ }
+
+ // -------------------------------------------------------------------------------------------
+ // 5. The rehearsal's OWN stimulus, replayed against THIS tree. Read the note before trusting it.
+ // -------------------------------------------------------------------------------------------
+
+ /**
+ * The seven-node rehearsal ran a GENESIS-anchored registry, and the line it logged after the
+ * simultaneous restart was the COVERAGE one: "no validator set has been observed yet, so registry
+ * COVERAGE cannot be proven. Attachment stays OFF (fail-safe)". That condition does not exist in
+ * this tree: {@code grep} for it returns nothing, because D-078 (2026-08-02) removed the fleet
+ * question from the per-commit gate. The rehearsal binary was built from the 2026-08-01 tree,
+ * which still had it.
+ *
+ * <p>So this test states what is true HERE: a genesis-anchored node, freshly constructed, with no
+ * validator set observed and no block imported, IS armed. The rehearsal's measured deadlock is
+ * closed for the genesis-anchored path by a repair that already landed - and NOT by the startup
+ * repair this class is about.
+ *
+ * <p>Which is exactly why the startup repair is still needed: on the LATE-ANCHOR path, the one
+ * the live chain must use because it cannot be re-genesised, {@code lateActivated} is still set
+ * from one place only. Tests 1-3 measure that path.
+ *
+ * <p>NOT MEASURED: that seven live nodes on a genesis-anchored network recover from a
+ * simultaneous restart with a binary built from this tree.
+ */
+ @Test
+ public void aGenesisAnchoredNodeIsArmedImmediatelyAfterRestart() throws Exception {
+ System.clearProperty("aere.falcon.manifest");
+ System.clearProperty("aere.falcon.anchor.address");
+ System.clearProperty("aere.falcon.anchor.block");
+ System.setProperty("aere.falcon.genesis", genesisPath.toAbsolutePath().toString());
+ resetFalconSingleton();
+
+ final FalconSealSupport pqc = FalconSealSupport.instance();
+
+ assertThat(pqc.genesisAnchored())
+ .describedAs("fixture control: the genesis manifest must verify against the anchored hash")
+ .isTrue();
+ assertThat(pqc.registrySize()).isEqualTo(N);
+ assertThat(pqc.addressBound()).isTrue();
+ assertThat(pqc.attachmentArmed(HEAD))
+ .describedAs(
+ "a genesis-anchored node arms with NO validator set observed and NO block imported. "
+ + "The rehearsal's coverage condition is gone from this tree.")
+ .isTrue();
+ }
+
+ private static void resetFalconSingleton() throws Exception {
+ final Field f = FalconSealSupport.class.getDeclaredField("instance");
+ f.setAccessible(true);
+ f.set(null, null);
+ }
+}
diff --git a/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqForkArmingTest.java b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqForkArmingTest.java
new file mode 100755
index 000000000..f7276f91e
--- /dev/null
+++ b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqForkArmingTest.java
@@ -0,0 +1,370 @@
+/*
+ * Copyright contributors to Besu / AERE Network.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.common.bft;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+
+import java.lang.reflect.Field;
+import java.nio.file.Files;
+import java.nio.file.Path;
+
+import org.apache.tuweni.bytes.Bytes;
+import org.bouncycastle.crypto.digests.KeccakDigest;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+
+/**
+ * D-079. THE MEASUREMENT THAT DID NOT EXIST.
+ *
+ * <p>The registry entry reads: "a malformed forkBlock falls OPEN, with only a log line, and arming
+ * it at or before the anchor observation height passes undetected", and it carried {@code verifica:
+ * NICIUNA} since 18 July. This file is the command that can fail.
+ *
+ * <p>Both halves of the finding are about the SAME shape of defect, the one the Holesky Pectra
+ * incident of February 2025 made expensive for everybody: a fork-activation parameter that is wrong
+ * or absent does not stop the node, it changes what the node silently believes. Half one is the
+ * value itself. Half two is the ORDER between that value and the height at which the registry the
+ * value depends on becomes active.
+ *
+ * <p>WHAT EACH TEST MEASURES, and how each can fail:
+ *
+ * <ol>
+ * <li>{@link #controlAWellFormedLateAnchorConfigurationStarts()} - the fixture's own negative
+ * control. If the late-anchor manifest did not load, or the singleton were not really being
+ * rebuilt, every refusal below would be a refusal for the wrong reason.
+ * <li>{@link #aMalformedForkBlockRefusesToStart()} and {@link #aNegativeForkBlockRefusesToStart()}
+ * - the config-time half of the finding, at construction.
+ * <li>{@link #theForkBlockIsResolvedOnceAndCannotBeReopenedAfterStartup()} - the RESIDUAL half
+ * one. The startup guard only ever looked at the property once, but {@code forkBlock()}
+ * re-read the property on every call and fell back to "never blocking" with a log line on
+ * anything it could not parse. A guard that validates a value it does not then own is not a
+ * guard; this test drives that exact gap.
+ * <li>{@link #blockingOverAPendingAnchorWithNoDeclaredObservationHeightRefuses()} - half two. A
+ * blocking height is stated over a registry that is not active yet and whose activation
+ * height is nowhere stated, so nothing in the process can compare the two.
+ * <li>{@link #anAttachHeightBeforeTheObservationHeightRefuses()} and {@link
+ * #aForkHeightAtTheObservationHeightRefuses()} - half two on its own stimulus: the ordering
+ * is wrong and the node starts anyway.
+ * <li>{@link #aMalformedObservationHeightRefuses()} and {@link
+ * #aNegativeObservationHeightRefuses()} - the new value must fail closed like every other
+ * {@code aere.falcon.*} value. A half-fail-closed property set is worse than either extreme.
+ * <li>{@link #aGenesisAnchoredRegistryNeedsNoObservationHeight()} and {@link
+ * #anObservationHeightWithoutBlockingIsHarmless()} - the scope controls. A guard that refused
+ * every blocking configuration would pass every test above and be useless.
+ * </ol>
+ *
+ * <p>NOT MEASURED here, deliberately, and named so it is not mistaken for covered: whether a real
+ * Besu node process exits with a non-zero status when this exception is thrown. This class measures
+ * the decision, not the process. The exception is thrown from the constructor, on the same path as
+ * the guards that already abort, and nothing in this tree catches {@code
+ * FalconSealSupport.ActivationConfigException}.
+ */
+// The D-079 label is our internal finding id. It names a fact about this
+// code, not anything outside it.
+public class PqForkArmingTest {
+
+ /** Fleet size; nine, because the blocking guard refuses to arm below nine. */
+ private static final int N = 9;
+
+ /** Height at which the on-chain late-anchor registry contract is expected to be observed. */
+ private static final long OBSERVE = 5_000L;
+
+ /** Seal-attachment height: at or after OBSERVE, so a seal can actually be emitted. */
+ private static final long ATTACH = 6_000L;
+
+ /** Blocking height: at least minAttachLead (256) after ATTACH. */
+ private static final long FORK = 7_000L;
+
+ private static final String ANCHOR_ADDRESS = "0x0000000000000000000000000000000000000fa1";
+
+ /**
+ * AERE D-146: the chain this fixture's registries are BOUND to. Every proof commits to it, so it
+ * has to be stated rather than defaulted.
+ */
+ private static final long CHAIN_ID = 2_800L;
+
+ @TempDir private Path tmp;
+
+ private Path manifestPath;
+ private Path genesisPath;
+
+ @BeforeEach
+ public void setUp() throws Exception {
+ // AERE D-146 (2026-08-06): both registries below are v2 and PROOF-BOUND, bound at FORK, the
+ // height this fixture arms from. They used to carry addresses spelled 0xB00+i, which no
+ // secp256k1 key can sign for, so this whole fixture became unstartable the moment
+ // AERE-PQC-REG-ARM-02 was wired into the constructor.
+
+ // LATE-ANCHOR manifest: the registry is PENDING until the anchor contract is observed on chain.
+ final StringBuilder late = new StringBuilder("{");
+ late.append(PqV2Fixture.manifestHeader(N, CHAIN_ID, FORK));
+ for (int i = 0; i < N; i++) {
+ late.append(',').append(PqV2Fixture.manifestEntry(i, N, CHAIN_ID, FORK));
+ }
+ late.append("}");
+ manifestPath = tmp.resolve("falcon-late-manifest.json");
+ Files.writeString(manifestPath, late.toString());
+
+ // GENESIS-ANCHORED manifest: the registry is ACTIVE from block 0, so no observation height can
+ // exist and none may be demanded. Built exactly the way a real genesis is, hash included.
+ final KeccakDigest kd = new KeccakDigest(256);
+ final StringBuilder gen = new StringBuilder("{\"config\":{\"aereFalconRegistry\":{");
+ gen.append(PqV2Fixture.manifestHeader(N, CHAIN_ID, FORK));
+ for (int i = 0; i < N; i++) {
+ final byte[] anchoredRow = PqV2Fixture.anchorPreimageRow(i);
+ kd.update(anchoredRow, 0, anchoredRow.length);
+ gen.append(',').append(PqV2Fixture.manifestEntry(i, N, CHAIN_ID, FORK));
+ }
+ final byte[] anchoredHash = new byte[32];
+ kd.doFinal(anchoredHash, 0);
+ gen.append("}},\"alloc\":{\"0000000000000000000000000000000000000fa1\":{\"storage\":{\"0x")
+ .append("0".repeat(64))
+ .append("\":\"0x")
+ .append(Bytes.wrap(anchoredHash).toUnprefixedHexString())
+ .append("\"}}}}");
+ genesisPath = tmp.resolve("genesis-registry.json");
+ Files.writeString(genesisPath, gen.toString());
+
+ System.setProperty("aere.falcon.validatorCount", Integer.toString(N));
+ resetFalconSingleton();
+ }
+
+ @AfterEach
+ public void tearDown() throws Exception {
+ for (final String p :
+ new String[] {
+ "aere.falcon.manifest",
+ "aere.falcon.genesis",
+ "aere.falcon.anchor.address",
+ "aere.falcon.anchor.block",
+ "aere.falcon.attachBlock",
+ "aere.falcon.forkBlock",
+ "aere.falcon.validatorCount"
+ }) {
+ System.clearProperty(p);
+ }
+ resetFalconSingleton();
+ }
+
+ // -------------------------------------------------------------------------------------------
+ // 1. The fixture's own control.
+ // -------------------------------------------------------------------------------------------
+
+ @Test
+ public void controlAWellFormedLateAnchorConfigurationStarts() {
+ lateAnchor();
+ System.setProperty("aere.falcon.anchor.block", Long.toString(OBSERVE));
+ System.setProperty("aere.falcon.attachBlock", Long.toString(ATTACH));
+ System.setProperty("aere.falcon.forkBlock", Long.toString(FORK));
+
+ final FalconSealSupport pqc = FalconSealSupport.instance();
+ assertThat(pqc.lateAnchorPending())
+ .describedAs(
+ "the late-anchor manifest must load and stay PENDING, or every refusal below is a "
+ + "refusal about a registry that was never there")
+ .isTrue();
+ assertThat(pqc.forkBlock()).isEqualTo(FORK);
+ assertThat(pqc.attachBlock()).isEqualTo(ATTACH);
+ assertThat(pqc.forkBlock())
+ .describedAs(
+ "the ordering the guard exists to enforce, stated as a property: blocking arms strictly "
+ + "AFTER the height at which the registry it depends on can become active")
+ .isGreaterThan(OBSERVE);
+ }
+
+ // -------------------------------------------------------------------------------------------
+ // 2-3. Half one at config time.
+ // -------------------------------------------------------------------------------------------
+
+ @Test
+ public void aMalformedForkBlockRefusesToStart() {
+ lateAnchor();
+ System.setProperty("aere.falcon.anchor.block", Long.toString(OBSERVE));
+ System.setProperty("aere.falcon.attachBlock", Long.toString(ATTACH));
+ // The exact typo shape a human makes when copying a height out of a document.
+ System.setProperty("aere.falcon.forkBlock", "9_189_161");
+
+ assertThatThrownBy(FalconSealSupport::instance)
+ .describedAs(
+ "a malformed blocking height must ABORT, never degrade to never-blocking with a log line")
+ .isInstanceOf(FalconSealSupport.ActivationConfigException.class)
+ .hasMessageContaining("MALFORMED");
+ }
+
+ @Test
+ public void aNegativeForkBlockRefusesToStart() {
+ lateAnchor();
+ System.setProperty("aere.falcon.anchor.block", Long.toString(OBSERVE));
+ System.setProperty("aere.falcon.attachBlock", Long.toString(ATTACH));
+ System.setProperty("aere.falcon.forkBlock", "-1");
+
+ assertThatThrownBy(FalconSealSupport::instance)
+ .isInstanceOf(FalconSealSupport.ActivationConfigException.class)
+ .hasMessageContaining("negative");
+ }
+
+ // -------------------------------------------------------------------------------------------
+ // 4. Half one where it actually survived: the value was validated but never OWNED.
+ // -------------------------------------------------------------------------------------------
+
+ @Test
+ public void theForkBlockIsResolvedOnceAndCannotBeReopenedAfterStartup() {
+ lateAnchor();
+ System.setProperty("aere.falcon.anchor.block", Long.toString(OBSERVE));
+ System.setProperty("aere.falcon.attachBlock", Long.toString(ATTACH));
+ System.setProperty("aere.falcon.forkBlock", Long.toString(FORK));
+
+ final FalconSealSupport pqc = FalconSealSupport.instance();
+ assertThat(pqc.forkBlock()).isEqualTo(FORK);
+
+ // The startup guard has already run and passed. Nothing will run it again. If the accessor
+ // re-reads the property, then the ONE decision the whole PQC layer is gated on is a value that
+ // can still turn into "never blocking" at any moment, for any reason that leaves the property
+ // unparseable, and the only trace is one WARN line per call.
+ System.setProperty("aere.falcon.forkBlock", "not-a-number");
+ assertThat(pqc.forkBlock())
+ .describedAs(
+ "the blocking height must be resolved ONCE, at the boundary, and owned thereafter. A "
+ + "value that is validated at startup and re-parsed on every use is not validated.")
+ .isEqualTo(FORK);
+ }
+
+ // -------------------------------------------------------------------------------------------
+ // 5-7. Half two: the ORDER between the blocking height and the anchor observation height.
+ // -------------------------------------------------------------------------------------------
+
+ @Test
+ public void blockingOverAPendingAnchorWithNoDeclaredObservationHeightRefuses() {
+ lateAnchor();
+ System.setProperty("aere.falcon.attachBlock", Long.toString(ATTACH));
+ System.setProperty("aere.falcon.forkBlock", Long.toString(FORK));
+ // aere.falcon.anchor.block deliberately NOT set.
+
+ assertThatThrownBy(FalconSealSupport::instance)
+ .describedAs(
+ "with the registry still PENDING and no stated activation height, nothing in this "
+ + "process can compare the blocking height against the height at which the registry "
+ + "becomes usable, so the ordering error the finding names cannot be detected at all")
+ .isInstanceOf(FalconSealSupport.ActivationConfigException.class)
+ .hasMessageContaining("AERE-PQC-CFG-UNSAFE-06");
+ }
+
+ @Test
+ public void anAttachHeightBeforeTheObservationHeightRefuses() {
+ lateAnchor();
+ System.setProperty("aere.falcon.anchor.block", Long.toString(ATTACH + 1L));
+ System.setProperty("aere.falcon.attachBlock", Long.toString(ATTACH));
+ System.setProperty("aere.falcon.forkBlock", Long.toString(FORK));
+
+ assertThatThrownBy(FalconSealSupport::instance)
+ .describedAs(
+ "attachment before the registry can be active emits nothing, so the log-only soak "
+ + "window measures nothing and the blocking height arrives over a registry no node "
+ + "has ever produced a seal against")
+ .isInstanceOf(FalconSealSupport.ActivationConfigException.class)
+ .hasMessageContaining("AERE-PQC-CFG-UNSAFE-07");
+ }
+
+ @Test
+ public void aForkHeightAtTheObservationHeightRefuses() {
+ lateAnchor();
+ System.setProperty("aere.falcon.anchor.block", Long.toString(FORK));
+ System.setProperty("aere.falcon.attachBlock", Long.toString(ATTACH));
+ System.setProperty("aere.falcon.forkBlock", Long.toString(FORK));
+
+ assertThatThrownBy(FalconSealSupport::instance)
+ .describedAs("the literal stimulus in the finding: armed AT the anchor observation height")
+ .isInstanceOf(FalconSealSupport.ActivationConfigException.class)
+ .hasMessageContaining("AERE-PQC-CFG-UNSAFE-07");
+ }
+
+ // -------------------------------------------------------------------------------------------
+ // 8-9. The new value must fail closed like every other one.
+ // -------------------------------------------------------------------------------------------
+
+ @Test
+ public void aMalformedObservationHeightRefuses() {
+ lateAnchor();
+ System.setProperty("aere.falcon.anchor.block", "1e3");
+ System.setProperty("aere.falcon.attachBlock", Long.toString(ATTACH));
+ System.setProperty("aere.falcon.forkBlock", Long.toString(FORK));
+
+ assertThatThrownBy(FalconSealSupport::instance)
+ .isInstanceOf(FalconSealSupport.ActivationConfigException.class)
+ .hasMessageContaining("AERE-PQC-CFG-SYNTAX-09");
+ }
+
+ @Test
+ public void aNegativeObservationHeightRefuses() {
+ lateAnchor();
+ System.setProperty("aere.falcon.anchor.block", "-5");
+ System.setProperty("aere.falcon.attachBlock", Long.toString(ATTACH));
+ System.setProperty("aere.falcon.forkBlock", Long.toString(FORK));
+
+ assertThatThrownBy(FalconSealSupport::instance)
+ .isInstanceOf(FalconSealSupport.ActivationConfigException.class)
+ .hasMessageContaining("AERE-PQC-CFG-SYNTAX-10");
+ }
+
+ // -------------------------------------------------------------------------------------------
+ // 10-11. Scope controls. A guard that refuses everything is not a guard.
+ // -------------------------------------------------------------------------------------------
+
+ @Test
+ public void aGenesisAnchoredRegistryNeedsNoObservationHeight() {
+ System.setProperty("aere.falcon.genesis", genesisPath.toAbsolutePath().toString());
+ System.setProperty("aere.falcon.attachBlock", Long.toString(ATTACH));
+ System.setProperty("aere.falcon.forkBlock", Long.toString(FORK));
+ // aere.falcon.anchor.block deliberately NOT set: a genesis-anchored registry is active from
+ // block 0, so there IS no observation height and demanding one would break the whole
+ // genesis-anchored deployment path.
+
+ final FalconSealSupport pqc = FalconSealSupport.instance();
+ assertThat(pqc.genesisAnchored()).isTrue();
+ assertThat(pqc.addressBound()).isTrue();
+ assertThat(pqc.forkBlock()).isEqualTo(FORK);
+ }
+
+ @Test
+ public void anObservationHeightWithoutBlockingIsHarmless() {
+ lateAnchor();
+ System.setProperty("aere.falcon.anchor.block", Long.toString(OBSERVE));
+ // No forkBlock, no attachBlock: the log-only baseline every node on chain 2800 runs today.
+
+ final FalconSealSupport pqc = FalconSealSupport.instance();
+ assertThat(pqc.forkBlock()).isEqualTo(Long.MAX_VALUE);
+ assertThat(pqc.attachBlock()).isEqualTo(Long.MAX_VALUE);
+ assertThat(pqc.lateAnchorPending()).isTrue();
+ }
+
+ // -------------------------------------------------------------------------------------------
+ // Helpers.
+ // -------------------------------------------------------------------------------------------
+
+ private void lateAnchor() {
+ System.setProperty("aere.falcon.manifest", manifestPath.toAbsolutePath().toString());
+ System.setProperty("aere.falcon.anchor.address", ANCHOR_ADDRESS);
+ }
+
+ private static void resetFalconSingleton() throws Exception {
+ final Field f = FalconSealSupport.class.getDeclaredField("instance");
+ f.setAccessible(true);
+ f.set(null, null);
+ }
+}
diff --git a/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqForkThresholdReachabilityTest.java b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqForkThresholdReachabilityTest.java
new file mode 100755
index 000000000..81bdb8bab
--- /dev/null
+++ b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqForkThresholdReachabilityTest.java
@@ -0,0 +1,354 @@
+/*
+ * Copyright contributors to Besu / AERE Network.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.common.bft;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatCode;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+
+import java.lang.reflect.Field;
+import java.nio.file.Files;
+import java.nio.file.Path;
+
+import org.apache.tuweni.bytes.Bytes;
+import org.bouncycastle.crypto.digests.KeccakDigest;
+import org.bouncycastle.pqc.crypto.falcon.FalconPrivateKeyParameters;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.hyperledger.besu.consensus.common.bft.blockcreation.PqAnchorProducer;
+import org.junit.jupiter.api.io.TempDir;
+
+/**
+ * D-078, THE HALF THAT WAS STILL OPEN: is the threshold K one the fleet can be GUARANTEED to meet?
+ *
+ * <p>The 2026-08-02 repair closed the mechanism that stopped the chain on one add-validator vote: it
+ * took the fleet-wide coverage question out of the per-commit attachment gate and made coverage a
+ * REPORT. That repair is correct and it is measured next door in {@code PqForkValidatorSetChangeTest}.
+ * But it left behind an explicit promise, written in the javadoc of {@code attachmentArmed}:
+ *
+ * <blockquote>
+ *
+ * "What coverage genuinely protects - that blocking is not ARMED over a partial manifest - is an
+ * arm-time decision, and it is made at arm time by armingReadinessDiagnostic() and by the operator".
+ *
+ * </blockquote>
+ *
+ * <p>MEASURED 2026-08-03: {@code armingReadinessDiagnostic()} checks exactly one thing, whether the
+ * manifest is ADDRESS-BOUND. It never reads the fleet size, never reads how many validators hold an
+ * anchored key, and never reads K. The arm-time decision the comment names did not exist, so the
+ * compensating control for the repair was a sentence. This class is what makes it exist.
+ *
+ * <p>THE ARITHMETIC, which is the whole finding and is not an opinion. A block needs {@code
+ * ceil(2N/3)} ECDSA committers, and Falcon seals ride on Commit messages, so the seals a proposer is
+ * GUARANTEED to hear are only those of the keyed validators it cannot avoid: {@code quorum - (N -
+ * keyed)}. The row that matters for this project:
+ *
+ * <pre>
+ * N=7, keyed 7, quorum 5 -&gt; 5 guaranteed K=5 reachable, margin exactly 0
+ * N=9, keyed 7, quorum 6 -&gt; 4 guaranteed K=5 NOT guaranteed
+ * </pre>
+ *
+ * <p>The second row is the standing plan. "Grow to N=9 BEFORE arming" is right, and if the manifest
+ * is not re-anchored on the way there it produces a fleet that arms a threshold no proposer is
+ * guaranteed to meet. Before this guard a node in that state started, joined, armed, and the failure
+ * appeared later as a proposer that could not propose. That is the most expensive shape a
+ * configuration error can take, and it is the same shape the A8 repair already refused to allow for
+ * a non-address-bound manifest.
+ *
+ * <p>WHY AT CONFIG TIME AND NOWHERE ELSE. The lesson is borrowed, not invented: CometBFT applies a
+ * validator-set change only at H+2 and Ethereum's light-client protocol carries {@code
+ * next_sync_committee} a whole period ahead, both so that the set a cryptographic check runs over is
+ * known and comparable BEFORE the boundary rather than discovered at it. We cannot copy their
+ * mechanism, because at seven nodes under one operator there is no committee to sample. We can copy
+ * the discipline: DECLARE the fleet size, compare it against the threshold at config time, and
+ * refuse to cross the boundary if the comparison fails. The same reasoning already produced
+ * AERE-PQC-CFG-UNSAFE-04 and, for the fork height, AERE-PQC-CFG-UNSAFE-06/07 in D-079.
+ *
+ * <p>NOT MEASURED here, and named so it is not read as covered: what a LIVE fleet does in the rounds
+ * between the vote landing and the first proposer failing. That needs a network. This class measures
+ * the decision, which is the thing a node can be stopped from taking.
+ */
+// The D-078 label is our internal finding id. It names a fact about this
+// code, not anything outside it.
+public class PqForkThresholdReachabilityTest {
+
+ /** Anchor activation height H. */
+ private static final long H = 1_000L;
+
+ /** The height from which the staged threshold is K. */
+ private static final long K_AT = H + 10L;
+
+ /** The threshold this project intends to arm. */
+ private static final int K = 5;
+
+ /**
+ * AERE D-146: the chain the registries this fixture writes are BOUND to. It is the same value
+ * {@link #armAnchor} states in {@code aere.pq.chainId}: a registry bound to one chain and an
+ * anchor armed on another is a configuration this fixture must never accidentally describe.
+ */
+ private static final long CHAIN_ID = 2_800L;
+
+ @TempDir private Path tmp;
+
+ @BeforeEach
+ public void setUp() throws Exception {
+ resetFalconSingleton();
+ }
+
+ @AfterEach
+ public void tearDown() throws Exception {
+ for (final String p :
+ new String[] {
+ "aere.falcon.genesis",
+ "aere.falcon.key",
+ "aere.falcon.attachBlock",
+ "aere.falcon.validatorCount",
+ "aere.falcon.testnetAllowSmallFleet",
+ PqAnchorConfig.PROPERTY_ANCHOR_BLOCK,
+ PqAnchorConfig.PROPERTY_MIN_SEALS,
+ PqAnchorConfig.PROPERTY_CHAIN_ID
+ }) {
+ System.clearProperty(p);
+ }
+ // Clearing the properties is NOT enough. PqAnchorProducer holds the configuration in a
+ // remembered field, and that field outlives the properties. Measured 2026-08-11: without the
+ // line below, this class leaves the anchor ARMED for whichever class runs next, and four tests
+ // in PqStartupHistoryTest fail on a guard that is firing CORRECTLY. The suite was green because
+ // the ordering of the day hid the leak, not because the leak was absent.
+ PqAnchorProducer.useConfigForTesting(null);
+ resetFalconSingleton();
+ }
+
+ // -------------------------------------------------------------------------------------------
+ // 1. THE FINDING. A threshold the fleet is not guaranteed to meet must not start.
+ // -------------------------------------------------------------------------------------------
+
+ @Test
+ public void armingAThresholdTheFleetCannotGuaranteeMustRefuseToStart() throws Exception {
+ // The exact state the standing plan walks through: the set has grown to nine, the anchored
+ // manifest still names the original seven, and the threshold is the one the schedule arms.
+ writeAnchoredRegistry(7);
+ System.setProperty("aere.falcon.validatorCount", "9");
+ armAnchor(K);
+
+ assertThatThrownBy(FalconSealSupport::instance)
+ .describedAs(
+ "N=9 with 7 keyed guarantees only %d Falcon seal(s) among a block's committers, and the "
+ + "armed threshold is K=%d. A node must refuse to start rather than arm a threshold "
+ + "no proposer is guaranteed to be able to meet.",
+ FalconSealSupport.worstCaseKeyedSigners(9, 7), K)
+ .isInstanceOf(FalconSealSupport.ActivationConfigException.class)
+ .hasMessageContaining("AERE-PQC-CFG-UNSAFE-08")
+ // The message has to carry BOTH numbers. "Unsafe" without them sends an operator to read
+ // code; the two numbers are the whole diagnosis and the whole remedy.
+ .hasMessageContaining("K=" + K)
+ .hasMessageContaining("guaranteed");
+ }
+
+ // -------------------------------------------------------------------------------------------
+ // 2. NEGATIVE CONTROL. A guard that refuses everything is not a guard.
+ // -------------------------------------------------------------------------------------------
+
+ @Test
+ public void aReachableThresholdMustStillStart() throws Exception {
+ // N=7 fully keyed: quorum 5, guaranteed 5, K=5. Margin is exactly zero, which is a different
+ // statement from "unreachable", and the guard must not confuse the two. This is also the
+ // configuration the fleet runs today, so a guard that refused it would be a self-inflicted halt.
+ writeAnchoredRegistry(7);
+ System.setProperty("aere.falcon.validatorCount", "7");
+ armAnchor(K);
+
+ assertThatCode(FalconSealSupport::instance)
+ .describedAs("N=7 fully keyed guarantees exactly K=%d; zero margin is not unreachable", K)
+ .doesNotThrowAnyException();
+ assertThat(FalconSealSupport.instance().registrySize()).isEqualTo(7);
+ }
+
+ @Test
+ public void growingTheManifestWithTheSetIsWhatMakesNineSafe() throws Exception {
+ // The remedy the refusal names, measured rather than asserted: re-anchor the manifest for the
+ // whole set and the same N=9, same K=5 starts.
+ writeAnchoredRegistry(9);
+ System.setProperty("aere.falcon.validatorCount", "9");
+ armAnchor(K);
+
+ assertThatCode(FalconSealSupport::instance).doesNotThrowAnyException();
+ assertThat(FalconSealSupport.worstCaseKeyedSigners(9, 9))
+ .describedAs("nine keyed of nine guarantees the full ECDSA quorum")
+ .isEqualTo(6);
+ }
+
+ // -------------------------------------------------------------------------------------------
+ // 3. INERT WHERE IT MUST BE INERT. Chain 2800 as it stands today.
+ // -------------------------------------------------------------------------------------------
+
+ @Test
+ public void withNoAnchorConfiguredTheGuardIsInert() throws Exception {
+ // aere.pq.anchorBlock is UNSET on the live chain, so K does not exist and there is nothing to
+ // compare. A guard that could stop a node in that state would be a new way to lose the fleet,
+ // which is a strictly worse defect than the one it repairs.
+ writeAnchoredRegistry(7);
+ System.setProperty("aere.falcon.validatorCount", "9");
+
+ assertThatCode(FalconSealSupport::instance)
+ .describedAs("no anchor configured: no threshold, no comparison, no refusal")
+ .doesNotThrowAnyException();
+ }
+
+ @Test
+ public void aScheduleThatNeverRaisesTheThresholdAboveZeroIsInert() throws Exception {
+ writeAnchoredRegistry(7);
+ System.setProperty("aere.falcon.validatorCount", "9");
+ armAnchor(0);
+
+ assertThatCode(FalconSealSupport::instance)
+ .describedAs("K=0 everywhere is the warm-up regime; nothing can fail to be met")
+ .doesNotThrowAnyException();
+ }
+
+ // -------------------------------------------------------------------------------------------
+ // 4. THE CASE WITH NO KEYS AT ALL, which is the same arithmetic at its floor.
+ // -------------------------------------------------------------------------------------------
+
+ @Test
+ public void aPositiveThresholdWithNoAnchoredKeysMustRefuseToStart() throws Exception {
+ // No manifest anywhere and K=5: guaranteed is 0, so every block at or above H would be rejected
+ // for want of a certificate nobody can produce. Distinct from the A8 refusal, which only fires
+ // when aere.falcon.forkBlock is set; the anchor path has its own arming height.
+ System.setProperty("aere.falcon.validatorCount", "7");
+ armAnchor(K);
+
+ assertThatThrownBy(FalconSealSupport::instance)
+ .isInstanceOf(FalconSealSupport.ActivationConfigException.class)
+ .hasMessageContaining("AERE-PQC-CFG-UNSAFE-08");
+ }
+
+ // -------------------------------------------------------------------------------------------
+ // 5. THE WAIVER IS EXPLICIT, NAMED, AND ONLY FOR ISOLATED NETWORKS.
+ // -------------------------------------------------------------------------------------------
+
+ @Test
+ public void anIsolatedTestNetworkCanWaiveTheGuardExplicitly() throws Exception {
+ writeAnchoredRegistry(7);
+ System.setProperty("aere.falcon.validatorCount", "9");
+ System.setProperty("aere.falcon.testnetAllowSmallFleet", "true");
+ armAnchor(K);
+
+ assertThatCode(FalconSealSupport::instance)
+ .describedAs(
+ "the same switch that waives the N>=9 rule waives this one, because both say the same "
+ + "thing: this fleet has no Falcon fault margin and must not be a mainnet")
+ .doesNotThrowAnyException();
+ }
+
+ // -------------------------------------------------------------------------------------------
+ // 6. THE ARITHMETIC ITSELF, at the boundary, as a pure function.
+ // -------------------------------------------------------------------------------------------
+
+ @Test
+ public void theDeficitIsTheDistanceBetweenTheThresholdAndTheGuarantee() {
+ assertThat(FalconSealSupport.thresholdDeficit(7, 7, 5))
+ .describedAs("N=7 fully keyed meets K=5 exactly")
+ .isZero();
+ assertThat(FalconSealSupport.thresholdDeficit(8, 7, 5))
+ .describedAs("one unkeyed validator added: still met")
+ .isZero();
+ assertThat(FalconSealSupport.thresholdDeficit(9, 7, 5))
+ .describedAs("two added without re-anchoring: short by one, which is the halt")
+ .isEqualTo(1);
+ assertThat(FalconSealSupport.thresholdDeficit(9, 9, 5)).isZero();
+ assertThat(FalconSealSupport.thresholdDeficit(7, 0, 1))
+ .describedAs("no keys at all: a positive threshold is short by all of it")
+ .isEqualTo(1);
+ assertThat(FalconSealSupport.thresholdDeficit(7, 7, 0))
+ .describedAs("K=0 can never be in deficit")
+ .isZero();
+ }
+
+ // -------------------------------------------------------------------------------------------
+ // Helpers.
+ // -------------------------------------------------------------------------------------------
+
+ /** Arm the V2 anchor from system configuration with a staged threshold that reaches {@code k}. */
+ private static void armAnchor(final int k) {
+ System.setProperty(PqAnchorConfig.PROPERTY_ANCHOR_BLOCK, Long.toString(H));
+ // AERE CONFIGURATIE-STRICTA (2026-08-06): an activation height without an explicit
+ // chain id is now a startup refusal, because a silently defaulted 0 in the D and M
+ // pre-images is the Holesky shape. The fixture states what the fleet states.
+ System.setProperty(PqAnchorConfig.PROPERTY_CHAIN_ID, Long.toString(CHAIN_ID));
+ System.setProperty(
+ PqAnchorConfig.PROPERTY_MIN_SEALS, H + ":0," + K_AT + ":" + k);
+ }
+
+ /**
+ * Write a genesis-anchored, address-bound Falcon manifest for {@code count} validators and point
+ * this node at index 0's key, exactly as {@code PqForkValidatorSetChangeTest} does. The anchored hash
+ * is accumulated in lockstep with the manifest text, so the fixture is anchored the way a real
+ * genesis is rather than by a flag.
+ */
+ private void writeAnchoredRegistry(final int count) throws Exception {
+ // AERE D-146 (2026-08-06): v2, proof-bound, bound at H, the height armAnchor() arms from. The
+ // rows come from PqV2Fixture because a v2 claim must be signed by the validator whose address
+ // is on the row, and the 0xA00+i addresses this used to spell have no key behind them.
+ final KeccakDigest kd = new KeccakDigest(256);
+ final StringBuilder manifest = new StringBuilder();
+ manifest
+ .append("{\"config\":{\"aereFalconRegistry\":{")
+ .append(PqV2Fixture.manifestHeader(count, CHAIN_ID, H));
+ for (int i = 0; i < count; i++) {
+ final FalconPrivateKeyParameters priv = PqV2Fixture.privateKey(i);
+ final byte[] anchoredRow = PqV2Fixture.anchorPreimageRow(i);
+ kd.update(anchoredRow, 0, anchoredRow.length);
+ manifest.append(',').append(PqV2Fixture.manifestEntry(i, count, CHAIN_ID, H));
+ if (i == 0) {
+ final Path key0 = tmp.resolve("falcon-key-0.properties");
+ Files.writeString(
+ key0,
+ "index=0\n"
+ + "f="
+ + Bytes.wrap(priv.getSpolyf()).toHexString()
+ + "\n"
+ + "g="
+ + Bytes.wrap(priv.getG()).toHexString()
+ + "\n"
+ + "F="
+ + Bytes.wrap(priv.getSpolyF()).toHexString()
+ + "\n"
+ + "pk="
+ + Bytes.wrap(PqV2Fixture.publicKey(i)).toHexString()
+ + "\n");
+ System.setProperty("aere.falcon.key", key0.toAbsolutePath().toString());
+ }
+ }
+ manifest.append("}},\"alloc\":{\"0000000000000000000000000000000000000fa1\":{\"storage\":{\"0x")
+ .append("0".repeat(64))
+ .append("\":\"0x");
+ final byte[] anchoredHash = new byte[32];
+ kd.doFinal(anchoredHash, 0);
+ manifest.append(Bytes.wrap(anchoredHash).toUnprefixedHexString()).append("\"}}}}");
+
+ final Path genesis = tmp.resolve("genesis-registry.json");
+ Files.writeString(genesis, manifest.toString());
+ System.setProperty("aere.falcon.genesis", genesis.toAbsolutePath().toString());
+ }
+
+ private static void resetFalconSingleton() throws Exception {
+ final Field f = FalconSealSupport.class.getDeclaredField("instance");
+ f.setAccessible(true);
+ f.set(null, null);
+ }
+}
diff --git a/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqForkValidatorSetChangeTest.java b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqForkValidatorSetChangeTest.java
new file mode 100755
index 000000000..724650d85
--- /dev/null
+++ b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqForkValidatorSetChangeTest.java
@@ -0,0 +1,430 @@
+/*
+ * Copyright contributors to Besu / AERE Network.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.common.bft;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+import static org.mockito.Mockito.withSettings;
+
+import org.hyperledger.besu.consensus.common.bft.blockcreation.PqAnchorProducer;
+import org.hyperledger.besu.consensus.common.validator.ValidatorProvider;
+import org.hyperledger.besu.datatypes.Address;
+import org.hyperledger.besu.ethereum.ProtocolContext;
+import org.hyperledger.besu.ethereum.core.BlockHeader;
+import org.hyperledger.besu.ethereum.core.BlockHeaderTestFixture;
+
+import java.lang.reflect.Field;
+import java.nio.file.Files;
+import java.nio.file.Path;
+
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.Collections;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.OptionalInt;
+
+import org.apache.tuweni.bytes.Bytes;
+import org.apache.tuweni.bytes.Bytes32;
+import org.bouncycastle.crypto.digests.KeccakDigest;
+import org.bouncycastle.pqc.crypto.falcon.FalconPrivateKeyParameters;
+import org.bouncycastle.pqc.crypto.falcon.FalconSigner;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+import org.mockito.quality.Strictness;
+
+/**
+ * D-078. THE MEASUREMENT THAT DID NOT EXIST.
+ *
+ * <p>The registry entry reads: "if PQC were armed, an ordinary add-validator vote would stop the
+ * chain: the Falcon blocking quorum follows the dynamic set and cannot be reached inside the vote
+ * window", and it carried {@code verifica: NICIUNA} because "the direct measurement would require
+ * ARMING PQC on a chain, which is exactly the thing that stops the chain".
+ *
+ * <p>That is true of a whole chain. It is NOT true of the decision that stops it. Every step from
+ * "the validator set changed" to "no block can be proposed" is taken by three objects in this
+ * module, each of which is a pure function of its inputs: {@link FalconSealSupport#attachmentArmed}
+ * decides whether this node emits a Falcon seal at all, {@link PqSealCache} holds what was heard,
+ * and {@link PqAnchorProducer#apply} decides whether this node may propose. This class drives those
+ * three with a REAL address-bound genesis-anchored registry and REAL Falcon-512 keys, and asks the
+ * question the registry says cannot be asked.
+ *
+ * <p>WHAT EACH TEST MEASURES, and why each of them can fail:
+ *
+ * <ol>
+ * <li>{@link #baselineTheGateIsArmedWhileTheRegistryCoversTheSet()} - the negative control for
+ * every other test here. If the gate were simply always off, or the registry never loaded,
+ * the three tests below would "pass" for a reason that has nothing to do with D-078. This one
+ * fails if the fixture is not genuinely armed.
+ * <li>{@link #addingOneValidatorMustNotTurnSealAttachmentOff()} - D-078 itself, on the exact
+ * stimulus in the title: one more validator in the set, with no Falcon key.
+ * <li>{@link #aNodeStartedAboveTheAnchorHeightMustStillAttach()} - the SAME halt through a much
+ * more ordinary door than a vote: a restart. Above the anchor height the only caller of
+ * {@code observeValidators} has retired, so a node that starts there never observes a
+ * validator set at all.
+ * <li>{@link #theProposerRefusesWhenNothingWasAttachedAndProposesWhenSomethingWas()} - the causal
+ * link, measured in both directions, so that "attachment off" to "chain stopped" is not an
+ * assertion. Nothing heard: the proposer throws and cannot propose. Five real seals heard:
+ * the proposer produces extraData carrying a five-seal certificate.
+ * </ol>
+ *
+ * <p>NOT MEASURED here, deliberately, and named so it is not mistaken for covered: how many rounds a
+ * live fleet takes to stop once every proposer refuses, and what a syncing node does meanwhile.
+ * Those need a network, and the network run is separate evidence.
+ */
+// The D-078 label is our internal finding id. It names a fact about this
+// code, not anything outside it.
+public class PqForkValidatorSetChangeTest {
+
+ /** Anchor activation height H used throughout. */
+ private static final long H = 1_000L;
+
+ /** Seal-attachment height, comfortably below H. */
+ private static final long ATTACH = 900L;
+
+ /** Height from which the staged threshold K is 5, i.e. the armed regime. */
+ private static final long K_AT = H + 10L;
+
+ private static final int K = 5;
+
+ private static final int N = 7;
+
+ private static final long CHAIN_ID = 220_878L;
+
+ @TempDir private Path tmp;
+
+ private final List<Address> keyedValidators = new ArrayList<>();
+ private final List<FalconPrivateKeyParameters> privateKeys = new ArrayList<>();
+ private Address newcomer;
+ private Path genesisPath;
+ private Path key0Path;
+
+ @BeforeEach
+ public void setUp() throws Exception {
+ // The genesis-anchored path is only satisfied when keccak256(addr20 || pk, indices ascending)
+ // equals the hash stored in the genesis alloc. The digest is accumulated here in lockstep with
+ // the manifest text, so the fixture is anchored the same way a real genesis is.
+ //
+ // AERE D-146 (2026-08-06): v2, proof-bound, bound at H. The addresses come from PqV2Fixture and
+ // are DERIVED from real secp256k1 keys, because a claim has to be signed by the validator whose
+ // address is on the row and no key produces the 0xA00+i addresses this used to spell.
+ final KeccakDigest kd = new KeccakDigest(256);
+ final StringBuilder manifest = new StringBuilder();
+ manifest
+ .append("{\"config\":{\"aereFalconRegistry\":{")
+ .append(PqV2Fixture.manifestHeader(N, CHAIN_ID, H));
+ for (int i = 0; i < N; i++) {
+ final FalconPrivateKeyParameters priv = PqV2Fixture.privateKey(i);
+ privateKeys.add(priv);
+ keyedValidators.add(PqV2Fixture.address(i));
+ final byte[] anchoredRow = PqV2Fixture.anchorPreimageRow(i);
+ kd.update(anchoredRow, 0, anchoredRow.length);
+ manifest.append(',').append(PqV2Fixture.manifestEntry(i, N, CHAIN_ID, H));
+ if (i == 0) {
+ key0Path = tmp.resolve("falcon-key-0.properties");
+ Files.writeString(
+ key0Path,
+ "index=0\n"
+ + "f="
+ + Bytes.wrap(priv.getSpolyf()).toHexString()
+ + "\n"
+ + "g="
+ + Bytes.wrap(priv.getG()).toHexString()
+ + "\n"
+ + "F="
+ + Bytes.wrap(priv.getSpolyF()).toHexString()
+ + "\n"
+ + "pk="
+ + Bytes.wrap(PqV2Fixture.publicKey(i)).toHexString()
+ + "\n");
+ System.setProperty("aere.falcon.key", key0Path.toAbsolutePath().toString());
+ }
+ }
+ manifest.append("}},\"alloc\":{\"0000000000000000000000000000000000000fa1\":{\"storage\":{\"0x")
+ .append("0".repeat(64))
+ .append("\":\"0x");
+ final byte[] anchoredHash = new byte[32];
+ kd.doFinal(anchoredHash, 0);
+ manifest.append(Bytes.wrap(anchoredHash).toUnprefixedHexString()).append("\"}}}}");
+ // The eighth validator: a perfectly ordinary node that an ordinary vote admits, and that has no
+ // Falcon key because the manifest that is anchored on chain was written for seven. It is row N
+ // of the same probe pool, so it is a REAL address with a REAL key behind it that simply was not
+ // filed in the registry - which is the situation this test is about.
+ newcomer = PqV2Fixture.address(N);
+
+ genesisPath = tmp.resolve("genesis-registry.json");
+ Files.writeString(genesisPath, manifest.toString());
+ System.setProperty("aere.falcon.genesis", genesisPath.toAbsolutePath().toString());
+ System.setProperty("aere.falcon.attachBlock", Long.toString(ATTACH));
+
+ resetFalconSingleton();
+ PqSealCache.instance().clear();
+ PqAnchorProducer.useConfigForTesting(
+ new PqAnchorConfig(CHAIN_ID, H, Map.of(H, 0, K_AT, K), OptionalInt.empty(), false));
+ }
+
+ @AfterEach
+ public void tearDown() throws Exception {
+ System.clearProperty("aere.falcon.genesis");
+ System.clearProperty("aere.falcon.key");
+ System.clearProperty("aere.falcon.attachBlock");
+ resetFalconSingleton();
+ PqSealCache.instance().clear();
+ PqAnchorProducer.useConfigForTesting(null);
+ }
+
+ // -----------------------------------------------------------------------------------------
+ // 1. Negative control for the fixture itself.
+ // -----------------------------------------------------------------------------------------
+
+ @Test
+ public void baselineTheGateIsArmedWhileTheRegistryCoversTheSet() {
+ final FalconSealSupport pqc = FalconSealSupport.instance();
+ assertThat(pqc.genesisAnchored())
+ .describedAs("the fixture must load a GENESIS-ANCHORED registry, or nothing below means anything")
+ .isTrue();
+ assertThat(pqc.addressBound()).isTrue();
+ assertThat(pqc.registrySize()).isEqualTo(N);
+ assertThat(pqc.signingEnabled()).isTrue();
+
+ pqc.observeValidators(H + 1L, keyedValidators);
+ assertThat(pqc.attachmentArmed(H + 2L))
+ .describedAs("with the registry covering all %d validators the gate must be ARMED", N)
+ .isTrue();
+ final Optional<FalconSeal> seal = pqc.sign(H + 2L, message(H + 1L));
+ assertThat(seal).isPresent();
+ assertThat(pqc.verify(0, message(H + 1L), seal.get().getSignature())).isTrue();
+ }
+
+ // -----------------------------------------------------------------------------------------
+ // 2. D-078 on its own stimulus: one validator added.
+ // -----------------------------------------------------------------------------------------
+
+ @Test
+ public void addingOneValidatorMustNotTurnSealAttachmentOff() {
+ final FalconSealSupport pqc = FalconSealSupport.instance();
+
+ pqc.observeValidators(H + 1L, keyedValidators);
+ assertThat(pqc.attachmentArmed(H + 2L))
+ .describedAs("armed before the set changes")
+ .isTrue();
+
+ final List<Address> afterVote = new ArrayList<>(keyedValidators);
+ afterVote.add(newcomer);
+ pqc.observeValidators(H + 2L, afterVote);
+
+ assertThat(pqc.attachmentArmed(H + 3L))
+ .describedAs(
+ "D-078: one ordinary add-validator vote must not switch Falcon seal ATTACHMENT off. "
+ + "It is a fleet-wide fact, so it turns off on EVERY node at the same height; with "
+ + "no node attaching, no proposer can gather K=%d seals and the chain stops with no "
+ + "way to carry the re-anchoring transaction that would repair it.",
+ K)
+ .isTrue();
+ assertThat(pqc.sign(H + 3L, message(H + 2L)))
+ .describedAs("and the seal must actually be produced, not merely permitted")
+ .isPresent();
+ }
+
+ // -----------------------------------------------------------------------------------------
+ // 3. The same halt through a restart, which needs no vote at all.
+ // -----------------------------------------------------------------------------------------
+
+ @Test
+ public void aNodeStartedAboveTheAnchorHeightMustStillAttach() {
+ // No observeValidators call at all. Above H the only caller of it, FalconSealValidationRule,
+ // returns at its retirement gate before observing, so this is exactly the state of a node whose
+ // chain head is already above H when the process starts.
+ final FalconSealSupport pqc = FalconSealSupport.instance();
+ assertThat(pqc.attachmentArmed(H + 50L))
+ .describedAs(
+ "a node that starts above the anchor height has observed no validator set, and "
+ + "\"I could not measure the set\" must not be answered with \"stop signing\": that "
+ + "answer is the halt. Restarting a node is an ordinary operation.")
+ .isTrue();
+ assertThat(pqc.sign(H + 50L, message(H + 49L))).isPresent();
+ }
+
+ // -----------------------------------------------------------------------------------------
+ // 4. The causal link, measured in BOTH directions.
+ // -----------------------------------------------------------------------------------------
+
+ @Test
+ public void theProposerRefusesWhenNothingWasAttachedAndProposesWhenSomethingWas() {
+ final BlockHeader parent = new BlockHeaderTestFixture().number(K_AT + 20L).buildHeader();
+ final ProtocolContext context = contextWith(keyedValidators);
+ final BftExtraData base =
+ new BftExtraData(
+ Bytes32.ZERO,
+ Collections.emptyList(),
+ Optional.empty(),
+ 0,
+ keyedValidators,
+ Collections.emptyList());
+
+ // (a) nothing heard, because nothing was attached: the proposer cannot propose.
+ assertThatThrownBy(() -> PqAnchorProducer.apply(base, parent, context))
+ .isInstanceOf(PqAnchorNotReadyException.class);
+
+ // (b) five real Falcon seals heard: the same proposer, same inputs, produces a certificate.
+ // Without this half, (a) would be satisfied by a producer that always refuses.
+ final Bytes32 m =
+ PqAnchor.commitMessage(CHAIN_ID, parent.getNumber(), parent.getHash().getBytes());
+ final List<FalconSeal> heard = new ArrayList<>();
+ for (int i = 0; i < K; i++) {
+ heard.add(new FalconSeal(i, Bytes.wrap(falconSign(privateKeys.get(i), m))));
+ }
+ PqSealCache.instance().record(parent.getNumber(), parent.getHash(), heard);
+
+ final BftExtraData produced = PqAnchorProducer.apply(base, parent, context);
+ assertThat(produced.getFalconSeals()).hasSize(K);
+ assertThat(produced.getVanityData())
+ .isEqualTo(
+ PqAnchor.anchorDigest(
+ CHAIN_ID,
+ parent.getNumber(),
+ parent.getHash().getBytes(),
+ PqAnchor.sortedByIndex(heard)));
+ }
+
+ // -----------------------------------------------------------------------------------------
+ // 4b. What an unkeyed validator actually costs, as a number rather than as a worry.
+ // -----------------------------------------------------------------------------------------
+
+ /**
+ * Removing coverage from the attachment gate stops the halt; it does not make adding an unkeyed
+ * validator free. The price is the guaranteed number of anchored-key holders among a block's ECDSA
+ * committers, and it is arithmetic, not opinion: a block needs {@code ceil(2N/3)} committers, and
+ * the unluckiest committer set takes every unkeyed validator first.
+ *
+ * <p>The three rows below are the ones that decide the project's own arming order, so they are
+ * measured here rather than reasoned about in a document:
+ *
+ * <pre>
+ * N=7, keyed 7, quorum 5 -&gt; 5 guaranteed K=5 is met, with EXACTLY zero margin
+ * N=8, keyed 7, quorum 6 -&gt; 5 guaranteed K=5 is still met, still zero margin
+ * N=9, keyed 7, quorum 6 -&gt; 4 guaranteed K=5 is NOT guaranteed any more
+ * </pre>
+ *
+ * <p>Read against the standing rule "grow to N=9 BEFORE arming", that third row is the warning:
+ * growing to nine while the anchored manifest still names seven is exactly the state in which a
+ * proposer can legitimately fail to assemble a certificate. The manifest has to grow with the set.
+ */
+ @Test
+ public void theCostOfAnUnkeyedValidatorIsANumberAndTheNumberIsThis() {
+ assertThat(FalconSealSupport.worstCaseKeyedSigners(7, 7))
+ .describedAs("N=7 fully keyed: K=5 is met with zero margin")
+ .isEqualTo(5);
+ assertThat(FalconSealSupport.worstCaseKeyedSigners(8, 7))
+ .describedAs("one validator added without re-anchoring: K=5 still met, still zero margin")
+ .isEqualTo(5);
+ assertThat(FalconSealSupport.worstCaseKeyedSigners(9, 7))
+ .describedAs(
+ "two added without re-anchoring: below K=5, so a proposer can legitimately fail. This "
+ + "is the row that constrains growing to N=9 before arming.")
+ .isEqualTo(4);
+ assertThat(FalconSealSupport.worstCaseKeyedSigners(7, 0)).isZero();
+ assertThat(FalconSealSupport.worstCaseKeyedSigners(0, 0)).isZero();
+ }
+
+ // -----------------------------------------------------------------------------------------
+ // 5. NEGATIVE CONTROL for this whole file: the gate must still refuse what it must refuse.
+ // -----------------------------------------------------------------------------------------
+
+ /**
+ * Every other test here asserts that the gate says YES. Replace {@code attachmentArmed} with
+ * {@code return true} and all of them still pass, which would make this file a proof that cannot
+ * fail. These four assertions are what makes that substitution impossible: each names a condition
+ * the D-078 repair deliberately did NOT touch.
+ *
+ * @throws Exception if the fixture cannot be rebuilt
+ */
+ @Test
+ public void theGateStillRefusesEverythingItMustStillRefuse() throws Exception {
+ // (1) below the configured attachment height.
+ assertThat(FalconSealSupport.instance().attachmentArmed(ATTACH - 1L))
+ .describedAs("below the attachment height nothing may be attached")
+ .isFalse();
+
+ // (2) no attachment height configured at all, which is the default and the state of chain 2800.
+ System.clearProperty("aere.falcon.attachBlock");
+ resetFalconSingleton();
+ assertThat(FalconSealSupport.instance().attachmentArmed(H + 5L))
+ .describedAs("with aere.falcon.attachBlock unset a node holding a key attaches nothing")
+ .isFalse();
+
+ // (3) attachment height reached, but no anchored registry to be checked against.
+ System.setProperty("aere.falcon.attachBlock", Long.toString(ATTACH));
+ System.clearProperty("aere.falcon.genesis");
+ resetFalconSingleton();
+ assertThat(FalconSealSupport.instance().attachmentArmed(H + 5L))
+ .describedAs("a seal is never emitted against a registry that cannot be checked")
+ .isFalse();
+
+ // (4) anchored, address-bound registry, but it does not bind THIS node's index. The seal would
+ // be unattributable, so the seals rule would refuse the whole header carrying it.
+ System.setProperty("aere.falcon.genesis", genesisPath.toAbsolutePath().toString());
+ final Path strayKey = tmp.resolve("falcon-key-stray.properties");
+ Files.writeString(strayKey, Files.readString(key0Path).replace("index=0", "index=42"));
+ System.setProperty("aere.falcon.key", strayKey.toAbsolutePath().toString());
+ resetFalconSingleton();
+ final FalconSealSupport stray = FalconSealSupport.instance();
+ assertThat(stray.genesisAnchored())
+ .describedAs("the registry must still load, or (4) would pass for the wrong reason")
+ .isTrue();
+ assertThat(stray.attachmentArmed(H + 5L))
+ .describedAs("an index the anchored registry does not bind must not attach")
+ .isFalse();
+ assertThat(stray.sign(H + 5L, message(H + 4L))).isEmpty();
+ }
+
+ // -----------------------------------------------------------------------------------------
+ // Helpers.
+ // -----------------------------------------------------------------------------------------
+
+ private static Bytes32 message(final long blockNumber) {
+ return PqAnchor.commitMessage(CHAIN_ID, blockNumber, Bytes32.leftPad(Bytes.of(1)));
+ }
+
+ private static byte[] falconSign(final FalconPrivateKeyParameters key, final Bytes32 m) {
+ final FalconSigner signer = new FalconSigner();
+ signer.init(true, key);
+ return signer.generateSignature(m.toArray());
+ }
+
+ private static ProtocolContext contextWith(final Collection<Address> validators) {
+ final ValidatorProvider validatorProvider =
+ mock(ValidatorProvider.class, withSettings().strictness(Strictness.LENIENT));
+ when(validatorProvider.getValidatorsForBlock(any())).thenReturn(validators);
+ when(validatorProvider.getValidatorsAfterBlock(any())).thenReturn(validators);
+ final BftContext bftContext =
+ mock(BftContext.class, withSettings().strictness(Strictness.LENIENT));
+ when(bftContext.getValidatorProvider()).thenReturn(validatorProvider);
+ when(bftContext.as(any())).thenReturn(bftContext);
+ return new ProtocolContext.Builder().withConsensusContext(bftContext).build();
+ }
+
+ private static void resetFalconSingleton() throws Exception {
+ final Field f = FalconSealSupport.class.getDeclaredField("instance");
+ f.setAccessible(true);
+ f.set(null, null);
+ }
+}
diff --git a/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqInertBinaryTest.java b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqInertBinaryTest.java
new file mode 100755
index 000000000..80a2cefe9
--- /dev/null
+++ b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqInertBinaryTest.java
@@ -0,0 +1,475 @@
+/*
+ * Copyright contributors to Besu / AERE Network.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.common.bft;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatCode;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+import static org.mockito.Mockito.withSettings;
+
+import org.hyperledger.besu.consensus.common.bft.blockcreation.PqAnchorProducer;
+import org.hyperledger.besu.consensus.common.validator.ValidatorProvider;
+import org.hyperledger.besu.datatypes.Address;
+import org.hyperledger.besu.ethereum.ProtocolContext;
+import org.hyperledger.besu.ethereum.core.BlockHeader;
+import org.hyperledger.besu.ethereum.core.BlockHeaderTestFixture;
+
+import java.lang.reflect.Field;
+import java.lang.reflect.InvocationHandler;
+import java.lang.reflect.Method;
+import java.lang.reflect.Proxy;
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.Collections;
+import java.util.List;
+import java.util.Locale;
+import java.util.Optional;
+import java.util.Properties;
+import java.util.stream.Collectors;
+
+import org.apache.logging.log4j.Level;
+import org.apache.tuweni.bytes.Bytes32;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.mockito.quality.Strictness;
+
+/**
+ * THE COMPATIBILITY PROPERTY, which is the one that decides whether any of this can be shipped.
+ *
+ * <p>The three anchor patches plus the D-146 arming gate are meant to travel onto the seven live
+ * boxes BEFORE the activation height, so that the fleet is already running the binary when the
+ * height arrives and activation is a restart-free event. That plan is only sound if a node holding
+ * this binary and NO {@code aere.pq.*} configuration is indistinguishable from one holding the
+ * binary it replaces: it must start, it must produce blocks, and it must not say a word about an
+ * anchor that is not armed. If that property is lost, the whole package is unusable regardless of
+ * how correct the anchor logic is, because it could not be staged.
+ *
+ * <p>WHY THE SILENCE IS MEASURED AND NOT ASSUMED. "It returns early, so it cannot log" is a reading
+ * of the code, not a measurement, and the integrated tree has four patches whose log sites nobody
+ * has looked at together. Here the actual Log4j2 pipeline is tapped and the lines are counted.
+ *
+ * <p>WHY {@link #positiveControlTheCaptorSEESTheAnchorWhenItISArmed} is not optional. A captor that
+ * attaches to nothing reports silence forever, and every assertion in {@link
+ * #withNoAerePropertiesTheProposerProducesABlockAndSaysNOTHING} would pass against a broken tap.
+ * The positive control arms the anchor and requires that the SAME captor, in the same JVM, sees the
+ * producer's activation line. Without it this class would be a proof that cannot go red.
+ *
+ * <p>WHY THE CAPTOR IS BUILT BY REFLECTION. {@code log4j-core}, which owns the appender API, is on
+ * this module's RUNTIME test classpath but not its COMPILE one - measured, not assumed. Adding it as
+ * a compile dependency would put a build file into the AERE overlay, which until now is Java only.
+ * Reflection keeps the overlay unchanged, and the positive control is what makes it safe: if any of
+ * the reflective steps silently failed, the captor would see nothing and the positive control would
+ * be the test that fails.
+ *
+ * <p>NOT MEASURED, and written rather than implied: nothing is deployed and no node is started. That
+ * an unarmed node on one of the seven real boxes behaves this way over a real chain, at 523 ms
+ * blocks, alongside a peer that IS armed, is NOT MEASURED and needs the rehearsal network.
+ */
+public class PqInertBinaryTest {
+
+ /**
+ * Loggers that exist ONLY because of the anchor work, so any line from them on an unarmed node is
+ * by itself a finding.
+ *
+ * <p>{@code FalconSealSupport} is deliberately NOT here even though it is the loudest of them.
+ * It predates the anchor and legitimately says one thing at startup; listing it would make the
+ * filter report a four-year-old INFO line as new anchor chatter. Its armed messages are caught by
+ * {@link #ANCHOR_WORDS} instead, which keys on what the line SAYS rather than who said it.
+ */
+ private static final List<String> ANCHOR_LOGGERS =
+ List.of(
+ "org.hyperledger.besu.consensus.common.bft.blockcreation.PqAnchorProducer",
+ "org.hyperledger.besu.consensus.common.bft.PqAnchorConfig",
+ "org.hyperledger.besu.consensus.common.bft.PqSealStore",
+ "org.hyperledger.besu.consensus.common.bft.PqRegistryBinding");
+
+ /**
+ * Words that name the ANCHOR - the capability these patches add - in a message body, whichever
+ * logger emitted it. Deliberately narrower than "anything mentioning Falcon": the Falcon registry
+ * predates all of this, and a filter that cannot tell the new surface from the old one would call
+ * a pre-existing line a regression.
+ */
+ private static final List<String> ANCHOR_WORDS =
+ List.of("pq-anchor", "anchor", "aere-pqc", "aere pqc d2");
+
+ /**
+ * THE ONE LINE an unarmed node has always written, quoted so that any NEW startup chatter turns
+ * this class red.
+ *
+ * <p>MEASURED 2026-08-06, and it is the reason this constant exists rather than an {@code
+ * isEmpty()} on everything. The first shape of this test asserted total silence and went red on
+ * this line. It is not a regression: {@code git log -S} places it in commit 307fd0d0, the snapshot
+ * of everything built between 14 June and 2 August, so it predates all three anchor patches and
+ * the arming gate. It is {@code LOG.info} and it says the node has no Falcon registry, which is
+ * true and was equally true of the binary being replaced.
+ *
+ * <p>So the property that is actually worth defending is not "says nothing" - that was never true
+ * - but "says nothing NEW, and nothing about the anchor". Pinning the exact text is what makes the
+ * second half enforceable: a fourth patch that adds one more startup line has to come here and
+ * change this constant deliberately.
+ */
+ private static final String THE_ONE_PRE_EXISTING_LINE =
+ "AERE PQC: no Falcon registry configured "
+ + "(aere.falcon.genesis/aere.falcon.manifest/aere.falcon.registry); "
+ + "hybrid seal verification will be a no-op.";
+
+ private static final long CHAIN_ID = 220_878L;
+
+ private static final long H = 4_000L;
+
+ /**
+ * Every property this class may touch. The unarmed test does not rely on this list - it sweeps the
+ * whole property table - but the armed one must put back exactly what it took.
+ */
+ private static final List<String> OWNED_PROPERTIES =
+ List.of(
+ "aere.falcon.registry",
+ "aere.falcon.forkBlock",
+ "aere.falcon.attachBlock",
+ "aere.falcon.validatorCount",
+ "aere.falcon.testnetAllowSmallFleet",
+ PqAnchorConfig.PROPERTY_ANCHOR_BLOCK,
+ PqAnchorConfig.PROPERTY_CHAIN_ID,
+ PqAnchorConfig.PROPERTY_MIN_SEALS);
+
+ @BeforeEach
+ public void setUp() throws Exception {
+ clearOwnedProperties();
+ forgetAnchorConfig();
+ resetFalconSingleton();
+ }
+
+ @AfterEach
+ public void tearDown() throws Exception {
+ clearOwnedProperties();
+ forgetAnchorConfig();
+ resetFalconSingleton();
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // THE PROPERTY.
+ // ---------------------------------------------------------------------------------------------
+
+ /**
+ * A node carrying the integrated binary and no anchor configuration starts, produces a block, and
+ * logs nothing about the anchor.
+ *
+ * <p>The block-production half is asserted on OBJECT IDENTITY, not equality. {@code
+ * PqAnchorProducer.apply} returns its argument unchanged at the first branch when the anchor is
+ * not active; an equal-but-rebuilt {@code BftExtraData} would mean the producer had walked the
+ * certificate path and merely arrived back at the same value, which is a different and much
+ * weaker statement.
+ */
+ @Test
+ public void withNoAerePropertiesTheProposerProducesABlockAndSaysNOTHING() throws Exception {
+ // The precondition is MEASURED over the whole property table rather than trusted to the
+ // teardown of whatever test ran before this one in this JVM.
+ assertThat(systemPropertiesStartingWith("aere."))
+ .describedAs("the precondition of this test, measured rather than assumed")
+ .isEmpty();
+
+ final LogCaptor captor = LogCaptor.attach();
+ final BftExtraData produced;
+ final BftExtraData base = plainExtraData();
+ try {
+ assertThatCode(FalconSealSupport::instance)
+ .describedAs("a box with no key ceremony behind it must still come up")
+ .doesNotThrowAnyException();
+
+ final BlockHeader parent = new BlockHeaderTestFixture().number(H + 500L).buildHeader();
+ produced = PqAnchorProducer.apply(base, parent, contextWith(List.of()));
+ } finally {
+ captor.detach();
+ }
+
+ assertThat(produced)
+ .describedAs(
+ "the unarmed producer must hand back the very object it was given; an equal copy would "
+ + "mean it had walked the certificate path")
+ .isSameAs(base);
+
+ assertThat(PqAnchorProducer.config().everActive())
+ .describedAs("and it must consider itself never-active, not merely inactive right now")
+ .isFalse();
+
+ assertThat(captor.anchorLines())
+ .describedAs(
+ "an operator staging this binary before the height must see NOTHING about the anchor; "
+ + "%d line(s) in total were seen, so the captor was live",
+ captor.total())
+ .isEmpty();
+
+ // And nothing NEW of any kind. This is the half that catches a future patch adding chatter.
+ assertThat(captor.aereLines())
+ .describedAs(
+ "the whole AERE output of an unarmed node, pinned: exactly the one INFO line that "
+ + "predates these patches (commit 307fd0d0). A new line here is a staging "
+ + "regression even when it is harmless, because it changes what the fleet prints "
+ + "on a restart that is supposed to be a no-op.")
+ .containsExactly(THE_ONE_PRE_EXISTING_LINE);
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // THE POSITIVE CONTROL, without which the test above proves nothing.
+ // ---------------------------------------------------------------------------------------------
+
+ /**
+ * The same captor, the same JVM, the same loggers - with the anchor armed. If this does not see a
+ * line, the silence measured above is the silence of a broken tap and means nothing.
+ *
+ * <p>The line chosen is the producer's own activation notice, emitted from {@code
+ * PqAnchorProducer.config()} the first time a configuration is built. Its once-per-JVM latch is
+ * reset by {@code useConfigForTesting(null)}, which is why {@link #forgetAnchorConfig()} runs
+ * before every test in this class.
+ */
+ @Test
+ public void positiveControlTheCaptorSEESTheAnchorWhenItISArmed() throws Exception {
+ System.setProperty(PqAnchorConfig.PROPERTY_ANCHOR_BLOCK, Long.toString(H));
+ System.setProperty(PqAnchorConfig.PROPERTY_CHAIN_ID, Long.toString(CHAIN_ID));
+ // THIS WAS `H + ":0"` UNTIL 2026-08-07, and the threshold floor added the same day refused it.
+ // Refused correctly, and it is worth reading twice: this positive control only needed "an
+ // armed anchor", so it had used the shortest form that got past the loader, and that form
+ // was exactly the TOOTHLESS one, a schedule whose threshold is zero for ever. In other
+ // words our own test property had picked, without meaning to, precisely the dangerous
+ // configuration, and would have passed it on as "this is how the anchor is armed" to anyone
+ // who copied from here.
+ //
+ // The warm-up window is kept, because that is the form the activation plan recommends, and
+ // the step that gives the schedule teeth is added. The positive control measures the same
+ // thing: the captor hears the producer's arming line.
+ System.setProperty(PqAnchorConfig.PROPERTY_MIN_SEALS, H + ":0," + (H + 1000L) + ":3");
+
+ final LogCaptor captor = LogCaptor.attach();
+ try {
+ PqAnchorProducer.config();
+ } finally {
+ captor.detach();
+ }
+
+ assertThat(captor.anchorLines())
+ .describedAs(
+ "the captor must be able to hear the anchor, or the silence next door is worthless")
+ .isNotEmpty();
+ assertThat(String.join("\n", captor.anchorLines())).contains("producer armed");
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // Helpers.
+ // ---------------------------------------------------------------------------------------------
+
+ /** Extra data with no anchor digest, i.e. exactly what a pre-fork proposer builds. */
+ private static BftExtraData plainExtraData() {
+ return new BftExtraData(
+ Bytes32.ZERO,
+ Collections.emptyList(),
+ Optional.empty(),
+ 0,
+ Collections.emptyList(),
+ Collections.emptyList());
+ }
+
+ private static ProtocolContext contextWith(final Collection<Address> validators) {
+ final ValidatorProvider validatorProvider =
+ mock(ValidatorProvider.class, withSettings().strictness(Strictness.LENIENT));
+ when(validatorProvider.getValidatorsForBlock(any())).thenReturn(validators);
+ when(validatorProvider.getValidatorsAfterBlock(any())).thenReturn(validators);
+ final BftContext bftContext =
+ mock(BftContext.class, withSettings().strictness(Strictness.LENIENT));
+ when(bftContext.getValidatorProvider()).thenReturn(validatorProvider);
+ when(bftContext.as(any())).thenReturn(bftContext);
+ return new ProtocolContext.Builder().withConsensusContext(bftContext).build();
+ }
+
+ private static List<String> systemPropertiesStartingWith(final String prefix) {
+ final Properties p = System.getProperties();
+ return p.stringPropertyNames().stream()
+ .filter(n -> n.startsWith(prefix))
+ .sorted()
+ .collect(Collectors.toList());
+ }
+
+ private static void clearOwnedProperties() {
+ for (final String p : OWNED_PROPERTIES) {
+ System.clearProperty(p);
+ }
+ }
+
+ private static void forgetAnchorConfig() {
+ PqAnchorProducer.useConfigForTesting(null);
+ }
+
+ private static void resetFalconSingleton() throws Exception {
+ final Field f = FalconSealSupport.class.getDeclaredField("instance");
+ f.setAccessible(true);
+ f.set(null, null);
+ }
+
+ /**
+ * A Log4j2 appender built as a dynamic proxy and attached to the root logger, so that this module
+ * can read the real logging pipeline without taking a compile dependency on {@code log4j-core}.
+ *
+ * <p>{@link #attach()} throws if any reflective step fails. It does NOT fall back to a silent
+ * captor: a captor that quietly captures nothing is precisely the failure this class is written to
+ * exclude.
+ */
+ private static final class LogCaptor {
+
+ private final List<String> lines = Collections.synchronizedList(new ArrayList<>());
+ private final Object rootLoggerConfig;
+ private final Object loggerContext;
+ private final Level priorLevel;
+
+ private LogCaptor(
+ final Object rootLoggerConfig, final Object loggerContext, final Level priorLevel) {
+ this.rootLoggerConfig = rootLoggerConfig;
+ this.loggerContext = loggerContext;
+ this.priorLevel = priorLevel;
+ }
+
+ static LogCaptor attach() throws Exception {
+ final Class<?> appenderCls = Class.forName("org.apache.logging.log4j.core.Appender");
+ final Class<?> eventCls = Class.forName("org.apache.logging.log4j.core.LogEvent");
+ final Class<?> configCls = Class.forName("org.apache.logging.log4j.core.config.Configuration");
+ final Class<?> loggerConfigCls =
+ Class.forName("org.apache.logging.log4j.core.config.LoggerConfig");
+ final Class<?> filterCls = Class.forName("org.apache.logging.log4j.core.Filter");
+ final Class<?> ctxCls = Class.forName("org.apache.logging.log4j.core.LoggerContext");
+ final Class<?> stateCls = Class.forName("org.apache.logging.log4j.core.LifeCycle$State");
+
+ // LogManager is reached reflectively as well, not out of symmetry but because the build bans
+ // the symbol: [BannedMethod] "Do not use org.apache.logging.log4j.LogManager, use
+ // org.slf4j.LoggerFactory instead", and the ban is right for production code. A test that
+ // needs to inspect the logging pipeline itself is the one place it cannot be honoured, and
+ // going through the SLF4J facade cannot reach the appender list at all.
+ final Class<?> logManagerCls = Class.forName("org.apache.logging.log4j.LogManager");
+ final Object ctx =
+ logManagerCls.getMethod("getContext", boolean.class).invoke(null, Boolean.FALSE);
+ if (!ctxCls.isInstance(ctx)) {
+ throw new IllegalStateException(
+ "the SLF4J binding in this JVM is not log4j-core, so the log cannot be tapped: "
+ + ctx.getClass().getName());
+ }
+ final Object configuration = ctxCls.getMethod("getConfiguration").invoke(ctx);
+ final Object rootLoggerConfig = configCls.getMethod("getRootLogger").invoke(configuration);
+
+ final List<String> sink = Collections.synchronizedList(new ArrayList<>());
+ final Method getMessage = eventCls.getMethod("getMessage");
+ final Method getLoggerName = eventCls.getMethod("getLoggerName");
+ Object startedState = null;
+ for (final Object c : stateCls.getEnumConstants()) {
+ if ("STARTED".equals(((Enum<?>) c).name())) {
+ startedState = c;
+ }
+ }
+ final Object started = startedState;
+
+ final InvocationHandler handler =
+ (proxy, method, args) -> {
+ switch (method.getName()) {
+ case "append":
+ final Object event = args[0];
+ final Object msg = getMessage.invoke(event);
+ final String text =
+ (String) msg.getClass().getMethod("getFormattedMessage").invoke(msg);
+ sink.add(getLoggerName.invoke(event) + " | " + text);
+ return null;
+ case "getName":
+ return "aere-d147-captor";
+ case "isStarted":
+ return Boolean.TRUE;
+ case "isStopped":
+ return Boolean.FALSE;
+ case "getState":
+ return started;
+ case "ignoreExceptions":
+ return Boolean.TRUE;
+ case "equals":
+ return proxy == args[0];
+ case "hashCode":
+ return System.identityHashCode(proxy);
+ case "toString":
+ return "aere-d147-captor";
+ default:
+ return null;
+ }
+ };
+ final Object appender =
+ Proxy.newProxyInstance(
+ PqInertBinaryTest.class.getClassLoader(), new Class<?>[] {appenderCls}, handler);
+
+ final Level prior = (Level) loggerConfigCls.getMethod("getLevel").invoke(rootLoggerConfig);
+ loggerConfigCls
+ .getMethod("addAppender", appenderCls, Level.class, filterCls)
+ .invoke(rootLoggerConfig, appender, Level.ALL, null);
+ loggerConfigCls.getMethod("setLevel", Level.class).invoke(rootLoggerConfig, Level.ALL);
+ ctxCls.getMethod("updateLoggers").invoke(ctx);
+
+ final LogCaptor captor = new LogCaptor(rootLoggerConfig, ctx, prior);
+ captor.bind(sink);
+ return captor;
+ }
+
+ /** The proxy writes into its own list; this keeps a single reading surface. */
+ private List<String> bound;
+
+ private void bind(final List<String> sink) {
+ this.bound = sink;
+ }
+
+ void detach() throws Exception {
+ final Class<?> loggerConfigCls =
+ Class.forName("org.apache.logging.log4j.core.config.LoggerConfig");
+ final Class<?> ctxCls = Class.forName("org.apache.logging.log4j.core.LoggerContext");
+ loggerConfigCls
+ .getMethod("removeAppender", String.class)
+ .invoke(rootLoggerConfig, "aere-d147-captor");
+ loggerConfigCls.getMethod("setLevel", Level.class).invoke(rootLoggerConfig, priorLevel);
+ ctxCls.getMethod("updateLoggers").invoke(loggerContext);
+ lines.addAll(bound);
+ }
+
+ int total() {
+ return lines.size();
+ }
+
+ /** Every captured line that names the ANCHOR, by logger or by wording. */
+ List<String> anchorLines() {
+ return lines.stream()
+ .filter(
+ l -> {
+ final String lower = l.toLowerCase(Locale.ROOT);
+ return ANCHOR_LOGGERS.contains(loggerOf(l))
+ || ANCHOR_WORDS.stream().anyMatch(lower::contains);
+ })
+ .collect(Collectors.toList());
+ }
+
+ /** Every captured message body that AERE code emitted, logger prefix stripped. */
+ List<String> aereLines() {
+ return lines.stream()
+ .filter(l -> loggerOf(l).contains(".bft") || l.contains("AERE"))
+ .map(l -> l.substring(l.indexOf(" | ") + 3))
+ .collect(Collectors.toList());
+ }
+
+ private static String loggerOf(final String line) {
+ final int i = line.indexOf(" | ");
+ return i < 0 ? "" : line.substring(0, i);
+ }
+ }
+}
diff --git a/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqParentHeightAlignmentTest.java b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqParentHeightAlignmentTest.java
new file mode 100755
index 000000000..393cbeac4
--- /dev/null
+++ b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqParentHeightAlignmentTest.java
@@ -0,0 +1,229 @@
+/*
+ * Copyright contributors to Besu / AERE Network.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.common.bft;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import org.hyperledger.besu.consensus.common.bft.blockcreation.PqAnchorProducer;
+import org.hyperledger.besu.datatypes.Address;
+
+import java.lang.reflect.Field;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+import java.util.OptionalInt;
+
+import org.apache.tuweni.bytes.Bytes;
+import org.apache.tuweni.bytes.Bytes32;
+import org.bouncycastle.crypto.digests.KeccakDigest;
+import org.bouncycastle.pqc.crypto.falcon.FalconPrivateKeyParameters;
+import org.bouncycastle.pqc.crypto.falcon.FalconSigner;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+
+/**
+ * D-228 (2026-08-15): the PARENT-HEIGHT question at the first anchor.
+ *
+ * <p>WHAT WAS MEASURED, on a public node synced from genesis on the live chain. {@code
+ * PqAnchorSealsRule} judges the certificate carried by the block at the first anchor height H by
+ * asking the registry at the PARENT's height H-1, because that is the height the seals commit to.
+ * The schedule binds INCLUSIVELY from H, so at H-1 it binds nothing, and both height-resolved
+ * lookups fell back to the HEAD registry - which on a public node synced from genesis is EMPTY. A
+ * perfectly valid certificate was refused with "certificate carries index 0, which the registry
+ * does not bind to any validator address", and the node parked one block below the first anchor
+ * forever (measured: head 13,013,999 = H-1, 6,646 R2 rejections in the log).
+ *
+ * <p>THE REPAIR UNDER TEST. In the branch where {@code requiredHashAt(schedule, blockNumber)} is
+ * empty, before the head fallback: when the schedule has an entry at EXACTLY {@code blockNumber+1},
+ * answer from that entry's VERIFIED bound registry. The only historical question ever asked at H-1
+ * is about the certificate carried by the block at H, whose governing registry is the one bound at
+ * H; the alignment uses the verified v2 registry, not an unverified head file.
+ *
+ * <p>THE FIXTURE IS THE PUBLIC-NODE SHAPE, DELIBERATELY: no {@code aere.falcon.genesis}, so the
+ * head registry is EMPTY, and the registry reaches the node ONLY as history ({@code
+ * aere.falcon.registry.history}) bound by hash to the schedule entry at H. That emptiness is what
+ * makes the negative control possible - with a populated head, the H-1 assertions would pass
+ * through the old head fallback and prove nothing about the repair. {@link
+ * #baselineTheHeadIsEmptyOtherwiseNothingHereMeansAnything()} pins that shape.
+ */
+public class PqParentHeightAlignmentTest {
+
+ /** Anchor activation height H: the schedule's FIRST entry sits exactly here. */
+ private static final long H = 1_000L;
+
+ /** Height from which the staged threshold is non-zero, i.e. the fully armed regime. */
+ private static final long K_AT = H + 10L;
+
+ private static final int N = 7;
+
+ private static final long CHAIN_ID = 220_878L;
+
+ @TempDir private Path tmp;
+
+ private final List<FalconPrivateKeyParameters> privateKeys = new ArrayList<>();
+ private final List<Address> validators = new ArrayList<>();
+ private Path genesisPath;
+
+ /** A fixed 32-byte message, standing in for M(parent) of the first anchor block. */
+ private static final Bytes32 MESSAGE = Bytes32.fromHexString("0x" + "5a".repeat(32));
+
+ private Bytes sealByIndexZero;
+
+ @BeforeEach
+ public void setUp() throws Exception {
+ // The same v2 proof-bound manifest as PqRegistryHeightRefusalTest, bound at H.
+ final KeccakDigest kd = new KeccakDigest(256);
+ final StringBuilder manifest = new StringBuilder();
+ manifest
+ .append("{\"config\":{\"aereFalconRegistry\":{")
+ .append(PqV2Fixture.manifestHeader(N, CHAIN_ID, H));
+ for (int i = 0; i < N; i++) {
+ privateKeys.add(PqV2Fixture.privateKey(i));
+ validators.add(PqV2Fixture.address(i));
+ final byte[] anchoredRow = PqV2Fixture.anchorPreimageRow(i);
+ kd.update(anchoredRow, 0, anchoredRow.length);
+ manifest.append(',').append(PqV2Fixture.manifestEntry(i, N, CHAIN_ID, H));
+ }
+ manifest
+ .append("}},\"alloc\":{\"0000000000000000000000000000000000000fa1\":{\"storage\":{\"0x")
+ .append("0".repeat(64))
+ .append("\":\"0x");
+ final byte[] anchoredHash = new byte[32];
+ kd.doFinal(anchoredHash, 0);
+ manifest.append(Bytes.wrap(anchoredHash).toUnprefixedHexString()).append("\"}}}}");
+
+ genesisPath = tmp.resolve("genesis-d228.json");
+ Files.writeString(genesisPath, manifest.toString());
+ // DELIBERATELY NOT setting aere.falcon.genesis: the head registry stays EMPTY, which is the
+ // public-node shape D-228 was measured on.
+
+ // A genuine Falcon-512 signature by index 0 over MESSAGE.
+ final FalconSigner signer = new FalconSigner();
+ signer.init(true, privateKeys.get(0));
+ sealByIndexZero = Bytes.wrap(signer.generateSignature(MESSAGE.toArray()));
+
+ resetFalconSingleton();
+ // ARMED at H, exactly like the live fleet at its first anchor height.
+ PqAnchorProducer.useConfigForTesting(
+ new PqAnchorConfig(CHAIN_ID, H, Map.of(H, 0, K_AT, 3), OptionalInt.empty(), false));
+
+ // The registry reaches this node ONLY as history, exactly like the public package does it.
+ System.setProperty(
+ FalconSealSupport.PROPERTY_REGISTRY_HISTORY, genesisPath.toAbsolutePath().toString());
+ final FalconSealSupport pqc = FalconSealSupport.instance();
+ final PqRegistryHash.Registry held = PqRegistryHash.loadAuto(genesisPath);
+ final PqRegistryHash.Schedule schedule =
+ scheduleFromGenesis(Map.of(H, PqRegistryHash.hashFor(held, CHAIN_ID)));
+ pqc.verifyRegistryBindingOrAbort(0L, CHAIN_ID, schedule);
+ }
+
+ @AfterEach
+ public void tearDown() throws Exception {
+ System.clearProperty("aere.falcon.genesis");
+ System.clearProperty("aere.pq.genesis");
+ System.clearProperty(FalconSealSupport.PROPERTY_REGISTRY_HISTORY);
+ resetFalconSingleton();
+ PqAnchorProducer.useConfigForTesting(null);
+ }
+
+ // -------------------------------------------------------------------------------------------
+ // 0. The fixture itself: the head must be EMPTY, or the two tests below pass through the old
+ // head fallback and the negative control cannot go red.
+ // -------------------------------------------------------------------------------------------
+
+ @Test
+ public void baselineTheHeadIsEmptyOtherwiseNothingHereMeansAnything() {
+ final FalconSealSupport pqc = FalconSealSupport.instance();
+ assertThat(pqc.addressForIndex(0))
+ .describedAs("the HEAD registry must be empty: this is the public-node shape")
+ .isNull();
+ assertThat(pqc.verify(0, MESSAGE, sealByIndexZero))
+ .describedAs("a head verify must fail for the same reason")
+ .isFalse();
+ }
+
+ // -------------------------------------------------------------------------------------------
+ // 1. THE MEASUREMENT. At H-1, the question is about the certificate of the block at H, and the
+ // registry bound at H answers it.
+ // -------------------------------------------------------------------------------------------
+
+ @Test
+ public void atTheParentOfTheFirstAnchorTheBoundRegistryAnswers() {
+ final FalconSealSupport pqc = FalconSealSupport.instance();
+ assertThat(pqc.addressForIndexAtHistoric(H - 1L, 0))
+ .describedAs(
+ "D-228: PqAnchorSealsRule asks at the PARENT height H-1 about the certificate carried "
+ + "by the block at H. The registry governing that certificate is the one bound at "
+ + "H, and it is VERIFIED; refusing here parks a syncing node at H-1 forever")
+ .isEqualTo(validators.get(0));
+ assertThat(pqc.verifyAtHistoric(H - 1L, 0, MESSAGE, sealByIndexZero))
+ .describedAs("and the key half must answer from the same bound registry")
+ .isTrue();
+ }
+
+ // -------------------------------------------------------------------------------------------
+ // 2. THE BOUNDARY IS EXACTLY ONE BLOCK. At H-2 and below, nothing changes: the head fallback
+ // still answers, and on this empty head that answer is a refusal, exactly as before.
+ // -------------------------------------------------------------------------------------------
+
+ @Test
+ public void theBoundaryIsExactlyOneBlock() {
+ final FalconSealSupport pqc = FalconSealSupport.instance();
+ assertThat(pqc.addressForIndexAtHistoric(H - 2L, 0))
+ .describedAs("H-2 is not the parent of any anchor-governed height: old behaviour, refusal")
+ .isNull();
+ assertThat(pqc.verifyAtHistoric(H - 2L, 0, MESSAGE, sealByIndexZero)).isFalse();
+ assertThat(pqc.addressForIndexAtHistoric(0L, 0))
+ .describedAs("and deep below, the same")
+ .isNull();
+ }
+
+ // -------------------------------------------------------------------------------------------
+ // Helpers, borrowed from PqRegistryHeightRefusalTest.
+ // -------------------------------------------------------------------------------------------
+
+ private PqRegistryHash.Schedule scheduleFromGenesis(final Map<Long, String> entries)
+ throws Exception {
+ final List<Long> heights = new ArrayList<>(entries.keySet());
+ heights.sort(Long::compare);
+ final StringBuilder sb = new StringBuilder("{\"config\":{\"pqRegistryHash\":[");
+ for (int i = 0; i < heights.size(); i++) {
+ if (i > 0) {
+ sb.append(',');
+ }
+ final long b = heights.get(i);
+ String h = entries.get(b);
+ if (!h.startsWith("0x")) {
+ h = "0x" + h;
+ }
+ sb.append("{\"block\":").append(b).append(",\"hash\":\"").append(h).append("\"}");
+ }
+ sb.append("]}}");
+ final Path p =
+ tmp.resolve("genesis-schedule-" + heights.size() + "-" + heights.get(0) + ".json");
+ Files.writeString(p, sb.toString());
+ return PqRegistryHash.loadScheduleFromGenesis(p);
+ }
+
+ private static void resetFalconSingleton() throws Exception {
+ final Field f = FalconSealSupport.class.getDeclaredField("instance");
+ f.setAccessible(true);
+ f.set(null, null);
+ }
+}
diff --git a/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqRegistryBindingTest.java b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqRegistryBindingTest.java
new file mode 100755
index 000000000..dae5cb9b6
--- /dev/null
+++ b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqRegistryBindingTest.java
@@ -0,0 +1,595 @@
+/*
+ * Copyright contributors to Besu.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.common.bft;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+import org.hyperledger.besu.crypto.KeyPair;
+import org.hyperledger.besu.crypto.SECPSignature;
+import org.hyperledger.besu.crypto.SecureRandomProvider;
+import org.hyperledger.besu.crypto.SignatureAlgorithm;
+import org.hyperledger.besu.crypto.SignatureAlgorithmFactory;
+import org.hyperledger.besu.datatypes.Address;
+import org.hyperledger.besu.ethereum.core.Util;
+
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.security.SecureRandom;
+import java.util.ArrayList;
+import java.util.List;
+
+import org.apache.tuweni.bytes.Bytes;
+import org.apache.tuweni.bytes.Bytes32;
+import org.bouncycastle.crypto.AsymmetricCipherKeyPair;
+import org.bouncycastle.pqc.crypto.falcon.FalconKeyGenerationParameters;
+import org.bouncycastle.pqc.crypto.falcon.FalconKeyPairGenerator;
+import org.bouncycastle.pqc.crypto.falcon.FalconParameters;
+import org.bouncycastle.pqc.crypto.falcon.FalconPrivateKeyParameters;
+import org.bouncycastle.pqc.crypto.falcon.FalconPublicKeyParameters;
+import org.bouncycastle.pqc.crypto.falcon.FalconSigner;
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+
+/**
+ * AERE D-146. The registry says validator i has Falcon key k. Nothing said validator i ever agreed
+ * to that, or that anybody holds k's secret.
+ *
+ * <p>WHAT WAS MEASURED BEFORE THIS TEST EXISTED, on the real verification path, with the startup
+ * gate reporting MATCH and the header ACCEPTED every time:
+ *
+ * <ul>
+ * <li>T3, one row's address repointed: a seal made by validator 0's key credited to validator 1.
+ * <li>T4, one key at two indices: two seals from a SINGLE private key satisfy a threshold of 2.
+ * <li>T6A, two rows' keys swapped: accepted, and the registry has NO duplicate key and NO
+ * duplicate address, so no uniqueness rule can ever see it.
+ * <li>T6B, two rows' addresses swapped: accepted, again with nothing duplicated, and every seal
+ * attributed to the wrong validator.
+ * </ul>
+ *
+ * <p>T6A and T6B are the reason this test class needs signatures and not just a set. Uniqueness
+ * makes the THRESHOLD honest again; only a signature by the validator's own consensus key makes the
+ * ATTRIBUTION honest.
+ *
+ * <p>KEYS. Every Falcon and ECDSA key here is generated in memory, used inside one test method, and
+ * never written anywhere but a JUnit temporary directory. Nothing in this file touches the key
+ * ceremony, the vault, or the three locks that stand in front of real key generation.
+ */
+class PqRegistryBindingTest {
+
+ private static final long CHAIN_ID = 2800L;
+ private static final long OTHER_CHAIN_ID = 442807L;
+ private static final long BIND_HEIGHT = 12_000_000L;
+ private static final int N = 4;
+
+ /** One validator's material: a Falcon pair and the ECDSA consensus key that must vouch for it. */
+ private record Holder(
+ byte[] falconPublicKey, FalconPrivateKeyParameters falconPrivate, KeyPair ecdsa) {
+ Address address() {
+ return Util.publicKeyToAddress(ecdsa.getPublicKey());
+ }
+ }
+
+ private static List<Holder> holders;
+ private static SignatureAlgorithm ecdsa;
+
+ @BeforeAll
+ static void generateProbeKeys() {
+ ecdsa = SignatureAlgorithmFactory.getInstance();
+ final SecureRandom rnd = SecureRandomProvider.publicSecureRandom();
+ final FalconKeyPairGenerator gen = new FalconKeyPairGenerator();
+ gen.init(new FalconKeyGenerationParameters(rnd, FalconParameters.falcon_512));
+ holders = new ArrayList<>();
+ for (int i = 0; i < N; i++) {
+ final AsymmetricCipherKeyPair kp = gen.generateKeyPair();
+ holders.add(
+ new Holder(
+ ((FalconPublicKeyParameters) kp.getPublic()).getH(),
+ (FalconPrivateKeyParameters) kp.getPrivate(),
+ ecdsa.generateKeyPair()));
+ }
+ }
+
+ // ===================================================================================
+ // The positive control. Without this, every refusal below proves only that the loader
+ // refuses everything.
+ // ===================================================================================
+
+ @Test
+ void anHonestlySignedRegistryLoadsAndIsProofBound(@TempDir final Path dir) throws IOException {
+ final Path f = writeRegistry(dir, "honest.properties", rows(), CHAIN_ID, BIND_HEIGHT);
+
+ final PqRegistryHash.Registry r = PqRegistryHash.loadAuto(f);
+
+ assertThat(r.count()).isEqualTo(N);
+ assertThat(r.addressBound()).isTrue();
+ assertThat(r.proofBound()).isTrue();
+ assertThat(r.declaredChainId()).isEqualTo(CHAIN_ID);
+ assertThat(r.bindHeight()).isEqualTo(BIND_HEIGHT);
+ for (final PqRegistryHash.Entry e : r.entries()) {
+ assertThat(e.possessionProof()).isNotNull().isNotEmpty();
+ assertThat(e.claimProof()).hasSize(65);
+ }
+ }
+
+ // ===================================================================================
+ // T3 and T6: attribution. These are the cases NO uniqueness rule can catch.
+ // ===================================================================================
+
+ @Test
+ void t6aSwappingTwoRowsPublicKeysIsRefused(@TempDir final Path dir) throws IOException {
+ final List<Row> rows = rows();
+ final byte[] pk0 = rows.get(0).publicKey;
+ rows.get(0).publicKey = rows.get(2).publicKey;
+ rows.get(2).publicKey = pk0;
+ final Path f = writeRegistry(dir, "t6a.properties", rows, CHAIN_ID, BIND_HEIGHT);
+
+ // The registry still has four distinct keys and four distinct addresses. Measured on the real
+ // path on 2026-08-06, exactly this file produced an ACCEPTED header.
+ assertThat(distinct(rows, true)).isEqualTo(N);
+ assertThat(distinct(rows, false)).isEqualTo(N);
+
+ assertThatThrownBy(() -> PqRegistryHash.loadAuto(f))
+ .isInstanceOf(PqRegistryHash.RegistryConfigException.class)
+ .hasMessageContaining("AERE-PQC-REG-BIND-03");
+ }
+
+ @Test
+ void t6bSwappingTwoRowsAddressesIsRefused(@TempDir final Path dir) throws IOException {
+ final List<Row> rows = rows();
+ final Address a0 = rows.get(0).address;
+ rows.get(0).address = rows.get(2).address;
+ rows.get(2).address = a0;
+ final Path f = writeRegistry(dir, "t6b.properties", rows, CHAIN_ID, BIND_HEIGHT);
+
+ assertThat(distinct(rows, true)).isEqualTo(N);
+ assertThat(distinct(rows, false)).isEqualTo(N);
+
+ assertThatThrownBy(() -> PqRegistryHash.loadAuto(f))
+ .isInstanceOf(PqRegistryHash.RegistryConfigException.class)
+ .hasMessageContaining("AERE-PQC-REG-BIND-03");
+ }
+
+ @Test
+ void t3AKeyFiledUnderAnotherValidatorsAddressIsRefused(@TempDir final Path dir)
+ throws IOException {
+ // The exact T3 shape, with the proofs re-signed by the party that WOULD hold them at a key
+ // ceremony: the registry writer, who has every FALCON secret. It signs a perfectly valid
+ // possession proof for key 0 sitting under validator 1's address. Only the ECDSA claim, which
+ // needs validator 1's consensus key, stops it - and that is the whole argument for why a Falcon
+ // proof-of-possession alone does not repair D-146.
+ final List<Row> rows = rows();
+ rows.get(0).address = holders.get(1).address();
+ rows.get(1).address = holders.get(3).address(); // keep addresses distinct
+ rows.get(3).address = holders.get(0).address();
+ resignAsRegistryWriter(rows);
+ final Path f = writeRegistry(dir, "t3.properties", rows, CHAIN_ID, BIND_HEIGHT);
+
+ assertThat(distinct(rows, false)).isEqualTo(N);
+
+ assertThatThrownBy(() -> PqRegistryHash.loadAuto(f))
+ .isInstanceOf(PqRegistryHash.RegistryConfigException.class)
+ .hasMessageContaining("AERE-PQC-REG-BIND-04");
+ }
+
+ @Test
+ void aFalconPossessionProofAloneDoesNotBindTheAddress(@TempDir final Path dir) throws IOException {
+ // Stated as a test so nobody can quietly ship "we added proof of possession" as the repair.
+ // The possession proof below is genuine and verifies; the row is still a lie.
+ final List<Row> rows = rows();
+ rows.get(0).address = holders.get(1).address();
+ rows.get(1).address = holders.get(0).address();
+ resignAsRegistryWriter(rows);
+ final Path f = writeRegistry(dir, "pop-only.properties", rows, CHAIN_ID, BIND_HEIGHT);
+
+ final Row r0 = rows.get(0);
+ final Bytes32 popDigest =
+ PqRegistryBinding.possessionDigest(
+ CHAIN_ID, BIND_HEIGHT, N, 0, r0.address.getBytes().toArray(), r0.publicKey);
+ assertThat(PqRegistryBinding.verifyPossession(r0.publicKey, popDigest, r0.possession))
+ .as("the Falcon possession proof is genuine and verifies")
+ .isTrue();
+
+ assertThatThrownBy(() -> PqRegistryHash.loadAuto(f))
+ .as("and the registry is still refused, by the ECDSA half")
+ .isInstanceOf(PqRegistryHash.RegistryConfigException.class)
+ .hasMessageContaining("AERE-PQC-REG-BIND-04");
+ }
+
+ // ===================================================================================
+ // T4 and T5: the threshold. Uniqueness, no signature involved.
+ // ===================================================================================
+
+ @Test
+ void t4TheSameKeyAtTwoIndicesIsRefused(@TempDir final Path dir) throws IOException {
+ final List<Row> rows = rows();
+ rows.get(2).publicKey = rows.get(0).publicKey;
+ final Path f = writeRegistry(dir, "t4.properties", rows, CHAIN_ID, BIND_HEIGHT);
+
+ assertThatThrownBy(() -> PqRegistryHash.loadAuto(f))
+ .isInstanceOf(PqRegistryHash.RegistryConfigException.class)
+ .hasMessageContaining("AERE-PQC-REG-LOAD-19");
+ }
+
+ @Test
+ void t5TheSameAddressAtTwoIndicesIsRefused(@TempDir final Path dir) throws IOException {
+ final List<Row> rows = rows();
+ rows.get(2).address = rows.get(0).address;
+ final Path f = writeRegistry(dir, "t5.properties", rows, CHAIN_ID, BIND_HEIGHT);
+
+ assertThatThrownBy(() -> PqRegistryHash.loadAuto(f))
+ .isInstanceOf(PqRegistryHash.RegistryConfigException.class)
+ .hasMessageContaining("AERE-PQC-REG-LOAD-20");
+ }
+
+ @Test
+ void t4AndT5AreRefusedInALEGACYRegistryToo(@TempDir final Path dir) throws IOException {
+ // The uniqueness half must not be reachable only through the new format, or a v1 file remains
+ // the way to ship a duplicated key. This is the ONE case where the before/after can be measured
+ // on the SAME bytes by the unpatched binary, and it is: the probe loads this file on the old
+ // tree and refuses it on the new one.
+ final StringBuilder b = new StringBuilder("count=" + N + "\n");
+ for (int i = 0; i < N; i++) {
+ b.append(i).append('=').append(hex(holders.get(i == 2 ? 0 : i).falconPublicKey())).append('\n');
+ b.append(i).append(".addr=").append(hex(holders.get(i).address().getBytes().toArray())).append('\n');
+ }
+ final Path f = dir.resolve("legacy-dup.properties");
+ Files.writeString(f, b.toString(), StandardCharsets.UTF_8);
+
+ assertThatThrownBy(() -> PqRegistryHash.loadAuto(f))
+ .isInstanceOf(PqRegistryHash.RegistryConfigException.class)
+ .hasMessageContaining("AERE-PQC-REG-LOAD-19");
+ }
+
+ // ===================================================================================
+ // Replay: the fields that are inside the signed message earn their place here.
+ // ===================================================================================
+
+ @Test
+ void aProofLiftedToAnotherIndexIsRefused(@TempDir final Path dir) throws IOException {
+ final List<Row> rows = rows();
+ final byte[] pop0 = rows.get(0).possession;
+ rows.get(0).possession = rows.get(1).possession;
+ rows.get(1).possession = pop0;
+ final Path f = writeRegistry(dir, "lift.properties", rows, CHAIN_ID, BIND_HEIGHT);
+
+ assertThatThrownBy(() -> PqRegistryHash.loadAuto(f))
+ .isInstanceOf(PqRegistryHash.RegistryConfigException.class)
+ .hasMessageContaining("AERE-PQC-REG-BIND-03");
+ }
+
+ @Test
+ void aRegistrySignedForAnotherHeightIsRefused(@TempDir final Path dir) throws IOException {
+ final Path f = writeRegistry(dir, "height.properties", rows(), CHAIN_ID, BIND_HEIGHT + 1);
+
+ assertThatThrownBy(() -> PqRegistryHash.loadAuto(f))
+ .isInstanceOf(PqRegistryHash.RegistryConfigException.class)
+ .hasMessageContaining("AERE-PQC-REG-BIND-03");
+ }
+
+ @Test
+ void aRegistryLiftedFromTheScratchChainIsRefusedAtTheGate(@TempDir final Path dir)
+ throws IOException {
+ // Signed for 442807, declared as 442807, internally perfect. It loads - the proofs really do
+ // verify - and the GATE refuses it, because the node is on 2800.
+ final Path f =
+ writeRegistry(dir, "scratch.properties", rows(OTHER_CHAIN_ID), OTHER_CHAIN_ID, BIND_HEIGHT);
+ final PqRegistryHash.Registry r = PqRegistryHash.loadAuto(f);
+ assertThat(r.proofBound()).isTrue();
+
+ assertThatThrownBy(
+ () ->
+ PqRegistryHash.verifyOrAbort(
+ PqRegistryHash.emptySchedule(), r, BIND_HEIGHT, CHAIN_ID))
+ .isInstanceOf(PqRegistryHash.RegistryConfigException.class)
+ .hasMessageContaining("AERE-PQC-REG-BIND-07");
+ }
+
+ @Test
+ void aTruncatedProofIsRefused(@TempDir final Path dir) throws IOException {
+ final List<Row> rows = rows();
+ final byte[] cut = new byte[rows.get(1).possession.length - 8];
+ System.arraycopy(rows.get(1).possession, 0, cut, 0, cut.length);
+ rows.get(1).possession = cut;
+ final Path f = writeRegistry(dir, "cut.properties", rows, CHAIN_ID, BIND_HEIGHT);
+
+ assertThatThrownBy(() -> PqRegistryHash.loadAuto(f))
+ .isInstanceOf(PqRegistryHash.RegistryConfigException.class)
+ .hasMessageContaining("AERE-PQC-REG-BIND-03");
+ }
+
+ @Test
+ void aClaimSignedByTheWrongValidatorIsRefused(@TempDir final Path dir) throws IOException {
+ final List<Row> rows = rows();
+ rows.get(1).claim =
+ signClaim(holders.get(2).ecdsa(), CHAIN_ID, BIND_HEIGHT, 1, rows.get(1));
+ final Path f = writeRegistry(dir, "wrongsigner.properties", rows, CHAIN_ID, BIND_HEIGHT);
+
+ assertThatThrownBy(() -> PqRegistryHash.loadAuto(f))
+ .isInstanceOf(PqRegistryHash.RegistryConfigException.class)
+ .hasMessageContaining("AERE-PQC-REG-BIND-04");
+ }
+
+ @Test
+ void aPartiallyBoundRegistryIsRefused(@TempDir final Path dir) throws IOException {
+ final List<Row> rows = rows();
+ rows.get(3).claim = null;
+ final Path f = writeRegistry(dir, "partial.properties", rows, CHAIN_ID, BIND_HEIGHT);
+
+ assertThatThrownBy(() -> PqRegistryHash.loadAuto(f))
+ .isInstanceOf(PqRegistryHash.RegistryConfigException.class)
+ .hasMessageContaining("AERE-PQC-REG-LOAD-21");
+ }
+
+ @Test
+ void proofsWithoutAChainIdOrBindHeightAreRefused(@TempDir final Path dir) throws IOException {
+ final Path f = writeRegistry(dir, "noheader.properties", rows(), -1L, -1L);
+
+ assertThatThrownBy(() -> PqRegistryHash.loadAuto(f))
+ .isInstanceOf(PqRegistryHash.RegistryConfigException.class)
+ .hasMessageContaining("AERE-PQC-REG-LOAD-22");
+ }
+
+ // ===================================================================================
+ // The hash must COVER the proofs, or they are advisory and can be stripped.
+ // ===================================================================================
+
+ @Test
+ void theCanonicalHashCoversBothProofsOfEveryRow(@TempDir final Path dir) throws IOException {
+ final List<Row> rows = rows();
+ final PqRegistryHash.Registry r =
+ PqRegistryHash.loadAuto(writeRegistry(dir, "cover.properties", rows, CHAIN_ID, BIND_HEIGHT));
+
+ final Bytes pre = Bytes.wrap(PqRegistryHash.canonicalPreimageV2(r, CHAIN_ID));
+ for (final Row row : rows) {
+ assertThat(indexOf(pre, Bytes.wrap(row.possession)))
+ .as("possession proof is inside the hashed pre-image")
+ .isNotNegative();
+ assertThat(indexOf(pre, Bytes.wrap(row.claim)))
+ .as("claim is inside the hashed pre-image")
+ .isNotNegative();
+ }
+ assertThat(PqRegistryHash.hashFor(r, CHAIN_ID)).isEqualTo(PqRegistryHash.hashV2(r, CHAIN_ID));
+ }
+
+ @Test
+ void strippingTheProofsChangesTheHashSoADowngradeCannotSatisfyASchedule(@TempDir final Path dir)
+ throws IOException {
+ final List<Row> rows = rows();
+ final PqRegistryHash.Registry bound =
+ PqRegistryHash.loadAuto(writeRegistry(dir, "bound.properties", rows, CHAIN_ID, BIND_HEIGHT));
+
+ // The same rows with the proof lines deleted: what an attacker writes to make the check
+ // disappear. It must not hash to the value genesis anchored.
+ final StringBuilder b = new StringBuilder("count=" + N + "\n");
+ for (int i = 0; i < N; i++) {
+ b.append(i).append('=').append(hex(rows.get(i).publicKey)).append('\n');
+ b.append(i).append(".addr=").append(hex(rows.get(i).address.getBytes().toArray())).append('\n');
+ }
+ final Path stripped = dir.resolve("stripped.properties");
+ Files.writeString(stripped, b.toString(), StandardCharsets.UTF_8);
+ final PqRegistryHash.Registry v1 = PqRegistryHash.loadAuto(stripped);
+
+ assertThat(v1.proofBound()).isFalse();
+ assertThat(PqRegistryHash.hashFor(v1, CHAIN_ID))
+ .isNotEqualTo(PqRegistryHash.hashFor(bound, CHAIN_ID));
+
+ final PqRegistryHash.Schedule schedule =
+ PqRegistryHash.parseSchedule(
+ scheduleNode(PqRegistryHash.hashFor(bound, CHAIN_ID)), "test");
+ assertThat(PqRegistryHash.matchesAt(schedule, bound, BIND_HEIGHT, CHAIN_ID)).isTrue();
+ assertThat(PqRegistryHash.matchesAt(schedule, v1, BIND_HEIGHT, CHAIN_ID)).isFalse();
+ }
+
+ // ===================================================================================
+ // Domain separation: a possession proof must never be usable as an anchor seal.
+ // ===================================================================================
+
+ @Test
+ void aPossessionProofIsNotASealForTheSameHeight(@TempDir final Path dir) throws IOException {
+ final List<Row> rows = rows();
+ final Row r0 = rows.get(0);
+ final Bytes32 pop =
+ PqRegistryBinding.possessionDigest(
+ CHAIN_ID, BIND_HEIGHT, N, 0, r0.address.getBytes().toArray(), r0.publicKey);
+ final Bytes32 commit =
+ PqAnchor.commitMessage(CHAIN_ID, BIND_HEIGHT, Bytes32.repeat((byte) 0x7e));
+
+ assertThat(pop).isNotEqualTo(commit);
+ // The tag is at offset 0 of the pre-image, so the two message spaces cannot overlap by
+ // construction rather than by luck.
+ final byte[] pre =
+ PqRegistryBinding.bindingPreimage(
+ CHAIN_ID, BIND_HEIGHT, N, 0, r0.address.getBytes().toArray(), r0.publicKey);
+ assertThat(new String(pre, 0, PqRegistryBinding.DOMAIN_POSSESSION.length(), StandardCharsets.US_ASCII))
+ .isEqualTo(PqRegistryBinding.DOMAIN_POSSESSION);
+ // A seal signed over the COMMIT message does not verify as a possession proof.
+ final byte[] sealOverCommit = falconSign(holders.get(0).falconPrivate(), commit);
+ assertThat(PqRegistryBinding.verifyPossession(r0.publicKey, pop, sealOverCommit)).isFalse();
+ // ... and the possession proof does not verify as a seal.
+ assertThat(PqRegistryBinding.verifyPossession(r0.publicKey, commit, r0.possession)).isFalse();
+ assertThat(dir).exists();
+ }
+
+ // ===================================================================================
+ // The arming precondition.
+ // ===================================================================================
+
+ @Test
+ void armingOverAnUnboundRegistryIsRefused(@TempDir final Path dir) throws IOException {
+ final StringBuilder b = new StringBuilder("count=" + N + "\n");
+ for (int i = 0; i < N; i++) {
+ b.append(i).append('=').append(hex(holders.get(i).falconPublicKey())).append('\n');
+ b.append(i).append(".addr=").append(hex(holders.get(i).address().getBytes().toArray())).append('\n');
+ }
+ final Path f = dir.resolve("unbound.properties");
+ Files.writeString(f, b.toString(), StandardCharsets.UTF_8);
+ final PqRegistryHash.Registry v1 = PqRegistryHash.loadAuto(f);
+
+ assertThatThrownBy(() -> PqRegistryHash.requireBindingsOrThrow(v1))
+ .isInstanceOf(PqRegistryHash.RegistryConfigException.class)
+ .hasMessageContaining("AERE-PQC-REG-ARM-02");
+
+ final PqRegistryHash.Registry v2 =
+ PqRegistryHash.loadAuto(writeRegistry(dir, "armed.properties", rows(), CHAIN_ID, BIND_HEIGHT));
+ PqRegistryHash.requireBindingsOrThrow(v2); // must not throw
+ }
+
+ // ===================================================================================
+ // Fixtures
+ // ===================================================================================
+
+ private static final class Row {
+ private byte[] publicKey;
+ private Address address;
+ private byte[] possession;
+ private byte[] claim;
+ }
+
+ /** Honest rows for CHAIN_ID at BIND_HEIGHT, every proof signed by the party that should sign it. */
+ private static List<Row> rows() {
+ return rows(CHAIN_ID);
+ }
+
+ private static List<Row> rows(final long chainId) {
+ final List<Row> out = new ArrayList<>();
+ for (int i = 0; i < N; i++) {
+ final Row r = new Row();
+ r.publicKey = holders.get(i).falconPublicKey();
+ r.address = holders.get(i).address();
+ out.add(r);
+ }
+ for (int i = 0; i < N; i++) {
+ final Row r = out.get(i);
+ r.possession =
+ falconSign(
+ holders.get(i).falconPrivate(),
+ PqRegistryBinding.possessionDigest(
+ chainId, BIND_HEIGHT, N, i, r.address.getBytes().toArray(), r.publicKey));
+ r.claim = signClaim(holders.get(i).ecdsa(), chainId, BIND_HEIGHT, i, r);
+ }
+ return out;
+ }
+
+ /**
+ * Re-sign every row the way THE REGISTRY WRITER would at a key ceremony: it holds every FALCON
+ * secret, so it can always produce a valid possession proof for whatever row it just wrote. The
+ * ECDSA claim it can produce is the one belonging to the holder of the key on that row, never the
+ * one belonging to the address it filed the key under. That gap is the whole of D-146 and it is
+ * why the Falcon half alone repairs nothing.
+ */
+ private static void resignAsRegistryWriter(final List<Row> rows) {
+ for (int i = 0; i < rows.size(); i++) {
+ final Row r = rows.get(i);
+ final Holder owner = ownerOfKey(r.publicKey);
+ r.possession =
+ falconSign(
+ owner.falconPrivate(),
+ PqRegistryBinding.possessionDigest(
+ CHAIN_ID, BIND_HEIGHT, N, i, r.address.getBytes().toArray(), r.publicKey));
+ r.claim = signClaim(owner.ecdsa(), CHAIN_ID, BIND_HEIGHT, i, r);
+ }
+ }
+
+ private static Holder ownerOfKey(final byte[] publicKey) {
+ for (final Holder h : holders) {
+ if (java.util.Arrays.equals(h.falconPublicKey(), publicKey)) {
+ return h;
+ }
+ }
+ throw new IllegalStateException("no probe holder owns that key");
+ }
+
+ private static byte[] signClaim(
+ final KeyPair kp, final long chainId, final long height, final int index, final Row r) {
+ final Bytes32 d =
+ PqRegistryBinding.claimDigest(
+ chainId, height, N, index, r.address.getBytes().toArray(), r.publicKey);
+ final SECPSignature s = ecdsa.sign(d, kp);
+ return s.encodedBytes().toArrayUnsafe();
+ }
+
+ private static byte[] falconSign(final FalconPrivateKeyParameters priv, final Bytes32 message) {
+ final FalconSigner signer = new FalconSigner();
+ signer.init(true, priv);
+ return signer.generateSignature(message.toArray());
+ }
+
+ private static Path writeRegistry(
+ final Path dir,
+ final String name,
+ final List<Row> rows,
+ final long chainId,
+ final long bindHeight)
+ throws IOException {
+ final StringBuilder b = new StringBuilder();
+ b.append("formatVersion=").append(PqRegistryBinding.FORMAT_VERSION).append('\n');
+ if (chainId >= 0) {
+ b.append("chainId=").append(chainId).append('\n');
+ }
+ if (bindHeight >= 0) {
+ b.append("bindHeight=").append(bindHeight).append('\n');
+ }
+ b.append("count=").append(rows.size()).append('\n');
+ for (int i = 0; i < rows.size(); i++) {
+ final Row r = rows.get(i);
+ b.append(i).append('=').append(hex(r.publicKey)).append('\n');
+ b.append(i).append(".addr=").append(hex(r.address.getBytes().toArray())).append('\n');
+ if (r.possession != null) {
+ b.append(i).append(".pop=").append(hex(r.possession)).append('\n');
+ }
+ if (r.claim != null) {
+ b.append(i).append(".claim=").append(hex(r.claim)).append('\n');
+ }
+ }
+ final Path f = dir.resolve(name);
+ Files.writeString(f, b.toString(), StandardCharsets.UTF_8);
+ return f;
+ }
+
+ private static long distinct(final List<Row> rows, final boolean keys) {
+ return rows.stream()
+ .map(r -> keys ? hex(r.publicKey) : hex(r.address.getBytes().toArray()))
+ .distinct()
+ .count();
+ }
+
+ private static int indexOf(final Bytes haystack, final Bytes needle) {
+ for (int i = 0; i + needle.size() <= haystack.size(); i++) {
+ if (haystack.slice(i, needle.size()).equals(needle)) {
+ return i;
+ }
+ }
+ return -1;
+ }
+
+ private static com.fasterxml.jackson.databind.JsonNode scheduleNode(final String hash) {
+ final com.fasterxml.jackson.databind.node.ArrayNode a =
+ new com.fasterxml.jackson.databind.ObjectMapper().createArrayNode();
+ a.addObject().put("block", BIND_HEIGHT).put("hash", "0x" + hash);
+ return a;
+ }
+
+ private static String hex(final byte[] b) {
+ final StringBuilder s = new StringBuilder(b.length * 2);
+ for (final byte x : b) {
+ s.append(Character.forDigit((x >> 4) & 0xf, 16)).append(Character.forDigit(x & 0xf, 16));
+ }
+ return s.toString();
+ }
+}
diff --git a/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqRegistryHeightRefusalTest.java b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqRegistryHeightRefusalTest.java
new file mode 100755
index 000000000..2b7a89cd5
--- /dev/null
+++ b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqRegistryHeightRefusalTest.java
@@ -0,0 +1,326 @@
+/*
+ * Copyright contributors to Besu / AERE Network.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.common.bft;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import org.hyperledger.besu.consensus.common.bft.blockcreation.PqAnchorProducer;
+import org.hyperledger.besu.datatypes.Address;
+
+import java.lang.reflect.Field;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+import java.util.OptionalInt;
+
+import org.apache.tuweni.bytes.Bytes;
+import org.apache.tuweni.bytes.Bytes32;
+import org.bouncycastle.crypto.digests.KeccakDigest;
+import org.bouncycastle.pqc.crypto.falcon.FalconPrivateKeyParameters;
+import org.bouncycastle.pqc.crypto.falcon.FalconSigner;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+
+/**
+ * D2, the adversarial review of 2026-08-02, at the layer that actually answers the question.
+ *
+ * <p>WHAT THE DOSSIER MEASURED. {@code PqSignerRegistry} had {@code addressForIndex(int)} and {@code
+ * verify(int, Bytes, Bytes)} with no height, and {@code FalconSealSupport} held ONE registry loaded
+ * at start-up. So a header that passed both anchor rules was REJECTED the moment index 0's Falcon
+ * key was rotated - same header, same parent, same validator set.
+ *
+ * <p>WHAT WAS REPAIRED BEFORE THIS FILE, AND WHAT WAS NOT. Commit f3ebe90c (D-081) gave the
+ * validation path {@code addressForIndexAt} / {@code verifyAt} and a height-indexed schedule. The
+ * measurement of 2026-08-05 found the repair INERT, for a reason that is one line long: with no
+ * {@code config.pqRegistryHash} in genesis - and there is none in any genesis this fleet runs -
+ * {@code keyAt} fell back to the registry in force AT THE HEAD, at every height. Height-aware
+ * signatures, head-registry answers. T2 stood exactly as measured.
+ *
+ * <p>WHAT THIS FILE ASSERTS, as a property and not as a scenario: <b>at and above the arming height,
+ * a node that cannot say which key set was in force must REFUSE, not guess.</b> Below the arming
+ * height it must keep answering from the head registry, because nothing there is being judged and
+ * the 11.8 million blocks already on chain 2800 must behave bit for bit as they did.
+ *
+ * <p>THE NEGATIVE CONTROL IS BUILT IN, not promised. {@link
+ * #belowTheArmingHeightTheHeadRegistryStillAnswers()} fails if the refusal is made unconditional;
+ * {@link #whenTheAnchorIsNotArmedNOTHINGCHANGES()} fails if it is made independent of arming; {@link
+ * #withTheScheduleConfiguredTheArmedHeightsAnswerAgain()} fails if the refusal is anything other
+ * than a missing height-to-registry binding. And the measurement itself, {@link
+ * #d2t2AtAndAboveTheArmingHeightWithNoScheduleTheAnswerIsRefusal()}, is GREEN on the unrepaired code
+ * only if the fallback is restored - which is exactly the one-line edit the repair removed.
+ */
+public class PqRegistryHeightRefusalTest {
+
+ /** Anchor activation height H: from here a header's Falcon certificate carries weight. */
+ private static final long H = 1_000L;
+
+ /** Height from which the staged threshold is non-zero, i.e. the fully armed regime. */
+ private static final long K_AT = H + 10L;
+
+ /** A height far above H, standing in for "a year of history above the arming height". */
+ private static final long DEEP = K_AT + 5_000L;
+
+ private static final int N = 7;
+
+ private static final long CHAIN_ID = 220_878L;
+
+ @TempDir private Path tmp;
+
+ private final List<FalconPrivateKeyParameters> privateKeys = new ArrayList<>();
+ private final List<Address> validators = new ArrayList<>();
+ private Path genesisPath;
+
+ /** A fixed 32-byte message, standing in for M(parent) or a committed-seal hash. */
+ private static final Bytes32 MESSAGE =
+ Bytes32.fromHexString("0x" + "5a".repeat(32));
+
+ private Bytes sealByIndexZero;
+
+ @BeforeEach
+ public void setUp() throws Exception {
+ // AERE D-146 (2026-08-06): v2, proof-bound, bound at H. See PqV2Fixture for why the addresses
+ // are derived from real secp256k1 keys and can no longer be spelled 0xA00+i.
+ final KeccakDigest kd = new KeccakDigest(256);
+ final StringBuilder manifest = new StringBuilder();
+ manifest
+ .append("{\"config\":{\"aereFalconRegistry\":{")
+ .append(PqV2Fixture.manifestHeader(N, CHAIN_ID, H));
+ for (int i = 0; i < N; i++) {
+ privateKeys.add(PqV2Fixture.privateKey(i));
+ validators.add(PqV2Fixture.address(i));
+ final byte[] anchoredRow = PqV2Fixture.anchorPreimageRow(i);
+ kd.update(anchoredRow, 0, anchoredRow.length);
+ manifest.append(',').append(PqV2Fixture.manifestEntry(i, N, CHAIN_ID, H));
+ }
+ manifest
+ .append("}},\"alloc\":{\"0000000000000000000000000000000000000fa1\":{\"storage\":{\"0x")
+ .append("0".repeat(64))
+ .append("\":\"0x");
+ final byte[] anchoredHash = new byte[32];
+ kd.doFinal(anchoredHash, 0);
+ manifest.append(Bytes.wrap(anchoredHash).toUnprefixedHexString()).append("\"}}}}");
+
+ genesisPath = tmp.resolve("genesis-d2.json");
+ Files.writeString(genesisPath, manifest.toString());
+ System.setProperty("aere.falcon.genesis", genesisPath.toAbsolutePath().toString());
+
+ // A genuine Falcon-512 signature by index 0 over MESSAGE. Everything below asks one question of
+ // it: at which heights does the node agree that this is index 0's signature.
+ final FalconSigner signer = new FalconSigner();
+ signer.init(true, privateKeys.get(0));
+ sealByIndexZero = Bytes.wrap(signer.generateSignature(MESSAGE.toArray()));
+
+ resetFalconSingleton();
+ // ARMED at H. On the live fleet aere.pq.anchorBlock is unset and this whole file's subject
+ // does not exist; see whenTheAnchorIsNotArmedNOTHINGCHANGES.
+ PqAnchorProducer.useConfigForTesting(
+ new PqAnchorConfig(CHAIN_ID, H, Map.of(H, 0, K_AT, 3), OptionalInt.empty(), false));
+ }
+
+ @AfterEach
+ public void tearDown() throws Exception {
+ System.clearProperty("aere.falcon.genesis");
+ System.clearProperty("aere.pq.genesis");
+ System.clearProperty(FalconSealSupport.PROPERTY_REGISTRY_HISTORY);
+ resetFalconSingleton();
+ PqAnchorProducer.useConfigForTesting(null);
+ }
+
+ // -------------------------------------------------------------------------------------------
+ // 0. The fixture itself. Without this, a green run below could mean the registry never loaded.
+ // -------------------------------------------------------------------------------------------
+
+ @Test
+ public void baselineTheFixtureIsGenesisAnchoredAndTheSealIsGENUINE() {
+ final FalconSealSupport pqc = FalconSealSupport.instance();
+ assertThat(pqc.genesisAnchored())
+ .describedAs("the fixture must load a GENESIS-ANCHORED registry, or nothing here means anything")
+ .isTrue();
+ assertThat(pqc.addressBound()).isTrue();
+ assertThat(pqc.verify(0, MESSAGE, sealByIndexZero))
+ .describedAs("the seal must be a REAL Falcon signature under the head registry")
+ .isTrue();
+ }
+
+ // -------------------------------------------------------------------------------------------
+ // 1. THE MEASUREMENT. Chain 2800 as it stands: armed, and no pqRegistryHash anywhere.
+ // -------------------------------------------------------------------------------------------
+
+ @Test
+ public void d2t2AtAndAboveTheArmingHeightWithNoScheduleTheAnswerIsRefusal() {
+ final FalconSealSupport pqc = FalconSealSupport.instance();
+
+ // No schedule was ever loaded: verifyRegistryBindingOrAbort has not run, which is the state of
+ // every node on chain 2800 today, because config.pqRegistryHash is in no genesis this fleet
+ // runs (measured 2026-08-05, grep over deploy/ and monitoring/ returns nothing).
+ assertThat(pqc.verifyAtHistoric(H, 0, MESSAGE, sealByIndexZero))
+ .describedAs(
+ "D2/T2: at the arming height itself, a node with no height-to-registry binding must "
+ + "REFUSE. Before 2026-08-06 it answered from the registry in force at the HEAD, "
+ + "so one key rotation made every block above H unverifiable while the node "
+ + "reported success")
+ .isFalse();
+
+ assertThat(pqc.verifyAtHistoric(DEEP, 0, MESSAGE, sealByIndexZero))
+ .describedAs("and the same, far above the arming height")
+ .isFalse();
+
+ assertThat(pqc.addressForIndexAtHistoric(DEEP, 0))
+ .describedAs(
+ "the address half must refuse identically: PqAnchorSealsRule refuses an index it "
+ + "cannot bind, and a bound-by-guess address is worse than an unbound one")
+ .isNull();
+ }
+
+ // -------------------------------------------------------------------------------------------
+ // 2. Negative control: the refusal is HEIGHT-GATED. A rule that always refuses is not a repair.
+ // -------------------------------------------------------------------------------------------
+
+ @Test
+ public void belowTheArmingHeightTheHeadRegistryStillAnswers() {
+ final FalconSealSupport pqc = FalconSealSupport.instance();
+ assertThat(pqc.verifyAtHistoric(H - 1L, 0, MESSAGE, sealByIndexZero))
+ .describedAs(
+ "one block below H nothing is being judged, so the head registry is the right answer "
+ + "and the 11.8 million blocks already on chain must behave exactly as before")
+ .isTrue();
+ assertThat(pqc.verifyAtHistoric(0L, 0, MESSAGE, sealByIndexZero)).isTrue();
+ assertThat(pqc.addressForIndexAtHistoric(H - 1L, 0)).isEqualTo(validators.get(0));
+ }
+
+ // -------------------------------------------------------------------------------------------
+ // 3. Negative control: the refusal is ARMING-gated. This is the proof that the live fleet is
+ // untouched, and it is the assertion that fails first if that stops being true.
+ // -------------------------------------------------------------------------------------------
+
+ @Test
+ public void whenTheAnchorIsNotArmedNOTHINGCHANGES() {
+ PqAnchorProducer.useConfigForTesting(PqAnchorConfig.never(CHAIN_ID));
+ final FalconSealSupport pqc = FalconSealSupport.instance();
+ assertThat(pqc.verifyAtHistoric(DEEP, 0, MESSAGE, sealByIndexZero))
+ .describedAs(
+ "chain 2800 today: aere.pq.anchorBlock unset, so there is no arming height, no height "
+ + "is at or above it, and every answer is what it was before this repair")
+ .isTrue();
+ assertThat(pqc.addressForIndexAtHistoric(DEEP, 0)).isEqualTo(validators.get(0));
+ }
+
+ // -------------------------------------------------------------------------------------------
+ // 4. Positive control: what the refusal is a refusal ABOUT. Configure the binding and the armed
+ // heights answer again - through the height-resolved path, not the head-registry fallback.
+ // -------------------------------------------------------------------------------------------
+
+ @Test
+ public void withTheScheduleConfiguredTheArmedHeightsAnswerAgain() throws Exception {
+ final FalconSealSupport pqc = FalconSealSupport.instance();
+ final PqRegistryHash.Registry held = PqRegistryHash.loadAuto(genesisPath);
+ final String hash = PqRegistryHash.hashFor(held, CHAIN_ID);
+
+ // The first scheduled entry sits EXACTLY at the arming height, which is the rule the epoch-list
+ // design states: below H requiredHashAt is empty and the fallback is unreachable by anything
+ // that decides a header.
+ // AERE D-146 (2026-08-06): the hash above is hashFor, not hashV1, because this fixture's
+ // registry is now v2 and hashes under a different domain tag. A schedule entry that names the
+ // v1 number names a registry this node does not hold.
+ final PqRegistryHash.Schedule schedule = scheduleFromGenesis(Map.of(H, hash));
+ pqc.verifyRegistryBindingOrAbort(0L, CHAIN_ID, schedule);
+
+ assertThat(pqc.verifyAtHistoric(DEEP, 0, MESSAGE, sealByIndexZero))
+ .describedAs(
+ "with the epoch bound at H and the registry held, the armed heights resolve through "
+ + "the schedule. If this is false the refusal is not about a missing binding and "
+ + "the measurement above proves nothing")
+ .isTrue();
+ assertThat(pqc.addressForIndexAtHistoric(DEEP, 0)).isEqualTo(validators.get(0));
+ assertThat(pqc.verifyAtHistoric(H - 1L, 0, MESSAGE, sealByIndexZero))
+ .describedAs("and below H the fallback is still the answer")
+ .isTrue();
+ }
+
+ // -------------------------------------------------------------------------------------------
+ // 5. The case the epoch list exists FOR: an epoch this node does not hold. Refused, and named.
+ // -------------------------------------------------------------------------------------------
+
+ @Test
+ public void anEpochThisNodeDoesNotHoldIsRefusedAndNAMED() throws Exception {
+ final FalconSealSupport pqc = FalconSealSupport.instance();
+ final PqRegistryHash.Registry held = PqRegistryHash.loadAuto(genesisPath);
+ final String hash = PqRegistryHash.hashFor(held, CHAIN_ID);
+ final long rotation = K_AT + 1_000L;
+
+ // Two epochs: the one this node holds, and a rotation to a registry it was never given. This is
+ // the shape of "an operator rotated a compromised key and one node did not get the file".
+ final PqRegistryHash.Schedule schedule =
+ scheduleFromGenesis(
+ new java.util.LinkedHashMap<>(
+ Map.of(H, hash, rotation, "0x" + "cd".repeat(32))));
+ pqc.verifyRegistryBindingOrAbort(0L, CHAIN_ID, schedule);
+
+ assertThat(pqc.verifyAtHistoric(rotation - 1L, 0, MESSAGE, sealByIndexZero))
+ .describedAs("below the rotation this node holds the epoch and answers")
+ .isTrue();
+ assertThat(pqc.verifyAtHistoric(rotation, 0, MESSAGE, sealByIndexZero))
+ .describedAs(
+ "at the rotation the epoch is covered by NOTHING this node holds. It stops here; it "
+ + "does not answer from whatever it happens to have")
+ .isFalse();
+ assertThat(pqc.addressForIndexAtHistoric(rotation, 0)).isNull();
+ }
+
+ // -------------------------------------------------------------------------------------------
+ // Helpers.
+ // -------------------------------------------------------------------------------------------
+
+ /**
+ * Build a schedule the way a node really gets one: written into a genesis file as {@code
+ * config.pqRegistryHash} and parsed back. Constructing the object directly would skip the parser,
+ * which is where the strictly-increasing rule lives.
+ *
+ * @param entries height to 0x-prefixed registry hash, in ascending order of height
+ * @return the parsed schedule
+ * @throws Exception when the temporary genesis cannot be written
+ */
+ private PqRegistryHash.Schedule scheduleFromGenesis(final Map<Long, String> entries)
+ throws Exception {
+ final List<Long> heights = new ArrayList<>(entries.keySet());
+ heights.sort(Long::compare);
+ final StringBuilder sb = new StringBuilder("{\"config\":{\"pqRegistryHash\":[");
+ for (int i = 0; i < heights.size(); i++) {
+ if (i > 0) {
+ sb.append(',');
+ }
+ final long b = heights.get(i);
+ String h = entries.get(b);
+ if (!h.startsWith("0x")) {
+ h = "0x" + h;
+ }
+ sb.append("{\"block\":").append(b).append(",\"hash\":\"").append(h).append("\"}");
+ }
+ sb.append("]}}");
+ final Path p = tmp.resolve("genesis-schedule-" + heights.size() + "-" + heights.get(0) + ".json");
+ Files.writeString(p, sb.toString());
+ return PqRegistryHash.loadScheduleFromGenesis(p);
+ }
+
+ private static void resetFalconSingleton() throws Exception {
+ final Field f = FalconSealSupport.class.getDeclaredField("instance");
+ f.setAccessible(true);
+ f.set(null, null);
+ }
+}
diff --git a/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqRegistryRotationTest.java b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqRegistryRotationTest.java
new file mode 100755
index 000000000..96debad37
--- /dev/null
+++ b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqRegistryRotationTest.java
@@ -0,0 +1,486 @@
+/*
+ * Copyright contributors to Besu / AERE Network.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.common.bft;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.ArrayList;
+import java.util.List;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+
+/**
+ * D-081: the Falcon signer registry has no usable rotation and no usable revocation.
+ *
+ * <p>WHAT IS MEASURED HERE, and why it is measured against the real classes rather than described.
+ * {@code config.pqRegistryHash} is a SCHEDULE of {block, hash} entries, and the A8 dossier states
+ * that "a later entry expresses a key rotation". This file asks whether that sentence survives
+ * contact with the code that enforces it.
+ *
+ * <p>The enforcement side is {@link PqRegistryHash#matchesAt} and, on the block path, {@code
+ * FalconSealSupport.registryBindingSatisfiedAt(height)}, which calls it. Both take exactly ONE
+ * loaded registry, and the node loads exactly one file ({@code aere.falcon.registry}). The entry the
+ * schedule makes active at a height decides which hash is required THERE. So after one rotation at
+ * H2 there are two intervals with two different required hashes, and one file can satisfy at most
+ * one of them.
+ *
+ * <p>The consequence is not cosmetic and it is not confined to the rotation moment. {@code
+ * PqRegistryBindingRule} is a DETACHED rule, so it runs on the header-download path, and {@code
+ * PqAnchorSyncModeGuard} refuses to start an armed node in anything but FULL sync. A node acquiring
+ * history therefore validates every height, including the interval before the rotation. Holding the
+ * post-rotation registry it is refused there; holding the pre-rotation registry it is refused at the
+ * head. There is no third choice. ONE rotation makes the chain permanently unjoinable.
+ *
+ * <p>This is the lesson Cosmos ADR-016 writes down explicitly: a rotation scheme has to keep the
+ * MAPPING FROM HEIGHT TO KEY SET, not only the current key set, or blocks signed under the old set
+ * stop being verifiable. Cosmos may bound that history by the unbonding period. We may not: chain
+ * 2800 has no unbonding period and a node syncing from genesis must verify every block that was ever
+ * produced, so every entry ever scheduled has to stay loadable forever.
+ *
+ * <p>{@code rotationDoesNotBrickHistory} and {@code revocationDoesNotBrickHistory} are the
+ * measurement. They FAIL while the defect is present and pass only when a node can be configured to
+ * satisfy the binding at EVERY scheduled height at once. The other tests are controls: they assert
+ * that the schedule really does express rotation and really does refuse a malformed one, so a
+ * failure of the two measurements cannot be blamed on the fixture.
+ */
+// The D-081 label is our internal finding id. It names a fact about this
+// code, not anything outside it.
+public class PqRegistryRotationTest {
+
+ private static final long CHAIN_ID = 2800L;
+
+ /** First binding height: the height the post-quantum registry is first enforced from. */
+ private static final long H1 = 12_000_000L;
+
+ /** Rotation height: from here the chain requires the SECOND registry. */
+ private static final long H2 = 12_100_000L;
+
+ /** Falcon-512 public key length as this registry format stores it (bare h polynomial). */
+ private static final int PK_LENGTH = 896;
+
+ /** The seven validators of chain 2800. */
+ private static final int N = 7;
+
+ /**
+ * One node configuration, expressed as the only question the consensus path ever asks it: does
+ * the registry material this node holds satisfy the binding the chain requires at this height?
+ *
+ * <p>It is an interface and not a Registry so that the measurement can be stated once and asked of
+ * every configuration a node can actually be put into. Today there is exactly one shape of answer,
+ * {@link #single}, because a node loads one file. A repair that lets a node hold the whole
+ * scheduled history adds a second shape here and the assertion below stops failing. Nothing in the
+ * assertion has to change, which is the point: the property is fixed, the capability is what moves.
+ */
+ private interface NodeConfiguration {
+ boolean satisfiesAt(long height);
+
+ String describe();
+ }
+
+ private static NodeConfiguration single(
+ final String name, final PqRegistryHash.Schedule schedule, final PqRegistryHash.Registry r) {
+ return new NodeConfiguration() {
+ @Override
+ public boolean satisfiesAt(final long height) {
+ return PqRegistryHash.matchesAt(schedule, r, height, CHAIN_ID);
+ }
+
+ @Override
+ public String describe() {
+ return "node holding only registry " + name;
+ }
+ };
+ }
+
+ // ---------------------------------------------------------------------------------------
+ // Fixture. Two registries that differ in exactly one row, which is what both a rotation and a
+ // revocation look like on the wire: index 3 stops being the key it was.
+ // ---------------------------------------------------------------------------------------
+
+ private static byte[] deterministicKey(final int index, final int generation) {
+ final byte[] pk = new byte[PK_LENGTH];
+ for (int i = 0; i < pk.length; i++) {
+ pk[i] = (byte) ((i * 31) + (index * 7) + (generation * 101));
+ }
+ return pk;
+ }
+
+ private static byte[] address(final int index) {
+ final byte[] a = new byte[20];
+ for (int i = 0; i < a.length; i++) {
+ a[i] = (byte) ((index * 17) + i);
+ }
+ return a;
+ }
+
+ private static String hex(final byte[] b) {
+ final StringBuilder sb = new StringBuilder(b.length * 2);
+ for (final byte x : b) {
+ sb.append(String.format("%02x", x));
+ }
+ return sb.toString();
+ }
+
+ /**
+ * A seven-row address-bound registry. {@code rotatedIndex} is the row whose key belongs to
+ * generation 2; every other row is generation 1. Passing -1 gives the untouched registry.
+ */
+ private static Path writeRegistry(final Path dir, final String name, final int rotatedIndex)
+ throws IOException {
+ final StringBuilder sb = new StringBuilder();
+ sb.append("count=").append(N).append('\n');
+ for (int i = 0; i < N; i++) {
+ sb.append(i).append('=').append(hex(deterministicKey(i, i == rotatedIndex ? 2 : 1))).append('\n');
+ sb.append(i).append(".addr=").append(hex(address(i))).append('\n');
+ }
+ final Path p = dir.resolve(name);
+ Files.write(p, sb.toString().getBytes(StandardCharsets.UTF_8));
+ return p;
+ }
+
+ private static PqRegistryHash.Schedule scheduleOf(final String hashAtH1, final String hashAtH2) {
+ final String json =
+ "[{\"block\":"
+ + H1
+ + ",\"hash\":\"0x"
+ + hashAtH1
+ + "\"},{\"block\":"
+ + H2
+ + ",\"hash\":\"0x"
+ + hashAtH2
+ + "\"}]";
+ final JsonNode node;
+ try {
+ node = new ObjectMapper().readTree(json);
+ } catch (final IOException e) {
+ throw new IllegalStateException(e);
+ }
+ return PqRegistryHash.parseSchedule(node, "D-081 fixture");
+ }
+
+ /** Every height at which the binding is enforced and could differ across the rotation. */
+ private static List<Long> enforcedHeights() {
+ final List<Long> heights = new ArrayList<>();
+ heights.add(H1);
+ heights.add(H1 + 1);
+ heights.add(H2 - 1);
+ heights.add(H2);
+ heights.add(H2 + 1);
+ return heights;
+ }
+
+ /**
+ * The configurations a node can ACTUALLY be put into with the code as it stands. A repair that
+ * gives a node the whole scheduled history appends its configuration here; nothing else changes.
+ */
+ private static List<NodeConfiguration> availableConfigurations(
+ final PqRegistryHash.Schedule schedule,
+ final PqRegistryHash.Registry before,
+ final PqRegistryHash.Registry after) {
+ final List<NodeConfiguration> all = new ArrayList<>();
+ all.add(single("BEFORE", schedule, before));
+ all.add(single("AFTER", schedule, after));
+ all.add(wholeHistory(schedule, before, after));
+ return all;
+ }
+
+ /**
+ * D-081 repair: the node holds the WHOLE scheduled history and resolves by height. This
+ * configuration did not exist before the repair, which is why the assertion below could not be
+ * satisfied by any node at all.
+ */
+ private static NodeConfiguration wholeHistory(
+ final PqRegistryHash.Schedule schedule,
+ final PqRegistryHash.Registry before,
+ final PqRegistryHash.Registry after) {
+ final List<PqRegistryHash.Registry> held = new ArrayList<>();
+ held.add(before);
+ held.add(after);
+ final PqRegistryHash.RegistrySet set = PqRegistryHash.buildSet(schedule, held, CHAIN_ID);
+ return new NodeConfiguration() {
+ @Override
+ public boolean satisfiesAt(final long height) {
+ return PqRegistryHash.matchesAt(schedule, set, height, CHAIN_ID);
+ }
+
+ @Override
+ public String describe() {
+ return "node holding the whole scheduled history (" + set + ")";
+ }
+ };
+ }
+
+ // ---------------------------------------------------------------------------------------
+ // Controls. If these fail, the fixture is wrong and the measurements below mean nothing.
+ // ---------------------------------------------------------------------------------------
+
+ @Test
+ public void controlTheScheduleReallyDoesExpressARotation(@TempDir final Path dir)
+ throws IOException {
+ final PqRegistryHash.Registry before =
+ PqRegistryHash.loadPropertiesRegistry(writeRegistry(dir, "before.properties", -1));
+ final PqRegistryHash.Registry after =
+ PqRegistryHash.loadPropertiesRegistry(writeRegistry(dir, "after.properties", 3));
+
+ final String hashBefore = PqRegistryHash.hashV1(before, CHAIN_ID);
+ final String hashAfter = PqRegistryHash.hashV1(after, CHAIN_ID);
+ assertThat(hashBefore).isNotEqualTo(hashAfter);
+
+ final PqRegistryHash.Schedule schedule = scheduleOf(hashBefore, hashAfter);
+ assertThat(schedule.enforced()).isTrue();
+ assertThat(schedule.entries()).hasSize(2);
+
+ // Below the first entry nothing is bound: the 11.8 million existing blocks stay untouched.
+ assertThat(PqRegistryHash.requiredHashAt(schedule, H1 - 1)).isEmpty();
+ assertThat(PqRegistryHash.requiredHashAt(schedule, H1).orElseThrow().hash()).isEqualTo(hashBefore);
+ assertThat(PqRegistryHash.requiredHashAt(schedule, H2 - 1).orElseThrow().hash())
+ .isEqualTo(hashBefore);
+ assertThat(PqRegistryHash.requiredHashAt(schedule, H2).orElseThrow().hash()).isEqualTo(hashAfter);
+ }
+
+ @Test
+ public void controlAMalformedScheduleIsRefused(@TempDir final Path dir) throws IOException {
+ final PqRegistryHash.Registry before =
+ PqRegistryHash.loadPropertiesRegistry(writeRegistry(dir, "before.properties", -1));
+ final String h = PqRegistryHash.hashV1(before, CHAIN_ID);
+ final String json =
+ "[{\"block\":" + H2 + ",\"hash\":\"0x" + h + "\"},{\"block\":" + H1 + ",\"hash\":\"0x" + h + "\"}]";
+ final JsonNode node = new ObjectMapper().readTree(json);
+ assertThatThrownBy(() -> PqRegistryHash.parseSchedule(node, "D-081 fixture"))
+ .isInstanceOf(PqRegistryHash.RegistryConfigException.class)
+ .hasMessageContaining("STRICTLY INCREASING");
+ }
+
+ // ---------------------------------------------------------------------------------------
+ // THE MEASUREMENT.
+ // ---------------------------------------------------------------------------------------
+
+ @Test
+ public void rotationDoesNotBrickHistory(@TempDir final Path dir) throws IOException {
+ final PqRegistryHash.Registry before =
+ PqRegistryHash.loadPropertiesRegistry(writeRegistry(dir, "before.properties", -1));
+ final PqRegistryHash.Registry after =
+ PqRegistryHash.loadPropertiesRegistry(writeRegistry(dir, "after.properties", 3));
+ final PqRegistryHash.Schedule schedule =
+ scheduleOf(
+ PqRegistryHash.hashV1(before, CHAIN_ID), PqRegistryHash.hashV1(after, CHAIN_ID));
+
+ final List<Long> heights = enforcedHeights();
+ final List<NodeConfiguration> configurations =
+ availableConfigurations(schedule, before, after);
+
+ final List<String> report = new ArrayList<>();
+ NodeConfiguration complete = null;
+ for (final NodeConfiguration c : configurations) {
+ final List<Long> refused = new ArrayList<>();
+ for (final long h : heights) {
+ if (!c.satisfiesAt(h)) {
+ refused.add(h);
+ }
+ }
+ report.add(c.describe() + " is refused at " + refused);
+ if (refused.isEmpty()) {
+ complete = c;
+ }
+ }
+
+ assertThat(complete)
+ .withFailMessage(
+ "ROTATION IS NOT USABLE: one scheduled rotation at height %d leaves NO node configuration "
+ + "that "
+ + "satisfies the registry binding at every enforced height. %s. A node that cannot "
+ + "satisfy the binding at a height cannot import a header at that height "
+ + "(PqRegistryBindingRule is DETACHED, so it runs on the header-download path), and "
+ + "PqAnchorSyncModeGuard forces FULL sync when the anchor is armed, so every node "
+ + "acquiring history must pass through the pre-rotation interval AND reach the head. "
+ + "Using the rotation mechanism once therefore makes the chain permanently "
+ + "unjoinable. A rotation scheme must keep the whole HEIGHT-TO-KEY-SET mapping "
+ + "loadable, not only the current entry.",
+ H2,
+ String.join("; ", report))
+ .isNotNull();
+ }
+
+ @Test
+ public void revocationDoesNotBrickHistory(@TempDir final Path dir) throws IOException {
+ // Revocation is the same wire shape as rotation and is measured separately because it is the
+ // case with a deadline: a compromised Falcon key has to stop counting, and the operator has no
+ // reason to be able to re-sync afterwards only by luck.
+ final PqRegistryHash.Registry withCompromised =
+ PqRegistryHash.loadPropertiesRegistry(writeRegistry(dir, "compromised.properties", -1));
+ final PqRegistryHash.Registry revoked =
+ PqRegistryHash.loadPropertiesRegistry(writeRegistry(dir, "revoked.properties", 5));
+ final PqRegistryHash.Schedule schedule =
+ scheduleOf(
+ PqRegistryHash.hashV1(withCompromised, CHAIN_ID),
+ PqRegistryHash.hashV1(revoked, CHAIN_ID));
+
+ NodeConfiguration complete = null;
+ final List<String> report = new ArrayList<>();
+ for (final NodeConfiguration c : availableConfigurations(schedule, withCompromised, revoked)) {
+ boolean all = true;
+ final List<Long> refused = new ArrayList<>();
+ for (final long h : enforcedHeights()) {
+ if (!c.satisfiesAt(h)) {
+ all = false;
+ refused.add(h);
+ }
+ }
+ report.add(c.describe() + " is refused at " + refused);
+ if (all) {
+ complete = c;
+ }
+ }
+
+ assertThat(complete)
+ .withFailMessage(
+ "REVOCATION IS NOT USABLE: revoking one signer at height %d leaves NO node "
+ + "configuration that satisfies the binding at every enforced height. %s. The "
+ + "revocation is expressible and is not usable: performing it costs the ability to "
+ + "acquire the chain.",
+ H2,
+ String.join("; ", report))
+ .isNotNull();
+ }
+
+ @Test
+ public void theKeySetInForceBelowTheRotationIsTheOldOne(@TempDir final Path dir)
+ throws IOException {
+ // Coverage alone would be satisfied by a set that answered every height with the same registry.
+ // This is the positive proof that the height actually selects: an old block resolves to the OLD
+ // key set, which is the whole reason the history is kept.
+ final PqRegistryHash.Registry before =
+ PqRegistryHash.loadPropertiesRegistry(writeRegistry(dir, "before.properties", -1));
+ final PqRegistryHash.Registry after =
+ PqRegistryHash.loadPropertiesRegistry(writeRegistry(dir, "after.properties", 3));
+ final PqRegistryHash.Schedule schedule =
+ scheduleOf(PqRegistryHash.hashV1(before, CHAIN_ID), PqRegistryHash.hashV1(after, CHAIN_ID));
+ final List<PqRegistryHash.Registry> held = new ArrayList<>();
+ held.add(before);
+ held.add(after);
+ final PqRegistryHash.RegistrySet set = PqRegistryHash.buildSet(schedule, held, CHAIN_ID);
+
+ assertThat(set.coversWholeSchedule()).isTrue();
+ assertThat(PqRegistryHash.registryAt(schedule, set, H1 - 1)).isEmpty();
+ assertThat(PqRegistryHash.registryAt(schedule, set, H2 - 1).orElseThrow()).isSameAs(before);
+ assertThat(PqRegistryHash.registryAt(schedule, set, H2).orElseThrow()).isSameAs(after);
+
+ // And the two really do differ at the rotated index, so "same registry everywhere" could not
+ // have produced the answers above.
+ assertThat(PqRegistryHash.fingerprint(before, 3))
+ .isNotEqualTo(PqRegistryHash.fingerprint(after, 3));
+ assertThat(PqRegistryHash.fingerprint(before, 0)).isEqualTo(PqRegistryHash.fingerprint(after, 0));
+ }
+
+ @Test
+ public void aMissingHistoricalRegistryIsNamedAndFailsClosed(@TempDir final Path dir)
+ throws IOException {
+ // The repair must not turn "I do not hold that registry" into "fine". An uncovered entry is
+ // named by height and refuses at exactly the heights it governs, and nowhere else.
+ final PqRegistryHash.Registry before =
+ PqRegistryHash.loadPropertiesRegistry(writeRegistry(dir, "before.properties", -1));
+ final PqRegistryHash.Registry after =
+ PqRegistryHash.loadPropertiesRegistry(writeRegistry(dir, "after.properties", 3));
+ final PqRegistryHash.Schedule schedule =
+ scheduleOf(PqRegistryHash.hashV1(before, CHAIN_ID), PqRegistryHash.hashV1(after, CHAIN_ID));
+
+ final List<PqRegistryHash.Registry> onlyAfter = new ArrayList<>();
+ onlyAfter.add(after);
+ final PqRegistryHash.RegistrySet partial =
+ PqRegistryHash.buildSet(schedule, onlyAfter, CHAIN_ID);
+
+ assertThat(partial.coversWholeSchedule()).isFalse();
+ assertThat(partial.uncoveredEntryBlocks()).containsExactly(H1);
+ assertThat(PqRegistryHash.matchesAt(schedule, partial, H1, CHAIN_ID)).isFalse();
+ assertThat(PqRegistryHash.matchesAt(schedule, partial, H2 - 1, CHAIN_ID)).isFalse();
+ assertThat(PqRegistryHash.matchesAt(schedule, partial, H2, CHAIN_ID)).isTrue();
+ // Below the schedule nothing is enforced, so an incomplete set still leaves history alone.
+ assertThat(PqRegistryHash.matchesAt(schedule, partial, H1 - 1, CHAIN_ID)).isTrue();
+ // And a null set is refused wherever a binding is active, never passed over.
+ assertThat(PqRegistryHash.matchesAt(schedule, (PqRegistryHash.RegistrySet) null, H1, CHAIN_ID))
+ .isFalse();
+ }
+
+ @Test
+ public void theOperatorConfigurationStringProducesACoveringSet(@TempDir final Path dir)
+ throws IOException {
+ // WHY THIS EXISTS, and it is a gap the other six leave open on purpose-by-omission. Every one of
+ // them reaches the covering configuration by calling PqRegistryHash.buildSet with a list of
+ // Registry objects the test built itself. No operator can do that. What an operator can do is
+ // write a comma-separated list of FILE PATHS into aere.falcon.registry.history, and the node
+ // turns that string into the same set through parseRegistryPaths + loadAuto
+ // (FalconSealSupport.verifyRegistryBindingOrAbort, the D-081 block). If that route were broken
+ // the other six would still be green and the capability would still not be usable, which is the
+ // exact shape of "a green result in a reduced environment is true and worthless".
+ //
+ // So this measurement starts from the STRING and ends at the same property the measurement
+ // tests assert: satisfied at every enforced height.
+ final Path beforePath = writeRegistry(dir, "before.properties", -1);
+ final Path afterPath = writeRegistry(dir, "after.properties", 3);
+ final PqRegistryHash.Registry before = PqRegistryHash.loadPropertiesRegistry(beforePath);
+ final PqRegistryHash.Registry after = PqRegistryHash.loadPropertiesRegistry(afterPath);
+ final PqRegistryHash.Schedule schedule =
+ scheduleOf(PqRegistryHash.hashV1(before, CHAIN_ID), PqRegistryHash.hashV1(after, CHAIN_ID));
+
+ // Written the way an operator writes it: one string, comma separated, with the sloppy spacing
+ // a unit file actually carries. The node's own file is the FIRST element of the held list, so
+ // the string names the OTHER one; here both are named, which is also legal and must not
+ // double-count.
+ final String configured = " " + beforePath + " , " + afterPath + " ,";
+ final List<Path> paths = PqRegistryHash.parseRegistryPaths(configured);
+ assertThat(paths).hasSize(2);
+
+ final PqRegistryHash.RegistrySet set = PqRegistryHash.loadSet(schedule, paths, CHAIN_ID);
+ assertThat(set.coversWholeSchedule()).isTrue();
+ assertThat(set.uncoveredEntryBlocks()).isEmpty();
+
+ final List<Long> refused = new ArrayList<>();
+ for (final long h : enforcedHeights()) {
+ if (!PqRegistryHash.matchesAt(schedule, set, h, CHAIN_ID)) {
+ refused.add(h);
+ }
+ }
+ assertThat(refused)
+ .withFailMessage(
+ "ROTATION IS NOT USABLE on the route an operator can actually take: the history list %s "
+ + "parses "
+ + "and loads, and the resulting set is still refused at %s. The library can express "
+ + "the whole height-to-key-set mapping but the configuration string cannot reach "
+ + "it, so the rotation remains expressible and not usable.",
+ configured, refused)
+ .isEmpty();
+
+ // Positive proof that the string, not luck, did the selecting: below the rotation the OLD file
+ // is in force, at and above it the NEW one.
+ assertThat(PqRegistryHash.registryAt(schedule, set, H2 - 1).orElseThrow())
+ .isNotSameAs(PqRegistryHash.registryAt(schedule, set, H2).orElseThrow());
+
+ // And the failure direction on the same route: a history string that names only one of the two
+ // files leaves the other entry uncovered, named by height, and refusing exactly there.
+ final PqRegistryHash.RegistrySet partial =
+ PqRegistryHash.loadSet(
+ schedule, PqRegistryHash.parseRegistryPaths(afterPath.toString()), CHAIN_ID);
+ assertThat(partial.uncoveredEntryBlocks()).containsExactly(H1);
+ assertThat(PqRegistryHash.matchesAt(schedule, partial, H1, CHAIN_ID)).isFalse();
+ }
+}
diff --git a/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqSchemeScheduleTest.java b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqSchemeScheduleTest.java
new file mode 100755
index 000000000..41e03e825
--- /dev/null
+++ b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqSchemeScheduleTest.java
@@ -0,0 +1,127 @@
+/* AERE crypto-agility, step 5 proofs. The D-147 control is the one that matters: the dangerous
+ * step hides at the END of the schedule, and the gate must walk all of it. */
+package org.hyperledger.besu.consensus.common.bft;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+import java.security.SecureRandom;
+import java.util.Properties;
+import java.util.Set;
+
+import org.apache.tuweni.bytes.Bytes;
+import org.hyperledger.besu.crypto.SecureRandomProvider;
+import org.junit.jupiter.api.Test;
+
+class PqSchemeScheduleTest {
+
+ private static final String FALCON = "falcon-512";
+ private static final String SLHDSA = "slh-dsa-128s";
+
+ private final SecureRandom random = SecureRandomProvider.createSecureRandom();
+
+ // ------------------------------------------------------------------ parse + schemesAt
+
+ @Test
+ void schedulesParseAndAnswerByHeight() {
+ final PqSchemeSchedule orar =
+ PqSchemeSchedule.parse("100:falcon-512,200:falcon-512+slh-dsa-128s");
+ assertThat(orar.schemesAt(99)).isEmpty(); // inainte de prima treapta: v2 nearmat
+ assertThat(orar.schemesAt(100)).containsExactlyInAnyOrder(FALCON); // exact pe granita
+ assertThat(orar.schemesAt(150)).containsExactlyInAnyOrder(FALCON);
+ assertThat(orar.schemesAt(200)).containsExactlyInAnyOrder(FALCON, SLHDSA); // hibridul
+ assertThat(orar.schemesAt(1_000_000)).containsExactlyInAnyOrder(FALCON, SLHDSA);
+ }
+
+ // ------------------------------------------------------------------ refuzuri de parse
+
+ @Test
+ void unknownSchemeAnywhereRefusesTheWholeSchedule() {
+ assertThatThrownBy(() -> PqSchemeSchedule.parse("100:falcon-512,200:dilithium-notyet"))
+ .isInstanceOf(IllegalArgumentException.class)
+ .hasMessageContaining("dilithium-notyet");
+ }
+
+ @Test
+ void nonIncreasingHeightsRefuse() {
+ assertThatThrownBy(() -> PqSchemeSchedule.parse("200:falcon-512,100:falcon-512"))
+ .isInstanceOf(IllegalArgumentException.class)
+ .hasMessageContaining("strictly increase");
+ assertThatThrownBy(() -> PqSchemeSchedule.parse("200:falcon-512,200:slh-dsa-128s"))
+ .isInstanceOf(IllegalArgumentException.class)
+ .hasMessageContaining("strictly increase");
+ }
+
+ @Test
+ void emptyAndMalformedStepsRefuse() {
+ assertThatThrownBy(() -> PqSchemeSchedule.parse("")).isInstanceOf(IllegalArgumentException.class);
+ assertThatThrownBy(() -> PqSchemeSchedule.parse("100")).isInstanceOf(IllegalArgumentException.class);
+ assertThatThrownBy(() -> PqSchemeSchedule.parse("abc:falcon-512"))
+ .isInstanceOf(IllegalArgumentException.class);
+ assertThatThrownBy(() -> PqSchemeSchedule.parse("100:"))
+ .isInstanceOf(IllegalArgumentException.class);
+ assertThatThrownBy(() -> PqSchemeSchedule.parse("100:falcon-512+falcon-512"))
+ .isInstanceOf(IllegalArgumentException.class)
+ .hasMessageContaining("repeats");
+ assertThatThrownBy(() -> PqSchemeSchedule.parse("-5:falcon-512"))
+ .isInstanceOf(IllegalArgumentException.class);
+ }
+
+ // ------------------------------------------------------------- poarta de armare (D-147)
+
+ private HybridSignerRegistry registruCuAcoperire(final int falconi, final int slhuri) {
+ final Properties p = new Properties();
+ final int count = Math.max(falconi, Math.max(slhuri, 1));
+ p.setProperty("formatVersion", "hybrid-1");
+ p.setProperty("chainId", "2800");
+ p.setProperty("count", String.valueOf(count));
+ for (int i = 0; i < count; i++) {
+ p.setProperty(i + ".addr", "0x" + String.format("%040x", 0xB0 + i));
+ // fiecare index primeste macar o cheie; acoperirea per schema e controlata mai jos
+ if (i < falconi) {
+ p.setProperty(i + ".key." + FALCON,
+ Bytes.wrap(SealSchemes.FALCON_512.generate(random).publicRegistryForm()).toHexString());
+ }
+ if (i < slhuri) {
+ p.setProperty(i + ".key." + SLHDSA,
+ Bytes.wrap(SealSchemes.SLH_DSA_128S.generate(random).publicRegistryForm()).toHexString());
+ }
+ if (i >= falconi && i >= slhuri) {
+ p.setProperty(i + ".key." + FALCON,
+ Bytes.wrap(SealSchemes.FALCON_512.generate(random).publicRegistryForm()).toHexString());
+ }
+ }
+ return HybridSignerRegistry.fromProperties(p, "test");
+ }
+
+ @Test
+ void armabilityGateWalksTheWholeScheduleNotJustTheFirstStep() {
+ // the registry: 3 validators with Falcon, only 1 with SLH-DSA
+ final HybridSignerRegistry reg = registruCuAcoperire(3, 1);
+ // treapta PERICULOASA e ULTIMA: hibridul cere SLH-DSA cu acoperire 1 < K=3
+ final PqSchemeSchedule orar =
+ PqSchemeSchedule.parse("100:falcon-512,999999:falcon-512+slh-dsa-128s");
+ final var refusal = orar.firstUnsatisfied(reg, 3);
+ assertThat(refusal).isPresent();
+ assertThat(refusal.get()).contains("999999").contains(SLHDSA).contains("covers only 1");
+ }
+
+ @Test
+ void armabilityPassesWhenEverySchemeHasCoverage() {
+ final HybridSignerRegistry reg = registruCuAcoperire(3, 3);
+ final PqSchemeSchedule orar =
+ PqSchemeSchedule.parse("100:falcon-512,200:falcon-512+slh-dsa-128s");
+ assertThat(orar.firstUnsatisfied(reg, 3)).isEmpty();
+ // and the same gate's negative control: an impossible threshold must refuse
+ assertThat(orar.firstUnsatisfied(reg, 4)).isPresent();
+ }
+
+ @Test
+ void beforeTheFirstStepMeansLegacyNotSomeDefaultScheme() {
+ final PqSchemeSchedule orar = PqSchemeSchedule.parse("500:falcon-512");
+ assertThat(orar.schemesAt(0)).isEmpty();
+ assertThat(orar.schemesAt(499)).isEmpty();
+ assertThat(orar.steps()).hasSize(1);
+ assertThat(orar.steps().get(0).schemeIds()).isEqualTo(Set.of(FALCON));
+ }
+}
diff --git a/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqSealPersistenceTest.java b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqSealPersistenceTest.java
new file mode 100755
index 000000000..f0ffc4cab
--- /dev/null
+++ b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqSealPersistenceTest.java
@@ -0,0 +1,652 @@
+/*
+ * Copyright contributors to Besu / AERE Network.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.common.bft;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatCode;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+import static org.mockito.Mockito.withSettings;
+
+import org.hyperledger.besu.consensus.common.bft.blockcreation.PqAnchorProducer;
+import org.hyperledger.besu.consensus.common.validator.ValidatorProvider;
+import org.hyperledger.besu.crypto.SecureRandomProvider;
+import org.hyperledger.besu.datatypes.Address;
+import org.hyperledger.besu.ethereum.ProtocolContext;
+import org.hyperledger.besu.ethereum.core.BlockHeader;
+import org.hyperledger.besu.ethereum.core.BlockHeaderTestFixture;
+
+import java.lang.reflect.Field;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.Collection;
+import java.util.Collections;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.OptionalInt;
+import java.util.concurrent.atomic.AtomicBoolean;
+import java.util.concurrent.atomic.AtomicInteger;
+
+import org.apache.tuweni.bytes.Bytes;
+import org.apache.tuweni.bytes.Bytes32;
+import org.bouncycastle.crypto.digests.KeccakDigest;
+import org.bouncycastle.pqc.crypto.falcon.FalconPrivateKeyParameters;
+import org.bouncycastle.pqc.crypto.falcon.FalconSigner;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+import org.mockito.quality.Strictness;
+
+/**
+ * D-141. THE SECOND HALF OF THE FLEET-RESTART CHAIN DEATH: the heard seals themselves.
+ *
+ * <p>MEASURED ON A NETWORK FIRST, NOT ASSUMED. With the anchor armed at K&gt;0, a SIMULTANEOUS
+ * restart of all seven validators kills the chain permanently (rehearsal
+ * repetitie-activare-2026-08-05, isolated chain 330858). The FIRST half of that deadlock was the
+ * registry, repaired the same day: it now activates at start-up from chain-head state, and all
+ * seven nodes reported "anchor activation at STARTUP from head state: SUCCEEDED". The chain died
+ * anyway. The refusal only changed shape, from "registry address-bound=false" to "registry
+ * address-bound=TRUE ... Heard 0 seal(s)", frozen 150 s then 298 s.
+ *
+ * <p>THE SECOND CIRCLE. The Falcon seals over M(head) travel on nothing but the Commit messages of
+ * the head block, and those are never replayed after a restart. They exist nowhere else: the head's
+ * own header carries a certificate over its PARENT, not over itself. So every node came back holding
+ * zero seals, none could reach K, none could propose, and therefore none ever sent another Commit
+ * for another node to hear. Seals come from Commits, Commits come from proposals, proposals need
+ * seals.
+ *
+ * <p>WHAT THIS CLASS MEASURES, one test per link, with the causal chain driven in BOTH directions so
+ * that "refuses" is never satisfied by a producer that always refuses:
+ *
+ * <ol>
+ * <li>{@link #restartWithNoFileIsTheMeasuredDeadlockAndTheFileIsTheWayOut()} - the whole thing
+ * end to end: the same node, the same head, the same K. Without the file the producer throws;
+ * with the file restored it produces a K-seal certificate whose digest matches. This is the
+ * chain death and its exit, in one method.
+ * <li>{@link #aForgedSealInTheFileIsRejectedAtReadAndNeverEntersTheCache()} - THE SECURITY
+ * PROPERTY, and the test the build-time negative control turns RED. Three shapes of forgery in
+ * one file: a signature over the wrong message, random bytes, and a genuine seal re-labelled
+ * under someone else's index. None survives, and the genuine ones alongside them do.
+ * <li>{@link #aCorruptFileDoesNotStopTheNode()} - truncated, random, empty, a directory where the
+ * file should be. Every one of them yields an empty cache and no exception.
+ * <li>{@link #aFileFromAnotherHeightOrAnotherChainIsIgnored()} - the binding checks, before a
+ * single signature is verified.
+ * <li>{@link #theWriteIsAtomicUnderAConcurrentReader()} - a reader hammering the file across 120
+ * writes never observes a partial file.
+ * <li>{@link #thePathComesFromTheDataDirectory()} - the path is derived, never configured.
+ * <li>{@link #whatOneWriteCostsAgainstTheBlockInterval()} - the price of doing this on the
+ * consensus thread, as a number rather than as a hope.
+ * </ol>
+ *
+ * <p>NOT MEASURED here, and named so it is not read as covered: that seven live nodes recover from a
+ * real simultaneous restart with a binary built from this tree. That needs the rehearsal network and
+ * is separate evidence. This class measures every decision that recovery depends on.
+ */
+// The D-141 label is our internal finding id. It names a fact about this
+// code, not anything outside it.
+public class PqSealPersistenceTest {
+
+ /** Anchor activation height H. */
+ private static final long H = 1_000L;
+
+ /** Seal-attachment height, comfortably below H. */
+ private static final long ATTACH = 900L;
+
+ /** Height from which the staged threshold K is in force. */
+ private static final long K_AT = H + 10L;
+
+ /** The founder's decision of 2026-08-05: N=7 stays, and K=3 is the value with full margin. */
+ private static final int K = 3;
+
+ private static final int N = 7;
+
+ private static final long CHAIN_ID = 2_800L;
+
+ /** Measured block interval on the live chain, in milliseconds. */
+ private static final long BLOCK_INTERVAL_MS = 523L;
+
+ @TempDir private Path tmp;
+
+ /** Stands in for the node's data directory, which is where the real path comes from. */
+ private Path dataDirectory;
+
+ private final List<Address> validators = new ArrayList<>();
+ private final List<FalconPrivateKeyParameters> privateKeys = new ArrayList<>();
+ private BlockHeader head;
+ private ProtocolContext context;
+ private BftExtraData base;
+
+ @BeforeEach
+ public void setUp() throws Exception {
+ dataDirectory = Files.createDirectories(tmp.resolve("besu-data"));
+
+ // AERE D-146 (2026-08-06): v2, proof-bound, bound at H. See PqV2Fixture.
+ final KeccakDigest kd = new KeccakDigest(256);
+ final StringBuilder manifest =
+ new StringBuilder("{\"config\":{\"aereFalconRegistry\":{")
+ .append(PqV2Fixture.manifestHeader(N, CHAIN_ID, H));
+ for (int i = 0; i < N; i++) {
+ privateKeys.add(PqV2Fixture.privateKey(i));
+ validators.add(PqV2Fixture.address(i));
+ final byte[] anchoredRow = PqV2Fixture.anchorPreimageRow(i);
+ kd.update(anchoredRow, 0, anchoredRow.length);
+ manifest.append(',').append(PqV2Fixture.manifestEntry(i, N, CHAIN_ID, H));
+ }
+ final byte[] anchoredHash = new byte[32];
+ kd.doFinal(anchoredHash, 0);
+ manifest
+ .append("}},\"alloc\":{\"0000000000000000000000000000000000000fa1\":{\"storage\":{\"0x")
+ .append("0".repeat(64))
+ .append("\":\"0x")
+ .append(Bytes.wrap(anchoredHash).toUnprefixedHexString())
+ .append("\"}}}}");
+ final Path genesisPath = tmp.resolve("genesis-registry.json");
+ Files.writeString(genesisPath, manifest.toString());
+ System.setProperty("aere.falcon.genesis", genesisPath.toAbsolutePath().toString());
+ System.setProperty("aere.falcon.attachBlock", Long.toString(ATTACH));
+
+ resetFalconSingleton();
+ PqSealCache.instance().disablePersistence();
+ PqSealCache.instance().clear();
+ PqAnchorProducer.useConfigForTesting(
+ new PqAnchorConfig(CHAIN_ID, H, Map.of(H, 0, K_AT, K), OptionalInt.empty(), false));
+
+ head = new BlockHeaderTestFixture().number(K_AT + 20L).buildHeader();
+ context = contextWith(validators);
+ base =
+ new BftExtraData(
+ Bytes32.ZERO,
+ Collections.emptyList(),
+ Optional.empty(),
+ 0,
+ validators,
+ Collections.emptyList());
+ }
+
+ @AfterEach
+ public void tearDown() throws Exception {
+ System.clearProperty("aere.falcon.genesis");
+ System.clearProperty("aere.falcon.attachBlock");
+ PqSealCache.instance().disablePersistence();
+ PqSealCache.instance().clear();
+ PqAnchorProducer.useConfigForTesting(null);
+ resetFalconSingleton();
+ }
+
+ // -------------------------------------------------------------------------------------------
+ // 1. The chain death, and its exit, in one method.
+ // -------------------------------------------------------------------------------------------
+
+ @Test
+ public void restartWithNoFileIsTheMeasuredDeadlockAndTheFileIsTheWayOut() {
+ // Fixture control: without a genuinely armed registry every assertion below would be about
+ // nothing at all.
+ assertThat(FalconSealSupport.instance().genesisAnchored()).isTrue();
+ assertThat(FalconSealSupport.instance().addressBound()).isTrue();
+ assertThat(FalconSealSupport.instance().registrySize()).isEqualTo(N);
+
+ // --- BEFORE THE RESTART. The node is running, persistence is on, and it hears K Commits for
+ // its head exactly the way QbftRound.pqCacheHeardSeals feeds them in.
+ PqSealCache.instance().enablePersistence(dataDirectory, CHAIN_ID);
+ final Path file = PqSealStore.fileIn(dataDirectory);
+ for (int i = 0; i < K; i++) {
+ PqSealCache.instance().record(head.getNumber(), head.getHash(), List.of(genuineSeal(i)));
+ }
+ assertThat(file).exists();
+ assertThat(PqSealCache.instance().sealCount(head.getHash())).isEqualTo(K);
+
+ // --- THE RESTART. A fresh process: the map is gone, the file is not. Nothing else changes.
+ PqSealCache.instance().clear();
+ assertThat(PqSealCache.instance().sealCount(head.getHash()))
+ .describedAs("the in-memory map does not survive a restart, which is the whole problem")
+ .isZero();
+
+ // --- THE DEADLOCK, as measured on the seven-node network. Without the file this is terminal:
+ // no proposal means no Commit, and no Commit means no seal, for ever.
+ assertThatThrownBy(() -> PqAnchorProducer.apply(base, head, context))
+ .describedAs(
+ "the measured chain death: a restarted node holds no seals over M(head), so it cannot "
+ + "assemble a certificate and cannot propose")
+ .isInstanceOf(PqAnchorNotReadyException.class)
+ .hasMessageContaining("Heard 0 seal(s)");
+
+ // --- THE REPAIR. One read, every seal re-verified, and the same producer on the same inputs
+ // now produces a certificate. This is the ONLY thing the start-up code adds.
+ final int restored =
+ PqSealCache.instance()
+ .restoreFromDisk(
+ head.getNumber(), head.getHash(), PqSignerRegistry.falconSealSupport());
+ assertThat(restored).isEqualTo(K);
+ assertThat(PqSealCache.instance().sealCount(head.getHash())).isEqualTo(K);
+
+ final BftExtraData produced = PqAnchorProducer.apply(base, head, context);
+ assertThat(produced.getFalconSeals())
+ .describedAs("the restarted node can propose again, carrying a K=%d certificate", K)
+ .hasSize(K);
+ assertThat(PqAnchor.hasStrictlyIncreasingIndices(produced.getFalconSeals())).isTrue();
+ assertThat(produced.getVanityData())
+ .describedAs("and the anchor digest is the one the validator side will recompute")
+ .isEqualTo(
+ PqAnchor.anchorDigest(
+ CHAIN_ID,
+ head.getNumber(),
+ head.getHash().getBytes(),
+ PqAnchor.sortedByIndex(produced.getFalconSeals())));
+ }
+
+ // -------------------------------------------------------------------------------------------
+ // 2. THE SECURITY PROPERTY. This is the test the build-time negative control turns RED.
+ // -------------------------------------------------------------------------------------------
+
+ /**
+ * Persisting seals is only defensible because a seal is SELF-AUTHENTICATING: it is re-verified at
+ * read, against the anchored registry, over M rebuilt from the head this process just loaded. If
+ * that were not so, the file would be exactly defect A8 in another coat - state believed because
+ * it sits in a file a node can be pointed at.
+ *
+ * <p>Three shapes of forgery are in the one file, because "a forged seal" is not one thing:
+ *
+ * <ol>
+ * <li>index 3, a REAL Falcon signature by validator 3, but over another block's M. This is the
+ * replay an attacker with access to any past Commit traffic actually has.
+ * <li>index 4, random bytes of exactly the right length. The cheapest forgery there is.
+ * <li>index 5, validator 0's GENUINE signature over the right M, re-labelled as index 5. This
+ * one is the reason index alone can never be the check: the bytes are valid, the claim is
+ * not.
+ * </ol>
+ */
+ @Test
+ public void aForgedSealInTheFileIsRejectedAtReadAndNeverEntersTheCache() throws Exception {
+ final List<FalconSeal> genuine = List.of(genuineSeal(0), genuineSeal(1), genuineSeal(2));
+
+ final Bytes32 anotherBlocksMessage =
+ PqAnchor.commitMessage(CHAIN_ID, head.getNumber() - 1L, Bytes32.leftPad(Bytes.of(9)));
+ final byte[] randomBytes = new byte[genuine.get(0).getSignature().size()];
+ SecureRandomProvider.createSecureRandom().nextBytes(randomBytes);
+
+ final List<FalconSeal> forged =
+ List.of(
+ new FalconSeal(3, Bytes.wrap(falconSign(privateKeys.get(3), anotherBlocksMessage))),
+ new FalconSeal(4, Bytes.wrap(randomBytes)),
+ new FalconSeal(5, genuine.get(0).getSignature()));
+
+ final List<FalconSeal> all = new ArrayList<>(genuine);
+ all.addAll(forged);
+ final Path file = PqSealStore.fileIn(dataDirectory);
+ PqSealStore.writeAtomically(
+ file,
+ PqSealStore.encode(CHAIN_ID, head.getNumber(), head.getHash().getBytes(), all));
+ assertThat(file).exists();
+
+ PqSealCache.instance().enablePersistence(dataDirectory, CHAIN_ID);
+ final int restored =
+ PqSealCache.instance()
+ .restoreFromDisk(
+ head.getNumber(), head.getHash(), PqSignerRegistry.falconSealSupport());
+
+ assertThat(restored)
+ .describedAs(
+ "THE LOAD-BEARING ASSERTION. Six seals were in the file and only the three genuine ones "
+ + "may come out. Delete the verify() call in PqSealStore and this line goes red, "
+ + "which is exactly what the build-time negative control proves.")
+ .isEqualTo(3);
+
+ final List<FalconSeal> inCache =
+ PqSealCache.instance().sealsFor(head.getNumber(), head.getHash());
+ assertThat(inCache).hasSize(3);
+ assertThat(inCache.stream().map(FalconSeal::getValidatorIndex))
+ .describedAs("no forged index may reach the cache at all")
+ .containsExactly(0, 1, 2);
+ assertThat(inCache).containsExactlyInAnyOrderElementsOf(genuine);
+
+ // And the genuine ones are not merely present, they are usable: the producer, which verifies
+ // again at selection, accepts exactly these three. Without this half the test would be
+ // satisfied by a reader that rejected everything.
+ final BftExtraData produced = PqAnchorProducer.apply(base, head, context);
+ assertThat(produced.getFalconSeals()).hasSize(K).containsExactlyElementsOf(genuine);
+ }
+
+ // -------------------------------------------------------------------------------------------
+ // 3. A corrupt file must never be able to stop a node.
+ // -------------------------------------------------------------------------------------------
+
+ @Test
+ public void aCorruptFileDoesNotStopTheNode() throws Exception {
+ final Path file = PqSealStore.fileIn(dataDirectory);
+ final byte[] good =
+ PqSealStore.encode(
+ CHAIN_ID,
+ head.getNumber(),
+ head.getHash().getBytes(),
+ List.of(genuineSeal(0), genuineSeal(1), genuineSeal(2)));
+ PqSealCache.instance().enablePersistence(dataDirectory, CHAIN_ID);
+
+ // (a) no file at all: the ordinary first start.
+ Files.deleteIfExists(file);
+ assertRestoresNothingWithoutThrowing("no file at all");
+
+ // (b) truncated halfway: a write interrupted by a machine that lost power. The atomic rename
+ // is what stops this from happening, and this is what would happen if it did anyway.
+ Files.write(file, Arrays.copyOf(good, good.length / 2));
+ assertRestoresNothingWithoutThrowing("truncated file");
+
+ // (c) random bytes: a wrong file copied over it, or a corrupt sector.
+ final byte[] noise = new byte[good.length];
+ SecureRandomProvider.createSecureRandom().nextBytes(noise);
+ Files.write(file, noise);
+ assertRestoresNothingWithoutThrowing("random bytes");
+
+ // (d) empty file.
+ Files.write(file, new byte[0]);
+ assertRestoresNothingWithoutThrowing("empty file");
+
+ // (e) valid RLP, wrong domain: a file written for something else entirely.
+ Files.write(file, Bytes.fromHexString("0xc50102030405").toArrayUnsafe());
+ assertRestoresNothingWithoutThrowing("valid RLP, wrong shape");
+
+ // (f) a DIRECTORY where the file should be. Not exotic: a mount gone wrong does this.
+ Files.deleteIfExists(file);
+ Files.createDirectory(file);
+ assertRestoresNothingWithoutThrowing("a directory in place of the file");
+ Files.delete(file);
+
+ // And after all of that the node is still a working node: a good file still restores.
+ Files.write(file, good);
+ assertThat(
+ PqSealCache.instance()
+ .restoreFromDisk(
+ head.getNumber(), head.getHash(), PqSignerRegistry.falconSealSupport()))
+ .describedAs(
+ "positive control: without this line every assertion above would be satisfied by a "
+ + "reader that can never read anything")
+ .isEqualTo(3);
+ }
+
+ private void assertRestoresNothingWithoutThrowing(final String what) {
+ PqSealCache.instance().clear();
+ assertThatCode(
+ () ->
+ assertThat(
+ PqSealCache.instance()
+ .restoreFromDisk(
+ head.getNumber(),
+ head.getHash(),
+ PqSignerRegistry.falconSealSupport()))
+ .describedAs("%s must restore nothing", what)
+ .isZero())
+ .describedAs("%s must not throw: a node that cannot read the file is a node with none", what)
+ .doesNotThrowAnyException();
+ assertThat(PqSealCache.instance().sealCount(head.getHash())).isZero();
+ }
+
+ // -------------------------------------------------------------------------------------------
+ // 4. The binding checks, made before any signature is verified.
+ // -------------------------------------------------------------------------------------------
+
+ @Test
+ public void aFileFromAnotherHeightOrAnotherChainIsIgnored() throws Exception {
+ final Path file = PqSealStore.fileIn(dataDirectory);
+ final List<FalconSeal> seals = List.of(genuineSeal(0), genuineSeal(1), genuineSeal(2));
+ PqSealCache.instance().enablePersistence(dataDirectory, CHAIN_ID);
+
+ // Same seals, but the file claims another height. They cannot help the proposer of head+1.
+ PqSealStore.writeAtomically(
+ file,
+ PqSealStore.encode(CHAIN_ID, head.getNumber() - 1L, head.getHash().getBytes(), seals));
+ assertRestoresNothingWithoutThrowing("a file from another height");
+
+ // Same seals, another block hash at the right height: a fork of the same number.
+ PqSealStore.writeAtomically(
+ file,
+ PqSealStore.encode(
+ CHAIN_ID, head.getNumber(), Bytes32.leftPad(Bytes.of(7)), seals));
+ assertRestoresNothingWithoutThrowing("a file for another block at the same height");
+
+ // Another chain running the same binaries and possibly the same Falcon keys.
+ PqSealStore.writeAtomically(
+ file,
+ PqSealStore.encode(442_807L, head.getNumber(), head.getHash().getBytes(), seals));
+ assertRestoresNothingWithoutThrowing("a file from another chain");
+
+ // Positive control for this method: the same three seals, correctly bound, do restore.
+ PqSealStore.writeAtomically(
+ file, PqSealStore.encode(CHAIN_ID, head.getNumber(), head.getHash().getBytes(), seals));
+ PqSealCache.instance().clear();
+ assertThat(
+ PqSealCache.instance()
+ .restoreFromDisk(
+ head.getNumber(), head.getHash(), PqSignerRegistry.falconSealSupport()))
+ .isEqualTo(3);
+ }
+
+ // -------------------------------------------------------------------------------------------
+ // 5. Atomicity, measured against a reader rather than asserted from the API docs.
+ // -------------------------------------------------------------------------------------------
+
+ @Test
+ public void theWriteIsAtomicUnderAConcurrentReader() throws Exception {
+ final Path file = PqSealStore.fileIn(dataDirectory);
+ final List<FalconSeal> seals = new ArrayList<>();
+ for (int i = 0; i < N; i++) {
+ seals.add(genuineSeal(i));
+ }
+ PqSealStore.writeAtomically(
+ file, PqSealStore.encode(CHAIN_ID, head.getNumber(), head.getHash().getBytes(), seals));
+
+ final AtomicBoolean stop = new AtomicBoolean(false);
+ final AtomicInteger reads = new AtomicInteger();
+ final AtomicInteger partialReads = new AtomicInteger();
+ final Thread reader =
+ new Thread(
+ () -> {
+ while (!stop.get()) {
+ final List<FalconSeal> got =
+ PqSealStore.readVerified(
+ file,
+ CHAIN_ID,
+ head.getNumber(),
+ head.getHash(),
+ PqSignerRegistry.falconSealSupport());
+ reads.incrementAndGet();
+ if (got.isEmpty()) {
+ partialReads.incrementAndGet();
+ }
+ }
+ });
+ reader.setDaemon(true);
+ reader.start();
+
+ for (int round = 0; round < 120; round++) {
+ final List<FalconSeal> subset = seals.subList(0, 1 + (round % N));
+ PqSealStore.writeAtomically(
+ file,
+ PqSealStore.encode(CHAIN_ID, head.getNumber(), head.getHash().getBytes(), subset));
+ }
+ stop.set(true);
+ reader.join(30_000L);
+
+ assertThat(reads)
+ .describedAs("fixture control: the reader must actually have run")
+ .hasValueGreaterThan(0);
+ assertThat(partialReads)
+ .describedAs(
+ "%s reads across 120 writes and not one saw a half-written file. Temp plus rename is "
+ + "the reason; writing in place would have produced partial reads here.",
+ reads.get())
+ .hasValue(0);
+ assertThat(dataDirectory.resolve(PqSealStore.TEMP_FILE_NAME))
+ .describedAs("the temporary file must not be left behind")
+ .doesNotExist();
+ }
+
+ // -------------------------------------------------------------------------------------------
+ // 6. The path is DERIVED from the data directory, never separately configured.
+ // -------------------------------------------------------------------------------------------
+
+ @Test
+ public void thePathComesFromTheDataDirectory() {
+ assertThat(PqSealStore.fileIn(dataDirectory))
+ .isEqualTo(dataDirectory.resolve(PqSealStore.FILE_NAME));
+
+ PqSealCache.instance().enablePersistence(dataDirectory, CHAIN_ID);
+ assertThat(PqSealCache.instance().persistenceFile())
+ .isEqualTo(dataDirectory.resolve(PqSealStore.FILE_NAME));
+
+ final Path other = tmp.resolve("another-node");
+ PqSealCache.instance().enablePersistence(other, CHAIN_ID);
+ assertThat(PqSealCache.instance().persistenceFile())
+ .describedAs("two nodes on one machine never share the file")
+ .isEqualTo(other.resolve(PqSealStore.FILE_NAME))
+ .isNotEqualTo(dataDirectory.resolve(PqSealStore.FILE_NAME));
+
+ // A null data directory leaves persistence off rather than inventing a path.
+ PqSealCache.instance().disablePersistence();
+ PqSealCache.instance().enablePersistence(null, CHAIN_ID);
+ assertThat(PqSealCache.instance().persistenceFile()).isNull();
+ PqSealCache.instance().record(head.getNumber(), head.getHash(), List.of(genuineSeal(0)));
+ assertThat(PqSealCache.instance().sealCount(head.getHash()))
+ .describedAs("with persistence off the cache still works exactly as before")
+ .isEqualTo(1);
+ }
+
+ // -------------------------------------------------------------------------------------------
+ // 7. The price, as a number.
+ // -------------------------------------------------------------------------------------------
+
+ /**
+ * The write happens on the consensus thread, once per Commit heard, so its cost is a real
+ * property of this change and not a footnote. Seven seals is the whole fleet.
+ */
+ @Test
+ public void whatOneWriteCostsAgainstTheBlockInterval() throws Exception {
+ final Path file = PqSealStore.fileIn(dataDirectory);
+ final List<FalconSeal> seals = new ArrayList<>();
+ for (int i = 0; i < N; i++) {
+ seals.add(genuineSeal(i));
+ }
+ final byte[] payload =
+ PqSealStore.encode(CHAIN_ID, head.getNumber(), head.getHash().getBytes(), seals);
+
+ final int rounds = 100;
+ final long[] micros = new long[rounds];
+ for (int i = 0; i < rounds; i++) {
+ final long t0 = System.nanoTime();
+ PqSealStore.writeAtomically(file, payload);
+ micros[i] = (System.nanoTime() - t0) / 1_000L;
+ }
+ Arrays.sort(micros);
+ final long median = micros[rounds / 2];
+ final long p95 = micros[(int) (rounds * 0.95)];
+ final long worst = micros[rounds - 1];
+
+ // Printed so the number lands in the test XML and can be quoted as a measurement rather than
+ // remembered as an impression.
+ System.out.println(
+ "AERE PERSISTENTA-SIGILII MEASURED: payload="
+ + payload.length
+ + " bytes for "
+ + N
+ + " seals; write median="
+ + median
+ + " us, p95="
+ + p95
+ + " us, worst="
+ + worst
+ + " us over "
+ + rounds
+ + " writes; fsync="
+ + !"false".equalsIgnoreCase(System.getProperty(PqSealStore.PROPERTY_FSYNC))
+ + "; block interval="
+ + BLOCK_INTERVAL_MS
+ + " ms.");
+
+ assertThat(payload.length)
+ .describedAs("seven Falcon-512 seals plus the binding fields")
+ .isLessThan(16 * 1024);
+ assertThat(median)
+ .describedAs(
+ "one write must cost far less than one block interval, or persisting on the consensus "
+ + "thread would be trading a restart deadlock for a liveness cost")
+ .isLessThan(BLOCK_INTERVAL_MS * 1_000L / 10L);
+ }
+
+ // -------------------------------------------------------------------------------------------
+ // Helpers.
+ // -------------------------------------------------------------------------------------------
+
+ private FalconSeal genuineSeal(final int index) {
+ final Bytes32 m = PqAnchor.commitMessage(CHAIN_ID, head.getNumber(), head.getHash().getBytes());
+ return new FalconSeal(index, Bytes.wrap(falconSign(privateKeys.get(index), m)));
+ }
+
+ private static byte[] falconSign(final FalconPrivateKeyParameters key, final Bytes32 m) {
+ final FalconSigner signer = new FalconSigner();
+ signer.init(true, key);
+ return signer.generateSignature(m.toArray());
+ }
+
+ private static ProtocolContext contextWith(final Collection<Address> validatorSet) {
+ final ValidatorProvider validatorProvider =
+ mock(ValidatorProvider.class, withSettings().strictness(Strictness.LENIENT));
+ when(validatorProvider.getValidatorsForBlock(any())).thenReturn(validatorSet);
+ when(validatorProvider.getValidatorsAfterBlock(any())).thenReturn(validatorSet);
+ final BftContext bftContext =
+ mock(BftContext.class, withSettings().strictness(Strictness.LENIENT));
+ when(bftContext.getValidatorProvider()).thenReturn(validatorProvider);
+ when(bftContext.as(any())).thenReturn(bftContext);
+ return new ProtocolContext.Builder().withConsensusContext(bftContext).build();
+ }
+
+ private static void resetFalconSingleton() throws Exception {
+ final Field f = FalconSealSupport.class.getDeclaredField("instance");
+ f.setAccessible(true);
+ f.set(null, null);
+ }
+
+ /**
+ * D-330 (2026-09-03, testnet 28001): the main file followed the highest height HEARD, which was a
+ * proposal that never imported (168032), so after a fleet-wide restart no node held the seals of
+ * the head (168031). The previous slot keeps them one height longer.
+ */
+ @Test
+ public void theSealsOfTheHeadSurviveTheStoreMovingToALaterHeightThatNeverImported() {
+ PqSealCache.instance().enablePersistence(dataDirectory, CHAIN_ID);
+ for (int i = 0; i < K; i++) {
+ PqSealCache.instance().record(head.getNumber(), head.getHash(), List.of(genuineSeal(i)));
+ }
+ // the fleet now hears commits for a NEXT block that will never import
+ final BlockHeader next = new BlockHeaderTestFixture().number(head.getNumber() + 1L).buildHeader();
+ final Bytes32 mNext = PqAnchor.commitMessage(CHAIN_ID, next.getNumber(), next.getHash().getBytes());
+ final FalconSigner signer = new FalconSigner();
+ signer.init(true, privateKeys.get(0));
+ PqSealCache.instance()
+ .record(next.getNumber(), next.getHash(),
+ List.of(new FalconSeal(0, Bytes.wrap(signer.generateSignature(mNext.toArray())))));
+ assertThat(PqSealStore.previousFileIn(dataDirectory)).describedAs("the previous slot exists after the rotation").exists();
+ // restart: memory gone, the main file holds the never-imported height
+ PqSealCache.instance().clear();
+ final int restored =
+ PqSealCache.instance()
+ .restoreFromDisk(head.getNumber(), head.getHash(), PqSignerRegistry.falconSealSupport());
+ assertThat(restored).describedAs("the head's seals come back from the previous slot").isEqualTo(K);
+ assertThat(PqAnchorProducer.apply(base, head, context).getFalconSeals()).hasSize(K);
+ }
+}
diff --git a/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqSignedHeightTest.java b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqSignedHeightTest.java
new file mode 100755
index 000000000..8122465d0
--- /dev/null
+++ b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqSignedHeightTest.java
@@ -0,0 +1,402 @@
+/*
+ * Copyright contributors to Besu.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.common.bft;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatCode;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+import java.io.IOException;
+import java.lang.reflect.Field;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.OptionalInt;
+
+import org.hyperledger.besu.consensus.common.bft.blockcreation.PqAnchorProducer;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+
+/**
+ * AERE D-B (2026-08-06). THE SILENT DEFERRAL, and it is the worst of the three because nothing shows
+ * it.
+ *
+ * <p>WHAT IS SUPPOSED TO BE TRUE. Every row of a v2 registry carries two signatures - a Falcon
+ * possession proof and an ECDSA claim by that validator's own consensus key - and BOTH sign the bind
+ * height ({@code PqRegistryBinding.bindingPreimage}). A registry put in force from block B is
+ * therefore every one of those validators stating that B is the height they agreed to.
+ *
+ * <p>WHAT WAS ACTUALLY TRUE UNTIL THIS FILE. {@code bindHeight} was never compared with the {@code
+ * block} of the schedule entry that puts the registry in force. Not anywhere. The two numbers had
+ * been in the same lexical scope since D-081 and were never put on the same expression.
+ *
+ * <p>WHY THE HASH DOES NOT CATCH IT, which is the part that makes this invisible rather than merely
+ * missing. {@code bindHeight} is INSIDE the v2 pre-image, so it is covered by the hash - and that is
+ * exactly why the comparison looks unnecessary. But the enforcement is hash against hash: the
+ * required hash comes from genesis and the computed hash comes from the file, and a file signed for
+ * 40 and scheduled from 70 reproduces its own hash perfectly. Both sides agree, and neither side
+ * ever mentions a height. {@link #theHashMATCHESWhichIsWhyNobodyEverSawThis()} measures precisely
+ * that, and it is the assertion that makes the rest of this file mean something.
+ *
+ * <p>MEASURED ON A NETWORK OF SEVEN, 2026-08-06, scenario C2: the arming height moved from 40 to 70
+ * with the proofs left signed for 40. Seven of seven nodes started, the chain ran to head 95,
+ * agreement was 7 of 7, ZERO errors and ZERO refusals - while the offline tool, on the same files,
+ * said RED. The node and the tool disagreed and nothing put them face to face.
+ *
+ * <p>WHAT IT BUYS SOMEBODY WHO SHOULD NOT HAVE IT: moving the activation day costs 14 fresh
+ * validator signatures if this is checked and ZERO if it is not.
+ *
+ * <p>THE RULE CHOSEN, and why it is the correct one rather than merely a working one:
+ *
+ * <ul>
+ * <li>A proof-bound registry that reproduces the hash of schedule entry E must declare {@code
+ * bindHeight == E.block}. Enforced ({@code AERE-PQC-REG-BIND-08}). Both numbers come from
+ * genesis and the file, and genesis is the one document all seven nodes hold byte-identically,
+ * so this comparison is backed by the same agreement consensus already rests on.
+ * <li>NOT refused: a registry enforced from a FUTURE height. The comparison is against the
+ * ENTRY'S block, never against the chain head, so an entry scheduled a year out is untouched -
+ * {@link #aRegistryScheduledFarInTheFutureIsNOTRefused()}.
+ * <li>NOT refused: a schedule with several epochs. Each entry is compared against the registry
+ * that reproduces ITS hash, one pair at a time - {@link #twoEpochsEachSignedForItsOwnHeightAreFINE()}.
+ * <li>NOT touched: v1 registries. They carry no signatures over any height, {@code bindHeight} is
+ * -1, and the condition is gated on {@code proofBound()} - {@link #aV1RegistryIsNOTJudgedByThisRuleAtAll()}.
+ * <li>An entry no held file reproduces stays UNCOVERED, which is a different condition with a
+ * different message. It is not compared - {@link #anUncoveredEntryIsNotAMisboundOne()}.
+ * </ul>
+ *
+ * <p>AND THE HALF THAT CANNOT BE ENFORCED, written as a limitation and not as a to-do. {@code
+ * aere.pq.anchorBlock} is a system property set per node; it is in no genesis. The seven validators'
+ * agreement on an arming height therefore CANNOT be enforced by code running on one node - only
+ * DETECTED, which is {@code AERE-PQC-REG-BIND-09} and {@link
+ * #armingAtAHeightNobodySignedForIsREFUSEDLocally()}. Enforcement would require the height to move
+ * into genesis, which is a change to the chain and not to this class.
+ *
+ * <p>KEYS. Every key here is generated in memory by {@link PqV2Fixture} and never written outside a
+ * JUnit temporary directory.
+ */
+public class PqSignedHeightTest {
+
+ /** The height the fleet actually signed its registry for. */
+ private static final long SIGNED = 40L;
+
+ /** The height somebody moved the activation to, without asking anybody to sign again. */
+ private static final long MOVED = 70L;
+
+ private static final int N = 7;
+
+ private static final long CHAIN_ID = 220_878L;
+
+ @TempDir private Path tmp;
+
+ private Path signedForForty;
+ private String hashOfSignedForForty;
+
+ @BeforeEach
+ public void setUp() throws Exception {
+ signedForForty = writeRegistry("signed-for-40.properties", SIGNED);
+ hashOfSignedForForty =
+ PqRegistryHash.hashFor(PqRegistryHash.loadAuto(signedForForty), CHAIN_ID);
+ System.setProperty("aere.falcon.registry", signedForForty.toAbsolutePath().toString());
+ resetFalconSingleton();
+ PqAnchorProducer.useConfigForTesting(null);
+ }
+
+ @AfterEach
+ public void tearDown() throws Exception {
+ System.clearProperty("aere.falcon.registry");
+ System.clearProperty(FalconSealSupport.PROPERTY_REGISTRY_HISTORY);
+ resetFalconSingleton();
+ PqAnchorProducer.useConfigForTesting(null);
+ }
+
+ // -------------------------------------------------------------------------------------------
+ // 0. WHY NOBODY SAW IT. The hash agrees. If this assertion ever fails, the defect described in
+ // this file did not exist and everything below is theatre.
+ // -------------------------------------------------------------------------------------------
+
+ @Test
+ public void theHashMATCHESWhichIsWhyNobodyEverSawThis() throws Exception {
+ final PqRegistryHash.Registry r = PqRegistryHash.loadAuto(signedForForty);
+ assertThat(r.proofBound()).isTrue();
+ assertThat(r.bindHeight()).isEqualTo(SIGNED);
+
+ // The schedule puts this file in force from 70. The file was signed for 40. The hash the
+ // schedule requires and the hash the file computes are THE SAME NUMBER, because bindHeight sits
+ // inside the pre-image and travels with the file. Hash-against-hash can never see this.
+ final PqRegistryHash.Schedule moved = schedule(Map.of(MOVED, hashOfSignedForForty));
+ assertThat(PqRegistryHash.requiredHashAt(moved, MOVED).orElseThrow().hash())
+ .describedAs(
+ "the required hash and the computed hash agree perfectly while the heights differ by "
+ + "30 blocks. That agreement IS the defect")
+ .isEqualToIgnoringCase(PqRegistryHash.hashFor(r, CHAIN_ID));
+ }
+
+ // -------------------------------------------------------------------------------------------
+ // 1. THE MEASUREMENT, repaired: the two numbers are now put side by side and the node refuses.
+ // -------------------------------------------------------------------------------------------
+
+ @Test
+ public void aRegistryScheduledAtAHeightItWasNotSignedForIsREFUSED() throws Exception {
+ final FalconSealSupport pqc = FalconSealSupport.instance();
+
+ assertThatThrownBy(
+ () ->
+ pqc.verifyRegistryBindingOrAbort(
+ MOVED + 25L, CHAIN_ID, schedule(Map.of(MOVED, hashOfSignedForForty))))
+ .isInstanceOf(PqRegistryHash.RegistryConfigException.class)
+ .hasMessageContaining("AERE-PQC-REG-BIND-08")
+ // The message must carry BOTH numbers and name the field, or it is useless at 3am.
+ .hasMessageContaining("bindHeight")
+ .hasMessageContaining("in force FROM BLOCK " + MOVED)
+ .hasMessageContaining("bindHeight=" + SIGNED)
+ .hasMessageContaining("14 fresh validator signatures");
+ }
+
+ @Test
+ public void andItIsRefusedEVENWHENTheMovedHeightIsStillAhead() throws Exception {
+ // The whole hazard of a deferral is that it is invisible until the day arrives. Catching it only
+ // once the chain has reached the height would be catching it at the halt, which is the thing
+ // being repaired. Chain head is far below the moved entry here.
+ final FalconSealSupport pqc = FalconSealSupport.instance();
+ assertThatThrownBy(
+ () ->
+ pqc.verifyRegistryBindingOrAbort(
+ 0L, CHAIN_ID, schedule(Map.of(MOVED, hashOfSignedForForty))))
+ .isInstanceOf(PqRegistryHash.RegistryConfigException.class)
+ .hasMessageContaining("AERE-PQC-REG-BIND-08");
+ }
+
+ // -------------------------------------------------------------------------------------------
+ // 2. NEGATIVE CONTROLS. The rule must refuse the moved height and NOTHING ELSE.
+ // -------------------------------------------------------------------------------------------
+
+ @Test
+ public void theSameFileAtTheHeightItWASSignedForStarts() throws Exception {
+ final FalconSealSupport pqc = FalconSealSupport.instance();
+ assertThat(
+ pqc.verifyRegistryBindingOrAbort(
+ SIGNED + 25L, CHAIN_ID, schedule(Map.of(SIGNED, hashOfSignedForForty))))
+ .describedAs(
+ "identical file, identical hash, identical everything except the one number this rule "
+ + "is about. If this refuses too, the rule is a wedge and not a guard")
+ .isEqualTo(PqRegistryHash.GateState.MATCH);
+ }
+
+ @Test
+ public void aRegistryScheduledFarInTheFutureIsNOTRefused() throws Exception {
+ // A registry staged for an activation a year out: signed for that height, scheduled at that
+ // height, chain head nowhere near it. The comparison is entry-block against bindHeight and never
+ // against the chain head, so this is untouched.
+ final long future = 12_000_000L;
+ final Path staged = writeRegistry("staged.properties", future);
+ final String h = PqRegistryHash.hashFor(PqRegistryHash.loadAuto(staged), CHAIN_ID);
+ System.setProperty("aere.falcon.registry", staged.toAbsolutePath().toString());
+ resetFalconSingleton();
+ final FalconSealSupport pqc = FalconSealSupport.instance();
+
+ assertThat(pqc.verifyRegistryBindingOrAbort(1_000L, CHAIN_ID, schedule(Map.of(future, h))))
+ .isEqualTo(PqRegistryHash.GateState.NOT_ENFORCED_BELOW_FIRST_HEIGHT);
+ }
+
+ @Test
+ public void twoEpochsEachSignedForItsOwnHeightAreFINE() throws Exception {
+ final Path second = writeRegistry("epoch-two.properties", MOVED);
+ final String hSecond = PqRegistryHash.hashFor(PqRegistryHash.loadAuto(second), CHAIN_ID);
+ System.setProperty(
+ FalconSealSupport.PROPERTY_REGISTRY_HISTORY, second.toAbsolutePath().toString());
+ final FalconSealSupport pqc = FalconSealSupport.instance();
+
+ final Map<Long, String> both = new LinkedHashMap<>();
+ both.put(SIGNED, hashOfSignedForForty);
+ both.put(MOVED, hSecond);
+
+ assertThat(pqc.verifyRegistryBindingOrAbort(MOVED + 25L, CHAIN_ID, schedule(both)))
+ .describedAs(
+ "a multi-epoch schedule is the normal shape after a rotation. Each entry is judged "
+ + "against the file that reproduces ITS hash, so several epochs are several "
+ + "independent comparisons and not one blanket")
+ .isEqualTo(PqRegistryHash.GateState.MATCH);
+ }
+
+ @Test
+ public void aV1RegistryIsNOTJudgedByThisRuleAtAll() throws Exception {
+ // No proofs, therefore no signature over any height, therefore no height to disagree with.
+ // bindHeight is -1 here and would mismatch every entry there is; the gate on proofBound() is
+ // what keeps a v1 fleet from being refused by a rule about signatures it never made.
+ final Path v1 = writeV1Registry("legacy.properties");
+ final PqRegistryHash.Registry r = PqRegistryHash.loadAuto(v1);
+ assertThat(r.proofBound()).isFalse();
+ assertThat(r.bindHeight()).isNegative();
+
+ final String h = PqRegistryHash.hashFor(r, CHAIN_ID);
+ final PqRegistryHash.RegistrySet set =
+ PqRegistryHash.buildSet(schedule(Map.of(MOVED, h)), List.of(r), CHAIN_ID);
+
+ assertThat(set.misbound())
+ .describedAs("a v1 registry can never be misbound, because it never bound itself to a height")
+ .isEmpty();
+ assertThat(set.forEntryBlock(MOVED)).isSameAs(r);
+ }
+
+ @Test
+ public void anUncoveredEntryIsNotAMisboundOne() throws Exception {
+ // An entry whose hash nothing held reproduces is a MISSING file, which an operator legitimately
+ // has. It must not be reported as a signed-height mismatch: different mistake, different fix.
+ final Map<Long, String> both = new LinkedHashMap<>();
+ both.put(SIGNED, hashOfSignedForForty);
+ both.put(MOVED + 1_000L, "cd".repeat(32));
+ final PqRegistryHash.RegistrySet set =
+ PqRegistryHash.buildSet(
+ schedule(both), List.of(PqRegistryHash.loadAuto(signedForForty)), CHAIN_ID);
+
+ assertThat(set.misbound()).isEmpty();
+ assertThat(set.uncoveredEntryBlocks()).containsExactly(MOVED + 1_000L);
+ }
+
+ // -------------------------------------------------------------------------------------------
+ // 3. THE LOCAL HALF. Arming at a height nobody signed for: detected, and honestly labelled.
+ // -------------------------------------------------------------------------------------------
+
+ @Test
+ public void armingAtAHeightNobodySignedForIsREFUSEDLocally() throws Exception {
+ // The schedule is coherent - the file is signed for 40 and scheduled from 40 - and the ANCHOR
+ // has been moved to 70 on this node alone. Nothing in genesis constrains aere.pq.anchorBlock, so
+ // this can only be caught where both values are in one hand, which is here.
+ PqAnchorProducer.useConfigForTesting(
+ new PqAnchorConfig(CHAIN_ID, MOVED, Map.of(MOVED, 3), OptionalInt.empty(), false));
+ resetFalconSingleton();
+ final FalconSealSupport pqc = FalconSealSupport.instance();
+
+ assertThatThrownBy(
+ () ->
+ pqc.verifyRegistryBindingOrAbort(
+ SIGNED + 5L, CHAIN_ID, schedule(Map.of(SIGNED, hashOfSignedForForty))))
+ .isInstanceOf(PqRegistryHash.RegistryConfigException.class)
+ .hasMessageContaining("AERE-PQC-REG-BIND-09")
+ .hasMessageContaining("aere.pq.anchorBlock = " + MOVED)
+ .hasMessageContaining("config.pqRegistryHash heights = [" + SIGNED + "]")
+ // The honest limitation has to be IN the message, or an operator will read this as a
+ // consensus guarantee it is not.
+ .hasMessageContaining("DETECTION on this node only")
+ .hasMessageContaining("on every node and in the same change");
+ }
+
+ @Test
+ public void armingExactlyAtAScheduledHeightSTARTS() throws Exception {
+ PqAnchorProducer.useConfigForTesting(
+ new PqAnchorConfig(CHAIN_ID, SIGNED, Map.of(SIGNED, 3), OptionalInt.empty(), false));
+ resetFalconSingleton();
+ final FalconSealSupport pqc = FalconSealSupport.instance();
+
+ assertThat(
+ pqc.verifyRegistryBindingOrAbort(
+ SIGNED + 5L, CHAIN_ID, schedule(Map.of(SIGNED, hashOfSignedForForty))))
+ .describedAs(
+ "the positive half, and it is the expensive one: a gate that refuses every armed node "
+ + "is not a gate")
+ .isEqualTo(PqRegistryHash.GateState.MATCH);
+ }
+
+ @Test
+ public void anUNARMEDNodeIsNeverAskedTheQuestion() throws Exception {
+ // Chain 2800 as it stands: aere.pq.anchorBlock unset. The arming-height comparison must not
+ // even be reachable, whatever the schedule says.
+ PqAnchorProducer.useConfigForTesting(PqAnchorConfig.never(CHAIN_ID));
+ resetFalconSingleton();
+ final FalconSealSupport pqc = FalconSealSupport.instance();
+
+ assertThatCode(
+ () ->
+ pqc.verifyRegistryBindingOrAbort(
+ SIGNED + 5L, CHAIN_ID, schedule(Map.of(SIGNED, hashOfSignedForForty))))
+ .doesNotThrowAnyException();
+ }
+
+ // -------------------------------------------------------------------------------------------
+ // Helpers.
+ // -------------------------------------------------------------------------------------------
+
+ private Path writeRegistry(final String name, final long bindHeight) throws IOException {
+ final StringBuilder b = new StringBuilder();
+ b.append("formatVersion=").append(PqRegistryBinding.FORMAT_VERSION).append('\n');
+ b.append("chainId=").append(CHAIN_ID).append('\n');
+ b.append("bindHeight=").append(bindHeight).append('\n');
+ b.append("count=").append(N).append('\n');
+ for (int i = 0; i < N; i++) {
+ b.append(i).append('=').append(hex(PqV2Fixture.publicKey(i))).append('\n');
+ b.append(i).append(".addr=").append(PqV2Fixture.address(i).toHexString()).append('\n');
+ b.append(i).append(".pop=").append(PqV2Fixture.popHex(CHAIN_ID, bindHeight, N, i)).append('\n');
+ b.append(i)
+ .append(".claim=")
+ .append(PqV2Fixture.claimHex(CHAIN_ID, bindHeight, N, i))
+ .append('\n');
+ }
+ final Path f = tmp.resolve(name);
+ Files.writeString(f, b.toString(), StandardCharsets.UTF_8);
+ return f;
+ }
+
+ private Path writeV1Registry(final String name) throws IOException {
+ final StringBuilder b = new StringBuilder();
+ b.append("count=").append(N).append('\n');
+ for (int i = 0; i < N; i++) {
+ b.append(i).append('=').append(hex(PqV2Fixture.publicKey(i))).append('\n');
+ b.append(i).append(".addr=").append(PqV2Fixture.address(i).toHexString()).append('\n');
+ }
+ final Path f = tmp.resolve(name);
+ Files.writeString(f, b.toString(), StandardCharsets.UTF_8);
+ return f;
+ }
+
+ private PqRegistryHash.Schedule schedule(final Map<Long, String> entries) throws IOException {
+ final List<Long> heights = new ArrayList<>(entries.keySet());
+ heights.sort(Long::compare);
+ final StringBuilder sb = new StringBuilder("{\"config\":{\"pqRegistryHash\":[");
+ for (int i = 0; i < heights.size(); i++) {
+ if (i > 0) {
+ sb.append(',');
+ }
+ sb.append("{\"block\":")
+ .append(heights.get(i))
+ .append(",\"hash\":\"0x")
+ .append(entries.get(heights.get(i)))
+ .append("\"}");
+ }
+ sb.append("]}}");
+ final Path p = tmp.resolve("genesis-db-" + heights.size() + "-" + heights.get(0) + ".json");
+ Files.writeString(p, sb.toString(), StandardCharsets.UTF_8);
+ return PqRegistryHash.loadScheduleFromGenesis(p);
+ }
+
+ private static String hex(final byte[] b) {
+ final StringBuilder s = new StringBuilder(b.length * 2);
+ for (final byte x : b) {
+ s.append(Character.forDigit((x >> 4) & 0xf, 16)).append(Character.forDigit(x & 0xf, 16));
+ }
+ return s.toString();
+ }
+
+ private static void resetFalconSingleton() throws Exception {
+ final Field f = FalconSealSupport.class.getDeclaredField("instance");
+ f.setAccessible(true);
+ f.set(null, null);
+ }
+}
diff --git a/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqStartupHistoryTest.java b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqStartupHistoryTest.java
new file mode 100755
index 000000000..4826779da
--- /dev/null
+++ b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqStartupHistoryTest.java
@@ -0,0 +1,324 @@
+/*
+ * Copyright contributors to Besu.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.common.bft;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+import java.io.IOException;
+import java.lang.reflect.Field;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+
+/**
+ * AERE D-A (2026-08-06). AFTER THE FIRST ROTATION, NO NODE COULD BE RESTARTED WITH ITS OWN CORRECT
+ * CONFIGURATION.
+ *
+ * <p>WHAT WAS MEASURED, and it was measured twice: once during the rotation rehearsal on a network
+ * of seven, and again on 2026-08-06 with the chain head at 2554. A node configured exactly as the
+ * runbook says - the genesis manifest as the registry it signs with, every rotation registry named
+ * in {@code aere.falcon.registry.history} - refused to start with {@code AERE-PQC-REG-MISMATCH-01}.
+ * Nothing was wrong with it.
+ *
+ * <p>THE DEFECT WAS THE ORDER OF TWO BLOCKS OF CODE. {@code
+ * FalconSealSupport.verifyRegistryBindingOrAbort} loaded ONE registry, the primary, and handed it to
+ * the guard. The history list was read FORTY-ONE LINES FURTHER DOWN, to build the height-resolved
+ * set D-081 introduced. So the refusal was thrown before the code that knew the answer had run. The
+ * guard was not wrong about what it compared; it was never shown the other files.
+ *
+ * <p>WHY IT BITES EXACTLY AFTER A ROTATION AND NEVER BEFORE. The primary registry is the genesis
+ * manifest, and genesis does not change. A rotation adds a SECOND entry to {@code
+ * config.pqRegistryHash} and a second file, which can only arrive through the history property. From
+ * the rotation height onwards the entry in force names the second file, the guard compares the
+ * first, and every restart fails. Before the rotation there is one entry and one file and the two
+ * paths are indistinguishable - which is why this survived every test the tree had.
+ *
+ * <p>THE NEGATIVE CONTROLS ARE THE POINT. {@link #withNoHistoryConfiguredTheRefusalIsSTILLTHERE()}
+ * and {@link #aHistoryFileThatCoversNothingDoesNotRescueAnything()} fail if the repair is "stop
+ * refusing" rather than "consult the history". A guard that has stopped refusing is not a repaired
+ * guard, and this pair is what tells the two apart.
+ *
+ * <p>ALSO CLOSED HERE: a finding in its own right. Before this file, {@code
+ * AERE-PQC-REG-MISMATCH-01}, {@code AERE-PQC-REG-MISMATCH-02} and {@code GateState} appeared in NO
+ * test anywhere in the tree (searched over every src/test of every consensus module on
+ * 2026-08-06). The
+ * refusal to start had only ever been exercised by running real nodes.
+ *
+ * <p>KEYS. Every key here is generated in memory by {@link PqV2Fixture} and never written outside a
+ * JUnit temporary directory.
+ */
+public class PqStartupHistoryTest {
+
+ /** Where the chain first requires a registry: epoch one, the genesis manifest. */
+ private static final long H1 = 600L;
+
+ /** The rotation height: from here the chain requires the second registry. */
+ private static final long H2 = 2_000L;
+
+ private static final int N = 7;
+
+ private static final long CHAIN_ID = 220_878L;
+
+ @TempDir private Path tmp;
+
+ private Path epochOne;
+ private Path epochTwo;
+ private String hashOne;
+ private String hashTwo;
+
+ @BeforeEach
+ public void setUp() throws Exception {
+ // Two epochs of the SAME fleet, re-signed at two heights. That is the whole difference between
+ // the files and it is deliberate: it makes them two distinct registries with two distinct
+ // hashes, and it removes every other variable, so a guard that gets this wrong cannot be
+ // excused by a changed key.
+ epochOne = writeRegistry("epoch-one.properties", H1);
+ epochTwo = writeRegistry("epoch-two.properties", H2);
+ hashOne = PqRegistryHash.hashFor(PqRegistryHash.loadAuto(epochOne), CHAIN_ID);
+ hashTwo = PqRegistryHash.hashFor(PqRegistryHash.loadAuto(epochTwo), CHAIN_ID);
+ assertThat(hashOne).isNotEqualTo(hashTwo);
+
+ // A test that asserts what happens WITHOUT an anchor height must establish that itself, not
+ // inherit it from whoever ran before. Measured 2026-08-11: under its previous name this class
+ // sorted before every class that sets aere.pq.anchorBlock, so it passed for the right result and
+ // the wrong reason. The real leak is a remembered configuration, not the property, and it is
+ // fixed where it leaks; this stays as the belt to that pair of braces.
+ System.clearProperty("aere.pq.anchorBlock");
+ System.clearProperty("aere.pq.anchorMinSeals");
+ System.setProperty("aere.falcon.registry", epochOne.toAbsolutePath().toString());
+ resetFalconSingleton();
+ }
+
+ @AfterEach
+ public void tearDown() throws Exception {
+ System.clearProperty("aere.falcon.registry");
+ System.clearProperty(FalconSealSupport.PROPERTY_REGISTRY_HISTORY);
+ resetFalconSingleton();
+ }
+
+ // -------------------------------------------------------------------------------------------
+ // 0. The fixture. Without this a green run below could mean the guard was never armed at all.
+ // -------------------------------------------------------------------------------------------
+
+ @Test
+ public void baselineBeforeTheRotationTheOneFileIsENOUGH() throws Exception {
+ final FalconSealSupport pqc = FalconSealSupport.instance();
+ // One entry, one file, head below the rotation: the configuration every node ran before the
+ // rotation existed. This is the state in which the defect is INVISIBLE.
+ assertThat(pqc.verifyRegistryBindingOrAbort(H1 + 10L, CHAIN_ID, schedule(Map.of(H1, hashOne))))
+ .isEqualTo(PqRegistryHash.GateState.MATCH);
+ }
+
+ // -------------------------------------------------------------------------------------------
+ // 1. THE MEASUREMENT. The rotated fleet, configured exactly as its runbook says.
+ // -------------------------------------------------------------------------------------------
+
+ @Test
+ public void afterTheRotationTheNODESTARTSBecauseTheGuardREADSTheHistory() throws Exception {
+ System.setProperty(
+ FalconSealSupport.PROPERTY_REGISTRY_HISTORY, epochTwo.toAbsolutePath().toString());
+ final FalconSealSupport pqc = FalconSealSupport.instance();
+
+ final Map<Long, String> both = new LinkedHashMap<>();
+ both.put(H1, hashOne);
+ both.put(H2, hashTwo);
+
+ assertThat(pqc.verifyRegistryBindingOrAbort(H2 + 554L, CHAIN_ID, schedule(both)))
+ .describedAs(
+ "head above the rotation, the required registry held as HISTORY, the primary still the "
+ + "genesis manifest. This is the correct configuration and until 2026-08-06 it "
+ + "refused to start with AERE-PQC-REG-MISMATCH-01, because the guard was handed the "
+ + "primary alone and the history list was read 41 lines later")
+ .isEqualTo(PqRegistryHash.GateState.MATCH);
+ }
+
+ @Test
+ public void andTheWHOLESCHEDULEIsCoveredNotOnlyTheHead() throws Exception {
+ System.setProperty(
+ FalconSealSupport.PROPERTY_REGISTRY_HISTORY, epochTwo.toAbsolutePath().toString());
+ final FalconSealSupport pqc = FalconSealSupport.instance();
+ final Map<Long, String> both = new LinkedHashMap<>();
+ both.put(H1, hashOne);
+ both.put(H2, hashTwo);
+ pqc.verifyRegistryBindingOrAbort(H2 + 554L, CHAIN_ID, schedule(both));
+
+ // Starting is not the whole story: a node that starts and then refuses every header below the
+ // rotation has traded one halt for another. Both intervals must answer.
+ assertThat(pqc.registryBindingSatisfiedAt(H1)).isTrue();
+ assertThat(pqc.registryBindingSatisfiedAt(H2 - 1L)).isTrue();
+ assertThat(pqc.registryBindingSatisfiedAt(H2)).isTrue();
+ assertThat(pqc.registryBindingSatisfiedAt(H2 + 554L)).isTrue();
+ }
+
+ // -------------------------------------------------------------------------------------------
+ // 2. NEGATIVE CONTROL. The repair is "read the history", not "stop refusing".
+ // -------------------------------------------------------------------------------------------
+
+ @Test
+ public void withNoHistoryConfiguredTheRefusalIsSTILLTHERE() throws Exception {
+ final FalconSealSupport pqc = FalconSealSupport.instance();
+ final Map<Long, String> both = new LinkedHashMap<>();
+ both.put(H1, hashOne);
+ both.put(H2, hashTwo);
+
+ assertThatThrownBy(() -> pqc.verifyRegistryBindingOrAbort(H2 + 554L, CHAIN_ID, schedule(both)))
+ .describedAs(
+ "a node that genuinely does not hold the rotation registry must still refuse to start. "
+ + "If this passes, the repair removed the guard instead of feeding it")
+ .isInstanceOf(PqRegistryHash.RegistryConfigException.class)
+ .hasMessageContaining("AERE-PQC-REG-MISMATCH-01")
+ .hasMessageContaining("REGISTRY FILES THIS NODE HOLDS: 1")
+ .hasMessageContaining("aere.falcon.registry.history");
+ }
+
+ @Test
+ public void aHistoryFileThatCoversNothingDoesNotRescueAnything() throws Exception {
+ // A third file, signed for a height the schedule never mentions. It is a real, loadable,
+ // proof-bound registry; it simply answers for no interval of this chain.
+ final Path unrelated = writeRegistry("unrelated.properties", H2 + 999L);
+ System.setProperty(
+ FalconSealSupport.PROPERTY_REGISTRY_HISTORY, unrelated.toAbsolutePath().toString());
+ final FalconSealSupport pqc = FalconSealSupport.instance();
+ final Map<Long, String> both = new LinkedHashMap<>();
+ both.put(H1, hashOne);
+ both.put(H2, hashTwo);
+
+ assertThatThrownBy(() -> pqc.verifyRegistryBindingOrAbort(H2 + 554L, CHAIN_ID, schedule(both)))
+ .describedAs(
+ "holding MORE files is not the property that matters; holding the RIGHT one is. A "
+ + "repair that counted files instead of matching hashes would pass the test above "
+ + "and fail here")
+ .isInstanceOf(PqRegistryHash.RegistryConfigException.class)
+ .hasMessageContaining("AERE-PQC-REG-MISMATCH-01")
+ .hasMessageContaining("REGISTRY FILES THIS NODE HOLDS: 2");
+ }
+
+ @Test
+ public void aNodeWithNOREGISTRYATALLIsRefusedAndTheCodeIsTheOtherONE() throws Exception {
+ System.clearProperty("aere.falcon.registry");
+ resetFalconSingleton();
+ final FalconSealSupport pqc = FalconSealSupport.instance();
+
+ assertThatThrownBy(
+ () -> pqc.verifyRegistryBindingOrAbort(H1 + 10L, CHAIN_ID, schedule(Map.of(H1, hashOne))))
+ .describedAs(
+ "no registry at all is a different mistake from the wrong registry, and it has always "
+ + "had its own code. Until this file, neither code was asserted anywhere")
+ .isInstanceOf(PqRegistryHash.RegistryConfigException.class)
+ .hasMessageContaining("AERE-PQC-REG-MISMATCH-02")
+ .hasMessageContaining("NO REGISTRY AT ALL");
+ }
+
+ // -------------------------------------------------------------------------------------------
+ // 3. The states that are NOT refusals. A guard that only ever refuses is a wedge in a costume.
+ // -------------------------------------------------------------------------------------------
+
+ @Test
+ public void belowTheFirstScheduledHeightNothingIsEnforcedAndTheNodeIsTOLDItIsStaged()
+ throws Exception {
+ System.setProperty(
+ FalconSealSupport.PROPERTY_REGISTRY_HISTORY, epochTwo.toAbsolutePath().toString());
+ final FalconSealSupport pqc = FalconSealSupport.instance();
+ assertThat(pqc.verifyRegistryBindingOrAbort(H1 - 100L, CHAIN_ID, schedule(Map.of(H1, hashOne))))
+ .isEqualTo(PqRegistryHash.GateState.NOT_ENFORCED_BELOW_FIRST_HEIGHT);
+ }
+
+ @Test
+ public void withNoScheduleAtAllNOTHINGIsEnforcedWhichIsChain2800Today() throws Exception {
+ final FalconSealSupport pqc = FalconSealSupport.instance();
+ assertThat(
+ pqc.verifyRegistryBindingOrAbort(
+ H2 + 554L, CHAIN_ID, PqRegistryHash.emptySchedule()))
+ .describedAs(
+ "config.pqRegistryHash is in no genesis this fleet runs. This is the branch every "
+ + "live node takes, and it must stay first and unconditional")
+ .isEqualTo(PqRegistryHash.GateState.NOT_ENFORCED_NO_SCHEDULE);
+ }
+
+ // -------------------------------------------------------------------------------------------
+ // Helpers.
+ // -------------------------------------------------------------------------------------------
+
+ private Path writeRegistry(final String name, final long bindHeight) throws IOException {
+ final StringBuilder b = new StringBuilder();
+ b.append("formatVersion=").append(PqRegistryBinding.FORMAT_VERSION).append('\n');
+ b.append("chainId=").append(CHAIN_ID).append('\n');
+ b.append("bindHeight=").append(bindHeight).append('\n');
+ b.append("count=").append(N).append('\n');
+ for (int i = 0; i < N; i++) {
+ b.append(i).append('=').append(hex(PqV2Fixture.publicKey(i))).append('\n');
+ b.append(i)
+ .append(".addr=")
+ .append(PqV2Fixture.address(i).toHexString())
+ .append('\n');
+ b.append(i).append(".pop=").append(PqV2Fixture.popHex(CHAIN_ID, bindHeight, N, i)).append('\n');
+ b.append(i)
+ .append(".claim=")
+ .append(PqV2Fixture.claimHex(CHAIN_ID, bindHeight, N, i))
+ .append('\n');
+ }
+ final Path f = tmp.resolve(name);
+ Files.writeString(f, b.toString(), StandardCharsets.UTF_8);
+ return f;
+ }
+
+ /**
+ * Build a schedule the way a node really gets one: written into a genesis file and parsed back.
+ * Constructing the object directly would skip the parser, where the strictly-increasing rule is.
+ */
+ private PqRegistryHash.Schedule schedule(final Map<Long, String> entries) throws IOException {
+ final List<Long> heights = new ArrayList<>(entries.keySet());
+ heights.sort(Long::compare);
+ final StringBuilder sb = new StringBuilder("{\"config\":{\"pqRegistryHash\":[");
+ for (int i = 0; i < heights.size(); i++) {
+ if (i > 0) {
+ sb.append(',');
+ }
+ sb.append("{\"block\":")
+ .append(heights.get(i))
+ .append(",\"hash\":\"0x")
+ .append(entries.get(heights.get(i)))
+ .append("\"}");
+ }
+ sb.append("]}}");
+ final Path p = tmp.resolve("genesis-sched-" + heights.size() + "-" + heights.get(0) + ".json");
+ Files.writeString(p, sb.toString(), StandardCharsets.UTF_8);
+ return PqRegistryHash.loadScheduleFromGenesis(p);
+ }
+
+ private static String hex(final byte[] b) {
+ final StringBuilder s = new StringBuilder(b.length * 2);
+ for (final byte x : b) {
+ s.append(Character.forDigit((x >> 4) & 0xf, 16)).append(Character.forDigit(x & 0xf, 16));
+ }
+ return s.toString();
+ }
+
+ private static void resetFalconSingleton() throws Exception {
+ final Field f = FalconSealSupport.class.getDeclaredField("instance");
+ f.setAccessible(true);
+ f.set(null, null);
+ }
+}
diff --git a/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqV2Fixture.java b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqV2Fixture.java
new file mode 100755
index 000000000..4fb9529b3
--- /dev/null
+++ b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PqV2Fixture.java
@@ -0,0 +1,232 @@
+/*
+ * Copyright contributors to Besu.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.common.bft;
+
+import org.hyperledger.besu.crypto.KeyPair;
+import org.hyperledger.besu.crypto.SECPSignature;
+import org.hyperledger.besu.crypto.SecureRandomProvider;
+import org.hyperledger.besu.crypto.SignatureAlgorithm;
+import org.hyperledger.besu.crypto.SignatureAlgorithmFactory;
+import org.hyperledger.besu.datatypes.Address;
+import org.hyperledger.besu.ethereum.core.Util;
+
+import java.security.SecureRandom;
+import java.util.ArrayList;
+import java.util.List;
+
+import org.apache.tuweni.bytes.Bytes;
+import org.apache.tuweni.bytes.Bytes32;
+import org.bouncycastle.crypto.AsymmetricCipherKeyPair;
+import org.bouncycastle.pqc.crypto.falcon.FalconKeyGenerationParameters;
+import org.bouncycastle.pqc.crypto.falcon.FalconKeyPairGenerator;
+import org.bouncycastle.pqc.crypto.falcon.FalconParameters;
+import org.bouncycastle.pqc.crypto.falcon.FalconPrivateKeyParameters;
+import org.bouncycastle.pqc.crypto.falcon.FalconPublicKeyParameters;
+import org.bouncycastle.pqc.crypto.falcon.FalconSigner;
+
+/**
+ * AERE D-146 (2026-08-06). The shared probe fleet every arming fixture is now built from, and the
+ * reason it had to exist.
+ *
+ * <p>WHAT IT REPLACED, and why the replacement is not cosmetic. Until 2026-08-06 seven separate
+ * fixtures built their registries around addresses spelled {@code String.format("0x%040x", 0xA00 +
+ * i)}. Those addresses are arithmetic, not keys: no secp256k1 private key produces them, so no
+ * validator can ever sign a D-146 claim for one. The moment {@code AERE-PQC-REG-ARM-02} was wired
+ * into {@code FalconSealSupport}, all seven fixtures described a fleet that CANNOT EXIST - armed,
+ * and provably unable to produce the registry the arming path now requires. Measured on 2026-08-06:
+ * 35 tests across 7 classes, every failure carrying AERE-PQC-REG-ARM-02.
+ *
+ * <p>So each row here starts from a REAL secp256k1 key pair and the address is DERIVED from it,
+ * exactly as a validator's address is derived on the live fleet. That single change is what makes a
+ * v2 row signable at all.
+ *
+ * <p>WHY A SHARED POOL AND NOT A HELPER PER TEST. Falcon-512 key generation dominates the runtime of
+ * these fixtures, and every one of them wants the same thing: n validators, each with a Falcon pair,
+ * an ECDSA pair, and proofs over whatever {@code (chainId, bindHeight, count)} that test declares.
+ * Generating the pool once per JVM turns seven independent keygen loops into one. It also makes the
+ * fixtures COMPARABLE: two tests asking for index 3 get the same validator, so a registry written by
+ * one and read by another is the same fleet.
+ *
+ * <p>WHAT IS DELIBERATELY NOT SHARED: the proofs. {@link #popHex} and {@link #claimHex} take
+ * {@code chainId}, {@code bindHeight} and {@code count} because all three are inside the signed
+ * pre-image. A cached proof would be a proof for another registry, and the loader would - correctly
+ * - refuse it. Caching the KEYS is safe; caching the SIGNATURES would defeat the test.
+ *
+ * <p>KEYS. Every key here is generated in memory at test time and never written outside a JUnit
+ * temporary directory. Nothing in this file reads or produces fleet key material.
+ */
+public final class PqV2Fixture {
+
+ /** Size of the probe pool. Larger than any fixture needs, so one pool serves all of them. */
+ private static final int POOL = 16;
+
+ private static List<Holder> pool;
+ private static SignatureAlgorithm ecdsa;
+
+ private PqV2Fixture() {}
+
+ /** One validator's material: a Falcon pair plus the ECDSA consensus key that must vouch for it. */
+ private record Holder(
+ byte[] falconPublicKey, FalconPrivateKeyParameters falconPrivate, KeyPair ecdsa) {}
+
+ private static synchronized List<Holder> pool() {
+ if (pool == null) {
+ ecdsa = SignatureAlgorithmFactory.getInstance();
+ final SecureRandom rnd = SecureRandomProvider.publicSecureRandom();
+ final FalconKeyPairGenerator gen = new FalconKeyPairGenerator();
+ gen.init(new FalconKeyGenerationParameters(rnd, FalconParameters.falcon_512));
+ final List<Holder> built = new ArrayList<>(POOL);
+ for (int i = 0; i < POOL; i++) {
+ final AsymmetricCipherKeyPair kp = gen.generateKeyPair();
+ built.add(
+ new Holder(
+ ((FalconPublicKeyParameters) kp.getPublic()).getH(),
+ (FalconPrivateKeyParameters) kp.getPrivate(),
+ ecdsa.generateKeyPair()));
+ }
+ pool = built;
+ }
+ return pool;
+ }
+
+ /**
+ * The validator address of row {@code i}, DERIVED from that row's secp256k1 public key.
+ *
+ * @param i the row index
+ * @return the derived validator address
+ */
+ public static Address address(final int i) {
+ return Util.publicKeyToAddress(pool().get(i).ecdsa().getPublicKey());
+ }
+
+ /**
+ * The raw Falcon-512 public key of row {@code i}.
+ *
+ * @param i the row index
+ * @return the raw public key bytes
+ */
+ public static byte[] publicKey(final int i) {
+ return pool().get(i).falconPublicKey();
+ }
+
+ /**
+ * The Falcon private key of row {@code i}, for fixtures that must also SIGN as that validator.
+ *
+ * @param i the row index
+ * @return the Falcon private key parameters
+ */
+ public static FalconPrivateKeyParameters privateKey(final int i) {
+ return pool().get(i).falconPrivate();
+ }
+
+ /**
+ * The Falcon possession proof of row {@code i}, over the pre-image this registry declares.
+ *
+ * @param chainId the chain id the registry declares
+ * @param bindHeight the activation height the registry declares
+ * @param count the row count the registry declares
+ * @param i the row index
+ * @return the proof, 0x-prefixed hex
+ */
+ public static String popHex(
+ final long chainId, final long bindHeight, final int count, final int i) {
+ final Bytes32 digest =
+ PqRegistryBinding.possessionDigest(
+ chainId, bindHeight, count, i, address(i).getBytes().toArray(), publicKey(i));
+ final FalconSigner signer = new FalconSigner();
+ signer.init(true, privateKey(i));
+ return Bytes.wrap(signer.generateSignature(digest.toArray())).toHexString();
+ }
+
+ /**
+ * The ECDSA claim of row {@code i}, signed by that row's OWN consensus key.
+ *
+ * @param chainId the chain id the registry declares
+ * @param bindHeight the activation height the registry declares
+ * @param count the row count the registry declares
+ * @param i the row index
+ * @return the claim signature, 0x-prefixed hex
+ */
+ public static String claimHex(
+ final long chainId, final long bindHeight, final int count, final int i) {
+ final Bytes32 digest =
+ PqRegistryBinding.claimDigest(
+ chainId, bindHeight, count, i, address(i).getBytes().toArray(), publicKey(i));
+ final List<Holder> holders = pool(); // also the point at which 'ecdsa' is initialised
+ final SECPSignature s = ecdsa.sign(digest, holders.get(i).ecdsa());
+ return Bytes.wrap(s.encodedBytes().toArrayUnsafe()).toHexString();
+ }
+
+ /**
+ * The manifest-level header a v2 registry must carry, as JSON object fields with a trailing comma
+ * omitted: {@code "count":n,"chainId":c,"bindHeight":h,"formatVersion":2}.
+ *
+ * @param count the row count
+ * @param chainId the chain id
+ * @param bindHeight the activation height
+ * @return the header fields, ready to sit at the head of a manifest object
+ */
+ public static String manifestHeader(final int count, final long chainId, final long bindHeight) {
+ return "\"count\":"
+ + count
+ + ",\"chainId\":"
+ + chainId
+ + ",\"bindHeight\":"
+ + bindHeight
+ + ",\"formatVersion\":"
+ + PqRegistryBinding.FORMAT_VERSION;
+ }
+
+ /**
+ * One v2 manifest row, as a JSON object field: {@code "i":{"addr":..,"pk":..,"pop":..,"claim":..}}.
+ *
+ * @param i the row index
+ * @param count the row count the registry declares
+ * @param chainId the chain id the registry declares
+ * @param bindHeight the activation height the registry declares
+ * @return the row, ready to append after a comma
+ */
+ public static String manifestEntry(
+ final int i, final int count, final long chainId, final long bindHeight) {
+ return "\""
+ + i
+ + "\":{\"addr\":\""
+ + address(i).toHexString()
+ + "\",\"pk\":\""
+ + Bytes.wrap(publicKey(i)).toHexString()
+ + "\",\"pop\":\""
+ + popHex(chainId, bindHeight, count, i)
+ + "\",\"claim\":\""
+ + claimHex(chainId, bindHeight, count, i)
+ + "\"}";
+ }
+
+ /**
+ * The bytes the genesis anchor slot commits to for row {@code i}: {@code address || publicKey},
+ * which is what {@code hashV0Legacy} accumulates. Unchanged by D-146 - the proofs are outside the
+ * legacy pre-image - and kept here so a fixture cannot drift from the row it just wrote.
+ *
+ * @param i the row index
+ * @return the anchored pre-image bytes for that row
+ */
+ public static byte[] anchorPreimageRow(final int i) {
+ final byte[] a = address(i).getBytes().toArray();
+ final byte[] k = publicKey(i);
+ final byte[] out = new byte[a.length + k.length];
+ System.arraycopy(a, 0, out, 0, a.length);
+ System.arraycopy(k, 0, out, a.length, k.length);
+ return out;
+ }
+}
diff --git a/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PreparePqAttachGateTest.java b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PreparePqAttachGateTest.java
new file mode 100755
index 000000000..516897846
--- /dev/null
+++ b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/PreparePqAttachGateTest.java
@@ -0,0 +1,101 @@
+/*
+ * Copyright contributors to Besu.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.common.bft;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+import org.apache.tuweni.bytes.Bytes32;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.Test;
+
+/**
+ * THE GATE that emits a seal on PREPARE (step 2 of the 2026-08-28 design note).
+ *
+ * <p>What is measured here is the CONFIGURATION SURFACE, which is exactly the part that gets typed
+ * by hand and therefore mistyped: absent means never, a good value means from that height onwards,
+ * and a MISTYPED value refuses loudly instead of booting the node disarmed. The lesson paid for in
+ * the anchor loader is that a stray character must never disarm silently, because then nobody finds
+ * out.
+ *
+ * <p>What is NOT measured here, and it is said plainly: that an ARMED node actually produces a
+ * seal. That needs a Falcon key and a registry bound to addresses, which means a network; it is
+ * measured at the coverage step, on a testnet. What is proven here is that the gate is closed by
+ * default and cannot be opened by accident.
+ */
+class PreparePqAttachGateTest {
+
+ @AfterEach
+ void clearTheProperty() {
+ System.clearProperty(FalconSealSupport.PREPARE_ATTACH_PROPERTY);
+ }
+
+ @Test
+ void withoutThePropertyTheGateIsClosedForever() {
+ assertThat(FalconSealSupport.prepareAttachBlock()).isEqualTo(Long.MAX_VALUE);
+ }
+
+ @Test
+ void aGoodValueIsReadAsGiven() {
+ System.setProperty(FalconSealSupport.PREPARE_ATTACH_PROPERTY, "16500000");
+ assertThat(FalconSealSupport.prepareAttachBlock()).isEqualTo(16_500_000L);
+ }
+
+ @Test
+ void zeroIsALEGALValue() {
+ // A threshold of zero means "from genesis", and that is a legitimate configuration on a
+ // testnet. Treated as "unset", a correctly configured testnet would run disarmed in silence.
+ System.setProperty(FalconSealSupport.PREPARE_ATTACH_PROPERTY, "0");
+ assertThat(FalconSealSupport.prepareAttachBlock()).isZero();
+ }
+
+ @Test
+ void aMISTYPEDValueRefusesLoudly() {
+ for (final String bad : new String[] {"nu-e-numar", "16_500_000", "1e6", "-1", " "}) {
+ System.setProperty(FalconSealSupport.PREPARE_ATTACH_PROPERTY, bad);
+ if (bad.isBlank()) {
+ // whitespace is "unset", not a mistyped value: an empty field in a configuration file
+ // must not stop a node
+ assertThat(FalconSealSupport.prepareAttachBlock()).isEqualTo(Long.MAX_VALUE);
+ continue;
+ }
+ assertThatThrownBy(FalconSealSupport::prepareAttachBlock)
+ .as("the value '%s'", bad)
+ .isInstanceOf(FalconSealSupport.ActivationConfigException.class)
+ .hasMessageContaining("AERE-PQC-PREPARE-CONF-01");
+ }
+ }
+
+ @Test
+ void withNoKeyNothingIsSignedEvenWithTheGateOpen() {
+ // The gate is open from genesis and still nothing comes out: the node has no Falcon key. That
+ // is precisely the condition that makes the binary safe to roll onto the fleet before any
+ // decision is taken.
+ System.setProperty(FalconSealSupport.PREPARE_ATTACH_PROPERTY, "0");
+ assertThat(FalconSealSupport.instance().signPrepare(1L, Bytes32.ZERO)).isEmpty();
+ }
+
+ @Test
+ void thePREPAREGateIsNotTheCOMMITGate() {
+ // If it were the same one, rolling the binary onto the fleet would become a flag day: PREPARE
+ // emission would start the moment commit emission does, and that one is already on since block
+ // 13,889,296 on chain 2800.
+ assertThat(FalconSealSupport.PREPARE_ATTACH_PROPERTY).isNotEqualTo("aere.falcon.attachBlock");
+ System.setProperty(FalconSealSupport.PREPARE_ATTACH_PROPERTY, "16500000");
+ assertThat(FalconSealSupport.prepareAttachBlock()).isEqualTo(16_500_000L);
+ // the commit property stays untouched by the PREPARE one
+ assertThat(System.getProperty("aere.falcon.attachBlock")).isNull();
+ }
+}
diff --git a/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/ProposalPqAttachGateTest.java b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/ProposalPqAttachGateTest.java
new file mode 100755
index 000000000..00c8eacf9
--- /dev/null
+++ b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/ProposalPqAttachGateTest.java
@@ -0,0 +1,104 @@
+/*
+ * Copyright contributors to Besu.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.common.bft;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+import org.apache.tuweni.bytes.Bytes32;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.Test;
+
+/**
+ * THE GATE that emits a seal on the PROPOSAL (AERE PQ, 2026-08-30). Twin of the PREPARE gate,
+ * with the same shape on purpose.
+ *
+ * <p>What is measured here is the CONFIGURATION SURFACE, which is exactly the part that gets typed
+ * by hand and therefore mistyped: absent means never, a good value means from that height onwards,
+ * and a MISTYPED value refuses loudly instead of booting the node disarmed. The lesson paid for in
+ * the anchor loader is that a stray character must never disarm silently, because then nobody finds
+ * out.
+ *
+ * <p>What is NOT measured here, and it is said plainly: that an ARMED node actually produces a
+ * seal. That needs a Falcon key and a registry bound to addresses, which means a network; it is
+ * measured at the coverage step, on a testnet. What is proven here is that the gate is closed by
+ * default and cannot be opened by accident.
+ */
+class ProposalPqAttachGateTest {
+
+ @AfterEach
+ void clearTheProperty() {
+ System.clearProperty(FalconSealSupport.PROPOSAL_ATTACH_PROPERTY);
+ }
+
+ @Test
+ void withoutThePropertyTheGateIsClosedForever() {
+ assertThat(FalconSealSupport.proposalAttachBlock()).isEqualTo(Long.MAX_VALUE);
+ }
+
+ @Test
+ void aGoodValueIsReadAsGiven() {
+ System.setProperty(FalconSealSupport.PROPOSAL_ATTACH_PROPERTY, "16500000");
+ assertThat(FalconSealSupport.proposalAttachBlock()).isEqualTo(16_500_000L);
+ }
+
+ @Test
+ void zeroIsALEGALValue() {
+ // A threshold of zero means "from genesis", and that is a legitimate configuration on a
+ // testnet. Treated as "unset", a correctly configured testnet would run disarmed in silence.
+ System.setProperty(FalconSealSupport.PROPOSAL_ATTACH_PROPERTY, "0");
+ assertThat(FalconSealSupport.proposalAttachBlock()).isZero();
+ }
+
+ @Test
+ void aMISTYPEDValueRefusesLoudly() {
+ for (final String bad : new String[] {"nu-e-numar", "16_500_000", "1e6", "-1", " "}) {
+ System.setProperty(FalconSealSupport.PROPOSAL_ATTACH_PROPERTY, bad);
+ if (bad.isBlank()) {
+ // whitespace is "unset", not a mistyped value: an empty field in a configuration file
+ // must not stop a node
+ assertThat(FalconSealSupport.proposalAttachBlock()).isEqualTo(Long.MAX_VALUE);
+ continue;
+ }
+ assertThatThrownBy(FalconSealSupport::proposalAttachBlock)
+ .as("the value '%s'", bad)
+ .isInstanceOf(FalconSealSupport.ActivationConfigException.class)
+ .hasMessageContaining("AERE-PQC-PROPOSAL-CONF-01");
+ }
+ }
+
+ @Test
+ void withNoKeyNothingIsSignedEvenWithTheGateOpen() {
+ // The gate is open from genesis and still nothing comes out: the node has no Falcon key. That
+ // is precisely the condition that makes the binary safe to roll onto the fleet before any
+ // decision is taken.
+ System.setProperty(FalconSealSupport.PROPOSAL_ATTACH_PROPERTY, "0");
+ assertThat(FalconSealSupport.instance().signProposal(1L, Bytes32.ZERO)).isEmpty();
+ }
+
+ @Test
+ void thePROPOSALGateIsNotThePREPAREOrCOMMITGate() {
+ // Three layers, three switches. If any two shared one, the day one is turned on would become a
+ // flag day for the other - and commit emission is already on since block 13,889,296 on 2800.
+ assertThat(FalconSealSupport.PROPOSAL_ATTACH_PROPERTY).isNotEqualTo("aere.falcon.attachBlock");
+ assertThat(FalconSealSupport.PROPOSAL_ATTACH_PROPERTY)
+ .isNotEqualTo(FalconSealSupport.PREPARE_ATTACH_PROPERTY);
+ System.setProperty(FalconSealSupport.PROPOSAL_ATTACH_PROPERTY, "16500000");
+ assertThat(FalconSealSupport.proposalAttachBlock()).isEqualTo(16_500_000L);
+ // the commit and PREPARE properties stay untouched by the PROPOSAL one
+ assertThat(System.getProperty("aere.falcon.attachBlock")).isNull();
+ assertThat(System.getProperty(FalconSealSupport.PREPARE_ATTACH_PROPERTY)).isNull();
+ }
+}
diff --git a/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/RoundChangePqAttachGateTest.java b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/RoundChangePqAttachGateTest.java
new file mode 100755
index 000000000..19c105568
--- /dev/null
+++ b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/RoundChangePqAttachGateTest.java
@@ -0,0 +1,108 @@
+/*
+ * Copyright contributors to Besu.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.common.bft;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+import org.apache.tuweni.bytes.Bytes32;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.Test;
+
+/**
+ * THE GATE that emits a seal on the ROUND-CHANGE (AERE PQ, 2026-08-31). Twin of the PREPARE and
+ * PROPOSAL gates, with the same shape on purpose.
+ *
+ * <p>What is measured here is the CONFIGURATION SURFACE, which is exactly the part that gets typed
+ * by hand and therefore mistyped: absent means never, a good value means from that height onwards,
+ * and a MISTYPED value refuses loudly instead of booting the node disarmed. The lesson paid for in
+ * the anchor loader is that a stray character must never disarm silently, because then nobody finds
+ * out.
+ *
+ * <p>What is NOT measured here, and it is said plainly: that an ARMED node actually produces a
+ * seal. That needs a Falcon key, a registry bound to addresses, and a FAILED round to provoke the
+ * message at all, which means a network; it is measured at the coverage step, on a testnet. What is
+ * proven here is that the gate is closed by default and cannot be opened by accident.
+ */
+class RoundChangePqAttachGateTest {
+
+ @AfterEach
+ void clearTheProperty() {
+ System.clearProperty(FalconSealSupport.ROUNDCHANGE_ATTACH_PROPERTY);
+ }
+
+ @Test
+ void withoutThePropertyTheGateIsClosedForever() {
+ assertThat(FalconSealSupport.roundChangeAttachBlock()).isEqualTo(Long.MAX_VALUE);
+ }
+
+ @Test
+ void aGoodValueIsReadAsGiven() {
+ System.setProperty(FalconSealSupport.ROUNDCHANGE_ATTACH_PROPERTY, "16500000");
+ assertThat(FalconSealSupport.roundChangeAttachBlock()).isEqualTo(16_500_000L);
+ }
+
+ @Test
+ void zeroIsALEGALValue() {
+ // A threshold of zero means "from genesis", and that is a legitimate configuration on a
+ // testnet. Treated as "unset", a correctly configured testnet would run disarmed in silence.
+ System.setProperty(FalconSealSupport.ROUNDCHANGE_ATTACH_PROPERTY, "0");
+ assertThat(FalconSealSupport.roundChangeAttachBlock()).isZero();
+ }
+
+ @Test
+ void aMISTYPEDValueRefusesLoudly() {
+ for (final String bad : new String[] {"nu-e-numar", "16_500_000", "1e6", "-1", " "}) {
+ System.setProperty(FalconSealSupport.ROUNDCHANGE_ATTACH_PROPERTY, bad);
+ if (bad.isBlank()) {
+ // whitespace is "unset", not a mistyped value: an empty field in a configuration file
+ // must not stop a node
+ assertThat(FalconSealSupport.roundChangeAttachBlock()).isEqualTo(Long.MAX_VALUE);
+ continue;
+ }
+ assertThatThrownBy(FalconSealSupport::roundChangeAttachBlock)
+ .as("the value '%s'", bad)
+ .isInstanceOf(FalconSealSupport.ActivationConfigException.class)
+ .hasMessageContaining("AERE-PQC-ROUNDCHANGE-CONF-01");
+ }
+ }
+
+ @Test
+ void withNoKeyNothingIsSignedEvenWithTheGateOpen() {
+ // The gate is open from genesis and still nothing comes out: the node has no Falcon key. That
+ // is precisely the condition that makes the binary safe to roll onto the fleet before any
+ // decision is taken.
+ System.setProperty(FalconSealSupport.ROUNDCHANGE_ATTACH_PROPERTY, "0");
+ assertThat(FalconSealSupport.instance().signRoundChange(1L, Bytes32.ZERO)).isEmpty();
+ }
+
+ @Test
+ void theROUNDCHANGEGateIsNoneOfItsThreeSiblings() {
+ // Four layers, four switches. If any two shared one, the day one is turned on would become a
+ // flag day for the other - and commit emission is already on since block 13,889,296 on 2800.
+ assertThat(FalconSealSupport.ROUNDCHANGE_ATTACH_PROPERTY)
+ .isNotEqualTo("aere.falcon.attachBlock");
+ assertThat(FalconSealSupport.ROUNDCHANGE_ATTACH_PROPERTY)
+ .isNotEqualTo(FalconSealSupport.PREPARE_ATTACH_PROPERTY);
+ assertThat(FalconSealSupport.ROUNDCHANGE_ATTACH_PROPERTY)
+ .isNotEqualTo(FalconSealSupport.PROPOSAL_ATTACH_PROPERTY);
+ System.setProperty(FalconSealSupport.ROUNDCHANGE_ATTACH_PROPERTY, "16500000");
+ assertThat(FalconSealSupport.roundChangeAttachBlock()).isEqualTo(16_500_000L);
+ // the commit, PREPARE and PROPOSAL properties stay untouched by the ROUND-CHANGE one
+ assertThat(System.getProperty("aere.falcon.attachBlock")).isNull();
+ assertThat(System.getProperty(FalconSealSupport.PREPARE_ATTACH_PROPERTY)).isNull();
+ assertThat(System.getProperty(FalconSealSupport.PROPOSAL_ATTACH_PROPERTY)).isNull();
+ }
+}
diff --git a/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/SealSchemeAgilityTest.java b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/SealSchemeAgilityTest.java
new file mode 100755
index 000000000..91ca9bbfb
--- /dev/null
+++ b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/SealSchemeAgilityTest.java
@@ -0,0 +1,145 @@
+/* AERE crypto-agility, step 1 proofs. Every green here has a red twin: flipped signatures,
+ * flipped messages, wrong keys, and the cross-scheme controls that are the whole point of the
+ * layer (a Falcon artefact must never verify as SLH-DSA, and vice versa). A layer whose schemes
+ * cannot be told apart would be worse than no layer. */
+package org.hyperledger.besu.consensus.common.bft;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import java.nio.charset.StandardCharsets;
+import java.security.SecureRandom;
+import java.util.Optional;
+
+import org.hyperledger.besu.crypto.SecureRandomProvider;
+import org.junit.jupiter.api.Test;
+
+class SealSchemeAgilityTest {
+
+ private static final byte[] MESSAGE = "aere anchor commit hash stand-in".getBytes(StandardCharsets.UTF_8);
+ private static final byte[] OTHER_MESSAGE = "a different message entirely....".getBytes(StandardCharsets.UTF_8);
+
+ private final SecureRandom random = SecureRandomProvider.createSecureRandom();
+
+ // ------------------------------------------------------------------ per-scheme sign/verify
+
+ @Test
+ void falconSignsAndVerifies() {
+ roundTrip(SealSchemes.FALCON_512);
+ }
+
+ @Test
+ void slhDsaSignsAndVerifies() {
+ roundTrip(SealSchemes.SLH_DSA_128S);
+ }
+
+ private void roundTrip(final SealScheme scheme) {
+ final SealScheme.GeneratedPair pair = scheme.generate(random);
+ final Optional<byte[]> sig = scheme.sign(pair.privateKey(), MESSAGE);
+ assertThat(sig).isPresent();
+ assertThat(scheme.verify(pair.publicKey(), MESSAGE, sig.get())).isTrue();
+ assertThat(scheme.verifyRaw(pair.publicRegistryForm(), MESSAGE, sig.get())).isTrue();
+ }
+
+ // ------------------------------------------------------------------ negative controls
+
+ @Test
+ void flippedSignatureBitIsRejectedByBothSchemes() {
+ for (final SealScheme scheme : SealSchemes.all()) {
+ final SealScheme.GeneratedPair pair = scheme.generate(random);
+ final byte[] sig = scheme.sign(pair.privateKey(), MESSAGE).orElseThrow();
+ sig[sig.length / 2] ^= 0x01;
+ assertThat(scheme.verify(pair.publicKey(), MESSAGE, sig))
+ .as("%s must reject a signature with one flipped bit", scheme.id())
+ .isFalse();
+ }
+ }
+
+ @Test
+ void flippedMessageIsRejectedByBothSchemes() {
+ for (final SealScheme scheme : SealSchemes.all()) {
+ final SealScheme.GeneratedPair pair = scheme.generate(random);
+ final byte[] sig = scheme.sign(pair.privateKey(), MESSAGE).orElseThrow();
+ assertThat(scheme.verify(pair.publicKey(), OTHER_MESSAGE, sig))
+ .as("%s must reject the signature over a different message", scheme.id())
+ .isFalse();
+ }
+ }
+
+ @Test
+ void wrongKeyIsRejectedByBothSchemes() {
+ for (final SealScheme scheme : SealSchemes.all()) {
+ final SealScheme.GeneratedPair signer = scheme.generate(random);
+ final SealScheme.GeneratedPair stranger = scheme.generate(random);
+ final byte[] sig = scheme.sign(signer.privateKey(), MESSAGE).orElseThrow();
+ assertThat(scheme.verify(stranger.publicKey(), MESSAGE, sig))
+ .as("%s must reject a signature under a stranger's key", scheme.id())
+ .isFalse();
+ }
+ }
+
+ // ------------------------------------------------------- the point of the layer: cross-scheme
+
+ @Test
+ void falconArtefactsNeverVerifyAsSlhDsa() {
+ final SealScheme.GeneratedPair falcon = SealSchemes.FALCON_512.generate(random);
+ final byte[] falconSig = SealSchemes.FALCON_512.sign(falcon.privateKey(), MESSAGE).orElseThrow();
+ // the raw Falcon key is not even parseable as an SLH-DSA key (896 vs 32 bytes)...
+ assertThat(SealSchemes.SLH_DSA_128S.parsePublicKey(falcon.publicRegistryForm())).isEmpty();
+ // ...and the raw path must answer false, never throw
+ assertThat(SealSchemes.SLH_DSA_128S.verifyRaw(falcon.publicRegistryForm(), MESSAGE, falconSig)).isFalse();
+ // a Falcon PRIVATE handle fed to the SLH-DSA signer must refuse, not sign garbage
+ assertThat(SealSchemes.SLH_DSA_128S.sign(falcon.privateKey(), MESSAGE)).isEmpty();
+ }
+
+ @Test
+ void slhDsaArtefactsNeverVerifyAsFalcon() {
+ final SealScheme.GeneratedPair slh = SealSchemes.SLH_DSA_128S.generate(random);
+ final byte[] slhSig = SealSchemes.SLH_DSA_128S.sign(slh.privateKey(), MESSAGE).orElseThrow();
+ assertThat(SealSchemes.FALCON_512.parsePublicKey(slh.publicRegistryForm())).isEmpty();
+ assertThat(SealSchemes.FALCON_512.verifyRaw(slh.publicRegistryForm(), MESSAGE, slhSig)).isFalse();
+ assertThat(SealSchemes.FALCON_512.sign(slh.privateKey(), MESSAGE)).isEmpty();
+ }
+
+ @Test
+ void crossSchemeHandlesAreRejectedOnVerifyToo() {
+ final SealScheme.GeneratedPair falcon = SealSchemes.FALCON_512.generate(random);
+ final SealScheme.GeneratedPair slh = SealSchemes.SLH_DSA_128S.generate(random);
+ final byte[] falconSig = SealSchemes.FALCON_512.sign(falcon.privateKey(), MESSAGE).orElseThrow();
+ // a foreign PUBLIC handle on verify: false, never a ClassCastException
+ assertThat(SealSchemes.SLH_DSA_128S.verify(falcon.publicKey(), MESSAGE, falconSig)).isFalse();
+ assertThat(SealSchemes.FALCON_512.verify(slh.publicKey(), MESSAGE, falconSig)).isFalse();
+ }
+
+ // ------------------------------------------------------------------ registry and wire form
+
+ @Test
+ void registryFindsSchemesByIdAndWireTag() {
+ assertThat(SealSchemes.byId("falcon-512")).contains(SealSchemes.FALCON_512);
+ assertThat(SealSchemes.byId("slh-dsa-128s")).contains(SealSchemes.SLH_DSA_128S);
+ assertThat(SealSchemes.byWireId((byte) 0x01)).contains(SealSchemes.FALCON_512);
+ assertThat(SealSchemes.byWireId((byte) 0x02)).contains(SealSchemes.SLH_DSA_128S);
+ }
+
+ @Test
+ void unknownSchemesAreLoudlyAbsentNeverDefaulted() {
+ assertThat(SealSchemes.byId("dilithium-notyet")).isEmpty();
+ assertThat(SealSchemes.byId(null)).isEmpty();
+ // 0x00 is the legacy untagged certificate, deliberately NOT resolvable as a scheme
+ assertThat(SealSchemes.byWireId((byte) 0x00)).isEmpty();
+ assertThat(SealSchemes.byWireId((byte) 0x7f)).isEmpty();
+ }
+
+ @Test
+ void registryFormsHaveTheDocumentedLengths() {
+ // Falcon-512: 896 raw h bytes, the exact form the signer registry stores (measured on the
+ // proof-network registry files). The 897-byte pk(897) = 0x09 || h is the PRECOMPILE input
+ // format, one layer above; the first form of this assertion said 897 and went red, which is
+ // the measurement this comment records. Locking 896 here means a scheme change cannot
+ // silently change what a registry entry means.
+ assertThat(SealSchemes.FALCON_512.publicKeyLength()).isEqualTo(896);
+ assertThat(SealSchemes.FALCON_512.generate(random).publicRegistryForm()).hasSize(896);
+ // SLH-DSA-128s: 32 bytes (PK.seed || PK.root) per FIPS 205.
+ assertThat(SealSchemes.SLH_DSA_128S.publicKeyLength()).isEqualTo(32);
+ assertThat(SealSchemes.SLH_DSA_128S.generate(random).publicRegistryForm()).hasSize(32);
+ }
+}
diff --git a/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/SlhDsaCrossVectorTest.java b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/SlhDsaCrossVectorTest.java
new file mode 100755
index 000000000..00891a0fe
--- /dev/null
+++ b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/SlhDsaCrossVectorTest.java
@@ -0,0 +1,82 @@
+/*
+ * Copyright contributors to Aere Network.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.common.bft;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.nio.charset.StandardCharsets;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+
+import org.apache.tuweni.bytes.Bytes;
+import org.junit.jupiter.api.Test;
+
+/**
+ * D-325 (2026-09-03), the CROSS-IMPLEMENTATION vector: an SLH-DSA-SHA2-128s signature produced by the public
+ * verifier's library (@noble/post-quantum 0.7.1, FIPS 205 external form, empty context) must verify under this
+ * fork's {@link SlhDsaSealScheme} (BouncyCastle Java). Two implementations agreeing on one vector is the only
+ * proof that "the same form" is the same form; two self-consistent implementations prove nothing about each other.
+ *
+ * <p>With its pair: the same signature over a message that differs in one bit does NOT verify, and a signature with
+ * one bit flipped does NOT verify. A verifier that accepted everything would pass the positive half alone.
+ */
+class SlhDsaCrossVectorTest {
+
+ private static String field(final String json, final String name) {
+ final Matcher m = Pattern.compile("\"" + name + "\"\\s*:\\s*\"([0-9a-fA-F]+)\"").matcher(json);
+ if (!m.find()) {
+ throw new IllegalStateException("vector has no field " + name);
+ }
+ return m.group(1);
+ }
+
+ private static String vector() throws IOException {
+ try (InputStream in =
+ SlhDsaCrossVectorTest.class.getResourceAsStream("/vector-slh-dsa-noble-2026-09-03.json")) {
+ if (in == null) {
+ throw new IllegalStateException("vector-slh-dsa-noble-2026-09-03.json is not on the test classpath");
+ }
+ return new String(in.readAllBytes(), StandardCharsets.UTF_8);
+ }
+ }
+
+ @Test
+ void aSignatureFromTheJavaScriptImplementationVerifiesHereAndItsTamperedTwinsDoNot() throws IOException {
+ final String v = vector();
+ final byte[] pk = Bytes.fromHexString(field(v, "pk")).toArray();
+ final byte[] msg = Bytes.fromHexString(field(v, "msg")).toArray();
+ final byte[] sig = Bytes.fromHexString(field(v, "sig")).toArray();
+ assertThat(pk).hasSize(32);
+ assertThat(msg).hasSize(32);
+ assertThat(sig).hasSize(7856);
+ final SealScheme scheme = SealSchemes.SLH_DSA_128S;
+ assertThat(scheme.verifyRaw(pk, msg, sig))
+ .describedAs("the @noble/post-quantum signature verifies under BouncyCastle's SLH-DSA-SHA2-128s (external form)")
+ .isTrue();
+ final byte[] otherMsg = msg.clone();
+ otherMsg[0] ^= 0x01;
+ assertThat(scheme.verifyRaw(pk, otherMsg, sig)).describedAs("one message bit flipped").isFalse();
+ final byte[] badSig = sig.clone();
+ badSig[badSig.length / 2] ^= 0x01;
+ assertThat(scheme.verifyRaw(pk, msg, badSig)).describedAs("one signature bit flipped").isFalse();
+ // and the INTERNAL form (what the precompile at 0x0AE4 uses) must NOT be confused with it: a scheme that
+ // accepted both would let a seal stand in for a precompile call or the other way round.
+ assertThat(SealSchemes.byId("slh-dsa-sha2-128s")).isPresent();
+ assertThat(SealSchemes.byId("slh-dsa-128s")).describedAs("the pre-D-325 alias still resolves").isPresent();
+ }
+}
diff --git a/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/SlhDsaFastEngineTest.java b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/SlhDsaFastEngineTest.java
new file mode 100755
index 000000000..d1ca77a67
--- /dev/null
+++ b/consensus/common/src/test/java/org/hyperledger/besu/consensus/common/bft/SlhDsaFastEngineTest.java
@@ -0,0 +1,141 @@
+/*
+ * Copyright contributors to Aere Network.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.common.bft;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import java.nio.charset.StandardCharsets;
+import java.security.SecureRandom;
+import java.util.Arrays;
+import org.bouncycastle.crypto.AsymmetricCipherKeyPair;
+import org.hyperledger.besu.consensus.common.bft.slhdsa.SLHDSAKeyGenerationParameters;
+import org.hyperledger.besu.consensus.common.bft.slhdsa.SLHDSAKeyPairGenerator;
+import org.hyperledger.besu.consensus.common.bft.slhdsa.SLHDSAParameters;
+import org.hyperledger.besu.consensus.common.bft.slhdsa.SLHDSAPrivateKeyParameters;
+import org.hyperledger.besu.consensus.common.bft.slhdsa.SLHDSAPublicKeyParameters;
+import org.hyperledger.besu.consensus.common.bft.slhdsa.SLHDSASigner;
+import org.hyperledger.besu.crypto.SecureRandomProvider;
+import org.junit.jupiter.api.Test;
+
+/**
+ * D-337 (2026-09-04): the in-tree SLH-DSA engine (Bouncy Castle's algorithm on the JDK's SHA-NI
+ * digest) must be the SAME signature scheme as the Bouncy Castle original, bit for bit. Otherwise a
+ * faster signer is a different certificate, and the second client and the public verifier would
+ * reject every anchor. Each direction is pinned: fast-signed verifies under the original, original-
+ * signed verifies under the fast engine, deterministic signing gives identical bytes, and the fast
+ * engine still rejects a tampered signature (the negative control of the verifier).
+ */
+class SlhDsaFastEngineTest {
+
+ private static final org.bouncycastle.pqc.crypto.slhdsa.SLHDSAParameters ORIGINAL =
+ org.bouncycastle.pqc.crypto.slhdsa.SLHDSAParameters.sha2_128s;
+
+ private static AsymmetricCipherKeyPair fastKeyPair() {
+ final SLHDSAKeyPairGenerator gen = new SLHDSAKeyPairGenerator();
+ gen.init(new SLHDSAKeyGenerationParameters(SecureRandomProvider.createSecureRandom(), SLHDSAParameters.sha2_128s));
+ return gen.generateKeyPair();
+ }
+
+ private static org.bouncycastle.pqc.crypto.slhdsa.SLHDSAPublicKeyParameters originalPub(
+ final AsymmetricCipherKeyPair kp) {
+ return new org.bouncycastle.pqc.crypto.slhdsa.SLHDSAPublicKeyParameters(
+ ORIGINAL, ((SLHDSAPublicKeyParameters) kp.getPublic()).getEncoded());
+ }
+
+ private static org.bouncycastle.pqc.crypto.slhdsa.SLHDSAPrivateKeyParameters originalPriv(
+ final AsymmetricCipherKeyPair kp) {
+ return new org.bouncycastle.pqc.crypto.slhdsa.SLHDSAPrivateKeyParameters(
+ ORIGINAL, ((SLHDSAPrivateKeyParameters) kp.getPrivate()).getEncoded());
+ }
+
+ @Test
+ void aFastSignatureVerifiesUnderTheOriginalBouncyCastleEngine() {
+ final AsymmetricCipherKeyPair kp = fastKeyPair();
+ final byte[] msg = "AERE-PQ-ANCHOR-2 commit seal message".getBytes(StandardCharsets.UTF_8);
+ final SLHDSASigner signer = new SLHDSASigner();
+ signer.init(true, kp.getPrivate());
+ final byte[] sig = signer.generateSignature(msg);
+ assertThat(sig).hasSize(7856);
+
+ final org.bouncycastle.pqc.crypto.slhdsa.SLHDSASigner original =
+ new org.bouncycastle.pqc.crypto.slhdsa.SLHDSASigner();
+ original.init(false, originalPub(kp));
+ assertThat(original.verifySignature(msg, sig)).isTrue();
+
+ // negative control of the ORIGINAL verifier on the fast signature: one bit off, rejected
+ final byte[] bad = sig.clone();
+ bad[1234] ^= 0x01;
+ original.init(false, originalPub(kp));
+ assertThat(original.verifySignature(msg, bad)).isFalse();
+ }
+
+ @Test
+ void anOriginalSignatureVerifiesUnderTheFastEngineAndATamperedOneDoesNot() {
+ final AsymmetricCipherKeyPair kp = fastKeyPair();
+ final byte[] msg = new byte[32];
+ msg[31] = 7;
+ final org.bouncycastle.pqc.crypto.slhdsa.SLHDSASigner original =
+ new org.bouncycastle.pqc.crypto.slhdsa.SLHDSASigner();
+ original.init(true, originalPriv(kp));
+ final byte[] sig = original.generateSignature(msg);
+
+ final SLHDSASigner fast = new SLHDSASigner();
+ fast.init(false, kp.getPublic());
+ assertThat(fast.verifySignature(msg, sig)).isTrue();
+
+ final byte[] bad = sig.clone();
+ bad[100] ^= 0x01;
+ fast.init(false, kp.getPublic());
+ assertThat(fast.verifySignature(msg, bad)).isFalse();
+
+ final byte[] otherMsg = msg.clone();
+ otherMsg[0] ^= 0x01;
+ fast.init(false, kp.getPublic());
+ assertThat(fast.verifySignature(otherMsg, sig)).isFalse();
+ }
+
+ @Test
+ void deterministicSigningGivesTheSameBytesAsTheOriginal() {
+ // Without a SecureRandom both engines use the pk seed as opt_rand (FIPS 205 deterministic
+ // variant), so the SAME key and message must give the SAME 7856 bytes. This is the strongest
+ // statement that the hash swap changed nothing but the clock.
+ final AsymmetricCipherKeyPair kp = fastKeyPair();
+ final byte[] msg = "deterministic".getBytes(StandardCharsets.UTF_8);
+ final SLHDSASigner fast = new SLHDSASigner();
+ fast.init(true, kp.getPrivate());
+ final org.bouncycastle.pqc.crypto.slhdsa.SLHDSASigner original =
+ new org.bouncycastle.pqc.crypto.slhdsa.SLHDSASigner();
+ original.init(true, originalPriv(kp));
+ assertThat(Arrays.equals(fast.generateSignature(msg), original.generateSignature(msg)))
+ .isTrue();
+ }
+
+ @Test
+ void theSealSchemeItselfSignsThroughTheFastEngineAndTheOriginalAccepts() {
+ final SlhDsaSealScheme scheme = new SlhDsaSealScheme();
+ final SealScheme.GeneratedPair pair = scheme.generate(SecureRandomProvider.createSecureRandom());
+ final byte[] msg = new byte[32];
+ final byte[] sig = scheme.sign(pair.privateKey(), msg).orElseThrow();
+ final org.bouncycastle.pqc.crypto.slhdsa.SLHDSASigner original =
+ new org.bouncycastle.pqc.crypto.slhdsa.SLHDSASigner();
+ original.init(
+ false,
+ new org.bouncycastle.pqc.crypto.slhdsa.SLHDSAPublicKeyParameters(
+ ORIGINAL, pair.publicRegistryForm()));
+ assertThat(original.verifySignature(msg, sig)).isTrue();
+ assertThat(scheme.verifyRaw(pair.publicRegistryForm(), msg, sig)).isTrue();
+ }
+}
diff --git a/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/messagewrappers/Commit.java b/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/messagewrappers/Commit.java
index 142069ec7..00d7b78c2 100644
--- a/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/messagewrappers/Commit.java
+++ b/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/messagewrappers/Commit.java
@@ -11,9 +11,16 @@
* specific language governing permissions and limitations under the License.
*
* SPDX-License-Identifier: Apache-2.0
+ *
+ * Modifications Copyright contributors to the Aere Network.
+ *
+ * This file was modified by contributors to the Aere Network, as required by section 4(b) of the
+ * Apache License 2.0. The copyright header above is the upstream one and is left exactly as it was
+ * found, as section 4(c) requires. The change itself is in patches/0003-aere-pq-anchor.patch.
*/
package org.hyperledger.besu.consensus.qbft.core.messagewrappers;
+import org.hyperledger.besu.consensus.common.bft.FalconSeal;
import org.hyperledger.besu.consensus.common.bft.messagewrappers.BftMessage;
import org.hyperledger.besu.consensus.common.bft.payload.SignedData;
import org.hyperledger.besu.consensus.qbft.core.payload.CommitPayload;
@@ -22,6 +29,8 @@ import org.hyperledger.besu.datatypes.Hash;
import org.hyperledger.besu.ethereum.rlp.RLP;
import org.hyperledger.besu.ethereum.rlp.RLPInput;
+import java.util.Optional;
+
import org.apache.tuweni.bytes.Bytes;
/** The Commit payload message. */
@@ -45,11 +54,34 @@ public class Commit extends BftMessage<CommitPayload> {
return getPayload().getCommitSeal();
}
+ /**
+ * Gets the optional parallel post-quantum Falcon seal carried on this commit.
+ *
+ * @return the Falcon seal if present, otherwise empty
+ */
+ public Optional<FalconSeal> getFalconSeal() {
+ return getPayload().getFalconSeal();
+ }
+
/**
* Gets digest.
*
* @return the digest
*/
+ /**
+ * D-339 (2026-09-04): the hybrid extra seals this Commit carries, as a plain accessor.
+ *
+ * <p>It exists so the two places that keep seals out of a dying message (the late-seal salvage in
+ * the controller and the no-proposal path in the round) do not have to reach through the signed
+ * payload. Reaching through it also broke every test that mocks a Commit, which is exactly the
+ * kind of surprise a wrapper class is meant to absorb.
+ *
+ * @return the non-Falcon scheme seals, empty on every commit that carries none
+ */
+ public java.util.List<org.hyperledger.besu.consensus.common.bft.SchemeSeal> getExtraSeals() {
+ return getPayload().getExtraSeals();
+ }
+
public Hash getDigest() {
return getPayload().getDigest();
}
diff --git a/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/network/QbftMessageTransmitter.java b/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/network/QbftMessageTransmitter.java
index 30156ed6d..18437e30f 100644
--- a/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/network/QbftMessageTransmitter.java
+++ b/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/network/QbftMessageTransmitter.java
@@ -11,10 +11,18 @@
* specific language governing permissions and limitations under the License.
*
* SPDX-License-Identifier: Apache-2.0
+ *
+ * Modifications Copyright contributors to the Aere Network.
+ *
+ * This file was modified by contributors to the Aere Network, as required by section 4(b) of the
+ * Apache License 2.0. The copyright header above is the upstream one and is left exactly as it was
+ * found, as section 4(c) requires. The change itself is in patches/0003-aere-pq-anchor.patch.
*/
package org.hyperledger.besu.consensus.qbft.core.network;
import org.hyperledger.besu.consensus.common.bft.ConsensusRoundIdentifier;
+import org.hyperledger.besu.consensus.common.bft.FalconSeal;
+import org.hyperledger.besu.consensus.common.bft.SchemeSeal;
import org.hyperledger.besu.consensus.common.bft.network.ValidatorMulticaster;
import org.hyperledger.besu.consensus.common.bft.payload.SignedData;
import org.hyperledger.besu.consensus.qbft.core.messagedata.CommitMessageData;
@@ -76,10 +84,42 @@ public class QbftMessageTransmitter {
final Optional<BlockAccessList> blockAccessList,
final List<SignedData<RoundChangePayload>> roundChanges,
final List<SignedData<PreparePayload>> prepares) {
+ multicastProposal(roundIdentifier, block, blockAccessList, roundChanges, prepares,
+ Optional.empty());
+ }
+
+ /**
+ * Multicast proposal carrying the proposer's optional post-quantum seal (AERE PQ, 2026-08-30).
+ *
+ * <p>THE SEAL MUST BE THE SAME OBJECT the caller embedded in its local copy, and this overload
+ * exists because the first network run proved what happens without it: this method RE-CREATES
+ * the proposal from scratch, so the local copy carried a seal, the wire copy carried none, and
+ * at the enforcement height every peer refused round after round while the proposer's own log
+ * said it had emitted. F84 scenario A, 2026-08-30 - the witness went red, exactly its job.
+ * The same two-copies trap was closed at PREPARE the day before it could bite; here it bit
+ * first, on a testnet, which is where it is allowed to.
+ *
+ * @param roundIdentifier the round identifier
+ * @param block the block
+ * @param blockAccessList the block access list
+ * @param roundChanges the round changes
+ * @param prepares the prepares
+ * @param falconSeal the proposer's post-quantum seal, or empty
+ */
+ public void multicastProposal(
+ final ConsensusRoundIdentifier roundIdentifier,
+ final QbftBlock block,
+ final Optional<BlockAccessList> blockAccessList,
+ final List<SignedData<RoundChangePayload>> roundChanges,
+ final List<SignedData<PreparePayload>> prepares,
+ final Optional<FalconSeal> falconSeal) {
try {
final Proposal data =
- messageFactory.createProposal(
- roundIdentifier, block, blockAccessList, roundChanges, prepares);
+ falconSeal.isPresent()
+ ? messageFactory.createProposal(
+ roundIdentifier, block, blockAccessList, roundChanges, prepares, falconSeal)
+ : messageFactory.createProposal(
+ roundIdentifier, block, blockAccessList, roundChanges, prepares);
final ProposalMessageData message = ProposalMessageData.create(data);
@@ -96,8 +136,27 @@ public class QbftMessageTransmitter {
* @param digest the digest
*/
public void multicastPrepare(final ConsensusRoundIdentifier roundIdentifier, final Hash digest) {
+ multicastPrepare(roundIdentifier, digest, Optional.empty());
+ }
+
+ /**
+ * Multicast a prepare carrying an OPTIONAL post-quantum seal of this node.
+ *
+ * <p>Sigiliul vine GATA CALCULAT de la apelant, si asta nu e comoditate: semnaturile Falcon sunt
+ * randomized, so signing the same message twice yields two different byte strings. If the local
+ * copy and the one on the wire each signed their own, the same validator would produce two
+ * valide si DIFERITE pentru aceeasi runda. Se calculeaza o data, sus, si se trece prin amandoua.
+ *
+ * @param roundIdentifier the round identifier
+ * @param digest the digest
+ * @param falconSeal the seal, or empty
+ */
+ public void multicastPrepare(
+ final ConsensusRoundIdentifier roundIdentifier,
+ final Hash digest,
+ final Optional<FalconSeal> falconSeal) {
try {
- final Prepare data = messageFactory.createPrepare(roundIdentifier, digest);
+ final Prepare data = messageFactory.createPrepare(roundIdentifier, digest, falconSeal);
final PrepareMessageData message = PrepareMessageData.create(data);
@@ -118,8 +177,44 @@ public class QbftMessageTransmitter {
final ConsensusRoundIdentifier roundIdentifier,
final Hash digest,
final SECPSignature commitSeal) {
+ multicastCommit(roundIdentifier, digest, commitSeal, Optional.empty());
+ }
+
+ /**
+ * Multicast commit carrying an optional parallel Falcon-512 seal (AERE hybrid PQC).
+ *
+ * @param roundIdentifier the round identifier
+ * @param digest the digest
+ * @param commitSeal the ECDSA commit seal
+ * @param falconSeal the optional parallel post-quantum Falcon seal
+ */
+ public void multicastCommit(
+ final ConsensusRoundIdentifier roundIdentifier,
+ final Hash digest,
+ final SECPSignature commitSeal,
+ final Optional<FalconSeal> falconSeal) {
+ multicastCommit(roundIdentifier, digest, commitSeal, falconSeal, java.util.List.of());
+ }
+
+ /**
+ * Multicast commit carrying a HYBRID post-quantum certificate: the Falcon seal in its own slot
+ * plus the other schemes' seals alongside it (AERE HIBRID, 2026-08-25).
+ *
+ * @param roundIdentifier the round identifier
+ * @param digest the digest
+ * @param commitSeal the ECDSA commit seal
+ * @param falconSeal the optional parallel Falcon seal
+ * @param extraSeals the non-Falcon scheme seals; empty on every node not hybrid-configured
+ */
+ public void multicastCommit(
+ final ConsensusRoundIdentifier roundIdentifier,
+ final Hash digest,
+ final SECPSignature commitSeal,
+ final Optional<FalconSeal> falconSeal,
+ final java.util.List<SchemeSeal> extraSeals) {
try {
- final Commit data = messageFactory.createCommit(roundIdentifier, digest, commitSeal);
+ final Commit data =
+ messageFactory.createCommit(roundIdentifier, digest, commitSeal, falconSeal, extraSeals);
final CommitMessageData message = CommitMessageData.create(data);
@@ -149,4 +244,18 @@ public class QbftMessageTransmitter {
LOG.warn("Failed to generate signature for RoundChange (not sent): {} ", e.getMessage());
}
}
+
+ /**
+ * Multicast an ALREADY BUILT round change, without re-creating it. AERE PQ (2026-08-31): the
+ * height manager signs its round-change ONCE - Falcon signatures are randomised, so re-creating
+ * the message here would put a DIFFERENT object on the wire than the one handled locally, the
+ * exact defect F84 measured on the PROPOSAL (local copy sealed, wire copy not). The seal-less
+ * path keeps using the overload above, call for call as upstream.
+ *
+ * @param roundChange the round change to send, exactly as built
+ */
+ public void multicastRoundChange(final RoundChange roundChange) {
+ final RoundChangeMessageData message = RoundChangeMessageData.create(roundChange);
+ multicaster.send(message);
+ }
}
diff --git a/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/payload/CommitPayload.java b/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/payload/CommitPayload.java
index db481acd0..8b788f499 100644
--- a/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/payload/CommitPayload.java
+++ b/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/payload/CommitPayload.java
@@ -11,30 +11,62 @@
* specific language governing permissions and limitations under the License.
*
* SPDX-License-Identifier: Apache-2.0
+ *
+ * Modifications Copyright contributors to the Aere Network.
+ *
+ * This file was modified by contributors to the Aere Network, as required by section 4(b) of the
+ * Apache License 2.0. The copyright header above is the upstream one and is left exactly as it was
+ * found, as section 4(c) requires. The change itself is in patches/0003-aere-pq-anchor.patch.
*/
package org.hyperledger.besu.consensus.qbft.core.payload;
import org.hyperledger.besu.consensus.common.bft.ConsensusRoundIdentifier;
+import org.hyperledger.besu.consensus.common.bft.FalconSeal;
+import org.hyperledger.besu.consensus.common.bft.PqAnchorV2;
+import org.hyperledger.besu.consensus.common.bft.SchemeSeal;
+import org.hyperledger.besu.consensus.common.bft.SealSchemes;
import org.hyperledger.besu.consensus.common.bft.payload.Payload;
import org.hyperledger.besu.consensus.qbft.core.messagedata.QbftV1;
import org.hyperledger.besu.crypto.SECPSignature;
import org.hyperledger.besu.crypto.SignatureAlgorithmFactory;
import org.hyperledger.besu.datatypes.Hash;
+import org.hyperledger.besu.ethereum.rlp.RLPException;
import org.hyperledger.besu.ethereum.rlp.RLPInput;
import org.hyperledger.besu.ethereum.rlp.RLPOutput;
+import java.util.List;
import java.util.Objects;
+import java.util.Optional;
import java.util.StringJoiner;
-/** The Commit payload. */
+import org.apache.tuweni.bytes.Bytes;
+
+/**
+ * The Commit payload.
+ *
+ * <p>AERE hybrid PQC extension: a Commit payload MAY carry an OPTIONAL parallel Falcon-512 seal, so
+ * that every validator's post-quantum seal over the commit hash is GOSSIPED alongside the decisive
+ * ECDSA commit seal on the same message. The Falcon seal is appended only when present, so a
+ * Falcon-less Commit encodes byte-for-byte identically to upstream Besu. When present, the whole
+ * payload (including the Falcon seal) is covered by the author's ECDSA signature, binding the
+ * claimed Falcon validator index to the sender's identity.
+ *
+ * <p>AERE FIX-MALEABILITATE: this payload has exactly ONE valid encoding for a given value. See
+ * {@link #readFrom(RLPInput)}.
+ */
public class CommitPayload extends QbftPayload {
private static final int TYPE = QbftV1.COMMIT;
private final ConsensusRoundIdentifier roundIdentifier;
private final Hash digest;
private final SECPSignature commitSeal;
+ private final Optional<FalconSeal> falconSeal;
+ // AERE HIBRID (2026-08-25): the NON-Falcon scheme seals of a hybrid certificate. Falcon keeps
+ // living in the legacy slot above, so one signature has exactly one home and the wire format of
+ // a Falcon-only commit is untouched. Empty on every commit the live fleet emits today.
+ private final List<SchemeSeal> extraSeals;
/**
- * Instantiates a new Commit payload.
+ * Instantiates a new Commit payload (no Falcon seal).
*
* @param roundIdentifier the round identifier
* @param digest the digest
@@ -44,26 +76,197 @@ public class CommitPayload extends QbftPayload {
final ConsensusRoundIdentifier roundIdentifier,
final Hash digest,
final SECPSignature commitSeal) {
+ this(roundIdentifier, digest, commitSeal, Optional.empty());
+ }
+
+ /**
+ * Instantiates a new Commit payload with an optional parallel Falcon-512 seal.
+ *
+ * @param roundIdentifier the round identifier
+ * @param digest the digest
+ * @param commitSeal the ECDSA commit seal (decisive)
+ * @param falconSeal the optional parallel post-quantum Falcon seal over the same commit hash
+ */
+ public CommitPayload(
+ final ConsensusRoundIdentifier roundIdentifier,
+ final Hash digest,
+ final SECPSignature commitSeal,
+ final Optional<FalconSeal> falconSeal) {
+ this(roundIdentifier, digest, commitSeal, falconSeal, List.of());
+ }
+
+ /**
+ * Instantiates a new Commit payload carrying a HYBRID post-quantum certificate.
+ *
+ * <p>AERE HIBRID (2026-08-25), the founder's step two of 2026-08-07. A hybrid certificate is
+ * Falcon-512 PLUS a second, structurally unrelated scheme (SLH-DSA/SPHINCS+): if lattices fall
+ * the hash-based one holds, and the reverse. Falcon stays in the legacy slot and the OTHER
+ * schemes travel here, so:
+ *
+ * <ul>
+ * <li>a Falcon-only commit encodes byte-for-byte as it does on the live fleet today, which is
+ * the condition for warming this binary without a coordinated flag day;
+ * <li>the two positions are unambiguous by COUNT (0 trailing elements = no PQ, 1 = Falcon
+ * only, 2 = Falcon + extras), so no clever structural sniffing is needed in a consensus
+ * decoder, where cleverness is how D-235-class mistakes are made;
+ * <li>a signature has exactly ONE home, so the two slots can never disagree about Falcon.
+ * </ul>
+ *
+ * <p>The extras are encoded with {@link PqAnchorV2}, the same scheme-tagged codec the V2 anchor
+ * certificate uses: one vocabulary, one canonicality discipline, one place to get it wrong.
+ *
+ * <p>ADDING THIS ELEMENT IS A CONSENSUS BREAKING CHANGE, exactly as {@link #readFrom(RLPInput)}
+ * warns: an older binary cannot parse a commit that carries it. What protects the fleet is not
+ * leniency, which cannot work, but the EMISSION gate: nothing emits extras until every peer can
+ * read them. Same discipline as the Falcon attachment gate.
+ *
+ * @param roundIdentifier the round identifier
+ * @param digest the digest
+ * @param commitSeal the ECDSA commit seal (decisive)
+ * @param falconSeal the Falcon seal; REQUIRED whenever extras are present
+ * @param extraSeals the non-Falcon scheme seals; empty for every commit on the fleet today
+ */
+ public CommitPayload(
+ final ConsensusRoundIdentifier roundIdentifier,
+ final Hash digest,
+ final SECPSignature commitSeal,
+ final Optional<FalconSeal> falconSeal,
+ final List<SchemeSeal> extraSeals) {
this.roundIdentifier = roundIdentifier;
this.digest = digest;
this.commitSeal = commitSeal;
+ this.falconSeal = falconSeal == null ? Optional.empty() : falconSeal;
+ this.extraSeals = extraSeals == null ? List.of() : List.copyOf(extraSeals);
+ if (!this.extraSeals.isEmpty()) {
+ // The wire format cannot even REPRESENT extras without a Falcon seal, because the slots are
+ // told apart by count. Refusing here means an object that could not be written correctly
+ // cannot be built at all, instead of failing later at encode time on the consensus path.
+ if (this.falconSeal.isEmpty()) {
+ throw new IllegalArgumentException(
+ "AERE HIBRID: extra scheme seals require the Falcon seal to be present");
+ }
+ for (final SchemeSeal seal : this.extraSeals) {
+ if (seal.getSchemeWireId() == SealSchemes.FALCON_512.wireId()) {
+ throw new IllegalArgumentException(
+ "AERE HIBRID: Falcon belongs in its own slot, not in the extras");
+ }
+ }
+ // Validates canonicality and the seal cap NOW, so a payload that cannot be encoded cannot
+ // exist. PqAnchorV2.encode throws on a non-canonical or oversized certificate.
+ final Bytes unused = PqAnchorV2.encode(this.extraSeals);
+ if (unused.isEmpty()) {
+ throw new IllegalArgumentException("AERE HIBRID: empty encoding of a non-empty certificate");
+ }
+ }
}
/**
* Read from rlp input and return commit payload.
*
+ * <p>AERE FIX-MALEABILITATE: this decoder is STRICTLY CANONICAL. The payload is taken as an
+ * isolated RLP item, decoded, re-encoded, and the re-encoding must reproduce the received bytes
+ * exactly. Anything else is rejected.
+ *
+ * <p>Why canonical and not forward-tolerant. A Commit is an AUTHENTICATED consensus message:
+ * {@code SignedData.create} recovers the author from {@link QbftPayload#hashForSignature()},
+ * which is computed from the RE-ENCODED payload, not from the bytes that arrived. Any input the
+ * decoder silently ignores therefore does not change the recovered author, so one genuine Commit
+ * can be rewritten into several distinct byte strings that all still authenticate to the original
+ * validator. QBFT itself is not fooled, because it deduplicates Commits by AUTHOR, so no vote can
+ * be forged, stolen or double counted. The gossip layer is, because it deduplicates by message
+ * CONTENT. Tolerating ignorable input is therefore purely a message amplification channel into
+ * consensus, and it buys nothing in return, for the reason in the next paragraph.
+ *
+ * <p>What forward tolerance does NOT buy, stated correctly. An earlier version of this method
+ * ended both lists with {@code leaveListLenient()} and claimed that this generation of nodes
+ * "can never be made to discard a Commit by a newer peer". That claim was FALSE. Consider a
+ * future binary that appends a MEANINGFUL element to this payload: it signs over ITS OWN
+ * encoding, which includes that element. This binary would skip the element, re-encode WITHOUT
+ * it, obtain a different {@code hashForSignature}, ecrecover a different address, and drop the
+ * Commit anyway, as coming from a non-validator. Leniency only moves the discard from RLP
+ * decoding to author validation; it does not prevent it. The only thing that actually lets an old
+ * binary keep accepting a new peer's Commits is for the new peer NOT to change the signed bytes,
+ * which is exactly what the attachment gate in {@code FalconSealSupport} enforces.
+ *
+ * <p>Consequence for future format changes: adding any element to this payload is a CONSENSUS
+ * BREAKING change and must be rolled out behind a height gate, never by relying on old nodes to
+ * ignore it.
+ *
* @param rlpInput the rlp input
* @return the commit payload
+ * @throws RLPException if the received bytes are not the unique canonical encoding of the payload
*/
public static CommitPayload readFrom(final RLPInput rlpInput) {
- rlpInput.enterList();
- final ConsensusRoundIdentifier roundIdentifier = readConsensusRound(rlpInput);
- final Hash digest = Payload.readDigest(rlpInput);
+ // Take the payload as a self-contained RLP item so the EXACT bytes received for it are
+ // available for the canonicality check below. This also advances the enclosing input past the
+ // payload, exactly as the previous enterList/leaveList pair did.
+ final RLPInput payloadRlp = rlpInput.readAsRlp();
+ final Bytes received = payloadRlp.raw();
+
+ payloadRlp.enterList();
+ final ConsensusRoundIdentifier roundIdentifier = readConsensusRound(payloadRlp);
+ final Hash digest = Payload.readDigest(payloadRlp);
final SECPSignature commitSeal =
- rlpInput.readBytes(SignatureAlgorithmFactory.getInstance()::decodeSignature);
- rlpInput.leaveList();
+ payloadRlp.readBytes(SignatureAlgorithmFactory.getInstance()::decodeSignature);
+
+ // AERE hybrid PQC: an OPTIONAL parallel Falcon-512 seal [index, sig] may follow the ECDSA seal.
+ // A Falcon-less commit ends the list here and decodes to Optional.empty().
+ Optional<FalconSeal> falconSeal = Optional.empty();
+ if (!payloadRlp.isEndOfCurrentList()) {
+ payloadRlp.enterList();
+ final int idx = payloadRlp.readIntScalar();
+ final Bytes sig = payloadRlp.readBytes();
+ payloadRlp.leaveList();
+ falconSeal = Optional.of(new FalconSeal(idx, sig));
+ }
+
+ // AERE HIBRID: a SECOND optional element, the non-Falcon scheme seals. Unambiguous by count:
+ // it can only be here if the Falcon element above was already consumed, so the two slots can
+ // never be confused for one another and no structural sniffing is required.
+ List<SchemeSeal> extraSeals = List.of();
+ if (!payloadRlp.isEndOfCurrentList()) {
+ final Bytes extrasRaw = payloadRlp.readAsRlp().raw();
+ try {
+ extraSeals = PqAnchorV2.decode(extrasRaw);
+ } catch (final RuntimeException e) {
+ // A malformed certificate is a malformed MESSAGE. It must surface as an RLP failure so the
+ // gossip layer drops it like any other undecodable commit, never as an unchecked throw on
+ // the consensus path.
+ throw new RLPException("AERE HIBRID: undecodable extra certificate: " + e.getMessage());
+ }
+ if (extraSeals.isEmpty()) {
+ // An empty extras element and an absent one would be two encodings of the same value.
+ throw new RLPException("AERE HIBRID: empty extra certificate must be absent, not empty");
+ }
+ }
+ payloadRlp.leaveList();
+
+ final CommitPayload payload;
+ try {
+ payload =
+ new CommitPayload(roundIdentifier, digest, commitSeal, falconSeal, extraSeals);
+ } catch (final IllegalArgumentException e) {
+ // The constructor's invariants (Falcon not in the extras, extras imply Falcon) are part of
+ // what a valid message is, so a violation is a decode failure, not a crash.
+ throw new RLPException("AERE HIBRID: " + e.getMessage());
+ }
- return new CommitPayload(roundIdentifier, digest, commitSeal);
+ // AERE FIX-MALEABILITATE: exactly one encoding is accepted for a given payload value. This
+ // catches everything the RLP reader itself would tolerate, including any element the decode
+ // path above does not consume, and any encoding difference the reader does not consider an
+ // error. Cheap: one re-encode of a message that is already about to be keccak hashed for
+ // signature recovery.
+ final Bytes reencoded = payload.encoded();
+ if (!reencoded.equals(received)) {
+ throw new RLPException(
+ "Non-canonical Commit payload encoding: received "
+ + received.size()
+ + " bytes, canonical form is "
+ + reencoded.size()
+ + " bytes");
+ }
+
+ return payload;
}
@Override
@@ -72,6 +275,23 @@ public class CommitPayload extends QbftPayload {
writeConsensusRound(rlpOutput);
rlpOutput.writeBytes(digest.getBytes());
rlpOutput.writeBytes(commitSeal.encodedBytes());
+ // AERE hybrid PQC: append the parallel Falcon seal only when present, so a Falcon-less commit is
+ // byte-identical to upstream Besu. The author's ECDSA signature covers this element.
+ // This method defines THE canonical encoding: readFrom rejects anything that does not
+ // reproduce byte for byte what this method writes.
+ if (falconSeal.isPresent()) {
+ final FalconSeal fs = falconSeal.get();
+ rlpOutput.startList();
+ rlpOutput.writeIntScalar(fs.getValidatorIndex());
+ rlpOutput.writeBytes(fs.getSignature());
+ rlpOutput.endList();
+ }
+ // AERE HIBRID: the extras, only when there are any. Absent extras leave the encoding of a
+ // Falcon-only commit byte-for-byte as it is on the live fleet today, which is locked by a
+ // golden vector in CommitPayloadHybridTest.
+ if (!extraSeals.isEmpty()) {
+ rlpOutput.writeRaw(PqAnchorV2.encode(extraSeals));
+ }
rlpOutput.endList();
}
@@ -98,6 +318,24 @@ public class CommitPayload extends QbftPayload {
return commitSeal;
}
+ /**
+ * Gets the optional parallel post-quantum Falcon seal.
+ *
+ * @return the Falcon seal if this commit carried one, otherwise empty
+ */
+ public Optional<FalconSeal> getFalconSeal() {
+ return falconSeal;
+ }
+
+ /**
+ * Gets the non-Falcon scheme seals of a hybrid certificate.
+ *
+ * @return the extra seals, empty for every commit the live fleet emits today
+ */
+ public List<SchemeSeal> getExtraSeals() {
+ return extraSeals;
+ }
+
@Override
public ConsensusRoundIdentifier getRoundIdentifier() {
return roundIdentifier;
@@ -114,12 +352,14 @@ public class CommitPayload extends QbftPayload {
final CommitPayload that = (CommitPayload) o;
return Objects.equals(roundIdentifier, that.roundIdentifier)
&& Objects.equals(digest, that.digest)
- && Objects.equals(commitSeal, that.commitSeal);
+ && Objects.equals(commitSeal, that.commitSeal)
+ && Objects.equals(falconSeal, that.falconSeal)
+ && Objects.equals(extraSeals, that.extraSeals);
}
@Override
public int hashCode() {
- return Objects.hash(roundIdentifier, digest, commitSeal);
+ return Objects.hash(roundIdentifier, digest, commitSeal, falconSeal, extraSeals);
}
@Override
@@ -128,6 +368,8 @@ public class CommitPayload extends QbftPayload {
.add("roundIdentifier=" + roundIdentifier)
.add("digest=" + digest)
.add("commitSeal=" + commitSeal)
+ .add("falconSeal=" + falconSeal)
+ .add("extraSeals=" + extraSeals.size())
.toString();
}
}
diff --git a/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/payload/MessageFactory.java b/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/payload/MessageFactory.java
index 1bcd73ae9..11426d6a6 100644
--- a/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/payload/MessageFactory.java
+++ b/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/payload/MessageFactory.java
@@ -11,10 +11,17 @@
* specific language governing permissions and limitations under the License.
*
* SPDX-License-Identifier: Apache-2.0
+ *
+ * Modifications Copyright contributors to the Aere Network.
+ *
+ * This file was modified by contributors to the Aere Network, as required by section 4(b) of the
+ * Apache License 2.0. The copyright header above is the upstream one and is left exactly as it was
+ * found, as section 4(c) requires. The change itself is in patches/0003-aere-pq-anchor.patch.
*/
package org.hyperledger.besu.consensus.qbft.core.payload;
import org.hyperledger.besu.consensus.common.bft.ConsensusRoundIdentifier;
+import org.hyperledger.besu.consensus.common.bft.FalconSeal;
import org.hyperledger.besu.consensus.common.bft.payload.Payload;
import org.hyperledger.besu.consensus.common.bft.payload.SignedData;
import org.hyperledger.besu.consensus.qbft.core.messagewrappers.Commit;
@@ -75,6 +82,35 @@ public class MessageFactory {
return new Proposal(createSignedMessage(payload), roundChanges, prepares);
}
+ /**
+ * Create proposal carrying the proposer's optional post-quantum seal (AERE PQ, 2026-08-30).
+ *
+ * <p>The seal rides INSIDE the signed payload, so the proposer's ECDSA signature covers it and
+ * nobody can strip or replace it without failing authorship recovery. With the seal absent this
+ * overload produces byte-for-byte what the upstream overload produces.
+ *
+ * @param roundIdentifier the round identifier
+ * @param block the block
+ * @param blockAccessList the block access list
+ * @param roundChanges the round changes
+ * @param prepares the prepares
+ * @param falconSeal the proposer's post-quantum seal, or empty
+ * @return the proposal
+ */
+ public Proposal createProposal(
+ final ConsensusRoundIdentifier roundIdentifier,
+ final QbftBlock block,
+ final Optional<BlockAccessList> blockAccessList,
+ final List<SignedData<RoundChangePayload>> roundChanges,
+ final List<SignedData<PreparePayload>> prepares,
+ final Optional<FalconSeal> falconSeal) {
+
+ final ProposalPayload payload =
+ new ProposalPayload(roundIdentifier, block, blockEncoder, blockAccessList, falconSeal);
+
+ return new Proposal(createSignedMessage(payload), roundChanges, prepares);
+ }
+
/**
* Create proposal.
*
@@ -100,7 +136,27 @@ public class MessageFactory {
* @return the prepare
*/
public Prepare createPrepare(final ConsensusRoundIdentifier roundIdentifier, final Hash digest) {
- final PreparePayload payload = new PreparePayload(roundIdentifier, digest);
+ return createPrepare(roundIdentifier, digest, Optional.empty());
+ }
+
+ /**
+ * Create a Prepare carrying an OPTIONAL post-quantum seal of its author.
+ *
+ * <p>AERE PQ (2026-08-28), pasul 1: firul poate purta sigiliul, si nimic nu il emite inca -
+ * fiecare apel de azi trece prin varianta fara sigiliu de mai sus. Ca la commit, semnatura ECDSA
+ * a autorului acopera INTREG payload-ul, deci si sigiliul, ceea ce leaga indexul revendicat de
+ * identitatea celui care trimite mesajul.
+ *
+ * @param roundIdentifier the round identifier
+ * @param digest the digest
+ * @param falconSeal the author's post-quantum seal, or empty
+ * @return the prepare
+ */
+ public Prepare createPrepare(
+ final ConsensusRoundIdentifier roundIdentifier,
+ final Hash digest,
+ final Optional<FalconSeal> falconSeal) {
+ final PreparePayload payload = new PreparePayload(roundIdentifier, digest, falconSeal);
return new Prepare(createSignedMessage(payload));
}
@@ -116,7 +172,47 @@ public class MessageFactory {
final ConsensusRoundIdentifier roundIdentifier,
final Hash digest,
final SECPSignature commitSeal) {
- final CommitPayload payload = new CommitPayload(roundIdentifier, digest, commitSeal);
+ return createCommit(roundIdentifier, digest, commitSeal, Optional.empty());
+ }
+
+ /**
+ * Create commit payload carrying an optional parallel Falcon-512 seal. The whole payload
+ * (including the Falcon seal) is signed by this node's ECDSA key.
+ *
+ * @param roundIdentifier the round identifier
+ * @param digest the digest
+ * @param commitSeal the ECDSA commit seal
+ * @param falconSeal the optional parallel post-quantum Falcon seal over the same commit hash
+ * @return the commit
+ */
+ public Commit createCommit(
+ final ConsensusRoundIdentifier roundIdentifier,
+ final Hash digest,
+ final SECPSignature commitSeal,
+ final Optional<FalconSeal> falconSeal) {
+ return createCommit(roundIdentifier, digest, commitSeal, falconSeal, java.util.List.of());
+ }
+
+ /**
+ * Create a commit carrying a HYBRID post-quantum certificate: the Falcon seal in its own slot
+ * plus the other schemes alongside it. The whole payload, extras included, is signed by this
+ * node's ECDSA key, so the extras cannot be added or stripped by anyone else.
+ *
+ * @param roundIdentifier the round identifier
+ * @param digest the digest
+ * @param commitSeal the ECDSA commit seal
+ * @param falconSeal the Falcon seal; required whenever extras are present
+ * @param extraSeals the non-Falcon scheme seals
+ * @return the commit
+ */
+ public Commit createCommit(
+ final ConsensusRoundIdentifier roundIdentifier,
+ final Hash digest,
+ final SECPSignature commitSeal,
+ final Optional<FalconSeal> falconSeal,
+ final java.util.List<org.hyperledger.besu.consensus.common.bft.SchemeSeal> extraSeals) {
+ final CommitPayload payload =
+ new CommitPayload(roundIdentifier, digest, commitSeal, falconSeal, extraSeals);
return new Commit(createSignedMessage(payload));
}
@@ -130,6 +226,25 @@ public class MessageFactory {
public RoundChange createRoundChange(
final ConsensusRoundIdentifier roundIdentifier,
final Optional<PreparedCertificate> preparedRoundData) {
+ return createRoundChange(roundIdentifier, preparedRoundData, Optional.empty());
+ }
+
+ /**
+ * Create round change carrying the author's post-quantum seal. AERE PQ (2026-08-31): the sealed
+ * twin of the method above, exactly as at PREPARE and PROPOSAL. With the gate shut every call of
+ * today goes through the seal-less form, which encodes byte for byte as upstream. The author's
+ * ECDSA signature covers the WHOLE payload, seal included, which binds the claimed index to the
+ * identity of the sender.
+ *
+ * @param roundIdentifier the round identifier
+ * @param preparedRoundData the prepared round data
+ * @param falconSeal the author's post-quantum seal, or empty
+ * @return the round change
+ */
+ public RoundChange createRoundChange(
+ final ConsensusRoundIdentifier roundIdentifier,
+ final Optional<PreparedCertificate> preparedRoundData,
+ final Optional<FalconSeal> falconSeal) {
final RoundChangePayload payload;
if (preparedRoundData.isPresent()) {
@@ -140,7 +255,8 @@ public class MessageFactory {
roundIdentifier,
Optional.of(
new PreparedRoundMetadata(
- preparedBlock.getHash(), preparedRoundData.get().getRound())));
+ preparedBlock.getHash(), preparedRoundData.get().getRound())),
+ falconSeal);
return new RoundChange(
createSignedMessage(payload),
@@ -150,7 +266,7 @@ public class MessageFactory {
preparedRoundData.get().getPrepares());
} else {
- payload = new RoundChangePayload(roundIdentifier, Optional.empty());
+ payload = new RoundChangePayload(roundIdentifier, Optional.empty(), falconSeal);
return new RoundChange(
createSignedMessage(payload),
Optional.empty(),
diff --git a/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/payload/PreparePayload.java b/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/payload/PreparePayload.java
index b9d53d35f..727cbccc8 100644
--- a/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/payload/PreparePayload.java
+++ b/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/payload/PreparePayload.java
@@ -11,48 +11,127 @@
* specific language governing permissions and limitations under the License.
*
* SPDX-License-Identifier: Apache-2.0
+ *
+ * Modifications Copyright contributors to the Aere Network.
+ *
+ * This file was modified by contributors to the Aere Network, as required by section 4(b) of the
+ * Apache License 2.0. The copyright header above is the upstream one and is left exactly as it was
+ * found, as section 4(c) requires. The change itself is in patches/0003-aere-pq-anchor.patch.
*/
package org.hyperledger.besu.consensus.qbft.core.payload;
import org.hyperledger.besu.consensus.common.bft.ConsensusRoundIdentifier;
+import org.hyperledger.besu.consensus.common.bft.FalconSeal;
import org.hyperledger.besu.consensus.common.bft.payload.Payload;
import org.hyperledger.besu.consensus.qbft.core.messagedata.QbftV1;
import org.hyperledger.besu.datatypes.Hash;
+import org.hyperledger.besu.ethereum.rlp.RLPException;
import org.hyperledger.besu.ethereum.rlp.RLPInput;
import org.hyperledger.besu.ethereum.rlp.RLPOutput;
import java.util.Objects;
+import java.util.Optional;
import java.util.StringJoiner;
-/** The Prepare payload. */
+import org.apache.tuweni.bytes.Bytes;
+
+/**
+ * The Prepare payload.
+ *
+ * <p>AERE PQ (2026-08-28), step 1 of PREPARE-SI-ROUNDCHANGE-SUB-PQ-PROIECTARE-2026-08-28: a PREPARE
+ * MAY carry an OPTIONAL Falcon-512 seal from its author, appended at the end, exactly as
+ * {@code CommitPayload} does. A PREPARE without a seal encodes <b>byte for byte as upstream</b>,
+ * and that is precisely the property that lets the binary be rolled onto a live fleet without a
+ * flag day.
+ *
+ * <p><b>NOTHING EMITS SUCH A PREPARE YET.</b> This file only makes the wire capable of carrying one
+ * and of refusing a malformed one. Emission is the next step and has its own gate, following the
+ * rule paid for at commit: first the binary everywhere, then emission, and only much later
+ * enforcement.
+ *
+ * <p><b>What the seal signs is NOT this file's business</b>, and the design note states it: its own
+ * domain {@code AERE-PQ-PREPARE-1} over (chainId, number, ROUND, digest). If it signed the same
+ * bytes as a commit seal, a PREPARE seal given honestly could be pasted onto a forged COMMIT and
+ * the enforcement there would accept it.
+ */
public class PreparePayload extends QbftPayload {
private static final int TYPE = QbftV1.PREPARE;
private final ConsensusRoundIdentifier roundIdentifier;
private final Hash digest;
+ private final Optional<FalconSeal> falconSeal;
/**
- * Instantiates a new Prepare payload.
+ * Instantiates a new Prepare payload, without a post-quantum seal. Encodes byte-for-byte as
+ * upstream Besu.
*
* @param roundIdentifier the round identifier
* @param digest the digest
*/
public PreparePayload(final ConsensusRoundIdentifier roundIdentifier, final Hash digest) {
+ this(roundIdentifier, digest, Optional.empty());
+ }
+
+ /**
+ * Instantiates a new Prepare payload carrying an optional Falcon-512 seal of its author.
+ *
+ * @param roundIdentifier the round identifier
+ * @param digest the digest
+ * @param falconSeal the author's post-quantum seal, or empty
+ */
+ public PreparePayload(
+ final ConsensusRoundIdentifier roundIdentifier,
+ final Hash digest,
+ final Optional<FalconSeal> falconSeal) {
this.roundIdentifier = roundIdentifier;
this.digest = digest;
+ this.falconSeal = falconSeal == null ? Optional.empty() : falconSeal;
}
/**
* Read from rlp input and return prepare payload.
*
+ * <p>STRICTLY CANONICAL, as in {@code CommitPayload} and for the same reason: a PREPARE is an
+ * AUTHENTICATED message, and the author is recovered from the RE-ENCODED payload, not from the
+ * bytes that arrived. Anything the decoder tolerated silently would give several byte strings that
+ * authenticate to the same validator - that is malleability. Decode, re-encode, and the result
+ * must be exactly what came in.
+ *
* @param rlpInput the rlp input
* @return the prepare payload
+ * @throws RLPException if the received bytes are not the payload's unique canonical encoding
*/
public static PreparePayload readFrom(final RLPInput rlpInput) {
- rlpInput.enterList();
- final ConsensusRoundIdentifier roundIdentifier = readConsensusRound(rlpInput);
- final Hash digest = Payload.readDigest(rlpInput);
- rlpInput.leaveList();
- return new PreparePayload(roundIdentifier, digest);
+ final RLPInput payloadRlp = rlpInput.readAsRlp();
+ final Bytes received = payloadRlp.raw();
+
+ payloadRlp.enterList();
+ final ConsensusRoundIdentifier roundIdentifier = readConsensusRound(payloadRlp);
+ final Hash digest = Payload.readDigest(payloadRlp);
+
+ // AERE PQ: the OPTIONAL seal [index, signature]. A PREPARE without one ends the list here and
+ // decodes to Optional.empty(), so it stays identical to upstream.
+ Optional<FalconSeal> falconSeal = Optional.empty();
+ if (!payloadRlp.isEndOfCurrentList()) {
+ payloadRlp.enterList();
+ final int idx = payloadRlp.readIntScalar();
+ final Bytes sig = payloadRlp.readBytes();
+ payloadRlp.leaveList();
+ falconSeal = Optional.of(new FalconSeal(idx, sig));
+ }
+ payloadRlp.leaveList();
+
+ final PreparePayload payload = new PreparePayload(roundIdentifier, digest, falconSeal);
+
+ final Bytes reencoded = payload.encoded();
+ if (!reencoded.equals(received)) {
+ throw new RLPException(
+ "Non-canonical Prepare payload encoding: received "
+ + received.size()
+ + " bytes, canonical form is "
+ + reencoded.size()
+ + " bytes");
+ }
+ return payload;
}
@Override
@@ -60,6 +139,16 @@ public class PreparePayload extends QbftPayload {
rlpOutput.startList();
writeConsensusRound(rlpOutput);
rlpOutput.writeBytes(digest.getBytes());
+ // This method DEFINES the canonical encoding: readFrom refuses anything that does not reproduce
+ // it byte for byte. The seal is written only when present, so a seal-less PREPARE is identical
+ // to upstream.
+ if (falconSeal.isPresent()) {
+ final FalconSeal fs = falconSeal.get();
+ rlpOutput.startList();
+ rlpOutput.writeIntScalar(fs.getValidatorIndex());
+ rlpOutput.writeBytes(fs.getSignature());
+ rlpOutput.endList();
+ }
rlpOutput.endList();
}
@@ -77,6 +166,15 @@ public class PreparePayload extends QbftPayload {
return digest;
}
+ /**
+ * The author's post-quantum seal, when the message carries one.
+ *
+ * @return the seal, or empty
+ */
+ public Optional<FalconSeal> getFalconSeal() {
+ return falconSeal;
+ }
+
@Override
public ConsensusRoundIdentifier getRoundIdentifier() {
return roundIdentifier;
@@ -92,12 +190,13 @@ public class PreparePayload extends QbftPayload {
}
final PreparePayload that = (PreparePayload) o;
return Objects.equals(roundIdentifier, that.roundIdentifier)
- && Objects.equals(digest, that.digest);
+ && Objects.equals(digest, that.digest)
+ && Objects.equals(falconSeal, that.falconSeal);
}
@Override
public int hashCode() {
- return Objects.hash(roundIdentifier, digest);
+ return Objects.hash(roundIdentifier, digest, falconSeal);
}
@Override
@@ -105,6 +204,7 @@ public class PreparePayload extends QbftPayload {
return new StringJoiner(", ", PreparePayload.class.getSimpleName() + "[", "]")
.add("roundIdentifier=" + roundIdentifier)
.add("digest=" + digest)
+ .add("falconSeal=" + (falconSeal.isPresent() ? "present" : "absent"))
.toString();
}
}
diff --git a/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/payload/ProposalPayload.java b/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/payload/ProposalPayload.java
index eb1a2246c..813e798a9 100644
--- a/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/payload/ProposalPayload.java
+++ b/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/payload/ProposalPayload.java
@@ -11,15 +11,23 @@
* specific language governing permissions and limitations under the License.
*
* SPDX-License-Identifier: Apache-2.0
+ *
+ * Modifications Copyright contributors to the Aere Network.
+ *
+ * This file was modified by contributors to the Aere Network, as required by section 4(b) of the
+ * Apache License 2.0. The copyright header above is the upstream one and is left exactly as it was
+ * found, as section 4(c) requires. The change itself is in patches/0003-aere-pq-anchor.patch.
*/
package org.hyperledger.besu.consensus.qbft.core.payload;
import org.hyperledger.besu.consensus.common.bft.ConsensusRoundIdentifier;
+import org.hyperledger.besu.consensus.common.bft.FalconSeal;
import org.hyperledger.besu.consensus.qbft.core.messagedata.QbftV1;
import org.hyperledger.besu.consensus.qbft.core.types.QbftBlock;
import org.hyperledger.besu.consensus.qbft.core.types.QbftBlockCodec;
import org.hyperledger.besu.ethereum.core.encoding.BlockAccessListDecoder;
import org.hyperledger.besu.ethereum.mainnet.block.access.list.BlockAccessList;
+import org.hyperledger.besu.ethereum.rlp.RLPException;
import org.hyperledger.besu.ethereum.rlp.RLPInput;
import org.hyperledger.besu.ethereum.rlp.RLPOutput;
@@ -28,7 +36,33 @@ import java.util.Optional;
import com.google.common.base.MoreObjects;
-/** The Proposal payload. */
+/**
+ * The Proposal payload.
+ *
+ * <p>AERE PQ (2026-08-30), the hot-path step after PREPARE: a PROPOSAL MAY carry an OPTIONAL
+ * Falcon-512 seal from its proposer, appended after the block-access-list element, exactly as
+ * {@code PreparePayload} appends its seal. A proposal without a seal encodes <b>byte for byte as
+ * upstream</b>, which is the property that lets the binary be rolled onto a live fleet without a
+ * flag day.
+ *
+ * <p><b>NOTHING EMITS SUCH A PROPOSAL YET.</b> This file only makes the wire capable of carrying
+ * one and of refusing a malformed one. Emission has its own gate
+ * ({@code aere.pq.proposalPq.attachBlock}); enforcement has its own height
+ * ({@code aere.pq.proposalPq.forkBlock}); both are absent on every node today, and absent means
+ * never.
+ *
+ * <p><b>What the seal signs is NOT this file's business:</b> its own domain
+ * {@code AERE-PQ-PROPOSAL-1} over (chainId, height, ROUND, digest) - see
+ * {@code PqAnchor.proposalMessage}. A proposal is an offer, not a vote: with the commit or PREPARE
+ * domain, a proposal seal given honestly could be pasted onto a forged vote and counted.
+ *
+ * <p><b>Why the trailing element is parsed strictly:</b> the payload is AUTHENTICATED - the author
+ * is recovered from the signature over the encoded payload. A decoder that silently ignored an
+ * unknown trailing element would re-encode without it, so two different byte strings would
+ * authenticate to the same proposer. When a fifth element is present it must be exactly a seal,
+ * and it must be the last element; otherwise the message is refused. Messages of the upstream
+ * shapes (three or four elements) are read exactly as upstream reads them.
+ */
public class ProposalPayload extends QbftPayload {
private static final int TYPE = QbftV1.PROPOSAL;
@@ -36,24 +70,45 @@ public class ProposalPayload extends QbftPayload {
private final QbftBlock proposedBlock;
private final QbftBlockCodec blockEncoder;
private final Optional<BlockAccessList> blockAccessList;
+ private final Optional<FalconSeal> falconSeal;
/**
- * Instantiates a new Proposal payload.
+ * Instantiates a new Proposal payload carrying an optional post-quantum seal of its proposer.
*
* @param roundIdentifier the round identifier
* @param proposedBlock the proposed block
* @param blockEncoder the qbft block encoder
* @param blockAccessList the block access list
+ * @param falconSeal the proposer's post-quantum seal, or empty
*/
public ProposalPayload(
final ConsensusRoundIdentifier roundIdentifier,
final QbftBlock proposedBlock,
final QbftBlockCodec blockEncoder,
- final Optional<BlockAccessList> blockAccessList) {
+ final Optional<BlockAccessList> blockAccessList,
+ final Optional<FalconSeal> falconSeal) {
this.roundIdentifier = roundIdentifier;
this.proposedBlock = proposedBlock;
this.blockEncoder = blockEncoder;
this.blockAccessList = blockAccessList;
+ this.falconSeal = falconSeal == null ? Optional.empty() : falconSeal;
+ }
+
+ /**
+ * Instantiates a new Proposal payload, without a post-quantum seal. Encodes byte-for-byte as
+ * upstream Besu.
+ *
+ * @param roundIdentifier the round identifier
+ * @param proposedBlock the proposed block
+ * @param blockEncoder the qbft block encoder
+ * @param blockAccessList the block access list
+ */
+ public ProposalPayload(
+ final ConsensusRoundIdentifier roundIdentifier,
+ final QbftBlock proposedBlock,
+ final QbftBlockCodec blockEncoder,
+ final Optional<BlockAccessList> blockAccessList) {
+ this(roundIdentifier, proposedBlock, blockEncoder, blockAccessList, Optional.empty());
}
/**
@@ -67,7 +122,7 @@ public class ProposalPayload extends QbftPayload {
final ConsensusRoundIdentifier roundIdentifier,
final QbftBlock proposedBlock,
final QbftBlockCodec blockEncoder) {
- this(roundIdentifier, proposedBlock, blockEncoder, Optional.empty());
+ this(roundIdentifier, proposedBlock, blockEncoder, Optional.empty(), Optional.empty());
}
/**
@@ -83,9 +138,28 @@ public class ProposalPayload extends QbftPayload {
final ConsensusRoundIdentifier roundIdentifier = readConsensusRound(rlpInput);
final QbftBlock proposedBlock = blockEncoder.readFrom(rlpInput);
final Optional<BlockAccessList> blockAccessList = readBlockAccessList(rlpInput);
+
+ // AERE PQ: the OPTIONAL proposer seal [index, signature]. A proposal without one ends the list
+ // here and decodes to Optional.empty(), so the upstream shapes stay untouched. When a fifth
+ // element exists it must be a seal and it must be last: an unknown trailing element on an
+ // authenticated payload is malleability, not extensibility.
+ Optional<FalconSeal> falconSeal = Optional.empty();
+ if (!rlpInput.isEndOfCurrentList()) {
+ rlpInput.enterList();
+ final int idx = rlpInput.readIntScalar();
+ final org.apache.tuweni.bytes.Bytes sig = rlpInput.readBytes();
+ rlpInput.leaveList();
+ falconSeal = Optional.of(new FalconSeal(idx, sig));
+ if (!rlpInput.isEndOfCurrentList()) {
+ throw new RLPException(
+ "Proposal payload carries elements after the proposer seal; refusing an encoding the "
+ + "re-encoder would silently drop");
+ }
+ }
rlpInput.leaveList();
- return new ProposalPayload(roundIdentifier, proposedBlock, blockEncoder, blockAccessList);
+ return new ProposalPayload(
+ roundIdentifier, proposedBlock, blockEncoder, blockAccessList, falconSeal);
}
@Override
@@ -94,6 +168,14 @@ public class ProposalPayload extends QbftPayload {
writeConsensusRound(rlpOutput);
blockEncoder.writeTo(proposedBlock, rlpOutput);
blockAccessList.ifPresentOrElse((bal) -> bal.writeTo(rlpOutput), rlpOutput::writeNull);
+ // The seal is written only when present, so a seal-less proposal is identical to upstream.
+ if (falconSeal.isPresent()) {
+ final FalconSeal fs = falconSeal.get();
+ rlpOutput.startList();
+ rlpOutput.writeIntScalar(fs.getValidatorIndex());
+ rlpOutput.writeBytes(fs.getSignature());
+ rlpOutput.endList();
+ }
rlpOutput.endList();
}
@@ -115,6 +197,15 @@ public class ProposalPayload extends QbftPayload {
return blockAccessList;
}
+ /**
+ * The proposer's post-quantum seal, when the message carries one.
+ *
+ * @return the seal, or empty
+ */
+ public Optional<FalconSeal> getFalconSeal() {
+ return falconSeal;
+ }
+
@Override
public int getMessageType() {
return TYPE;
@@ -136,12 +227,13 @@ public class ProposalPayload extends QbftPayload {
ProposalPayload that = (ProposalPayload) o;
return Objects.equals(roundIdentifier, that.roundIdentifier)
&& Objects.equals(proposedBlock, that.proposedBlock)
- && Objects.equals(blockAccessList, that.blockAccessList);
+ && Objects.equals(blockAccessList, that.blockAccessList)
+ && Objects.equals(falconSeal, that.falconSeal);
}
@Override
public int hashCode() {
- return Objects.hash(roundIdentifier, proposedBlock, blockAccessList);
+ return Objects.hash(roundIdentifier, proposedBlock, blockAccessList, falconSeal);
}
@Override
@@ -150,6 +242,7 @@ public class ProposalPayload extends QbftPayload {
.add("roundIdentifier", roundIdentifier)
.add("proposedBlock", proposedBlock)
.add("blockAccessList", blockAccessList)
+ .add("falconSeal", falconSeal.isPresent() ? "present" : "absent")
.toString();
}
diff --git a/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/payload/RoundChangePayload.java b/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/payload/RoundChangePayload.java
index 9f4d9abed..8804b6a46 100644
--- a/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/payload/RoundChangePayload.java
+++ b/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/payload/RoundChangePayload.java
@@ -11,11 +11,19 @@
* specific language governing permissions and limitations under the License.
*
* SPDX-License-Identifier: Apache-2.0
+ *
+ * Modifications Copyright contributors to the Aere Network.
+ *
+ * This file was modified by contributors to the Aere Network, as required by section 4(b) of the
+ * Apache License 2.0. The copyright header above is the upstream one and is left exactly as it was
+ * found, as section 4(c) requires. The change itself is in patches/0003-aere-pq-anchor.patch.
*/
package org.hyperledger.besu.consensus.qbft.core.payload;
import org.hyperledger.besu.consensus.common.bft.ConsensusRoundIdentifier;
+import org.hyperledger.besu.consensus.common.bft.FalconSeal;
import org.hyperledger.besu.consensus.qbft.core.messagedata.QbftV1;
+import org.hyperledger.besu.ethereum.rlp.RLPException;
import org.hyperledger.besu.ethereum.rlp.RLPInput;
import org.hyperledger.besu.ethereum.rlp.RLPOutput;
@@ -24,23 +32,68 @@ import java.util.Optional;
import com.google.common.base.MoreObjects;
-/** The Round change payload. */
+/**
+ * The Round change payload.
+ *
+ * <p>AERE PQ (2026-08-31), the LAST hot-path message: a ROUND-CHANGE MAY carry an OPTIONAL
+ * Falcon-512 seal from its author, appended after the prepared-metadata list, exactly as {@code
+ * ProposalPayload} appends its seal. A round-change without a seal encodes <b>byte for byte as
+ * upstream</b>, which is the property that lets the binary be rolled onto a live fleet without a
+ * flag day.
+ *
+ * <p><b>NOTHING EMITS SUCH A ROUND-CHANGE YET.</b> This file only makes the wire capable of
+ * carrying one and of refusing a malformed one. Emission has its own gate
+ * ({@code aere.pq.roundChangePq.attachBlock}); enforcement has its own height
+ * ({@code aere.pq.roundChangePq.forkBlock}); both are absent on every node today, and absent means
+ * never.
+ *
+ * <p><b>What the seal signs is NOT this file's business:</b> its own domain
+ * {@code AERE-PQ-ROUNDCHANGE-1} over (chainId, height, targetRound, prepared metadata) - see
+ * {@code PqAnchor.roundChangeMessage}. A round-change STEERS rounds: a quorum of them opens a new
+ * round, and one claiming a prepared block decides which block gets re-proposed. Its seal must be
+ * transferable neither onto a vote nor onto a proposal, nor between a bare round-change and one
+ * with metadata.
+ *
+ * <p><b>Why the trailing element is parsed strictly:</b> the payload is AUTHENTICATED - the author
+ * is recovered from the signature over the encoded payload. A decoder that silently ignored an
+ * unknown trailing element would re-encode without it, so two different byte strings would
+ * authenticate to the same author. When a fourth element is present it must be exactly a seal, and
+ * it must be the last element; otherwise the message is refused. Messages of the upstream shape
+ * (three elements) are read exactly as upstream reads them.
+ */
public class RoundChangePayload extends QbftPayload {
private static final int TYPE = QbftV1.ROUND_CHANGE;
private final ConsensusRoundIdentifier roundChangeIdentifier;
private final Optional<PreparedRoundMetadata> preparedRoundMetadata;
+ private final Optional<FalconSeal> falconSeal;
/**
- * Instantiates a new Round change payload.
+ * Instantiates a new Round change payload carrying an optional post-quantum seal of its author.
*
* @param roundChangeIdentifier the round change identifier
* @param preparedRoundMetadata the prepared round metadata
+ * @param falconSeal the author's post-quantum seal, or empty
*/
public RoundChangePayload(
final ConsensusRoundIdentifier roundChangeIdentifier,
- final Optional<PreparedRoundMetadata> preparedRoundMetadata) {
+ final Optional<PreparedRoundMetadata> preparedRoundMetadata,
+ final Optional<FalconSeal> falconSeal) {
this.roundChangeIdentifier = roundChangeIdentifier;
this.preparedRoundMetadata = preparedRoundMetadata;
+ this.falconSeal = falconSeal == null ? Optional.empty() : falconSeal;
+ }
+
+ /**
+ * Instantiates a new Round change payload, without a post-quantum seal. Encodes byte-for-byte as
+ * upstream Besu.
+ *
+ * @param roundChangeIdentifier the round change identifier
+ * @param preparedRoundMetadata the prepared round metadata
+ */
+ public RoundChangePayload(
+ final ConsensusRoundIdentifier roundChangeIdentifier,
+ final Optional<PreparedRoundMetadata> preparedRoundMetadata) {
+ this(roundChangeIdentifier, preparedRoundMetadata, Optional.empty());
}
@Override
@@ -57,6 +110,15 @@ public class RoundChangePayload extends QbftPayload {
return preparedRoundMetadata;
}
+ /**
+ * The author's post-quantum seal, when the message carries one.
+ *
+ * @return the seal, or empty
+ */
+ public Optional<FalconSeal> getFalconSeal() {
+ return falconSeal;
+ }
+
@Override
public void writeTo(final RLPOutput rlpOutput) {
// RLP encode of the message data content (round identifier and prepared certificate)
@@ -67,6 +129,15 @@ public class RoundChangePayload extends QbftPayload {
preparedRoundMetadata.ifPresent(prm -> prm.writeTo(rlpOutput));
rlpOutput.endList();
+ // The seal is written only when present, so a seal-less round-change is identical to upstream.
+ if (falconSeal.isPresent()) {
+ final FalconSeal fs = falconSeal.get();
+ rlpOutput.startList();
+ rlpOutput.writeIntScalar(fs.getValidatorIndex());
+ rlpOutput.writeBytes(fs.getSignature());
+ rlpOutput.endList();
+ }
+
rlpOutput.endList();
}
@@ -89,8 +160,26 @@ public class RoundChangePayload extends QbftPayload {
}
rlpInput.leaveList();
+ // AERE PQ: the OPTIONAL author seal [index, signature]. A round-change without one ends the
+ // list here and decodes to Optional.empty(), so the upstream shape stays untouched. When a
+ // fourth element exists it must be a seal and it must be last: an unknown trailing element on
+ // an authenticated payload is malleability, not extensibility.
+ Optional<FalconSeal> falconSeal = Optional.empty();
+ if (!rlpInput.isEndOfCurrentList()) {
+ rlpInput.enterList();
+ final int idx = rlpInput.readIntScalar();
+ final org.apache.tuweni.bytes.Bytes sig = rlpInput.readBytes();
+ rlpInput.leaveList();
+ falconSeal = Optional.of(new FalconSeal(idx, sig));
+ if (!rlpInput.isEndOfCurrentList()) {
+ throw new RLPException(
+ "RoundChange payload carries elements after the author seal; refusing an encoding the "
+ + "re-encoder would silently drop");
+ }
+ }
+
rlpInput.leaveList();
- return new RoundChangePayload(roundIdentifier, preparedRoundMetadata);
+ return new RoundChangePayload(roundIdentifier, preparedRoundMetadata, falconSeal);
}
@Override
@@ -108,12 +197,13 @@ public class RoundChangePayload extends QbftPayload {
}
RoundChangePayload that = (RoundChangePayload) o;
return Objects.equals(roundChangeIdentifier, that.roundChangeIdentifier)
- && Objects.equals(preparedRoundMetadata, that.preparedRoundMetadata);
+ && Objects.equals(preparedRoundMetadata, that.preparedRoundMetadata)
+ && Objects.equals(falconSeal, that.falconSeal);
}
@Override
public int hashCode() {
- return Objects.hash(roundChangeIdentifier, preparedRoundMetadata);
+ return Objects.hash(roundChangeIdentifier, preparedRoundMetadata, falconSeal);
}
@Override
@@ -121,6 +211,7 @@ public class RoundChangePayload extends QbftPayload {
return MoreObjects.toStringHelper(this)
.add("roundChangeIdentifier", roundChangeIdentifier)
.add("preparedRoundMetadata", preparedRoundMetadata)
+ .add("falconSeal", falconSeal.isPresent() ? "present" : "absent")
.toString();
}
}
diff --git a/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/statemachine/QbftBlockHeightManager.java b/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/statemachine/QbftBlockHeightManager.java
index 49099c2c1..bc404409c 100644
--- a/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/statemachine/QbftBlockHeightManager.java
+++ b/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/statemachine/QbftBlockHeightManager.java
@@ -11,12 +11,19 @@
* specific language governing permissions and limitations under the License.
*
* SPDX-License-Identifier: Apache-2.0
+ *
+ * Modifications Copyright contributors to the Aere Network.
+ *
+ * This file was modified by contributors to the Aere Network, as required by section 4(b) of the
+ * Apache License 2.0. The copyright header above is the upstream one and is left exactly as it was
+ * found, as section 4(c) requires. The change itself is in patches/0003-aere-pq-anchor.patch.
*/
package org.hyperledger.besu.consensus.qbft.core.statemachine;
import org.hyperledger.besu.consensus.common.bft.ConsensusRoundIdentifier;
import org.hyperledger.besu.consensus.common.bft.events.RoundExpiry;
import org.hyperledger.besu.consensus.common.bft.messagewrappers.BftMessage;
+import org.hyperledger.besu.consensus.common.bft.PqAnchorNotReadyException;
import org.hyperledger.besu.consensus.common.bft.payload.Payload;
import org.hyperledger.besu.consensus.qbft.core.messagewrappers.Commit;
import org.hyperledger.besu.consensus.qbft.core.messagewrappers.Prepare;
@@ -200,8 +207,26 @@ public class QbftBlockHeightManager implements BaseQbftBlockHeightManager {
}
final long headerTimeStampSeconds = Math.round(clock.millis() / 1000D);
- final QbftBlockCreator.BlockCreationResult blockCreationResult =
- qbftRound.createBlock(headerTimeStampSeconds);
+ final QbftBlockCreator.BlockCreationResult blockCreationResult;
+ try {
+ blockCreationResult = qbftRound.createBlock(headerTimeStampSeconds);
+ } catch (final RuntimeException thrown) {
+ // MEASURED 2026-08-02: see PqAnchorNotReadyException.findIn. The refusal arrives wrapped in
+ // IllegalStateException from AbstractBlockCreator, so the narrow catch never fired. Anything
+ // that is not a refusal is rethrown untouched.
+ final PqAnchorNotReadyException e = PqAnchorNotReadyException.findIn(thrown);
+ if (e == null) {
+ throw thrown;
+ }
+ // AERE ANCHOR V2: this node is the proposer but cannot back the block with a Falcon quorum
+ // certificate that reaches the staged threshold K, so it does NOT propose. The round times
+ // out and the next proposer takes over. Proposing anyway would emit a header this node has
+ // already computed to be invalid under its own rules, and in QBFT it would cost exactly the
+ // same round timer, so it would buy nothing. The usual cause is a node that has just
+ // restarted and holds no seals until it takes part in one commit: at most one lost turn.
+ LOG.warn("AERE PQ-ANCHOR: not proposing. round={}. {}", roundIdentifier, e.getMessage());
+ return;
+ }
final QbftBlock block = blockCreationResult.block();
final Optional<BlockAccessList> blockAccessList = blockCreationResult.blockAccessList();
if (!block.isEmpty()) {
@@ -304,10 +329,16 @@ public class QbftBlockHeightManager implements BaseQbftBlockHeightManager {
}
QbftRound qbftRoundNew = currentRound.get();
+ RoundChange localRoundChange = null;
try {
- final RoundChange localRoundChange =
- messageFactory.createRoundChange(
- qbftRoundNew.getRoundIdentifier(), latestPreparedCertificate);
+ final Optional<org.hyperledger.besu.consensus.common.bft.FalconSeal> roundChangeSeal =
+ roundChangeSealFor(qbftRoundNew.getRoundIdentifier(), latestPreparedCertificate);
+ localRoundChange =
+ roundChangeSeal.isPresent()
+ ? messageFactory.createRoundChange(
+ qbftRoundNew.getRoundIdentifier(), latestPreparedCertificate, roundChangeSeal)
+ : messageFactory.createRoundChange(
+ qbftRoundNew.getRoundIdentifier(), latestPreparedCertificate);
// Its possible the locally created RoundChange triggers the transmission of a NewRound
// message - so it must be handled accordingly.
@@ -316,7 +347,45 @@ public class QbftBlockHeightManager implements BaseQbftBlockHeightManager {
LOG.warn("Failed to create signed RoundChange message.", e);
}
- transmitter.multicastRoundChange(qbftRoundNew.getRoundIdentifier(), latestPreparedCertificate);
+ // THE SAME seal object goes on the wire. The transmitter re-creates the round-change, so
+ // without this the local copy would be sealed and the wire copy not - the exact defect F84
+ // measured on the PROPOSAL. And it must be the SAME object, not a second signing: Falcon
+ // signatures are randomised, so a re-signed wire copy would differ from the local one byte for
+ // byte. With the gate closed the OLD call is taken, call for call, so a node that emits
+ // nothing new goes through the same calls as upstream.
+ if (localRoundChange != null
+ && localRoundChange.getSignedPayload().getPayload().getFalconSeal().isPresent()) {
+ transmitter.multicastRoundChange(localRoundChange);
+ } else {
+ transmitter.multicastRoundChange(
+ qbftRoundNew.getRoundIdentifier(), latestPreparedCertificate);
+ }
+ }
+
+ /**
+ * This node's own post-quantum seal for a ROUND-CHANGE it is about to emit, or empty on every
+ * node where the emission gate ({@code aere.pq.roundChangePq.attachBlock}) is shut - which is
+ * every node today. The prepared metadata goes INTO the signed message, so a seal from a bare
+ * round-change cannot be replayed onto one that claims a prepared block.
+ */
+ private Optional<org.hyperledger.besu.consensus.common.bft.FalconSeal> roundChangeSealFor(
+ final ConsensusRoundIdentifier roundIdentifier,
+ final Optional<PreparedCertificate> preparedCertificate) {
+ final long height = roundIdentifier.getSequenceNumber();
+ final long chainId =
+ org.hyperledger.besu.consensus.common.bft.blockcreation.PqAnchorProducer.config().chainId();
+ final org.apache.tuweni.bytes.Bytes32 message =
+ preparedCertificate.isPresent()
+ ? org.hyperledger.besu.consensus.common.bft.PqAnchor.roundChangeMessage(
+ chainId,
+ height,
+ roundIdentifier.getRoundNumber(),
+ preparedCertificate.get().getRound(),
+ preparedCertificate.get().getBlock().getHash().getBytes())
+ : org.hyperledger.besu.consensus.common.bft.PqAnchor.roundChangeMessage(
+ chainId, height, roundIdentifier.getRoundNumber());
+ return org.hyperledger.besu.consensus.common.bft.FalconSealSupport.instance()
+ .signRoundChange(height, message);
}
@Override
diff --git a/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/statemachine/QbftController.java b/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/statemachine/QbftController.java
index c049ccfe9..50100fd7a 100644
--- a/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/statemachine/QbftController.java
+++ b/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/statemachine/QbftController.java
@@ -11,6 +11,12 @@
* specific language governing permissions and limitations under the License.
*
* SPDX-License-Identifier: Apache-2.0
+ *
+ * Modifications Copyright contributors to the Aere Network.
+ *
+ * This file was modified by contributors to the Aere Network, as required by section 4(b) of the
+ * Apache License 2.0. The copyright header above is the upstream one and is left exactly as it was
+ * found, as section 4(c) requires. The change itself is in patches/0003-aere-pq-anchor.patch.
*/
package org.hyperledger.besu.consensus.qbft.core.statemachine;
@@ -19,6 +25,8 @@ import static org.hyperledger.besu.consensus.qbft.core.validation.ValidatorUtil.
import static org.hyperledger.besu.consensus.qbft.core.validation.ValidatorUtil.isMsgFromKnownValidator;
import org.hyperledger.besu.consensus.common.bft.ConsensusRoundIdentifier;
+import org.hyperledger.besu.consensus.common.bft.FalconSeal;
+import org.hyperledger.besu.consensus.common.bft.PqSealCache;
import org.hyperledger.besu.consensus.common.bft.MessageTracker;
import org.hyperledger.besu.consensus.common.bft.events.BlockTimerExpiry;
import org.hyperledger.besu.consensus.common.bft.events.RoundExpiry;
@@ -42,6 +50,7 @@ import org.hyperledger.besu.consensus.qbft.core.validation.MessageValidator;
import org.hyperledger.besu.consensus.qbft.core.validation.RoundChangeMessageValidator;
import org.hyperledger.besu.ethereum.p2p.rlpx.wire.MessageData;
+import java.util.List;
import java.util.Optional;
import java.util.concurrent.atomic.AtomicBoolean;
import java.util.function.Consumer;
@@ -211,6 +220,8 @@ public class QbftController implements QbftEventHandler {
// the currentHeightManager, but CAN be the same directly following import).
if (bftMessage.getRoundIdentifier().getSequenceNumber()
<= blockchain.getChainHeadBlockNumber()) {
+ // AERE D-227: before the message dies here, keep its Falcon seal if it is still useful.
+ pqSalvageLateSeal(bftMessage);
LOG.debug(
"Discarding a message which targets a height {} not above current chain height {}.",
bftMessage.getRoundIdentifier().getSequenceNumber(),
@@ -224,6 +235,58 @@ public class QbftController implements QbftEventHandler {
}
}
+ /**
+ * AERE D-227 (2026-08-14): keep the Falcon seal of a Commit that arrives AFTER its block was
+ * imported, instead of discarding it with the message.
+ *
+ * <p>Why this exists, measured on chain 2800: a block imports on the quorum-th Commit, and the
+ * Commits of the slowest validators consistently arrive tens of milliseconds later - after the
+ * height gate above starts discarding them. Their Falcon seals never reached the seal cache, so
+ * the proposer of the NEXT block (which reads the cache roughly half a block-period later, plenty
+ * of time) could never carry them. Seal circulation measured per signer: the two slowest-disk
+ * nodes appeared in 3% and 14% of other proposers' certificates while appearing in 100% of their
+ * own. The ECDSA path is unaffected either way - by the time a Commit reaches this branch its
+ * block is already imported.
+ *
+ * <p>What is deliberately NOT relaxed: the message itself still dies. Only the seal is copied
+ * out, and only when ALL of the following hold: the message is a Commit carrying a seal, its
+ * height is EXACTLY the chain head (an older seal can never be asked for again), its digest is
+ * the head's own hash (a losing round or a fork sibling is not ours to keep), and its author is
+ * a known validator (so a non-validator peer cannot write into the cache). A seal that lies
+ * about its signer index still cannot reach a header: the producer Falcon-verifies every cached
+ * seal against the anchored registry before carrying it.
+ */
+ private void pqSalvageLateSeal(final BftMessage<?> bftMessage) {
+ if (!(bftMessage instanceof Commit commit)) {
+ return;
+ }
+ final Optional<FalconSeal> seal = commit.getFalconSeal();
+ if (seal.isEmpty()) {
+ return;
+ }
+ final long head = blockchain.getChainHeadBlockNumber();
+ if (commit.getRoundIdentifier().getSequenceNumber() != head) {
+ return;
+ }
+ final QbftBlockHeader headHeader = blockchain.getChainHeadHeader();
+ if (!commit.getDigest().equals(headHeader.getHash())) {
+ return;
+ }
+ if (!finalState.getValidators().contains(commit.getAuthor())) {
+ return;
+ }
+ PqSealCache.instance().record(head, headHeader.getHash(), List.of(seal.get()));
+ // D-339 (2026-09-04): the hybrid extras ride the SAME late commits, and until today this path
+ // dropped them. The anchor needs K seals of EVERY scheme, so a salvaged Falcon seal without its
+ // SLH-DSA twin still left the proposer short and the anchor still lost its round.
+ final List<org.hyperledger.besu.consensus.common.bft.SchemeSeal> extras =
+ commit.getExtraSeals();
+ if (!extras.isEmpty()) {
+ PqSealCache.instance().recordExtras(head, headHeader.getHash(), extras);
+ }
+ LOG.trace("AERE D-227: salvaged a late Falcon seal for imported block {}", head);
+ }
+
@Override
public void handleNewBlockEvent(final QbftNewChainHead newChainHead) {
final QbftBlockHeader newBlockHeader = newChainHead.newChainHeadHeader();
diff --git a/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/statemachine/QbftRound.java b/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/statemachine/QbftRound.java
index 832149e2f..3d0138d9c 100644
--- a/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/statemachine/QbftRound.java
+++ b/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/statemachine/QbftRound.java
@@ -11,13 +11,25 @@
* specific language governing permissions and limitations under the License.
*
* SPDX-License-Identifier: Apache-2.0
+ *
+ * Modifications Copyright contributors to the Aere Network.
+ *
+ * This file was modified by contributors to the Aere Network, as required by section 4(b) of the
+ * Apache License 2.0. The copyright header above is the upstream one and is left exactly as it was
+ * found, as section 4(c) requires. The change itself is in patches/0003-aere-pq-anchor.patch.
*/
package org.hyperledger.besu.consensus.qbft.core.statemachine;
import static java.util.Collections.emptyList;
import org.hyperledger.besu.consensus.common.bft.ConsensusRoundIdentifier;
+import org.hyperledger.besu.consensus.common.bft.FalconSeal;
+import org.hyperledger.besu.consensus.common.bft.FalconSealSupport;
+import org.hyperledger.besu.consensus.common.bft.PqAnchor;
+import org.hyperledger.besu.consensus.common.bft.PqAnchorNotReadyException;
+import org.hyperledger.besu.consensus.common.bft.PqSealCache;
import org.hyperledger.besu.consensus.common.bft.RoundTimer;
+import org.hyperledger.besu.consensus.common.bft.blockcreation.PqAnchorProducer;
import org.hyperledger.besu.consensus.common.bft.payload.SignedData;
import org.hyperledger.besu.consensus.qbft.core.messagewrappers.Commit;
import org.hyperledger.besu.consensus.qbft.core.messagewrappers.Prepare;
@@ -42,6 +54,7 @@ import org.hyperledger.besu.ethereum.mainnet.block.access.list.BlockAccessList;
import org.hyperledger.besu.plugin.services.securitymodule.SecurityModuleException;
import org.hyperledger.besu.util.Subscribers;
+import java.util.Collection;
import java.util.List;
import java.util.Optional;
@@ -75,6 +88,22 @@ public class QbftRound {
private final QbftBlockHeader parentHeader;
+ // AERE hybrid PQC: guards against re-importing once a block has been successfully imported this
+ // round, while still allowing a retry if an earlier import attempt was rejected (e.g. a post-fork
+ // Falcon quorum certificate that was not yet complete when the first attempt ran).
+ private boolean blockImported = false;
+
+ // AERE ANCHOR V2: the ROUND-INDEPENDENT on-chain hash of the block this round is deciding.
+ //
+ // Why it is not simply block.getHash(): a proposal block is built with the COMMITTED-SEAL header
+ // functions, so its hash includes the round number and differs between rounds for one and the
+ // same block. The certificate carried by the NEXT block is looked up, and its message M is built,
+ // from the parent's on-chain hash, which excludes both the commit seals and the round. Keying the
+ // seal cache on anything round dependent would silently produce empty certificates at every round
+ // change. Replacing the round with 0 in the committed-seal encoding yields byte-for-byte the
+ // on-chain pre-image, so this is the same hash the parent header will carry once imported.
+ private Hash pqOnchainHash;
+
/**
* Instantiates a new Qbft round.
*
@@ -159,8 +188,26 @@ public class QbftRound {
final Optional<BlockAccessList> blockAccessList;
if (bestPreparedCertificate.isEmpty()) {
LOG.debug("Sending proposal with new block. round={}", roundState.getRoundIdentifier());
- final BlockCreationResult blockCreationResult =
- blockCreator.createBlock(headerTimestamp, this.parentHeader);
+ final BlockCreationResult blockCreationResult;
+ try {
+ blockCreationResult = blockCreator.createBlock(headerTimestamp, this.parentHeader);
+ } catch (final RuntimeException thrown) {
+ // MEASURED 2026-08-02: the refusal reaches here WRAPPED. AbstractBlockCreator.createBlock
+ // catches every exception from the extra-data calculator and rethrows it as
+ // IllegalStateException, so catching PqAnchorNotReadyException directly never fired and the
+ // escape aborted handleRoundChangePayload, skipping the multicastRoundChange that
+ // doRoundChange issues after it. Anything that is NOT a refusal is rethrown untouched.
+ final PqAnchorNotReadyException e = PqAnchorNotReadyException.findIn(thrown);
+ if (e == null) {
+ throw thrown;
+ }
+ // AERE ANCHOR V2: this node cannot back the block with a certificate that reaches the
+ // staged threshold, so it does NOT propose. See PqAnchorNotReadyException for why refusing
+ // is strictly better than proposing a header we have already computed to be invalid: in
+ // QBFT both end at the same round timer, so proposing anyway buys no liveness at all.
+ LOG.warn("AERE PQ-ANCHOR: not proposing. round={}. {}", getRoundIdentifier(), e.getMessage());
+ return;
+ }
blockToPublish = blockCreationResult.block();
blockAccessList = blockCreationResult.blockAccessList();
} else {
@@ -197,20 +244,48 @@ public class QbftRound {
final List<SignedData<PreparePayload>> prepares) {
final Proposal proposal;
try {
+ // AERE PQ PROPOSAL (2026-08-30): the seal is computed once, here, and rides INSIDE the
+ // signed payload. With the gate closed - every node today - the seal is empty and the OLD
+ // overload is taken call for call, so a node that emits nothing new behaves identically to
+ // one from before this change. Same pattern as PREPARE and commit, deliberately.
+ final Optional<FalconSeal> proposalSeal = proposalSealFor(block);
proposal =
- messageFactory.createProposal(
- getRoundIdentifier(), block, blockAccessList, roundChanges, prepares);
+ proposalSeal.isPresent()
+ ? messageFactory.createProposal(
+ getRoundIdentifier(), block, blockAccessList, roundChanges, prepares,
+ proposalSeal)
+ : messageFactory.createProposal(
+ getRoundIdentifier(), block, blockAccessList, roundChanges, prepares);
} catch (final SecurityModuleException e) {
LOG.warn("Failed to create a signed Proposal, waiting for next round.", e);
return;
}
- transmitter.multicastProposal(
- proposal.getRoundIdentifier(),
- proposal.getSignedPayload().getPayload().getProposedBlock(),
- proposal.getBlockAccessList(),
- roundChanges,
- prepares);
+ // THE SAME seal object goes on the wire. The transmitter re-creates the proposal, so without
+ // this the local copy is sealed and the wire copy is not - measured on the first network run
+ // (F84 scenario A): every peer refused height H round after round while this node's own log
+ // said it had emitted. And it must be the SAME object, not a second signing: Falcon signatures
+ // are randomised, so a re-signed wire copy would differ from the local one byte for byte.
+ // With the gate closed the OLD call is taken, call for call - the upstream tests assert the
+ // five-argument form, and a node that emits nothing new must go through the same calls.
+ final Optional<FalconSeal> wireSeal =
+ proposal.getSignedPayload().getPayload().getFalconSeal();
+ if (wireSeal.isPresent()) {
+ transmitter.multicastProposal(
+ proposal.getRoundIdentifier(),
+ proposal.getSignedPayload().getPayload().getProposedBlock(),
+ proposal.getBlockAccessList(),
+ roundChanges,
+ prepares,
+ wireSeal);
+ } else {
+ transmitter.multicastProposal(
+ proposal.getRoundIdentifier(),
+ proposal.getSignedPayload().getPayload().getProposedBlock(),
+ proposal.getBlockAccessList(),
+ roundChanges,
+ prepares);
+ }
if (updateStateWithProposedBlock(proposal)) {
sendPrepare(block);
}
@@ -235,16 +310,70 @@ public class QbftRound {
private void sendPrepare(final QbftBlock block) {
LOG.debug("Sending prepare message. round={}", roundState.getRoundIdentifier());
try {
+ // AERE PQ PREPARE (2026-08-28), step 2: the seal is computed EXACTLY ONCE here and is
+ // handed to both the local copy and the one on the wire. Falcon signatures are randomised,
+ // so two signings of the same message give two different byte strings; if each copy signed
+ // its own, the same validator would produce two valid and DIFFERENT PREPAREs for the same
+ // round. The gate is closed on every node today, so this is empty until a decision.
+ final Optional<FalconSeal> falconSeal = prepareSealFor(block);
+ // WITH THE GATE CLOSED the OLD path is taken, call for call. This is not style: the upstream
+ // tests assert exactly the two-argument call, and more importantly a node that emits nothing
+ // new must behave identically to one from before this change - not merely write the same
+ // bytes, but go through the same calls. That way the binary can sit on the fleet with
+ // nothing changing until a decision is made. Same pattern as commit.
final Prepare localPrepareMessage =
- messageFactory.createPrepare(getRoundIdentifier(), block.getHash());
+ falconSeal.isPresent()
+ ? messageFactory.createPrepare(getRoundIdentifier(), block.getHash(), falconSeal)
+ : messageFactory.createPrepare(getRoundIdentifier(), block.getHash());
peerIsPrepared(localPrepareMessage);
- transmitter.multicastPrepare(
- localPrepareMessage.getRoundIdentifier(), localPrepareMessage.getDigest());
+ if (falconSeal.isPresent()) {
+ transmitter.multicastPrepare(
+ localPrepareMessage.getRoundIdentifier(), localPrepareMessage.getDigest(), falconSeal);
+ } else {
+ transmitter.multicastPrepare(
+ localPrepareMessage.getRoundIdentifier(), localPrepareMessage.getDigest());
+ }
} catch (final SecurityModuleException e) {
LOG.warn("Failed to create a signed Prepare; {}", e.getMessage());
}
}
+ /**
+ * This node's post-quantum seal for the PREPARE of the given block, or empty.
+ *
+ * <p>The signed message has ITS OWN DOMAIN and contains the ROUND - see PqAnchor.prepareMessage
+ * and the 2026-08-28 design note. Under the commit domain, a PREPARE seal given honestly could
+ * be pasted onto a forged COMMIT.
+ */
+ private Optional<FalconSeal> prepareSealFor(final QbftBlock block) {
+ final long blockNumber = block.getHeader().getNumber();
+ final Bytes32 message =
+ PqAnchor.prepareMessage(
+ PqAnchorProducer.config().chainId(),
+ blockNumber,
+ getRoundIdentifier().getRoundNumber(),
+ block.getHash().getBytes());
+ return FalconSealSupport.instance().signPrepare(blockNumber, message);
+ }
+
+ /**
+ * This node's post-quantum seal for its own PROPOSAL of the given block, or empty.
+ *
+ * <p>Its own domain again - see PqAnchor.proposalMessage. A proposal is an offer, not a vote:
+ * under the PREPARE or commit domain, a proposal seal given honestly could be pasted onto a
+ * forged vote and counted.
+ */
+ private Optional<FalconSeal> proposalSealFor(final QbftBlock block) {
+ final long blockNumber = block.getHeader().getNumber();
+ final Bytes32 message =
+ PqAnchor.proposalMessage(
+ PqAnchorProducer.config().chainId(),
+ blockNumber,
+ getRoundIdentifier().getRoundNumber(),
+ block.getHash().getBytes());
+ return FalconSealSupport.instance().signProposal(blockNumber, message);
+ }
+
/**
* Handle prepare message.
*
@@ -282,23 +411,39 @@ public class QbftRound {
private boolean updateStateWithProposedBlock(final Proposal msg) {
final boolean wasPrepared = roundState.isPrepared();
- final boolean wasCommitted = roundState.isCommitted();
final boolean blockAccepted = roundState.setProposedBlock(msg);
if (blockAccepted) {
final QbftBlock block = roundState.getProposedBlock().get();
+
+ // AERE hybrid PQC: compute the commit hash once, then produce BOTH the decisive ECDSA commit
+ // seal and the parallel Falcon-512 seal over the SAME commit hash. The Falcon seal is gossiped
+ // on the commit message so every validator's post-quantum seal reaches the block assembler.
+ final Hash commitHash;
final SECPSignature commitSeal;
try {
- commitSeal = createCommitSeal(block);
+ commitHash = commitHashFor(block);
+ commitSeal = nodeKey.sign(Bytes32.wrap(commitHash.getBytes()));
} catch (final SecurityModuleException e) {
LOG.warn("Failed to construct commit seal; {}", e.getMessage());
return true;
}
+ final Optional<FalconSeal> falconSeal = falconSealFor(block, commitHash);
+ // AERE HYBRID: the other schemes' extras, over the SAME message; empty on any node today.
+ final java.util.List<org.hyperledger.besu.consensus.common.bft.SchemeSeal> extraSeals =
+ falconSeal.isPresent() ? extraSealsFor(block, commitHash) : java.util.List.of();
// There are times handling a proposed block is enough to enter prepared.
if (wasPrepared != roundState.isPrepared()) {
LOG.debug("Sending commit message. round={}", roundState.getRoundIdentifier());
- transmitter.multicastCommit(getRoundIdentifier(), block.getHash(), commitSeal);
+ if (!extraSeals.isEmpty()) {
+ transmitter.multicastCommit(
+ getRoundIdentifier(), block.getHash(), commitSeal, falconSeal, extraSeals);
+ } else if (falconSeal.isPresent()) {
+ transmitter.multicastCommit(getRoundIdentifier(), block.getHash(), commitSeal, falconSeal);
+ } else {
+ transmitter.multicastCommit(getRoundIdentifier(), block.getHash(), commitSeal);
+ }
}
// can automatically add _our_ commit message to the roundState
@@ -306,18 +451,27 @@ public class QbftRound {
// prepare
try {
final Commit localCommitMessage =
- messageFactory.createCommit(
- roundState.getRoundIdentifier(), msg.getBlock().getHash(), commitSeal);
+ falconSeal.isPresent()
+ ? messageFactory.createCommit(
+ roundState.getRoundIdentifier(),
+ msg.getBlock().getHash(),
+ commitSeal,
+ falconSeal,
+ extraSeals)
+ : messageFactory.createCommit(
+ roundState.getRoundIdentifier(), msg.getBlock().getHash(), commitSeal);
roundState.addCommitMessage(localCommitMessage);
} catch (final SecurityModuleException e) {
LOG.warn("Failed to create signed Commit message; {}", e.getMessage());
return true;
}
+ // AERE ANCHOR V2: remember every Falcon seal heard for THIS block, so the proposer of the
+ // NEXT block can carry a certificate over it. This is the local node's own seal.
+ pqCacheHeardSeals(block);
+
// It is possible sufficient commit seals are now available and the block should be imported
- if (wasCommitted != roundState.isCommitted()) {
- importBlockToChain();
- }
+ maybeImportBlock();
}
return blockAccepted;
@@ -330,7 +484,20 @@ public class QbftRound {
LOG.debug("Sending commit message. round={}", roundState.getRoundIdentifier());
final QbftBlock block = roundState.getProposedBlock().get();
try {
- transmitter.multicastCommit(getRoundIdentifier(), block.getHash(), createCommitSeal(block));
+ final Hash commitHash = commitHashFor(block);
+ final SECPSignature commitSeal = nodeKey.sign(Bytes32.wrap(commitHash.getBytes()));
+ final Optional<FalconSeal> falconSeal = falconSealFor(block, commitHash);
+ // AERE HIBRID: aceleasi extrase si pe drumul tarziu, ca cele doua locuri sa nu divearga.
+ final java.util.List<org.hyperledger.besu.consensus.common.bft.SchemeSeal> extraSeals =
+ falconSeal.isPresent() ? extraSealsFor(block, commitHash) : java.util.List.of();
+ if (!extraSeals.isEmpty()) {
+ transmitter.multicastCommit(
+ getRoundIdentifier(), block.getHash(), commitSeal, falconSeal, extraSeals);
+ } else if (falconSeal.isPresent()) {
+ transmitter.multicastCommit(getRoundIdentifier(), block.getHash(), commitSeal, falconSeal);
+ } else {
+ transmitter.multicastCommit(getRoundIdentifier(), block.getHash(), commitSeal);
+ }
// Note: the local-node's commit message was added to RoundState on block acceptance
// and thus does not need to be done again here.
} catch (final SecurityModuleException e) {
@@ -340,20 +507,50 @@ public class QbftRound {
}
private void peerIsCommitted(final Commit msg) {
- final boolean wasCommitted = roundState.isCommitted();
roundState.addCommitMessage(msg);
- if (wasCommitted != roundState.isCommitted()) {
+ // AERE ANCHOR V2: top up the seal cache on EVERY commit, including commits that arrive after
+ // this node has already imported the block. Those late seals are exactly the ones that let a
+ // proposer reach the threshold K without waiting for its own round to be re-run.
+ roundState.getProposedBlock().ifPresent(this::pqCacheHeardSeals);
+ if (roundState.getProposedBlock().isEmpty()) {
+ pqCacheSealsOfCommitWithoutProposal(msg);
+ }
+ // AERE hybrid PQC: attempt import on every commit while not yet imported. In the common case
+ // this fires exactly once (on the quorum-th commit). Post-fork, if the first attempt lacked a
+ // complete Falcon quorum certificate (e.g. one of the quorum's validators had a faulty Falcon
+ // key), a later commit that carries a valid Falcon seal lets the honest quorum complete.
+ maybeImportBlock();
+ }
+
+ private void maybeImportBlock() {
+ if (roundState.isCommitted() && !blockImported) {
importBlockToChain();
}
}
private void importBlockToChain() {
+ // AERE hybrid PQC: pass the gossiped Falcon seals collected from commit messages so the block
+ // assembler can embed the post-quantum certificate. When no Falcon seals were gossiped (Falcon
+ // disabled), fall back to the unchanged ECDSA-only sealing path.
+ //
+ // WHAT GETS EMBEDDED, corrected 2026-08-19 (finding D-235): NOT a per-block 2f+1 quorum. The
+ // assembler writes a certificate only at an anchor height, over the PARENT, and it needs at
+ // least K valid seals, K being the configured schedule (6 of 9 on chain 2800 today). Between
+ // anchor heights nothing is written. The older wording here said "a >= 2f+1 Falcon quorum
+ // certificate" and described the legacy per-block rule, which is retired at the anchor block.
+ final Collection<FalconSeal> falconSeals = roundState.getFalconSeals();
final QbftBlock blockToImport =
- blockCreator.createSealedBlock(
- roundState.getProposedBlock().get(),
- roundState.getRoundIdentifier().getRoundNumber(),
- roundState.getCommitSeals());
+ falconSeals.isEmpty()
+ ? blockCreator.createSealedBlock(
+ roundState.getProposedBlock().get(),
+ roundState.getRoundIdentifier().getRoundNumber(),
+ roundState.getCommitSeals())
+ : blockCreator.createSealedBlock(
+ roundState.getProposedBlock().get(),
+ roundState.getRoundIdentifier().getRoundNumber(),
+ roundState.getCommitSeals(),
+ falconSeals);
final long blockNumber = blockToImport.getHeader().getNumber();
if (getRoundIdentifier().getRoundNumber() > 0) {
@@ -373,19 +570,170 @@ public class QbftRound {
final boolean result =
blockImporter.importBlock(blockToImport, roundState.getProposedBlockAccessList());
if (!result) {
+ // Do NOT set blockImported: a post-fork block whose Falcon quorum certificate is not yet
+ // complete can be retried as more commits (with valid Falcon seals) arrive this round.
LOG.error(
"Failed to import proposed block to chain. block={} blockHeader={}",
blockNumber,
blockToImport.getHeader());
} else {
+ blockImported = true;
notifyNewBlockListeners(blockToImport);
}
}
- private SECPSignature createCommitSeal(final QbftBlock block) {
+ private Hash commitHashFor(final QbftBlock block) {
final QbftBlock commitBlock = createCommitBlock(block);
- final Hash commitHash = commitBlock.getHash();
- return nodeKey.sign(Bytes32.wrap(commitHash.getBytes()));
+ return commitBlock.getHash();
+ }
+
+ /**
+ * AERE ANCHOR V2: remember the Falcon seals heard for a block, keyed on its ROUND-INDEPENDENT
+ * on-chain hash, which is the key the producer of the next block looks under. Cheap and
+ * idempotent: the cache keeps the first seal seen per validator index.
+ */
+ /**
+ * D-339 (2026-09-04): keep the seals of a Commit even when this node has NO proposal for the
+ * round, keyed on the digest the Commit itself names.
+ *
+ * <p>Why, measured on chain 2800 the same evening: the proposer of an anchor kept refusing with
+ * "this node holds 1 valid eligible Falcon seal ... 0 rejected" - it was not rejecting seals, it
+ * had never heard them. The path above caches only when the round holds the proposed block, so a
+ * node that missed the proposal of the parent's round (or imported that block by any route other
+ * than its own round) collected the Commits and threw their seals away. It then could not build
+ * the certificate of the next anchor, the round expired, and every 32nd height paid the
+ * round-change timeout. Eleven of twelve anchors measured before this fix.
+ *
+ * <p>Safety: only the seal is copied, never the message; the digest is the one the Commit names,
+ * so a losing round writes an entry under a hash that never becomes canonical and is simply never
+ * looked up; and the producer Falcon-verifies every cached seal against the anchored registry
+ * before carrying it, so a seal that lies about its index still cannot reach a header.
+ *
+ * @param msg the commit whose seals are kept
+ */
+ private void pqCacheSealsOfCommitWithoutProposal(final Commit msg) {
+ final long height = roundState.getRoundIdentifier().getSequenceNumber();
+ msg.getFalconSeal()
+ .ifPresent(
+ seal ->
+ PqSealCache.instance()
+ .record(height, msg.getDigest(), java.util.List.of(seal)));
+ final java.util.List<org.hyperledger.besu.consensus.common.bft.SchemeSeal> extras =
+ msg.getExtraSeals();
+ if (!extras.isEmpty()) {
+ PqSealCache.instance().recordExtras(height, msg.getDigest(), extras);
+ }
+ }
+
+ private void pqCacheHeardSeals(final QbftBlock block) {
+ final Collection<FalconSeal> seals = roundState.getFalconSeals();
+ if (seals.isEmpty()) {
+ return;
+ }
+ final Hash onchain = pqOnchainHashOf(block);
+ PqSealCache.instance().record(block.getHeader().getNumber(), onchain, seals);
+ // AERE ANCHOR V2: the extra scheme seals ride the same commits and go under the same key.
+ final java.util.List<org.hyperledger.besu.consensus.common.bft.SchemeSeal> extras =
+ roundState.getExtraSeals();
+ if (!extras.isEmpty()) {
+ PqSealCache.instance().recordExtras(block.getHeader().getNumber(), onchain, extras);
+ }
+ }
+
+ /**
+ * AERE ANCHOR V2: the round-independent on-chain hash of the block this round is deciding,
+ * computed once per round. Replacing the round with 0 in the committed-seal encoding produces
+ * byte-for-byte the on-chain pre-image, because that encoding differs from the on-chain one only
+ * by writing the real round instead of a forced zero.
+ */
+ private Hash pqOnchainHashOf(final QbftBlock block) {
+ if (pqOnchainHash == null) {
+ pqOnchainHash = blockInterface.replaceRoundForCommitBlock(block, 0).getHash();
+ }
+ return pqOnchainHash;
+ }
+
+ /**
+ * AERE HIBRID (2026-08-25): the non-Falcon seals of this node's hybrid certificate, over the
+ * SAME message the Falcon seal signs (the two are one certificate; two messages would be two
+ * certificates and the verifier could not bind them). Empty on every node that is not
+ * hybrid-configured, and below the emission gate: {@link HybridSealProducer} never throws and
+ * never emits half a certificate.
+ */
+ private java.util.List<org.hyperledger.besu.consensus.common.bft.SchemeSeal> extraSealsFor(
+ final QbftBlock block, final Hash commitHash) {
+ // ANCHOR PARENTS ONLY (2026-09-03, D-329): an SLH-DSA-128s signature costs seconds here; it is
+ // only ever used in the next anchor's certificate, which is built over the anchor's parent. So
+ // the extras are signed only when the block being committed is the parent of an anchor height.
+ // The same predicate gates the enforcement (PqCommitEnforcement.anchorParentByConfig).
+ final long number = block.getHeader().getNumber();
+ if (!org.hyperledger.besu.consensus.common.bft.blockcreation.PqAnchorProducer.config()
+ .anchorAppliesAt(number + 1L)) {
+ return java.util.List.of();
+ }
+ return hybridExtrasOrEmpty(number, pqSealMessageFor(block, commitHash));
+ }
+
+ /**
+ * D-334 (2026-09-03, mainnet 2800, 125 s of halted chain): the hybrid loader is lazy, so a
+ * registry the container could not read surfaced here, as an exception thrown INTO the QBFT
+ * state machine, at every anchor parent, on every armed node. Three such nodes plus one node
+ * restarting left five of nine. A broken hybrid configuration may cost this node its SLH-DSA
+ * contribution; it must never cost the node its vote. The loader still refuses to START on the
+ * same defect (QbftBesuControllerBuilder calls it at boot), so this catch is the second net.
+ *
+ * @param number the height being committed
+ * @param message the seal message
+ * @return the extras, or an empty list with an ERROR line when the hybrid support cannot sign
+ */
+ static java.util.List<org.hyperledger.besu.consensus.common.bft.SchemeSeal> hybridExtrasOrEmpty(
+ final long number, final Bytes32 message) {
+ try {
+ return org.hyperledger.besu.consensus.common.bft.HybridSealSupport.instance()
+ .producer()
+ .sealsFor(number, message);
+ } catch (final RuntimeException e) {
+ LOG.error(
+ "AERE HIBRID: extras NOT signed at height {} - {}. This node keeps voting but contributes no"
+ + " SLH-DSA seal until the hybrid configuration is repaired (D-334).",
+ number,
+ e.getMessage());
+ return java.util.List.of();
+ }
+ }
+
+ /** The exact bytes a PQ seal over this block signs; shared by Falcon and the hybrid extras,
+ * so the two halves of a hybrid certificate can never drift onto different messages. */
+ private Bytes32 pqSealMessageFor(final QbftBlock block, final Hash commitHash) {
+ // AERE D-311 (2026-09-02): the form is decided in ONE place, shared with the verifier
+ // (MessageValidator.SubsequentMessageValidator). A second copy of this rule drifted once and
+ // stopped a chain; see PqAnchorProducer.commitSealMessage.
+ return PqAnchorProducer.commitSealMessage(
+ block.getHeader().getNumber(), () -> pqOnchainHashOf(block).getBytes(), commitHash);
+ }
+
+ private Optional<FalconSeal> falconSealFor(final QbftBlock block, final Hash commitHash) {
+ // FalconSealSupport.sign never throws (any fault is swallowed and logged), and returns empty
+ // when this node holds no Falcon signing key, so the ECDSA commit path is never affected.
+ //
+ // AERE FIX-OPRIRE-CONSENS (b): the block NUMBER is now a mandatory argument. Seal ATTACHMENT is
+ // gated on the activation height (and on registry coverage of the whole validator set) inside
+ // FalconSealSupport.sign, so merely holding a Falcon key no longer makes a node emit a
+ // Falcon-carrying Commit. There is deliberately no height-less sign() overload left: a call site
+ // physically cannot bypass the gate.
+ //
+ // AERE ANCHOR V2: WHAT IS SIGNED changes one block BEFORE the anchor activates, because the
+ // certificate carried by block H is made of seals over block H-1. From that height the message
+ // is M = keccak256(RLP["AERE-PQ-COMMIT-1", chainId, number, ON-CHAIN block hash]) instead of the
+ // ECDSA committed-seal hash. The committed-seal hash could not be used: it includes the ROUND,
+ // which is not in the block-hash pre-image, so a validator holding only the parent header could
+ // not rebuild it. Every node flips at the same height, since the height is a pure function of
+ // the same configured H; a node configured with a different H emits seals nobody can use, and
+ // the producer drops them on verification rather than carrying them into a header.
+ // AERE HIBRID (2026-08-25): mesajul se calculeaza acum intr-UN singur loc, pqSealMessageFor,
+ // impartit cu extrasele hibride; doua copii ale acestei logici ar fi divergat intr-o zi.
+ final long blockNumber = block.getHeader().getNumber();
+ return FalconSealSupport.instance().sign(blockNumber, pqSealMessageFor(block, commitHash));
}
private QbftBlock createCommitBlock(final QbftBlock block) {
diff --git a/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/statemachine/RoundState.java b/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/statemachine/RoundState.java
index 1c3078602..2c798c9e2 100644
--- a/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/statemachine/RoundState.java
+++ b/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/statemachine/RoundState.java
@@ -11,10 +11,17 @@
* specific language governing permissions and limitations under the License.
*
* SPDX-License-Identifier: Apache-2.0
+ *
+ * Modifications Copyright contributors to the Aere Network.
+ *
+ * This file was modified by contributors to the Aere Network, as required by section 4(b) of the
+ * Apache License 2.0. The copyright header above is the upstream one and is left exactly as it was
+ * found, as section 4(c) requires. The change itself is in patches/0003-aere-pq-anchor.patch.
*/
package org.hyperledger.besu.consensus.qbft.core.statemachine;
import org.hyperledger.besu.consensus.common.bft.ConsensusRoundIdentifier;
+import org.hyperledger.besu.consensus.common.bft.FalconSeal;
import org.hyperledger.besu.consensus.qbft.core.messagewrappers.Commit;
import org.hyperledger.besu.consensus.qbft.core.messagewrappers.Prepare;
import org.hyperledger.besu.consensus.qbft.core.messagewrappers.Proposal;
@@ -27,6 +34,7 @@ import org.hyperledger.besu.ethereum.mainnet.block.access.list.BlockAccessList;
import java.util.Collection;
import java.util.LinkedHashMap;
import java.util.Map;
+import java.util.Objects;
import java.util.Optional;
import java.util.stream.Collectors;
@@ -196,6 +204,35 @@ public class RoundState {
.collect(Collectors.toList());
}
+ /**
+ * Gets the parallel post-quantum Falcon seals gossiped on the collected commit messages (AERE
+ * hybrid PQC). Only commits that carried a Falcon seal contribute; the result is the raw set of
+ * gossiped seals, to be verified and de-duplicated by the block creator / header validation rule
+ * when the quorum certificate is assembled and checked.
+ *
+ * @return the gossiped Falcon seals (possibly empty, never null)
+ */
+ /**
+ * AERE ANCHOR V2: the extra (non-Falcon) scheme seals gossiped on the collected commit messages,
+ * raw and unverified, for the seal cache and the v2 certificate producer.
+ *
+ * @return the gossiped scheme seals (possibly empty, never null)
+ */
+ public java.util.List<org.hyperledger.besu.consensus.common.bft.SchemeSeal> getExtraSeals() {
+ return commitMessages.values().stream()
+ .flatMap(cp -> cp.getSignedPayload().getPayload().getExtraSeals().stream())
+ .collect(Collectors.toList());
+ }
+
+ public Collection<FalconSeal> getFalconSeals() {
+ return commitMessages.values().stream()
+ .map(cp -> cp.getSignedPayload().getPayload().getFalconSeal())
+ .filter(Objects::nonNull)
+ .filter(Optional::isPresent)
+ .map(Optional::get)
+ .collect(Collectors.toList());
+ }
+
/**
* Construct prepared certificate.
*
diff --git a/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/types/QbftBlockCreator.java b/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/types/QbftBlockCreator.java
index afe4fb00e..c397cab98 100644
--- a/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/types/QbftBlockCreator.java
+++ b/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/types/QbftBlockCreator.java
@@ -11,13 +11,21 @@
* specific language governing permissions and limitations under the License.
*
* SPDX-License-Identifier: Apache-2.0
+ *
+ * Modifications Copyright contributors to the Aere Network.
+ *
+ * This file was modified by contributors to the Aere Network, as required by section 4(b) of the
+ * Apache License 2.0. The copyright header above is the upstream one and is left exactly as it was
+ * found, as section 4(c) requires. The change itself is in patches/0003-aere-pq-anchor.patch.
*/
package org.hyperledger.besu.consensus.qbft.core.types;
+import org.hyperledger.besu.consensus.common.bft.FalconSeal;
import org.hyperledger.besu.crypto.SECPSignature;
import org.hyperledger.besu.ethereum.mainnet.block.access.list.BlockAccessList;
import java.util.Collection;
+import java.util.Collections;
import java.util.Optional;
/** Responsible for creating a block. */
@@ -50,4 +58,33 @@ public interface QbftBlockCreator {
*/
QbftBlock createSealedBlock(
final QbftBlock block, final int roundNumber, final Collection<SECPSignature> commitSeals);
+
+ /**
+ * Create sealed block, additionally embedding a gossiped parallel Falcon-512 quorum certificate
+ * (AERE hybrid PQC). The default implementation ignores the Falcon seals and delegates to the
+ * ECDSA-only sealing, so existing implementations remain valid; the QBFT block creator adaptor
+ * overrides this to aggregate the Falcon seals into a per-block quorum certificate.
+ *
+ * @param block the block
+ * @param roundNumber the round number
+ * @param commitSeals the decisive ECDSA commit seals
+ * @param falconSeals the gossiped parallel Falcon-512 seals collected from commit messages
+ * @return the block
+ */
+ default QbftBlock createSealedBlock(
+ final QbftBlock block,
+ final int roundNumber,
+ final Collection<SECPSignature> commitSeals,
+ final Collection<FalconSeal> falconSeals) {
+ return createSealedBlock(block, roundNumber, commitSeals);
+ }
+
+ /**
+ * Convenience empty Falcon seal collection.
+ *
+ * @return an empty collection of Falcon seals
+ */
+ static Collection<FalconSeal> noFalconSeals() {
+ return Collections.emptyList();
+ }
}
diff --git a/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/validation/CommitValidator.java b/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/validation/CommitValidator.java
index e211c6a8e..918607ad2 100644
--- a/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/validation/CommitValidator.java
+++ b/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/validation/CommitValidator.java
@@ -11,6 +11,14 @@
* specific language governing permissions and limitations under the License.
*
* SPDX-License-Identifier: Apache-2.0
+ *
+ * Modifications Copyright contributors to the Aere Network.
+ *
+ * This file was modified by contributors to the Aere Network, as required by section 4(b) of the
+ * Apache License 2.0. The copyright header above is the upstream one and is left exactly as it was
+ * found, as section 4(c) requires. The change: an OPTIONAL, height-gated post-quantum enforcement
+ * hook (see PqCommitEnforcement). When no enforcement is supplied, behaviour is byte-for-byte the
+ * upstream behaviour; the existing constructor keeps that contract for every existing caller.
*/
package org.hyperledger.besu.consensus.qbft.core.validation;
@@ -23,6 +31,7 @@ import org.hyperledger.besu.datatypes.Hash;
import org.hyperledger.besu.ethereum.core.Util;
import java.util.Collection;
+import java.util.Optional;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
@@ -38,9 +47,23 @@ public class CommitValidator {
private final ConsensusRoundIdentifier targetRound;
private final Hash expectedDigest;
private final Hash expectedCommitDigest;
+ // AERE D-311 (2026-09-02): the message the post-quantum seal must have signed. It is NOT always
+ // the committed-seal digest: once the anchor is armed the emitter signs the anchor form (see
+ // PqAnchorProducer.commitSealMessage). The upstream-shaped constructors keep the digest, so no
+ // existing caller changes behaviour; the production path (MessageValidator) passes the real one.
+ private final Hash expectedPqSealMessage;
+ // AERE full-PQ: optional height-gated enforcement. Null means "upstream behaviour", which is
+ // exactly what the pre-existing constructor supplies, so nothing changes for existing callers.
+ private final PqCommitEnforcement pqEnforcement;
/**
- * Instantiates a new Commit validator.
+ * Instantiates a new Commit validator, self-wiring the AERE post-quantum enforcement from the
+ * system configuration.
+ *
+ * <p>With {@code aere.pq.commitPq.forkBlock} absent -- every fleet node today, and every test
+ * JVM -- this is byte-for-byte the upstream behaviour. With it set, commits at or above that
+ * height only count with a valid post-quantum seal of their own author. A present but broken
+ * value refuses loudly here rather than silently disarming.
*
* @param validators the validators
* @param targetRound the target round
@@ -52,10 +75,93 @@ public class CommitValidator {
final ConsensusRoundIdentifier targetRound,
final Hash expectedDigest,
final Hash expectedCommitDigest) {
+ this(
+ validators,
+ targetRound,
+ expectedDigest,
+ expectedCommitDigest,
+ expectedCommitDigest,
+ PqCommitEnforcement.fromSystemConfig());
+ }
+
+ /**
+ * AERE D-311: the production constructor. Self-wires enforcement from the system configuration
+ * and takes the exact message the PQ seal signs at this height, computed by the caller with
+ * {@code PqAnchorProducer.commitSealMessage}, the same helper the emitter uses.
+ *
+ * @param validators the validators
+ * @param targetRound the target round
+ * @param expectedDigest the expected digest
+ * @param expectedCommitDigest the expected commit digest (ECDSA committed seal)
+ * @param expectedPqSealMessage the message the post-quantum seal must have signed
+ */
+ public CommitValidator(
+ final Collection<Address> validators,
+ final ConsensusRoundIdentifier targetRound,
+ final Hash expectedDigest,
+ final Hash expectedCommitDigest,
+ final Hash expectedPqSealMessage) {
+ this(
+ validators,
+ targetRound,
+ expectedDigest,
+ expectedCommitDigest,
+ expectedPqSealMessage,
+ PqCommitEnforcement.fromSystemConfig());
+ }
+
+ /**
+ * Instantiates a new Commit validator with optional post-quantum enforcement.
+ *
+ * <p>AERE full-PQ: when {@code pqEnforcement} is non-null and armed at this round's height, a
+ * Commit only validates if it carries a post-quantum seal whose index is bound to the message
+ * author and whose signature verifies over the commit digest. A vote without valid PQ does not
+ * count toward quorum.
+ *
+ * @param validators the validators
+ * @param targetRound the target round
+ * @param expectedDigest the expected digest
+ * @param expectedCommitDigest the expected commit digest
+ * @param pqEnforcement the height-gated enforcement, or null for upstream behaviour
+ */
+ public CommitValidator(
+ final Collection<Address> validators,
+ final ConsensusRoundIdentifier targetRound,
+ final Hash expectedDigest,
+ final Hash expectedCommitDigest,
+ final PqCommitEnforcement pqEnforcement) {
+ this(validators, targetRound, expectedDigest, expectedCommitDigest, expectedCommitDigest, pqEnforcement);
+ }
+
+ /** AERE D-311: the message the post-quantum seal must have signed; for the plumbing proof only. */
+ @com.google.common.annotations.VisibleForTesting
+ Hash expectedPqSealMessageForTesting() {
+ return expectedPqSealMessage;
+ }
+
+ /**
+ * AERE D-311: the fully explicit constructor (tests and the production constructor above).
+ *
+ * @param validators the validators
+ * @param targetRound the target round
+ * @param expectedDigest the expected digest
+ * @param expectedCommitDigest the expected commit digest (ECDSA committed seal)
+ * @param expectedPqSealMessage the message the post-quantum seal must have signed
+ * @param pqEnforcement the enforcement, or null for upstream behaviour
+ */
+ public CommitValidator(
+ final Collection<Address> validators,
+ final ConsensusRoundIdentifier targetRound,
+ final Hash expectedDigest,
+ final Hash expectedCommitDigest,
+ final Hash expectedPqSealMessage,
+ final PqCommitEnforcement pqEnforcement) {
this.validators = validators;
this.targetRound = targetRound;
this.expectedDigest = expectedDigest;
this.expectedCommitDigest = expectedCommitDigest;
+ this.expectedPqSealMessage = expectedPqSealMessage;
+ this.pqEnforcement = pqEnforcement;
}
/**
@@ -112,6 +218,22 @@ public class CommitValidator {
return false;
}
+ // AERE full-PQ: above the arming height a commit vote only counts with a valid post-quantum
+ // seal bound to this very author. Below it (or with no enforcement supplied) nothing changes.
+ if (pqEnforcement != null) {
+ final Optional<String> refusal =
+ pqEnforcement.refusal(
+ targetRound.getSequenceNumber(),
+ signedPayload.getAuthor(),
+ expectedPqSealMessage,
+ payload.getFalconSeal(),
+ payload.getExtraSeals());
+ if (refusal.isPresent()) {
+ LOG.info("{}: {}", ERROR_PREFIX, refusal.get());
+ return false;
+ }
+ }
+
return true;
}
}
diff --git a/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/validation/MessageValidator.java b/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/validation/MessageValidator.java
index d15d19e91..0f26c79a8 100644
--- a/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/validation/MessageValidator.java
+++ b/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/validation/MessageValidator.java
@@ -11,16 +11,24 @@
* specific language governing permissions and limitations under the License.
*
* SPDX-License-Identifier: Apache-2.0
+ *
+ * Modifications Copyright contributors to the Aere Network.
+ *
+ * This file was modified by contributors to the Aere Network, as required by section 4(b) of the
+ * Apache License 2.0. The copyright header above is the upstream one and is left exactly as it was
+ * found, as section 4(c) requires. The change itself is in patches/0003-aere-pq-anchor.patch.
*/
package org.hyperledger.besu.consensus.qbft.core.validation;
import org.hyperledger.besu.consensus.common.bft.ConsensusRoundIdentifier;
+import org.hyperledger.besu.consensus.common.bft.blockcreation.PqAnchorProducer;
import org.hyperledger.besu.consensus.qbft.core.messagewrappers.Commit;
import org.hyperledger.besu.consensus.qbft.core.messagewrappers.Prepare;
import org.hyperledger.besu.consensus.qbft.core.messagewrappers.Proposal;
import org.hyperledger.besu.consensus.qbft.core.types.QbftBlock;
import org.hyperledger.besu.consensus.qbft.core.types.QbftBlockInterface;
import org.hyperledger.besu.datatypes.Address;
+import org.hyperledger.besu.datatypes.Hash;
import java.util.Collection;
import java.util.Optional;
@@ -55,9 +63,23 @@ public class MessageValidator {
final QbftBlock commitBlock =
blockInterface.replaceRoundForCommitBlock(proposalBlock, targetRound.getRoundNumber());
prepareValidator = new PrepareValidator(validators, targetRound, proposalBlock.getHash());
+ // AERE D-311 (2026-09-02): the post-quantum seal on a commit signs the message that
+ // PqAnchorProducer.commitSealMessage names (the anchor form once the anchor is armed, the
+ // ECDSA committed-seal hash before), computed here exactly as the emitter computes it in
+ // QbftRound.pqSealMessageFor: same helper, same round-independent on-chain hash.
+ final Hash expectedPqSealMessage =
+ Hash.wrap(
+ PqAnchorProducer.commitSealMessage(
+ targetRound.getSequenceNumber(),
+ () -> blockInterface.replaceRoundForCommitBlock(proposalBlock, 0).getHash().getBytes(),
+ commitBlock.getHash()));
commitValidator =
new CommitValidator(
- validators, targetRound, proposalBlock.getHash(), commitBlock.getHash());
+ validators,
+ targetRound,
+ proposalBlock.getHash(),
+ commitBlock.getHash(),
+ expectedPqSealMessage);
}
/**
@@ -76,6 +98,12 @@ public class MessageValidator {
* @param msg the Commit payload msg
* @return the boolean
*/
+ /** AERE D-311: the commit validator this wiring built; for the plumbing proof only. */
+ @com.google.common.annotations.VisibleForTesting
+ CommitValidator commitValidatorForTesting() {
+ return commitValidator;
+ }
+
public boolean validate(final Commit msg) {
return commitValidator.validate(msg);
}
diff --git a/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/validation/PqCommitEnforcement.java b/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/validation/PqCommitEnforcement.java
new file mode 100755
index 000000000..d1aa1be8e
--- /dev/null
+++ b/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/validation/PqCommitEnforcement.java
@@ -0,0 +1,369 @@
+/*
+ * AERE full-PQ consensus (TOP 3 list, item 1), step 1: the enforcement core.
+ *
+ * WHAT IT DECIDES. From the arming height upward, a Commit message counts toward the 2f+1
+ * quorum ONLY if it carries the PQ seal (already transported in CommitPayload, live on the
+ * fleet) and the seal (a) exists, (b) has its index bound to the VERY author of the message
+ * through the height-indexed registry, (c) verifies over the commit digest. Without a valid
+ * PQ seal the vote does not count -- this puts post-quantum into the agreement itself, at the
+ * layer where the D-235 header rule could not live (headers between anchors carry no seals;
+ * the commit message can carry them all).
+ *
+ * HOW IT IS WIRED (updated the same night). CommitValidator calls it through the production
+ * constructor, which self-installs from fromSystemConfig(): absent property = null =
+ * upstream behaviour, DISARMED by default; a broken value = loud refusal, never a silent
+ * disarm. The core stays purely testable: the registry is injected (the PqSignerRegistry
+ * interface, which refuses by construction to answer without a height -- the D2 inheritance);
+ * the singleton enters only through the production factory, exactly like PqAnchorSealsRule.
+ */
+package org.hyperledger.besu.consensus.qbft.core.validation;
+
+import org.hyperledger.besu.consensus.common.bft.FalconSeal;
+import org.hyperledger.besu.consensus.common.bft.HybridSealSupport;
+import org.hyperledger.besu.consensus.common.bft.HybridSignerRegistry;
+import org.hyperledger.besu.consensus.common.bft.PqSchemeSchedule;
+import org.hyperledger.besu.consensus.common.bft.PqSignerRegistry;
+import org.hyperledger.besu.consensus.common.bft.SchemeSeal;
+import org.hyperledger.besu.consensus.common.bft.SealScheme;
+import org.hyperledger.besu.consensus.common.bft.SealSchemes;
+import org.hyperledger.besu.consensus.common.bft.blockcreation.PqAnchorProducer;
+import org.hyperledger.besu.datatypes.Address;
+import org.hyperledger.besu.datatypes.Hash;
+
+import java.util.List;
+import java.util.Optional;
+import java.util.Set;
+import java.util.function.LongPredicate;
+
+import org.apache.tuweni.bytes.Bytes;
+
+/** Height-gated decision: does this Commit's PQ seal let it count toward quorum? */
+public final class PqCommitEnforcement {
+
+ /** The disarmed height: no block ever reaches it, so nothing is enforced. */
+ public static final long DISARMED = Long.MAX_VALUE;
+
+ /**
+ * System property naming the first block height at which a Commit vote no longer counts without
+ * a valid post-quantum seal of its own author. Absent = disarmed, today's behaviour. Delivered
+ * per node through {@code BESU_OPTS}, like every other AERE consensus switch; there is NO
+ * consensus binding on the value, so the fleet must coordinate on it exactly as it does on the
+ * anchor heights. Env: {@code AERE_PQ_COMMITPQ_FORKBLOCK}.
+ */
+ public static final String PROPERTY_FORK_BLOCK = "aere.pq.commitPq.forkBlock";
+
+ /** Environment fallback for {@link #PROPERTY_FORK_BLOCK}. */
+ public static final String ENV_FORK_BLOCK = "AERE_PQ_COMMITPQ_FORKBLOCK";
+
+ /**
+ * The enforcement the production (4-arg) CommitValidator constructor wires in, read fresh from
+ * the system configuration on every call.
+ *
+ * <p>Absent configuration returns null, which CommitValidator treats as upstream behaviour --
+ * the honest default. A PRESENT but unparseable value REFUSES loudly instead of disarming:
+ * the paid-for lesson of the anchor loader is that a mistyped value must never start a node
+ * silently disarmed ("a mistyped comma boots the node DISARMED"). The throw happens at
+ * validator construction, i.e. at the first round the node processes, which is as close to
+ * startup as this layer can get.
+ *
+ * @return the armed enforcement, or null when the property is not set anywhere
+ * @throws IllegalStateException AERE-PQC-COMMIT-CONF-01 when the value is present but not a
+ * non-negative decimal block height
+ */
+ public static PqCommitEnforcement fromSystemConfig() {
+ String raw = System.getProperty(PROPERTY_FORK_BLOCK);
+ if (raw == null) {
+ raw = System.getenv(ENV_FORK_BLOCK);
+ }
+ if (raw == null) {
+ return null;
+ }
+ final long armedFrom;
+ try {
+ armedFrom = Long.parseLong(raw.trim());
+ if (armedFrom < 0) {
+ throw new NumberFormatException("negative");
+ }
+ } catch (final NumberFormatException e) {
+ throw new IllegalStateException(
+ "AERE-PQC-COMMIT-CONF-01: "
+ + PROPERTY_FORK_BLOCK
+ + " is set but not a non-negative block height: '"
+ + raw
+ + "'. A mistyped value must refuse, never silently disarm.");
+ }
+ // AERE HYBRID: when the node has the schedule+registry pair configured, enforcement
+ // receives it too, so from the hybrid step of the schedule onward a vote without ALL the
+ // required schemes does not count. Without the pair, this stays exactly the Falcon
+ // enforcement we had until now.
+ final HybridSealSupport hybrid = HybridSealSupport.instance();
+ if (hybrid.schedule().isPresent()) {
+ return new PqCommitEnforcement(
+ armedFrom,
+ PqSignerRegistry.falconSealSupport(),
+ hybrid.schedule().get(),
+ hybrid.registry().orElseThrow());
+ }
+ return new PqCommitEnforcement(armedFrom, PqSignerRegistry.falconSealSupport());
+ }
+
+ private final long armedFromBlock;
+ private final PqSignerRegistry registry;
+ // AERE HIBRID: null in Falcon-only mode, which is every node today.
+ private final PqSchemeSchedule schemeSchedule;
+ private final HybridSignerRegistry hybridRegistry;
+ private final LongPredicate extrasRequiredAt;
+
+ /**
+ * @param armedFromBlock first block height (inclusive) at which enforcement applies; use
+ * {@link #DISARMED} for the today-behaviour
+ * @param registry the height-aware signer registry (injected, never a singleton)
+ */
+ public PqCommitEnforcement(final long armedFromBlock, final PqSignerRegistry registry) {
+ this(armedFromBlock, registry, null, null);
+ }
+
+ /**
+ * Enforcement that also demands the HYBRID schemes a schedule requires at each height.
+ *
+ * <p>AERE HIBRID (2026-08-25). Above the arming height a vote must carry, besides the Falcon
+ * seal checked by the Falcon-only path, a valid seal for EVERY other scheme the schedule names
+ * at that height. The point of a hybrid is that the two families fail independently, so a
+ * partially satisfied certificate is worth exactly as much as the weakest family present, which
+ * is why a missing scheme refuses rather than degrades.
+ *
+ * <p>NO REGISTRY-ALIGNMENT ASSUMPTION. The hybrid registry and the legacy Falcon registry are
+ * two files, and the paid-for lesson of D-191 is that a pair of files that must agree will one
+ * day not agree. So this code never assumes their index spaces line up: an extra seal must
+ * carry the SAME validator index as the Falcon seal on the same message, and that index must
+ * resolve, IN THE HYBRID REGISTRY, to the very author of the message. Both facts are checked,
+ * neither is assumed.
+ *
+ * @param armedFromBlock first block height (inclusive) at which enforcement applies
+ * @param registry the height-aware Falcon signer registry
+ * @param schemeSchedule which schemes are required at which height; null for Falcon-only
+ * @param hybridRegistry per-validator public keys per scheme; null for Falcon-only
+ */
+ public PqCommitEnforcement(
+ final long armedFromBlock,
+ final PqSignerRegistry registry,
+ final PqSchemeSchedule schemeSchedule,
+ final HybridSignerRegistry hybridRegistry) {
+ this(armedFromBlock, registry, schemeSchedule, hybridRegistry, anchorParentByConfig());
+ }
+
+ /**
+ * ANCHOR PARENTS ONLY (2026-09-03, D-329). An SLH-DSA-SHA2-128s signature costs seconds in this
+ * runtime; demanded on EVERY commit it stretched the testnet from 0.5 s to 4 s per block. The
+ * extra seal is only ever USED in the certificate of the next anchor, which is built from the
+ * seals heard over the anchor's PARENT. So the extra scheme seals are required (and emitted, see
+ * QbftRound) only on commits over a block whose successor is an anchor height. Falcon stays on
+ * every commit, exactly as before.
+ *
+ * @return the predicate "the block at this height is the parent of an anchor", from the live
+ * anchor configuration
+ */
+ public static LongPredicate anchorParentByConfig() {
+ return h -> PqAnchorProducer.config().anchorAppliesAt(h + 1L);
+ }
+
+ /**
+ * Full constructor.
+ *
+ * @param extrasRequiredAt at which heights the extra (non-Falcon) scheme seals are demanded on a
+ * commit; production passes {@link #anchorParentByConfig()}
+ */
+ public PqCommitEnforcement(
+ final long armedFromBlock,
+ final PqSignerRegistry registry,
+ final PqSchemeSchedule schemeSchedule,
+ final HybridSignerRegistry hybridRegistry,
+ final LongPredicate extrasRequiredAt) {
+ this.armedFromBlock = armedFromBlock;
+ this.registry = registry;
+ this.schemeSchedule = schemeSchedule;
+ this.hybridRegistry = hybridRegistry;
+ this.extrasRequiredAt = extrasRequiredAt;
+ if ((schemeSchedule == null) != (hybridRegistry == null)) {
+ // Half a hybrid configuration is the shape that starts a node believing it enforces
+ // something it does not. Refuse at construction, the same stance as every other AERE gate.
+ throw new IllegalStateException(
+ "AERE-PQC-COMMIT-CONF-03: the scheme schedule and the hybrid registry are a PAIR;"
+ + " configure both or neither.");
+ }
+ }
+
+ /** Whether enforcement is active at {@code height}. */
+ public boolean armedAt(final long height) {
+ return height >= armedFromBlock;
+ }
+
+ /**
+ * Decide whether a Commit may count toward quorum.
+ *
+ * @param height the block height the commit targets (the round's sequence number)
+ * @param author the RECOVERED author of the signed Commit message (from its ECDSA signature)
+ * @param commitDigest the commit digest the PQ seal must have signed
+ * @param seal the optional PQ seal carried inside the payload
+ * @return empty when the commit counts; otherwise the refusal, with names and numbers
+ */
+ public Optional<String> refusal(
+ final long height,
+ final Address author,
+ final Hash commitDigest,
+ final Optional<FalconSeal> seal) {
+ return refusal(height, author, commitDigest, seal, List.of());
+ }
+
+ /**
+ * Decide whether a Commit may count toward quorum, hybrid certificate included.
+ *
+ * @param height the block height the commit targets
+ * @param author the RECOVERED author of the signed Commit message
+ * @param commitDigest the commit digest every seal must have signed
+ * @param seal the Falcon seal carried in its own slot
+ * @param extraSeals the non-Falcon scheme seals carried alongside it
+ * @return empty when the commit counts; otherwise the refusal, with names and numbers
+ */
+ public Optional<String> refusal(
+ final long height,
+ final Address author,
+ final Hash commitDigest,
+ final Optional<FalconSeal> seal,
+ final List<SchemeSeal> extraSeals) {
+ final Optional<String> falconVerdict = falconRefusal(height, author, commitDigest, seal);
+ if (falconVerdict.isPresent()
+ || !armedAt(height)
+ || schemeSchedule == null
+ || !extrasRequiredAt.test(height)) {
+ return falconVerdict;
+ }
+ return hybridRefusal(height, author, commitDigest, seal.orElseThrow(), extraSeals);
+ }
+
+ /**
+ * Every scheme the schedule names at this height, other than Falcon, must be present and valid.
+ */
+ private Optional<String> hybridRefusal(
+ final long height,
+ final Address author,
+ final Hash commitDigest,
+ final FalconSeal falconSeal,
+ final List<SchemeSeal> extraSeals) {
+ final Set<String> required = schemeSchedule.schemesAt(height);
+ for (final String schemeId : required) {
+ if (SealSchemes.FALCON_512.id().equals(schemeId)) {
+ continue; // already decided by the Falcon path above
+ }
+ final Optional<SealScheme> scheme = SealSchemes.byId(schemeId);
+ if (scheme.isEmpty()) {
+ return Optional.of(
+ "AERE HIBRID: the schedule requires scheme '" + schemeId + "' at height " + height
+ + " and this binary does not implement it - refusing rather than ignoring it");
+ }
+ final byte wire = scheme.get().wireId();
+ SchemeSeal found = null;
+ for (final SchemeSeal candidate : extraSeals) {
+ if (candidate.getSchemeWireId() == wire) {
+ found = candidate;
+ break;
+ }
+ }
+ if (found == null) {
+ return Optional.of(
+ "AERE HIBRID: commit at height " + height + " carries no " + schemeId
+ + " seal, which the schedule requires - the vote does not count");
+ }
+ // One identity per message: the hybrid seal must speak for the same validator as the Falcon
+ // seal, and that index must be THIS author in the hybrid registry. Neither is assumed.
+ if (found.getValidatorIndex() != falconSeal.getValidatorIndex()) {
+ return Optional.of(
+ "AERE HIBRID: " + schemeId + " seal is index " + found.getValidatorIndex()
+ + " but the Falcon seal on the same commit is index "
+ + falconSeal.getValidatorIndex() + " - one commit, one signer");
+ }
+ final Optional<byte[]> bound = hybridRegistry.address(found.getValidatorIndex());
+ if (bound.isEmpty()
+ || !Address.wrap(Bytes.wrap(bound.get())).equals(author)) {
+ return Optional.of(
+ "AERE HIBRID: index " + found.getValidatorIndex()
+ + " is not bound to the commit author " + author + " in the hybrid registry");
+ }
+ final Optional<byte[]> publicKey =
+ hybridRegistry.publicKey(found.getValidatorIndex(), schemeId);
+ if (publicKey.isEmpty()) {
+ return Optional.of(
+ "AERE HIBRID: the hybrid registry holds no " + schemeId + " key for index "
+ + found.getValidatorIndex());
+ }
+ final boolean valid;
+ try {
+ valid =
+ scheme
+ .get()
+ .verifyRaw(
+ publicKey.get(),
+ commitDigest.getBytes().toArray(),
+ found.getSignature().toArray());
+ } catch (final RuntimeException e) {
+ return Optional.of(
+ "AERE HIBRID: " + schemeId + " verification threw at height " + height + ": "
+ + e.getMessage());
+ }
+ if (!valid) {
+ return Optional.of(
+ "AERE HIBRID: the " + schemeId + " seal of index " + found.getValidatorIndex()
+ + " does NOT verify over the commit digest at height " + height
+ + " - the vote does not count");
+ }
+ }
+ return Optional.empty();
+ }
+
+ private Optional<String> falconRefusal(
+ final long height,
+ final Address author,
+ final Hash commitDigest,
+ final Optional<FalconSeal> seal) {
+ if (!armedAt(height)) {
+ return Optional.empty();
+ }
+ if (seal == null || seal.isEmpty()) {
+ return Optional.of(
+ "AERE FULL-PQ: commit at height " + height + " carries NO post-quantum seal and "
+ + "enforcement is armed from " + armedFromBlock + " - the vote does not count");
+ }
+ final FalconSeal fs = seal.get();
+ final Address bound;
+ try {
+ bound = registry.addressForIndexAtOwnHead(height, fs.getValidatorIndex());
+ } catch (final RuntimeException e) {
+ return Optional.of(
+ "AERE FULL-PQ: registry refused index " + fs.getValidatorIndex() + " at height "
+ + height + ": " + e.getMessage());
+ }
+ if (bound == null || !bound.equals(author)) {
+ return Optional.of(
+ "AERE FULL-PQ: seal index " + fs.getValidatorIndex() + " is bound to "
+ + bound + " but the commit was authored by " + author
+ + " - a seal cannot vouch for someone else's vote");
+ }
+ final boolean valid;
+ try {
+ valid =
+ registry.verifyAtOwnHead(
+ height, fs.getValidatorIndex(), commitDigest.getBytes(), fs.getSignature());
+ } catch (final RuntimeException e) {
+ return Optional.of(
+ "AERE FULL-PQ: verification threw for index " + fs.getValidatorIndex() + " at height "
+ + height + ": " + e.getMessage());
+ }
+ if (!valid) {
+ return Optional.of(
+ "AERE FULL-PQ: post-quantum seal of index " + fs.getValidatorIndex()
+ + " does NOT verify over the commit digest at height " + height
+ + " - the vote does not count");
+ }
+ return Optional.empty();
+ }
+}
diff --git a/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/validation/PqPrepareEnforcement.java b/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/validation/PqPrepareEnforcement.java
new file mode 100755
index 000000000..c95fdf691
--- /dev/null
+++ b/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/validation/PqPrepareEnforcement.java
@@ -0,0 +1,206 @@
+/*
+ * Copyright contributors to Besu.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.qbft.core.validation;
+
+import org.hyperledger.besu.consensus.common.bft.FalconSeal;
+import org.hyperledger.besu.consensus.common.bft.PqAnchor;
+import org.hyperledger.besu.consensus.common.bft.blockcreation.PqAnchorProducer;
+import org.hyperledger.besu.consensus.common.bft.PqSignerRegistry;
+import org.hyperledger.besu.datatypes.Address;
+import org.hyperledger.besu.datatypes.Hash;
+
+import java.util.Optional;
+
+import org.apache.tuweni.bytes.Bytes32;
+
+/**
+ * POST-QUANTUM ENFORCEMENT ON PREPARE. Step 4 of the design note
+ * PREPARE-SI-ROUNDCHANGE-SUB-PQ-PROIECTARE-2026-08-28.
+ *
+ * <p>From the armed height onwards, a PREPARE does not count without a valid post-quantum seal from
+ * its OWN author. The structure copies {@link PqCommitEnforcement} line for line on purpose: a
+ * second rendering of the same idea, written differently, diverges from the first one eventually.
+ *
+ * <p><b>WHY THIS IS A DIFFERENT LAYER FROM COMMIT, AND MORE DANGEROUS.</b> Measured 2026-08-28
+ * (finding D-277): commit enforcement can be bypassed by a single unarmed proposer. It gathers the
+ * commits, forms the block, and the others import it, because block import validates the HEADER,
+ * not the votes. PREPARE does not work that way: an armed node that refuses unsealed PREPAREs never
+ * reaches the "prepared" state, so it never sends COMMIT at all, and the unarmed node alone is not
+ * a quorum. So PREPARE enforcement is STRICTLY STRONGER - and that is exactly why it no longer has
+ * the safety net commit had during an activation. Arm it only after coverage has been measured.
+ *
+ * <p><b>WHAT THE SEAL SIGNS, AND WHY NOT THE SAME THING AS COMMIT.</b> Its own domain,
+ * {@code AERE-PQ-PREPARE-1}, over (chainId, height, ROUND, digest). Under the commit domain, a
+ * PREPARE seal produced HONESTLY could be pasted onto a forged COMMIT and the enforcement there
+ * would accept it. The round is part of the message too: two PREPAREs for the same block in
+ * different rounds are two different assertions, and a seal from a failed round must not justify
+ * another one.
+ *
+ * <p><b>DISARMED BY DEFAULT.</b> Without the property, {@link #fromSystemConfig()} returns null and
+ * the validator behaves exactly as upstream. A value that is PRESENT but unreadable REFUSES loudly:
+ * a node that boots disarmed because of a mistyped character looks exactly like a correctly
+ * configured one, right up to the day it matters.
+ */
+public final class PqPrepareEnforcement {
+
+ /** The height nothing ever reaches: disarmed. */
+ public static final long DISARMED = Long.MAX_VALUE;
+
+ /** The property that arms PREPARE enforcement. */
+ public static final String PROPERTY_FORK_BLOCK = "aere.pq.preparePq.forkBlock";
+
+ /** The equivalent environment variable. */
+ public static final String ENV_FORK_BLOCK = "AERE_PQ_PREPAREPQ_FORKBLOCK";
+
+ private final long armedFromBlock;
+ private final PqSignerRegistry registry;
+ private final long chainId;
+
+ /**
+ * @param armedFromBlock first height (inclusive) at which enforcement applies; {@link #DISARMED}
+ * for today's behaviour
+ * @param registry the signer registry, injected, never a singleton
+ * @param chainId the chain that goes into the signed message
+ */
+ public PqPrepareEnforcement(
+ final long armedFromBlock, final PqSignerRegistry registry, final long chainId) {
+ this.armedFromBlock = armedFromBlock;
+ this.registry = registry;
+ this.chainId = chainId;
+ }
+
+ /**
+ * The same enforcement, with the chain id taken from the anchor configuration.
+ *
+ * <p>THE CHAIN ID IS AN ARGUMENT, NOT A GLOBAL, and its own test caught that: the first version
+ * read it from {@code PqAnchorProducer.config()} in the middle of a consensus decision, so the
+ * test signed over 2800 while the enforcement verified over whatever the process configuration
+ * happened to be. A consensus decision that depends on global state cannot be tested honestly,
+ * and cannot be read either. The factories below fetch the value once, at construction, where it
+ * is visible.
+ *
+ * @param armedFromBlock first height at which enforcement applies
+ * @param registry the signer registry
+ */
+ public PqPrepareEnforcement(final long armedFromBlock, final PqSignerRegistry registry) {
+ this(armedFromBlock, registry, PqAnchorProducer.config().chainId());
+ }
+
+ /**
+ * The configured enforcement, read FRESH on every call.
+ *
+ * @return the armed enforcement, or null when the property is set nowhere
+ * @throws IllegalStateException AERE-PQC-PREPARE-ENF-01 when the value is present but is not a
+ * non-negative decimal height
+ */
+ public static PqPrepareEnforcement fromSystemConfig() {
+ String raw = System.getProperty(PROPERTY_FORK_BLOCK);
+ if (raw == null) {
+ raw = System.getenv(ENV_FORK_BLOCK);
+ }
+ if (raw == null || raw.isBlank()) {
+ return null;
+ }
+ final long armedFrom;
+ try {
+ armedFrom = Long.parseLong(raw.trim());
+ if (armedFrom < 0) {
+ throw new NumberFormatException("negative");
+ }
+ } catch (final NumberFormatException e) {
+ throw new IllegalStateException(
+ "AERE-PQC-PREPARE-ENF-01: "
+ + PROPERTY_FORK_BLOCK
+ + " is set but not a non-negative block height: '"
+ + raw
+ + "'. A mistyped value must refuse, never silently disarm.");
+ }
+ return new PqPrepareEnforcement(armedFrom, PqSignerRegistry.falconSealSupport());
+ }
+
+ /** Whether enforcement is active at this height. */
+ public boolean armedAt(final long height) {
+ return height >= armedFromBlock;
+ }
+
+ /**
+ * Decides whether a PREPARE may count.
+ *
+ * @param height the height the PREPARE targets (the round's sequence number)
+ * @param round the PREPARE's round; it is part of the signed message
+ * @param author the RECOVERED author of the signed message (from its ECDSA signature)
+ * @param digest the digest of the block the PREPARE speaks about
+ * @param seal the post-quantum seal carried by the payload, if any
+ * @return empty when the PREPARE counts; otherwise the refusal, with names and numbers
+ */
+ public Optional<String> refusal(
+ final long height,
+ final int round,
+ final Address author,
+ final Hash digest,
+ final Optional<FalconSeal> seal) {
+ if (!armedAt(height)) {
+ return Optional.empty();
+ }
+ if (seal == null || seal.isEmpty()) {
+ return Optional.of(
+ "AERE FULL-PQ: prepare at height " + height + " round " + round
+ + " carries NO post-quantum seal and enforcement is armed from " + armedFromBlock
+ + " - the vote does not count");
+ }
+ final FalconSeal fs = seal.get();
+ final Address bound;
+ try {
+ bound = registry.addressForIndexAtOwnHead(height, fs.getValidatorIndex());
+ } catch (final RuntimeException e) {
+ return Optional.of(
+ "AERE FULL-PQ: registry refused index " + fs.getValidatorIndex() + " at height "
+ + height + ": " + e.getMessage());
+ }
+ if (bound == null || !bound.equals(author)) {
+ return Optional.of(
+ "AERE FULL-PQ: prepare seal index " + fs.getValidatorIndex() + " is bound to " + bound
+ + " but the prepare was authored by " + author
+ + " - a seal cannot vouch for someone else's vote");
+ }
+
+ final Bytes32 message;
+ try {
+ message = PqAnchor.prepareMessage(chainId, height, round, digest.getBytes());
+ } catch (final RuntimeException e) {
+ // A message we cannot build means we cannot judge, and "cannot judge" must never be a pass:
+ // that would be exactly the silent disarming this file exists to refuse.
+ return Optional.of(
+ "AERE FULL-PQ: could not build the prepare message at height " + height + " round "
+ + round + ": " + e.getMessage());
+ }
+
+ final boolean valid;
+ try {
+ valid = registry.verifyAtOwnHead(height, fs.getValidatorIndex(), message, fs.getSignature());
+ } catch (final RuntimeException e) {
+ return Optional.of(
+ "AERE FULL-PQ: verification threw for index " + fs.getValidatorIndex() + " at height "
+ + height + ": " + e.getMessage());
+ }
+ if (!valid) {
+ return Optional.of(
+ "AERE FULL-PQ: post-quantum seal of index " + fs.getValidatorIndex()
+ + " does NOT verify over the prepare message at height " + height + " round " + round
+ + " - the vote does not count");
+ }
+ return Optional.empty();
+ }
+}
diff --git a/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/validation/PqProposalEnforcement.java b/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/validation/PqProposalEnforcement.java
new file mode 100755
index 000000000..ea8817cd6
--- /dev/null
+++ b/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/validation/PqProposalEnforcement.java
@@ -0,0 +1,202 @@
+/*
+ * Copyright contributors to Besu.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.qbft.core.validation;
+
+import org.hyperledger.besu.consensus.common.bft.FalconSeal;
+import org.hyperledger.besu.consensus.common.bft.PqAnchor;
+import org.hyperledger.besu.consensus.common.bft.blockcreation.PqAnchorProducer;
+import org.hyperledger.besu.consensus.common.bft.PqSignerRegistry;
+import org.hyperledger.besu.datatypes.Address;
+import org.hyperledger.besu.datatypes.Hash;
+
+import java.util.Optional;
+
+import org.apache.tuweni.bytes.Bytes32;
+
+/**
+ * POST-QUANTUM ENFORCEMENT ON THE PROPOSAL. The hot-path step after PREPARE (AERE PQ, 2026-08-30).
+ *
+ * <p>From the armed height onwards, a PROPOSAL is not accepted without a valid post-quantum seal
+ * from its OWN proposer. The structure copies {@link PqProposalEnforcement} line for line on
+ * purpose: a second rendering of the same idea, written differently, diverges eventually.
+ *
+ * <p><b>WHAT THIS LAYER BUYS, said precisely.</b> A proposal is an OFFER, not a vote: the design
+ * note of 2026-08-28 measures that "prepared" needs a full quorum of PREPAREs, proposer included,
+ * so an adversary who breaks ECDSA and forges proposals still cannot finalize anything while the
+ * PREPARE layer is armed. What forged proposals CAN do is start rounds and waste them - steering
+ * which honest proposals get considered and degrading liveness. This layer closes that: a proposal
+ * whose proposer cannot produce a Falcon seal does not even open a round on an armed node.
+ *
+ * <p><b>WHAT THE SEAL SIGNS.</b> Its own domain, {@code AERE-PQ-PROPOSAL-1}, over (chainId,
+ * height, ROUND, digest). Under the PREPARE or commit domain, a proposal seal given honestly could
+ * be pasted onto a forged vote and counted; one changed string in the preimage makes the
+ * signatures non-transferable in both directions.
+ *
+ * <p><b>DISARMED BY DEFAULT.</b> Without the property, {@link #fromSystemConfig()} returns null and
+ * the validator behaves exactly as upstream. A value that is PRESENT but unreadable REFUSES loudly:
+ * a node that boots disarmed because of a mistyped character looks exactly like a correctly
+ * configured one, right up to the day it matters.
+ */
+public final class PqProposalEnforcement {
+
+ /** The height nothing ever reaches: disarmed. */
+ public static final long DISARMED = Long.MAX_VALUE;
+
+ /** The property that arms PROPOSAL enforcement. */
+ public static final String PROPERTY_FORK_BLOCK = "aere.pq.proposalPq.forkBlock";
+
+ /** The equivalent environment variable. */
+ public static final String ENV_FORK_BLOCK = "AERE_PQ_PROPOSALPQ_FORKBLOCK";
+
+ private final long armedFromBlock;
+ private final PqSignerRegistry registry;
+ private final long chainId;
+
+ /**
+ * @param armedFromBlock first height (inclusive) at which enforcement applies; {@link #DISARMED}
+ * for today's behaviour
+ * @param registry the signer registry, injected, never a singleton
+ * @param chainId the chain that goes into the signed message
+ */
+ public PqProposalEnforcement(
+ final long armedFromBlock, final PqSignerRegistry registry, final long chainId) {
+ this.armedFromBlock = armedFromBlock;
+ this.registry = registry;
+ this.chainId = chainId;
+ }
+
+ /**
+ * The same enforcement, with the chain id taken from the anchor configuration.
+ *
+ * <p>THE CHAIN ID IS AN ARGUMENT, NOT A GLOBAL, and its own test caught that: the first version
+ * read it from {@code PqAnchorProducer.config()} in the middle of a consensus decision, so the
+ * test signed over 2800 while the enforcement verified over whatever the process configuration
+ * happened to be. A consensus decision that depends on global state cannot be tested honestly,
+ * and cannot be read either. The factories below fetch the value once, at construction, where it
+ * is visible.
+ *
+ * @param armedFromBlock first height at which enforcement applies
+ * @param registry the signer registry
+ */
+ public PqProposalEnforcement(final long armedFromBlock, final PqSignerRegistry registry) {
+ this(armedFromBlock, registry, PqAnchorProducer.config().chainId());
+ }
+
+ /**
+ * The configured enforcement, read FRESH on every call.
+ *
+ * @return the armed enforcement, or null when the property is set nowhere
+ * @throws IllegalStateException AERE-PQC-PROPOSAL-ENF-01 when the value is present but is not a
+ * non-negative decimal height
+ */
+ public static PqProposalEnforcement fromSystemConfig() {
+ String raw = System.getProperty(PROPERTY_FORK_BLOCK);
+ if (raw == null) {
+ raw = System.getenv(ENV_FORK_BLOCK);
+ }
+ if (raw == null || raw.isBlank()) {
+ return null;
+ }
+ final long armedFrom;
+ try {
+ armedFrom = Long.parseLong(raw.trim());
+ if (armedFrom < 0) {
+ throw new NumberFormatException("negative");
+ }
+ } catch (final NumberFormatException e) {
+ throw new IllegalStateException(
+ "AERE-PQC-PROPOSAL-ENF-01: "
+ + PROPERTY_FORK_BLOCK
+ + " is set but not a non-negative block height: '"
+ + raw
+ + "'. A mistyped value must refuse, never silently disarm.");
+ }
+ return new PqProposalEnforcement(armedFrom, PqSignerRegistry.falconSealSupport());
+ }
+
+ /** Whether enforcement is active at this height. */
+ public boolean armedAt(final long height) {
+ return height >= armedFromBlock;
+ }
+
+ /**
+ * Decides whether a PROPOSAL may be accepted.
+ *
+ * @param height the height the PROPOSAL targets (the round's sequence number)
+ * @param round the PROPOSAL's round; it is part of the signed message
+ * @param author the RECOVERED author of the signed message (from its ECDSA signature)
+ * @param digest the digest of the proposed block
+ * @param seal the post-quantum seal carried by the payload, if any
+ * @return empty when the PROPOSAL is acceptable; otherwise the refusal, with names and numbers
+ */
+ public Optional<String> refusal(
+ final long height,
+ final int round,
+ final Address author,
+ final Hash digest,
+ final Optional<FalconSeal> seal) {
+ if (!armedAt(height)) {
+ return Optional.empty();
+ }
+ if (seal == null || seal.isEmpty()) {
+ return Optional.of(
+ "AERE FULL-PQ: proposal at height " + height + " round " + round
+ + " carries NO post-quantum seal and enforcement is armed from " + armedFromBlock
+ + " - the proposal is refused");
+ }
+ final FalconSeal fs = seal.get();
+ final Address bound;
+ try {
+ bound = registry.addressForIndexAtOwnHead(height, fs.getValidatorIndex());
+ } catch (final RuntimeException e) {
+ return Optional.of(
+ "AERE FULL-PQ: registry refused index " + fs.getValidatorIndex() + " at height "
+ + height + ": " + e.getMessage());
+ }
+ if (bound == null || !bound.equals(author)) {
+ return Optional.of(
+ "AERE FULL-PQ: proposal seal index " + fs.getValidatorIndex() + " is bound to " + bound
+ + " but the proposal was authored by " + author
+ + " - a seal cannot vouch for someone else's proposal");
+ }
+
+ final Bytes32 message;
+ try {
+ message = PqAnchor.proposalMessage(chainId, height, round, digest.getBytes());
+ } catch (final RuntimeException e) {
+ // A message we cannot build means we cannot judge, and "cannot judge" must never be a pass:
+ // that would be exactly the silent disarming this file exists to refuse.
+ return Optional.of(
+ "AERE FULL-PQ: could not build the proposal message at height " + height + " round "
+ + round + ": " + e.getMessage());
+ }
+
+ final boolean valid;
+ try {
+ valid = registry.verifyAtOwnHead(height, fs.getValidatorIndex(), message, fs.getSignature());
+ } catch (final RuntimeException e) {
+ return Optional.of(
+ "AERE FULL-PQ: verification threw for index " + fs.getValidatorIndex() + " at height "
+ + height + ": " + e.getMessage());
+ }
+ if (!valid) {
+ return Optional.of(
+ "AERE FULL-PQ: post-quantum seal of index " + fs.getValidatorIndex()
+ + " does NOT verify over the proposal message at height " + height + " round " + round
+ + " - the proposal is refused");
+ }
+ return Optional.empty();
+ }
+}
diff --git a/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/validation/PqRoundChangeEnforcement.java b/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/validation/PqRoundChangeEnforcement.java
new file mode 100755
index 000000000..1b952f619
--- /dev/null
+++ b/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/validation/PqRoundChangeEnforcement.java
@@ -0,0 +1,209 @@
+/*
+ * Copyright contributors to Besu.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.qbft.core.validation;
+
+import org.hyperledger.besu.consensus.common.bft.FalconSeal;
+import org.hyperledger.besu.consensus.common.bft.PqAnchor;
+import org.hyperledger.besu.consensus.common.bft.blockcreation.PqAnchorProducer;
+import org.hyperledger.besu.consensus.common.bft.PqSignerRegistry;
+import org.hyperledger.besu.consensus.qbft.core.payload.PreparedRoundMetadata;
+import org.hyperledger.besu.datatypes.Address;
+
+import java.util.Optional;
+
+import org.apache.tuweni.bytes.Bytes32;
+
+/**
+ * POST-QUANTUM ENFORCEMENT ON THE ROUND-CHANGE. The last hot-path message (AERE PQ, 2026-08-31).
+ *
+ * <p>From the armed height onwards, a ROUND-CHANGE is not accepted without a valid post-quantum
+ * seal from its OWN author. The structure copies {@link PqProposalEnforcement} line for line on
+ * purpose: a second rendering of the same idea, written differently, diverges eventually.
+ *
+ * <p><b>WHAT THIS LAYER BUYS, said precisely.</b> With PREPARE armed, an adversary who breaks
+ * ECDSA cannot finalize; with PROPOSAL armed, it cannot open rounds. What it can still do is FORCE
+ * round changes: a forged quorum of round-changes moves every honest node to a round of the
+ * adversary's choosing, over and over - the remaining liveness lever, and, because a round-change
+ * may claim a prepared block, a lever over WHICH block gets re-proposed. This layer closes it: a
+ * round-change whose author cannot produce a Falcon seal does not count towards a round change on
+ * an armed node.
+ *
+ * <p><b>WHAT THE SEAL SIGNS.</b> Its own domain, {@code AERE-PQ-ROUNDCHANGE-1}, over (chainId,
+ * height, targetRound, prepared metadata). The metadata is in the preimage so a seal from a bare
+ * round-change cannot be pasted onto one that claims a prepared block, and vice versa.
+ *
+ * <p><b>DISARMED BY DEFAULT.</b> Without the property, {@link #fromSystemConfig()} returns null and
+ * the validator behaves exactly as upstream. A value that is PRESENT but unreadable REFUSES loudly:
+ * a node that boots disarmed because of a mistyped character looks exactly like a correctly
+ * configured one, right up to the day it matters.
+ */
+public final class PqRoundChangeEnforcement {
+
+ /** The height nothing ever reaches: disarmed. */
+ public static final long DISARMED = Long.MAX_VALUE;
+
+ /** The property that arms ROUND-CHANGE enforcement. */
+ public static final String PROPERTY_FORK_BLOCK = "aere.pq.roundChangePq.forkBlock";
+
+ /** The equivalent environment variable. */
+ public static final String ENV_FORK_BLOCK = "AERE_PQ_ROUNDCHANGEPQ_FORKBLOCK";
+
+ private final long armedFromBlock;
+ private final PqSignerRegistry registry;
+ private final long chainId;
+
+ /**
+ * @param armedFromBlock first height (inclusive) at which enforcement applies; {@link #DISARMED}
+ * for today's behaviour
+ * @param registry the signer registry, injected, never a singleton
+ * @param chainId the chain that goes into the signed message
+ */
+ public PqRoundChangeEnforcement(
+ final long armedFromBlock, final PqSignerRegistry registry, final long chainId) {
+ this.armedFromBlock = armedFromBlock;
+ this.registry = registry;
+ this.chainId = chainId;
+ }
+
+ /**
+ * The same enforcement, with the chain id taken from the anchor configuration.
+ *
+ * <p>THE CHAIN ID IS AN ARGUMENT, NOT A GLOBAL - the PROPOSAL enforcement's own test caught the
+ * version that read it mid-decision. The factories fetch the value once, at construction, where
+ * it is visible.
+ *
+ * @param armedFromBlock first height at which enforcement applies
+ * @param registry the signer registry
+ */
+ public PqRoundChangeEnforcement(final long armedFromBlock, final PqSignerRegistry registry) {
+ this(armedFromBlock, registry, PqAnchorProducer.config().chainId());
+ }
+
+ /**
+ * The configured enforcement, read FRESH on every call.
+ *
+ * @return the armed enforcement, or null when the property is set nowhere
+ * @throws IllegalStateException AERE-PQC-ROUNDCHANGE-ENF-01 when the value is present but is not
+ * a non-negative decimal height
+ */
+ public static PqRoundChangeEnforcement fromSystemConfig() {
+ String raw = System.getProperty(PROPERTY_FORK_BLOCK);
+ if (raw == null) {
+ raw = System.getenv(ENV_FORK_BLOCK);
+ }
+ if (raw == null || raw.isBlank()) {
+ return null;
+ }
+ final long armedFrom;
+ try {
+ armedFrom = Long.parseLong(raw.trim());
+ if (armedFrom < 0) {
+ throw new NumberFormatException("negative");
+ }
+ } catch (final NumberFormatException e) {
+ throw new IllegalStateException(
+ "AERE-PQC-ROUNDCHANGE-ENF-01: "
+ + PROPERTY_FORK_BLOCK
+ + " is set but not a non-negative block height: '"
+ + raw
+ + "'. A mistyped value must refuse, never silently disarm.");
+ }
+ return new PqRoundChangeEnforcement(armedFrom, PqSignerRegistry.falconSealSupport());
+ }
+
+ /** Whether enforcement is active at this height. */
+ public boolean armedAt(final long height) {
+ return height >= armedFromBlock;
+ }
+
+ /**
+ * Decides whether a ROUND-CHANGE may be accepted.
+ *
+ * @param height the height the round-change targets (the round's sequence number)
+ * @param targetRound the round the author wants to move to; it is part of the signed message
+ * @param author the RECOVERED author of the signed message (from its ECDSA signature)
+ * @param preparedRoundMetadata the prepared-round claim carried by the payload, if any; it is
+ * part of the signed message
+ * @param seal the post-quantum seal carried by the payload, if any
+ * @return empty when the round-change is acceptable; otherwise the refusal, with names and
+ * numbers
+ */
+ public Optional<String> refusal(
+ final long height,
+ final int targetRound,
+ final Address author,
+ final Optional<PreparedRoundMetadata> preparedRoundMetadata,
+ final Optional<FalconSeal> seal) {
+ if (!armedAt(height)) {
+ return Optional.empty();
+ }
+ if (seal == null || seal.isEmpty()) {
+ return Optional.of(
+ "AERE FULL-PQ: round-change at height " + height + " towards round " + targetRound
+ + " carries NO post-quantum seal and enforcement is armed from " + armedFromBlock
+ + " - the round-change is refused");
+ }
+ final FalconSeal fs = seal.get();
+ final Address bound;
+ try {
+ bound = registry.addressForIndexAtOwnHead(height, fs.getValidatorIndex());
+ } catch (final RuntimeException e) {
+ return Optional.of(
+ "AERE FULL-PQ: registry refused index " + fs.getValidatorIndex() + " at height "
+ + height + ": " + e.getMessage());
+ }
+ if (bound == null || !bound.equals(author)) {
+ return Optional.of(
+ "AERE FULL-PQ: round-change seal index " + fs.getValidatorIndex() + " is bound to "
+ + bound + " but the round-change was authored by " + author
+ + " - a seal cannot vouch for someone else's round-change");
+ }
+
+ final Bytes32 message;
+ try {
+ message =
+ preparedRoundMetadata.isPresent()
+ ? PqAnchor.roundChangeMessage(
+ chainId,
+ height,
+ targetRound,
+ preparedRoundMetadata.get().getPreparedRound(),
+ preparedRoundMetadata.get().getPreparedBlockHash().getBytes())
+ : PqAnchor.roundChangeMessage(chainId, height, targetRound);
+ } catch (final RuntimeException e) {
+ // A message we cannot build means we cannot judge, and "cannot judge" must never be a pass:
+ // that would be exactly the silent disarming this file exists to refuse.
+ return Optional.of(
+ "AERE FULL-PQ: could not build the round-change message at height " + height
+ + " towards round " + targetRound + ": " + e.getMessage());
+ }
+
+ final boolean valid;
+ try {
+ valid = registry.verifyAtOwnHead(height, fs.getValidatorIndex(), message, fs.getSignature());
+ } catch (final RuntimeException e) {
+ return Optional.of(
+ "AERE FULL-PQ: verification threw for index " + fs.getValidatorIndex() + " at height "
+ + height + ": " + e.getMessage());
+ }
+ if (!valid) {
+ return Optional.of(
+ "AERE FULL-PQ: post-quantum seal of index " + fs.getValidatorIndex()
+ + " does NOT verify over the round-change message at height " + height
+ + " towards round " + targetRound + " - the round-change is refused");
+ }
+ return Optional.empty();
+ }
+}
diff --git a/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/validation/PrepareValidator.java b/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/validation/PrepareValidator.java
index 61bde6a80..bfe651ad6 100644
--- a/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/validation/PrepareValidator.java
+++ b/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/validation/PrepareValidator.java
@@ -11,6 +11,12 @@
* specific language governing permissions and limitations under the License.
*
* SPDX-License-Identifier: Apache-2.0
+ *
+ * Modifications Copyright contributors to the Aere Network.
+ *
+ * This file was modified by contributors to the Aere Network, as required by section 4(b) of the
+ * Apache License 2.0. The copyright header above is the upstream one and is left exactly as it was
+ * found, as section 4(c) requires. The change itself is in patches/0003-aere-pq-anchor.patch.
*/
package org.hyperledger.besu.consensus.qbft.core.validation;
@@ -22,11 +28,20 @@ import org.hyperledger.besu.datatypes.Address;
import org.hyperledger.besu.datatypes.Hash;
import java.util.Collection;
+import java.util.Optional;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
-/** The Prepare validator. */
+/**
+ * The Prepare validator.
+ *
+ * <p>AERE (2026-08-29), step 4 of PREPARE-SI-ROUNDCHANGE-SUB-PQ-PROIECTARE-2026-08-28: an OPTIONAL
+ * post-quantum enforcement hook, gated on height (see {@link PqPrepareEnforcement}). When no
+ * enforcement is supplied, behaviour is byte for byte the upstream one - and that is the
+ * configuration of every node today. Same pattern as {@link CommitValidator}, deliberately: a
+ * second rendering of the same idea, written differently, diverges eventually.
+ */
public class PrepareValidator {
private static final String ERROR_PREFIX = "Invalid Prepare Message";
@@ -36,9 +51,13 @@ public class PrepareValidator {
private final Collection<Address> validators;
private final ConsensusRoundIdentifier targetRound;
private final Hash expectedDigest;
+ // AERE full-PQ: optional enforcement, gated on height. Null means upstream behaviour, which is
+ // exactly what runs on every node today.
+ private final PqPrepareEnforcement pqEnforcement;
/**
- * Instantiates a new Prepare validator.
+ * Instantiates a new Prepare validator, self-wiring the AERE post-quantum enforcement from the
+ * system configuration. Without the arming property the hook is null and nothing changes.
*
* @param validators the validators
* @param targetRound the target round
@@ -48,9 +67,26 @@ public class PrepareValidator {
final Collection<Address> validators,
final ConsensusRoundIdentifier targetRound,
final Hash expectedDigest) {
+ this(validators, targetRound, expectedDigest, PqPrepareEnforcement.fromSystemConfig());
+ }
+
+ /**
+ * Instantiates a new Prepare validator with optional post-quantum enforcement.
+ *
+ * @param validators the validators
+ * @param targetRound the target round
+ * @param expectedDigest the expected digest
+ * @param pqEnforcement the height-gated enforcement, or null for upstream behaviour
+ */
+ public PrepareValidator(
+ final Collection<Address> validators,
+ final ConsensusRoundIdentifier targetRound,
+ final Hash expectedDigest,
+ final PqPrepareEnforcement pqEnforcement) {
this.validators = validators;
this.targetRound = targetRound;
this.expectedDigest = expectedDigest;
+ this.pqEnforcement = pqEnforcement;
}
/**
@@ -87,6 +123,22 @@ public class PrepareValidator {
return false;
}
+ // AERE full-PQ: from the armed height on, a PREPARE counts only with a valid post-quantum seal
+ // bound to THIS very author. Below it, or with no enforcement supplied, nothing changes.
+ if (pqEnforcement != null) {
+ final Optional<String> refusal =
+ pqEnforcement.refusal(
+ targetRound.getSequenceNumber(),
+ targetRound.getRoundNumber(),
+ signedPayload.getAuthor(),
+ expectedDigest,
+ payload.getFalconSeal());
+ if (refusal.isPresent()) {
+ LOG.info("{}: {}", ERROR_PREFIX, refusal.get());
+ return false;
+ }
+ }
+
return true;
}
}
diff --git a/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/validation/ProposalPayloadValidator.java b/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/validation/ProposalPayloadValidator.java
index 58b768531..7d8c72076 100644
--- a/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/validation/ProposalPayloadValidator.java
+++ b/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/validation/ProposalPayloadValidator.java
@@ -11,6 +11,12 @@
* specific language governing permissions and limitations under the License.
*
* SPDX-License-Identifier: Apache-2.0
+ *
+ * Modifications Copyright contributors to the Aere Network.
+ *
+ * This file was modified by contributors to the Aere Network, as required by section 4(b) of the
+ * Apache License 2.0. The copyright header above is the upstream one and is left exactly as it was
+ * found, as section 4(c) requires. The change itself is in patches/0003-aere-pq-anchor.patch.
*/
package org.hyperledger.besu.consensus.qbft.core.validation;
@@ -30,7 +36,20 @@ import com.google.common.annotations.VisibleForTesting;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
-/** The Proposal payload validator. */
+/**
+ * The Proposal payload validator.
+ *
+ * <p>AERE (2026-08-30): an OPTIONAL post-quantum enforcement hook, gated on height (see {@link
+ * PqProposalEnforcement}). When no enforcement is supplied, behaviour is byte for byte the upstream
+ * one - and that is the configuration of every node today. Same pattern as the PREPARE and commit
+ * validators, deliberately: a second rendering of the same idea, written differently, diverges
+ * eventually.
+ *
+ * <p>The 3-argument constructor - the one production code calls - wires the enforcement itself
+ * from the system configuration, exactly as {@link PrepareValidator} does. That self-wiring is the
+ * security property: an enforcement that had to be passed in explicitly could be dropped by any
+ * refactor without a single test failing.
+ */
public class ProposalPayloadValidator {
private static final String ERROR_PREFIX = "Invalid Proposal Payload";
@@ -39,9 +58,11 @@ public class ProposalPayloadValidator {
private final Address expectedProposer;
private final ConsensusRoundIdentifier targetRound;
private final QbftBlockValidator blockValidator;
+ private final PqProposalEnforcement pqEnforcement;
/**
- * Instantiates a new Proposal payload validator.
+ * Instantiates a new Proposal payload validator, with the post-quantum enforcement wired from
+ * the system configuration. This is the constructor production code calls.
*
* @param expectedProposer the expected proposer
* @param targetRound the target round
@@ -52,9 +73,28 @@ public class ProposalPayloadValidator {
final Address expectedProposer,
final ConsensusRoundIdentifier targetRound,
final QbftBlockValidator blockValidator) {
+ this(expectedProposer, targetRound, blockValidator, PqProposalEnforcement.fromSystemConfig());
+ }
+
+ /**
+ * Instantiates a new Proposal payload validator with an explicit post-quantum enforcement. Test
+ * seam; production goes through the 3-argument constructor above.
+ *
+ * @param expectedProposer the expected proposer
+ * @param targetRound the target round
+ * @param blockValidator the block validator
+ * @param pqEnforcement the post-quantum enforcement, or null for upstream behaviour
+ */
+ @VisibleForTesting
+ public ProposalPayloadValidator(
+ final Address expectedProposer,
+ final ConsensusRoundIdentifier targetRound,
+ final QbftBlockValidator blockValidator,
+ final PqProposalEnforcement pqEnforcement) {
this.expectedProposer = expectedProposer;
this.targetRound = targetRound;
this.blockValidator = blockValidator;
+ this.pqEnforcement = pqEnforcement;
}
/**
@@ -109,6 +149,23 @@ public class ProposalPayloadValidator {
return false;
}
+ // AERE full-PQ: from the armed height, a proposal is not accepted without a valid post-quantum
+ // seal from its OWN proposer. Below the height, and on every node without the property, this
+ // is a null check and nothing more - the upstream path, call for call.
+ if (pqEnforcement != null) {
+ final Optional<String> refusal =
+ pqEnforcement.refusal(
+ payload.getRoundIdentifier().getSequenceNumber(),
+ payload.getRoundIdentifier().getRoundNumber(),
+ signedPayload.getAuthor(),
+ block.getHash(),
+ payload.getFalconSeal());
+ if (refusal.isPresent()) {
+ LOG.info("{}: {}", ERROR_PREFIX, refusal.get());
+ return false;
+ }
+ }
+
return true;
}
diff --git a/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/validation/RoundChangePayloadValidator.java b/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/validation/RoundChangePayloadValidator.java
index 549acdd9c..8fd9bed3e 100644
--- a/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/validation/RoundChangePayloadValidator.java
+++ b/consensus/qbft-core/src/main/java/org/hyperledger/besu/consensus/qbft/core/validation/RoundChangePayloadValidator.java
@@ -11,6 +11,12 @@
* specific language governing permissions and limitations under the License.
*
* SPDX-License-Identifier: Apache-2.0
+ *
+ * Modifications Copyright contributors to the Aere Network.
+ *
+ * This file was modified by contributors to the Aere Network, as required by section 4(b) of the
+ * Apache License 2.0. The copyright header above is the upstream one and is left exactly as it was
+ * found, as section 4(c) requires. The change itself is in patches/0003-aere-pq-anchor.patch.
*/
package org.hyperledger.besu.consensus.qbft.core.validation;
@@ -20,7 +26,9 @@ import org.hyperledger.besu.consensus.qbft.core.payload.RoundChangePayload;
import org.hyperledger.besu.datatypes.Address;
import java.util.Collection;
+import java.util.Optional;
+import com.google.common.annotations.VisibleForTesting;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
@@ -28,6 +36,19 @@ import org.slf4j.LoggerFactory;
* Note: This does not validate that the received payload is for a future round, only that it was
* signed by a known validator, and is for the current chain height. Future-round check must be
* performed elsewhere (eg. the BlockHeightManager)
+ *
+ * <p>AERE (2026-08-31): an OPTIONAL post-quantum enforcement hook, gated on height (see {@link
+ * PqRoundChangeEnforcement}). When no enforcement is supplied, behaviour is byte for byte the
+ * upstream one - and that is the configuration of every node today. Same pattern as the PREPARE,
+ * commit and PROPOSAL validators, deliberately: a second rendering of the same idea, written
+ * differently, diverges eventually.
+ *
+ * <p>The 2-argument constructor - the one production code calls, from both {@code
+ * MessageValidatorFactory} and {@code ProposalValidator} (the justification path) - wires the
+ * enforcement itself from the system configuration. That self-wiring is the security property: an
+ * enforcement that had to be passed in explicitly could be dropped by any refactor without a
+ * single test failing. It also means round-changes are judged in BOTH places they arrive:
+ * standalone, and inside a proposal's round-change certificate.
*/
public class RoundChangePayloadValidator {
@@ -36,16 +57,35 @@ public class RoundChangePayloadValidator {
private final Collection<Address> validators;
private final long chainHeight;
+ private final PqRoundChangeEnforcement pqEnforcement;
/**
- * Instantiates a new Round change payload validator.
+ * Instantiates a new Round change payload validator, with the post-quantum enforcement wired
+ * from the system configuration. This is the constructor production code calls.
*
* @param validators the validators
* @param chainHeight the chain height
*/
public RoundChangePayloadValidator(final Collection<Address> validators, final long chainHeight) {
+ this(validators, chainHeight, PqRoundChangeEnforcement.fromSystemConfig());
+ }
+
+ /**
+ * Instantiates a new Round change payload validator with an explicit post-quantum enforcement.
+ * Test seam; production goes through the 2-argument constructor above.
+ *
+ * @param validators the validators
+ * @param chainHeight the chain height
+ * @param pqEnforcement the post-quantum enforcement, or null for upstream behaviour
+ */
+ @VisibleForTesting
+ public RoundChangePayloadValidator(
+ final Collection<Address> validators,
+ final long chainHeight,
+ final PqRoundChangeEnforcement pqEnforcement) {
this.validators = validators;
this.chainHeight = chainHeight;
+ this.pqEnforcement = pqEnforcement;
}
/**
@@ -86,6 +126,24 @@ public class RoundChangePayloadValidator {
return false;
}
}
+
+ // AERE full-PQ: from the armed height, a round-change is not accepted without a valid
+ // post-quantum seal from its OWN author. Below the height, and on every node without the
+ // property, this is a null check and nothing more - the upstream path, call for call.
+ if (pqEnforcement != null) {
+ final Optional<String> refusal =
+ pqEnforcement.refusal(
+ payload.getRoundIdentifier().getSequenceNumber(),
+ targetRound,
+ signedPayload.getAuthor(),
+ payload.getPreparedRoundMetadata(),
+ payload.getFalconSeal());
+ if (refusal.isPresent()) {
+ LOG.info("{}: {}", ERROR_PREFIX, refusal.get());
+ return false;
+ }
+ }
+
return true;
}
}
diff --git a/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/network/ProposalSealPlumbingTest.java b/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/network/ProposalSealPlumbingTest.java
new file mode 100755
index 000000000..4fe68e20f
--- /dev/null
+++ b/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/network/ProposalSealPlumbingTest.java
@@ -0,0 +1,101 @@
+/*
+ * Copyright contributors to Besu.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.qbft.core.network;
+
+import static java.util.Collections.emptyList;
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.lenient;
+import static org.mockito.Mockito.verify;
+
+import org.hyperledger.besu.consensus.common.bft.ConsensusRoundIdentifier;
+import org.hyperledger.besu.consensus.common.bft.FalconSeal;
+import org.hyperledger.besu.consensus.common.bft.network.ValidatorMulticaster;
+import org.hyperledger.besu.consensus.qbft.core.QbftBlockTestFixture;
+import org.hyperledger.besu.consensus.qbft.core.messagedata.ProposalMessageData;
+import org.hyperledger.besu.consensus.qbft.core.messagewrappers.Proposal;
+import org.hyperledger.besu.consensus.qbft.core.payload.MessageFactory;
+import org.hyperledger.besu.consensus.qbft.core.types.QbftBlock;
+import org.hyperledger.besu.consensus.qbft.core.types.QbftBlockCodec;
+import org.hyperledger.besu.consensus.qbft.core.types.QbftBlockHeader;
+import org.hyperledger.besu.consensus.qbft.core.validation.QbftBlockHeaderTestFixture;
+import org.hyperledger.besu.cryptoservices.NodeKeyUtils;
+import org.hyperledger.besu.ethereum.p2p.rlpx.wire.MessageData;
+
+import java.util.Optional;
+
+import org.apache.tuweni.bytes.Bytes;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.ArgumentCaptor;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+
+/**
+ * THE PLUMBING between the local proposal and the one on the wire.
+ *
+ * <p>This test exists because the first network run of proposal enforcement (F84 scenario A,
+ * 2026-08-30) went red on its own WITNESS: every node emitted a seal on its local proposal, and
+ * the chain still stopped dead at the enforcement height, because {@code multicastProposal}
+ * re-creates the proposal from scratch and the wire copy carried no seal. Every unit test we had
+ * passed, since none of them looked at what actually leaves the node. This one does.
+ */
+@ExtendWith(MockitoExtension.class)
+public class ProposalSealPlumbingTest {
+
+ private static final ConsensusRoundIdentifier ROUND_ID = new ConsensusRoundIdentifier(1, 0);
+
+ @Mock private QbftBlockCodec blockEncoder;
+ @Mock private QbftBlock block;
+ @Mock private ValidatorMulticaster multicaster;
+
+ private Proposal sentProposal(final Optional<FalconSeal> seal) {
+ lenient().when(blockEncoder.readFrom(any())).thenReturn(block);
+ final MessageFactory factory = new MessageFactory(NodeKeyUtils.generate(), blockEncoder);
+ final QbftMessageTransmitter transmitter = new QbftMessageTransmitter(factory, multicaster);
+
+ if (seal.isPresent()) {
+ transmitter.multicastProposal(
+ ROUND_ID, block, Optional.empty(), emptyList(), emptyList(), seal);
+ } else {
+ transmitter.multicastProposal(ROUND_ID, block, Optional.empty(), emptyList(), emptyList());
+ }
+
+ final ArgumentCaptor<MessageData> captor = ArgumentCaptor.forClass(MessageData.class);
+ verify(multicaster).send(captor.capture());
+ return ProposalMessageData.fromMessageData(captor.getValue()).decode(blockEncoder);
+ }
+
+ @Test
+ public void theSealHandedToTheTransmitterIsTheSealOnTheWire() {
+ final FalconSeal seal = new FalconSeal(4, Bytes.fromHexString("0xdeadbeef"));
+ final Proposal wire = sentProposal(Optional.of(seal));
+ assertThat(wire.getSignedPayload().getPayload().getFalconSeal()).contains(seal);
+ }
+
+ @Test
+ public void withoutASealTheWireProposalCarriesNone() {
+ final Proposal wire = sentProposal(Optional.empty());
+ assertThat(wire.getSignedPayload().getPayload().getFalconSeal()).isEmpty();
+ }
+
+ /** Kept so the fixture imports stay honest if the wrappers change shape. */
+ @Test
+ public void theFixturesStillBuildARealBlock() {
+ final QbftBlockHeader header = new QbftBlockHeaderTestFixture().number(1).buildHeader();
+ final QbftBlock real = new QbftBlockTestFixture().blockHeader(header).build();
+ assertThat(real.getHeader().getNumber()).isEqualTo(1);
+ }
+}
diff --git a/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/network/RoundChangeSealPlumbingTest.java b/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/network/RoundChangeSealPlumbingTest.java
new file mode 100755
index 000000000..878925888
--- /dev/null
+++ b/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/network/RoundChangeSealPlumbingTest.java
@@ -0,0 +1,88 @@
+/*
+ * Copyright contributors to Besu.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.qbft.core.network;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.mockito.Mockito.verify;
+
+import org.hyperledger.besu.consensus.common.bft.ConsensusRoundIdentifier;
+import org.hyperledger.besu.consensus.common.bft.FalconSeal;
+import org.hyperledger.besu.consensus.common.bft.network.ValidatorMulticaster;
+import org.hyperledger.besu.consensus.qbft.core.messagedata.RoundChangeMessageData;
+import org.hyperledger.besu.consensus.qbft.core.messagewrappers.RoundChange;
+import org.hyperledger.besu.consensus.qbft.core.payload.MessageFactory;
+import org.hyperledger.besu.consensus.qbft.core.types.QbftBlockCodec;
+import org.hyperledger.besu.cryptoservices.NodeKeyUtils;
+import org.hyperledger.besu.ethereum.p2p.rlpx.wire.MessageData;
+
+import java.util.Optional;
+
+import org.apache.tuweni.bytes.Bytes;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.ArgumentCaptor;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+
+/**
+ * THE PLUMBING between the local round-change and the one on the wire.
+ *
+ * <p>This test exists because of what F84 measured on the PROPOSAL (2026-08-30): the transmitter
+ * re-created the message from scratch, so the local copy carried a seal and the wire copy did not,
+ * and every unit test passed because none looked at what actually leaves the node. The round-change
+ * path has the same shape - the height manager builds a local round-change AND the transmitter used
+ * to build its own - so it gets the same test: the sealed overload must put the EXACT object it was
+ * handed on the wire.
+ */
+@ExtendWith(MockitoExtension.class)
+public class RoundChangeSealPlumbingTest {
+
+ // A round-change targets a positive round.
+ private static final ConsensusRoundIdentifier ROUND_ID = new ConsensusRoundIdentifier(1, 1);
+
+ @Mock private QbftBlockCodec blockEncoder;
+ @Mock private ValidatorMulticaster multicaster;
+
+ private RoundChange sentRoundChange(final Optional<FalconSeal> seal) {
+ final MessageFactory factory = new MessageFactory(NodeKeyUtils.generate(), blockEncoder);
+ final QbftMessageTransmitter transmitter = new QbftMessageTransmitter(factory, multicaster);
+
+ if (seal.isPresent()) {
+ // The sealed path: the caller builds ONCE and the transmitter must not rebuild - Falcon
+ // signatures are randomised, so a rebuild would put a different object on the wire.
+ final RoundChange built = factory.createRoundChange(ROUND_ID, Optional.empty(), seal);
+ transmitter.multicastRoundChange(built);
+ } else {
+ transmitter.multicastRoundChange(ROUND_ID, Optional.empty());
+ }
+
+ final ArgumentCaptor<MessageData> captor = ArgumentCaptor.forClass(MessageData.class);
+ verify(multicaster).send(captor.capture());
+ return RoundChangeMessageData.fromMessageData(captor.getValue()).decode(blockEncoder);
+ }
+
+ @Test
+ public void theSealHandedToTheTransmitterIsTheSealOnTheWire() {
+ final FalconSeal seal = new FalconSeal(4, Bytes.fromHexString("0xdeadbeef"));
+ final RoundChange wire = sentRoundChange(Optional.of(seal));
+ assertThat(wire.getSignedPayload().getPayload().getFalconSeal()).contains(seal);
+ }
+
+ @Test
+ public void withoutASealTheWireRoundChangeCarriesNone() {
+ final RoundChange wire = sentRoundChange(Optional.empty());
+ assertThat(wire.getSignedPayload().getPayload().getFalconSeal()).isEmpty();
+ }
+}
diff --git a/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/payload/CommitPayloadHybridTest.java b/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/payload/CommitPayloadHybridTest.java
new file mode 100755
index 000000000..ec0f88451
--- /dev/null
+++ b/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/payload/CommitPayloadHybridTest.java
@@ -0,0 +1,277 @@
+/* AERE HYBRID, step 1: the hybrid certificate inside the commit message.
+ *
+ * The proof that matters most comes FIRST: the golden vectors. They were measured on the
+ * binary from BEFORE this change (2026-08-24, by printing the encoding of a CommitPayload
+ * built from fixed values) and are copied here to be immovable. As long as they stay green,
+ * a commit without extras encodes exactly as on the live fleet, so the new binary can be
+ * warmed on a real node with no flag day. If anyone ever changes the base encoding, they
+ * turn red before the change can reach the chain.
+ *
+ * The rest proves the hybrid is truly hybrid: REAL Falcon plus REAL SLH-DSA, two unrelated
+ * mathematical families in the same message, each verified with its own scheme. */
+package org.hyperledger.besu.consensus.qbft.core.payload;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+import org.hyperledger.besu.consensus.common.bft.ConsensusRoundIdentifier;
+import org.hyperledger.besu.consensus.common.bft.FalconSeal;
+import org.hyperledger.besu.consensus.common.bft.PqAnchorV2;
+import org.hyperledger.besu.consensus.common.bft.SchemeSeal;
+import org.hyperledger.besu.consensus.common.bft.SealScheme;
+import org.hyperledger.besu.consensus.common.bft.SealSchemes;
+import org.hyperledger.besu.crypto.SECPSignature;
+import org.hyperledger.besu.crypto.SecureRandomProvider;
+import org.hyperledger.besu.crypto.SignatureAlgorithmFactory;
+import org.hyperledger.besu.datatypes.Hash;
+import org.hyperledger.besu.ethereum.rlp.BytesValueRLPInput;
+import org.hyperledger.besu.ethereum.rlp.BytesValueRLPOutput;
+import org.hyperledger.besu.ethereum.rlp.RLPException;
+
+import java.security.SecureRandom;
+import java.util.List;
+import java.util.Optional;
+
+import org.apache.tuweni.bytes.Bytes;
+import org.junit.jupiter.api.Test;
+
+public class CommitPayloadHybridTest {
+
+ // ---- VECTORII DE AUR, masurati pe binarul de DINAINTE de aceasta schimbare -------------------
+ private static final String AUR_FARA_PQ =
+ "0xf8660703a0000000000000000000000000000000000000000000000000000000000000002a"
+ + "b8410101010101010101010101010101010101010101010101010101010101010101"
+ + "020202020202020202020202020202020202020202020202020202020202020200";
+ private static final String AUR_CU_FALCON =
+ "0xf86d0703a0000000000000000000000000000000000000000000000000000000000000002a"
+ + "b8410101010101010101010101010101010101010101010101010101010101010101"
+ + "020202020202020202020202020202020202020202020202020202020202020200"
+ + "c60384deadbeef";
+ private static final String AUR_HASH_FARA_PQ =
+ "0xe4e36f241e03352338d89a5a0c98a59c5595d034f5a5d10e2316239ee0aecc40";
+ private static final String AUR_HASH_CU_FALCON =
+ "0x03e71e08f2b72cde0e493edfce8e26529a34b92c3c0daf0ab3591a175aec4b13";
+
+ private static final ConsensusRoundIdentifier ROUND = new ConsensusRoundIdentifier(7L, 3);
+ private static final Hash DIGEST = Hash.fromHexStringLenient("0x2a");
+ private static final FalconSeal FALCON_AUR =
+ new FalconSeal(3, Bytes.fromHexString("0xdeadbeef"));
+
+ private final SecureRandom random = SecureRandomProvider.createSecureRandom();
+
+ private static SECPSignature ecdsa() {
+ return SignatureAlgorithmFactory.getInstance()
+ .decodeSignature(
+ Bytes.fromHexString(
+ "0x"
+ + "0101010101010101010101010101010101010101010101010101010101010101"
+ + "0202020202020202020202020202020202020202020202020202020202020202"
+ + "00"));
+ }
+
+ private static CommitPayload prinCodec(final CommitPayload original) {
+ final BytesValueRLPOutput out = new BytesValueRLPOutput();
+ original.writeTo(out);
+ return CommitPayload.readFrom(new BytesValueRLPInput(out.encoded(), false));
+ }
+
+ // ============================================================ 1. LACATUL: flota vie neatinsa
+
+ @Test
+ public void aCommitWithoutPqEncodesExactlyAsTheLiveFleetDoes() {
+ final CommitPayload p = new CommitPayload(ROUND, DIGEST, ecdsa());
+ assertThat(p.encoded().toHexString()).isEqualTo(AUR_FARA_PQ);
+ assertThat(p.hashForSignature().toHexString()).isEqualTo(AUR_HASH_FARA_PQ);
+ }
+
+ @Test
+ public void aFalconOnlyCommitEncodesExactlyAsTheLiveFleetDoes() {
+ final CommitPayload p =
+ new CommitPayload(ROUND, DIGEST, ecdsa(), Optional.of(FALCON_AUR));
+ assertThat(p.encoded().toHexString()).isEqualTo(AUR_CU_FALCON);
+ assertThat(p.hashForSignature().toHexString()).isEqualTo(AUR_HASH_CU_FALCON);
+ }
+
+ @Test
+ public void theGoldenBytesOfTheLiveFleetStillDecode() {
+ final CommitPayload p =
+ CommitPayload.readFrom(
+ new BytesValueRLPInput(Bytes.fromHexString(AUR_CU_FALCON), false));
+ assertThat(p.getFalconSeal()).contains(FALCON_AUR);
+ assertThat(p.getExtraSeals()).isEmpty();
+ }
+
+ // ============================================================ 2. hibridul, cu crypto REALA
+
+ @Test
+ public void aRealHybridCertificateSurvivesTheRoundTrip() {
+ final SealScheme.GeneratedPair slh = SealSchemes.SLH_DSA_128S.generate(random);
+ final byte[] sig =
+ SealSchemes.SLH_DSA_128S.sign(slh.privateKey(), DIGEST.getBytes().toArray()).orElseThrow();
+ final SchemeSeal extra =
+ new SchemeSeal(SealSchemes.SLH_DSA_128S.wireId(), 3, Bytes.wrap(sig));
+
+ final CommitPayload original =
+ new CommitPayload(ROUND, DIGEST, ecdsa(), Optional.of(FALCON_AUR), List.of(extra));
+ final CommitPayload back = prinCodec(original);
+
+ assertThat(back).isEqualTo(original);
+ assertThat(back.getFalconSeal()).contains(FALCON_AUR);
+ assertThat(back.getExtraSeals()).hasSize(1);
+ // si semnatura chiar se verifica dupa drumul prin codec, cu SCHEMA ei
+ assertThat(
+ SealSchemes.SLH_DSA_128S.verifyRaw(
+ slh.publicRegistryForm(),
+ DIGEST.getBytes().toArray(),
+ back.getExtraSeals().get(0).getSignature().toArray()))
+ .isTrue();
+ }
+
+ @Test
+ public void twoUnrelatedFamiliesTravelInOneCommitAndEachVerifiesWithItsOwn() {
+ final SealScheme.GeneratedPair falcon = SealSchemes.FALCON_512.generate(random);
+ final SealScheme.GeneratedPair slh = SealSchemes.SLH_DSA_128S.generate(random);
+ final byte[] message = DIGEST.getBytes().toArray();
+ final byte[] sigFalcon = SealSchemes.FALCON_512.sign(falcon.privateKey(), message).orElseThrow();
+ final byte[] sigSlh = SealSchemes.SLH_DSA_128S.sign(slh.privateKey(), message).orElseThrow();
+
+ final CommitPayload p =
+ new CommitPayload(
+ ROUND,
+ DIGEST,
+ ecdsa(),
+ Optional.of(new FalconSeal(3, Bytes.wrap(sigFalcon))),
+ List.of(new SchemeSeal(SealSchemes.SLH_DSA_128S.wireId(), 3, Bytes.wrap(sigSlh))));
+ final CommitPayload back = prinCodec(p);
+
+ assertThat(
+ SealSchemes.FALCON_512.verifyRaw(
+ falcon.publicRegistryForm(),
+ message,
+ back.getFalconSeal().orElseThrow().getSignature().toArray()))
+ .isTrue();
+ assertThat(
+ SealSchemes.SLH_DSA_128S.verifyRaw(
+ slh.publicRegistryForm(),
+ message,
+ back.getExtraSeals().get(0).getSignature().toArray()))
+ .isTrue();
+ // the CROSSED CONTROL: each signature is refused by the OTHER scheme, so the hybrid
+ // really stands on two legs and not on the same leg twice
+ assertThat(SealSchemes.SLH_DSA_128S.verifyRaw(slh.publicRegistryForm(), message, sigFalcon))
+ .isFalse();
+ assertThat(SealSchemes.FALCON_512.verifyRaw(falcon.publicRegistryForm(), message, sigSlh))
+ .isFalse();
+ }
+
+ @Test
+ public void theEcdsaSignedBytesCoverTheExtras() {
+ final SchemeSeal extra =
+ new SchemeSeal(SealSchemes.SLH_DSA_128S.wireId(), 3, Bytes.fromHexString("0xabcdef"));
+ final CommitPayload faraExtras =
+ new CommitPayload(ROUND, DIGEST, ecdsa(), Optional.of(FALCON_AUR));
+ final CommitPayload cuExtras =
+ new CommitPayload(ROUND, DIGEST, ecdsa(), Optional.of(FALCON_AUR), List.of(extra));
+ // if the hash were the same, extras could be added or removed by anyone without
+ // breaking the author's signature
+ assertThat(cuExtras.hashForSignature()).isNotEqualTo(faraExtras.hashForSignature());
+ }
+
+ // ============================================================ 3. refuzurile
+
+ @Test
+ public void extrasWithoutAFalconSealAreRefusedAtConstruction() {
+ final SchemeSeal extra =
+ new SchemeSeal(SealSchemes.SLH_DSA_128S.wireId(), 3, Bytes.fromHexString("0xabcdef"));
+ assertThatThrownBy(
+ () -> new CommitPayload(ROUND, DIGEST, ecdsa(), Optional.empty(), List.of(extra)))
+ .isInstanceOf(IllegalArgumentException.class)
+ .hasMessageContaining("require the Falcon seal");
+ }
+
+ @Test
+ public void falconInTheExtrasIsRefusedSoOneSignatureHasOneHome() {
+ final SchemeSeal falconInExtras =
+ new SchemeSeal(SealSchemes.FALCON_512.wireId(), 3, Bytes.fromHexString("0xabcdef"));
+ assertThatThrownBy(
+ () ->
+ new CommitPayload(
+ ROUND, DIGEST, ecdsa(), Optional.of(FALCON_AUR), List.of(falconInExtras)))
+ .isInstanceOf(IllegalArgumentException.class)
+ .hasMessageContaining("own slot");
+ }
+
+ @Test
+ public void anEmptyExtrasElementOnTheWireIsRefused() {
+ // doua codificari ale aceleiasi valori nu au voie sa existe: extras gol == extras absent
+ final BytesValueRLPOutput out = new BytesValueRLPOutput();
+ out.startList();
+ out.writeLongScalar(ROUND.getSequenceNumber());
+ out.writeIntScalar(ROUND.getRoundNumber());
+ out.writeBytes(DIGEST.getBytes());
+ out.writeBytes(ecdsa().encodedBytes());
+ out.startList();
+ out.writeIntScalar(FALCON_AUR.getValidatorIndex());
+ out.writeBytes(FALCON_AUR.getSignature());
+ out.endList();
+ out.writeRaw(PqAnchorV2.encode(List.of()));
+ out.endList();
+
+ assertThatThrownBy(
+ () -> CommitPayload.readFrom(new BytesValueRLPInput(out.encoded(), false)))
+ .isInstanceOf(RLPException.class);
+ }
+
+ @Test
+ public void aThirdTrailingElementIsRefusedByCanonicality() {
+ final BytesValueRLPOutput out = new BytesValueRLPOutput();
+ out.startList();
+ out.writeLongScalar(ROUND.getSequenceNumber());
+ out.writeIntScalar(ROUND.getRoundNumber());
+ out.writeBytes(DIGEST.getBytes());
+ out.writeBytes(ecdsa().encodedBytes());
+ out.startList();
+ out.writeIntScalar(FALCON_AUR.getValidatorIndex());
+ out.writeBytes(FALCON_AUR.getSignature());
+ out.endList();
+ out.writeRaw(
+ PqAnchorV2.encode(
+ List.of(
+ new SchemeSeal(
+ SealSchemes.SLH_DSA_128S.wireId(), 3, Bytes.fromHexString("0xabcdef")))));
+ out.writeBytes(Bytes.fromHexString("0x99")); // al treilea element, nu exista in format
+ out.endList();
+
+ assertThatThrownBy(
+ () -> CommitPayload.readFrom(new BytesValueRLPInput(out.encoded(), false)))
+ .isInstanceOf(RLPException.class);
+ }
+
+ @Test
+ public void aCorruptedExtrasElementIsAnRlpFailureNotACrash() {
+ final BytesValueRLPOutput out = new BytesValueRLPOutput();
+ out.startList();
+ out.writeLongScalar(ROUND.getSequenceNumber());
+ out.writeIntScalar(ROUND.getRoundNumber());
+ out.writeBytes(DIGEST.getBytes());
+ out.writeBytes(ecdsa().encodedBytes());
+ out.startList();
+ out.writeIntScalar(FALCON_AUR.getValidatorIndex());
+ out.writeBytes(FALCON_AUR.getSignature());
+ out.endList();
+ // un element care NU e un certificat v2: versiune necunoscuta
+ final BytesValueRLPOutput bad = new BytesValueRLPOutput();
+ bad.startList();
+ bad.writeIntScalar(99);
+ bad.startList();
+ bad.endList();
+ bad.endList();
+ out.writeRaw(bad.encoded());
+ out.endList();
+
+ assertThatThrownBy(
+ () -> CommitPayload.readFrom(new BytesValueRLPInput(out.encoded(), false)))
+ .isInstanceOf(RLPException.class)
+ .hasMessageContaining("AERE HIBRID");
+ }
+}
diff --git a/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/payload/PreparePayloadPqTest.java b/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/payload/PreparePayloadPqTest.java
new file mode 100755
index 000000000..d2f91c43c
--- /dev/null
+++ b/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/payload/PreparePayloadPqTest.java
@@ -0,0 +1,209 @@
+/*
+ * Copyright contributors to Besu.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.qbft.core.payload;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+import org.hyperledger.besu.consensus.common.bft.ConsensusRoundIdentifier;
+import org.hyperledger.besu.consensus.common.bft.FalconSeal;
+import org.hyperledger.besu.consensus.common.bft.PqAnchor;
+import org.hyperledger.besu.datatypes.Hash;
+import org.hyperledger.besu.ethereum.rlp.BytesValueRLPInput;
+import org.hyperledger.besu.ethereum.rlp.BytesValueRLPOutput;
+import org.hyperledger.besu.ethereum.rlp.RLPException;
+
+import java.util.Optional;
+
+import org.apache.tuweni.bytes.Bytes;
+import org.apache.tuweni.bytes.Bytes32;
+import org.junit.jupiter.api.Test;
+
+/**
+ * STEP 1 of PREPARE-SI-ROUNDCHANGE-SUB-PQ-PROIECTARE-2026-08-28: the wire can carry a
+ * post-quantum seal on a PREPARE, and NOTHING emits one yet.
+ *
+ * <p>The test that matters most is the first one: a PREPARE without a seal encodes EXACTLY as it
+ * did before this change. Without it the new binary cannot be rolled onto a live fleet, because the
+ * neighbours would compute a different signature hash and reject every PREPARE. The golden vector
+ * is built from the canonical encoding of the OLD form, not from a run of the new code.
+ */
+public class PreparePayloadPqTest {
+
+ private static final ConsensusRoundIdentifier ROUND = new ConsensusRoundIdentifier(7, 3);
+ private static final Hash DIGEST =
+ Hash.wrap(
+ Bytes32.fromHexString(
+ "0x000000000000000000000000000000000000000000000000000000000000002a"));
+
+ /**
+ * THE GOLDEN VECTOR of the old form: RLP[ sequence, round, digest(32) ]. Built here from its
+ * elements, not copied from a run, so that what it is made of stays visible.
+ *
+ * <p>The first version of this test wrapped sequence and round in a LIST, and it failed. The
+ * source (QbftPayload.writeConsensusRound) writes them as two FLAT scalars. The test was the
+ * wrong one, not the code - and that is worth saying, because a golden vector written from
+ * intuition instead of from the source would have either refused good code or, worse, been
+ * "fixed" by moving the code to match it.
+ */
+ private static Bytes goldenOldForm() {
+ final BytesValueRLPOutput out = new BytesValueRLPOutput();
+ out.startList();
+ out.writeLongScalar(7L);
+ out.writeIntScalar(3);
+ out.writeBytes(DIGEST.getBytes());
+ out.endList();
+ return out.encoded();
+ }
+
+ @Test
+ public void aPrepareWithoutASealEncodesEXACTLYAsBefore() {
+ final PreparePayload p = new PreparePayload(ROUND, DIGEST);
+ assertThat(p.encoded()).isEqualTo(goldenOldForm());
+ // and the signature hash, which is precisely what binds the author to the message
+ assertThat(p.hashForSignature())
+ .isEqualTo(new PreparePayload(ROUND, DIGEST, Optional.empty()).hashForSignature());
+ }
+
+ @Test
+ public void aPrepareWithoutASealReadsBackIdentical() {
+ final Bytes encoded = new PreparePayload(ROUND, DIGEST).encoded();
+ final PreparePayload decoded = PreparePayload.readFrom(new BytesValueRLPInput(encoded, false));
+ assertThat(decoded.getFalconSeal()).isEmpty();
+ assertThat(decoded.getDigest()).isEqualTo(DIGEST);
+ assertThat(decoded.getRoundIdentifier()).isEqualTo(ROUND);
+ assertThat(decoded.encoded()).isEqualTo(encoded);
+ }
+
+ @Test
+ public void aPrepareWithASealReadsBackIdentical() {
+ final FalconSeal seal = new FalconSeal(4, Bytes.fromHexString("0xdeadbeef"));
+ final PreparePayload p = new PreparePayload(ROUND, DIGEST, Optional.of(seal));
+ final Bytes encoded = p.encoded();
+
+ // it is longer than the old form, and CONTAINS it as a prefix of the content
+ assertThat(encoded.size()).isGreaterThan(goldenOldForm().size());
+
+ final PreparePayload decoded = PreparePayload.readFrom(new BytesValueRLPInput(encoded, false));
+ assertThat(decoded.getFalconSeal()).isPresent();
+ assertThat(decoded.getFalconSeal().get().getValidatorIndex()).isEqualTo(4);
+ assertThat(decoded.getFalconSeal().get().getSignature()).isEqualTo(Bytes.fromHexString("0xdeadbeef"));
+ assertThat(decoded).isEqualTo(p);
+ assertThat(decoded.encoded()).isEqualTo(encoded);
+ }
+
+ @Test
+ public void aSealChangesTheSignatureHash() {
+ // If it did not change it, the author's ECDSA signature would not cover the seal, and anyone
+ // could paste a foreign index onto an otherwise valid PREPARE.
+ final PreparePayload without = new PreparePayload(ROUND, DIGEST);
+ final PreparePayload with =
+ new PreparePayload(ROUND, DIGEST, Optional.of(new FalconSeal(4, Bytes.fromHexString("0xdeadbeef"))));
+ assertThat(with.hashForSignature()).isNotEqualTo(without.hashForSignature());
+ }
+
+ @Test
+ public void aNONCANONICALEncodingIsRefused() {
+ // A third element that is not a seal: the decoder could ignore it, and then two different byte
+ // strings would authenticate to the same validator. It is refused.
+ final BytesValueRLPOutput out = new BytesValueRLPOutput();
+ out.startList();
+ out.writeLongScalar(7L);
+ out.writeIntScalar(3);
+ out.writeBytes(DIGEST.getBytes());
+ out.startList();
+ out.writeIntScalar(4);
+ out.writeBytes(Bytes.fromHexString("0xdeadbeef"));
+ out.writeBytes(Bytes.fromHexString("0xff")); // element in plus INAUNTRUL sigiliului
+ out.endList();
+ out.endList();
+
+ assertThatThrownBy(() -> PreparePayload.readFrom(new BytesValueRLPInput(out.encoded(), false)))
+ .isInstanceOf(RLPException.class);
+ }
+
+ // ---- domain separation: the security part of the design -------------------------------------
+
+ @Test
+ public void thePREPAREMessageIsNotTheCOMMITMessage() {
+ // If it were the same, a PREPARE seal given HONESTLY could be pasted onto a forged COMMIT and
+ // the enforcement there would accept it. That is exactly the attack this separation closes.
+ final Bytes32 prep = PqAnchor.prepareMessage(2800L, 100L, 3, DIGEST.getBytes());
+ final Bytes32 comm = PqAnchor.commitMessage(2800L, 100L, DIGEST.getBytes());
+ assertThat(prep).isNotEqualTo(comm);
+ }
+
+ @Test
+ public void thePREPAREMessageDependsOnTheROUND() {
+ // Two PREPAREs for the same block in different rounds are two different assertions. Without the
+ // round in the preimage, a seal from a failed round would justify another one.
+ final Bytes32 r3 = PqAnchor.prepareMessage(2800L, 100L, 3, DIGEST.getBytes());
+ final Bytes32 r4 = PqAnchor.prepareMessage(2800L, 100L, 4, DIGEST.getBytes());
+ assertThat(r3).isNotEqualTo(r4);
+ }
+
+ @Test
+ public void thePREPAREMessageDependsOnCHAINAndHEIGHT() {
+ final Bytes32 baza = PqAnchor.prepareMessage(2800L, 100L, 3, DIGEST.getBytes());
+ assertThat(PqAnchor.prepareMessage(2801L, 100L, 3, DIGEST.getBytes())).isNotEqualTo(baza);
+ assertThat(PqAnchor.prepareMessage(2800L, 101L, 3, DIGEST.getBytes())).isNotEqualTo(baza);
+ }
+
+ @Test
+ public void thePREPAREMessageRefusesImpossibleInputs() {
+ assertThatThrownBy(() -> PqAnchor.prepareMessage(2800L, -1L, 3, DIGEST.getBytes()))
+ .isInstanceOf(IllegalArgumentException.class);
+ assertThatThrownBy(() -> PqAnchor.prepareMessage(2800L, 100L, -1, DIGEST.getBytes()))
+ .isInstanceOf(IllegalArgumentException.class);
+ assertThatThrownBy(() -> PqAnchor.prepareMessage(2800L, 100L, 3, Bytes.fromHexString("0x00")))
+ .isInstanceOf(IllegalArgumentException.class);
+ }
+
+ // ===============================================================================================
+ // THE BRIDGE TO CLIENT 2, added 2026-08-29 (finding D-282).
+ //
+ // The two strings below are written LITERALLY in client 2's test as well
+ // (AereQbftPrepareSealWireProofTests), for the same values. This is not a round trip: each
+ // implementation encodes the payload on its own and compares it with THE SAME string. If either
+ // one moves, one of the two tests fails - and that is exactly the question that matters, because
+ // a client-2 decoder strict at three elements would have rejected every PREPARE of a fleet with
+ // emission armed, exactly as its decoder strict at four rejected every commit at an anchor
+ // height.
+ //
+ // And so that this is not two implementations being wrong in the same way, the bytes were checked
+ // with a THIRD RLP encoder as well, written separately in python, with no connection to either
+ // project: both strings matched exactly.
+ //
+ // The structure, so it can be read by eye:
+ // e3 | 07 | 03 | a0 <32 digest bytes> = old form, three elements
+ // ea | 07 | 03 | a0 <32 digest bytes> | c6 04 84 deadbeef = with a seal, four elements
+ // ===============================================================================================
+
+ private static final String AUR_FARA_SIGILIU =
+ "0xe30703a0000000000000000000000000000000000000000000000000000000000000002a";
+ private static final String AUR_CU_SIGILIU =
+ "0xea0703a0000000000000000000000000000000000000000000000000000000000000002ac60484deadbeef";
+
+ @Test
+ public void theWireBytesAreTHESAMEAsInClient2sTest() {
+ assertThat(new PreparePayload(ROUND, DIGEST).encoded())
+ .isEqualTo(Bytes.fromHexString(AUR_FARA_SIGILIU));
+
+ final PreparePayload with =
+ new PreparePayload(
+ ROUND, DIGEST, Optional.of(new FalconSeal(4, Bytes.fromHexString("0xdeadbeef"))));
+ assertThat(with.encoded()).isEqualTo(Bytes.fromHexString(AUR_CU_SIGILIU));
+ }
+}
diff --git a/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/payload/ProposalPayloadPqTest.java b/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/payload/ProposalPayloadPqTest.java
new file mode 100755
index 000000000..c6b6de065
--- /dev/null
+++ b/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/payload/ProposalPayloadPqTest.java
@@ -0,0 +1,202 @@
+/*
+ * Copyright contributors to Besu.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.qbft.core.payload;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.lenient;
+
+import org.hyperledger.besu.consensus.common.bft.ConsensusRoundIdentifier;
+import org.hyperledger.besu.consensus.common.bft.FalconSeal;
+import org.hyperledger.besu.consensus.common.bft.PqAnchor;
+import org.hyperledger.besu.consensus.qbft.core.types.QbftBlock;
+import org.hyperledger.besu.consensus.qbft.core.types.QbftBlockCodec;
+import org.hyperledger.besu.ethereum.rlp.BytesValueRLPInput;
+import org.hyperledger.besu.ethereum.rlp.BytesValueRLPOutput;
+import org.hyperledger.besu.ethereum.rlp.RLPException;
+
+import java.util.Optional;
+
+import org.apache.tuweni.bytes.Bytes;
+import org.apache.tuweni.bytes.Bytes32;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+
+/**
+ * The wire can carry a post-quantum seal on a PROPOSAL, and NOTHING emits one yet (AERE PQ,
+ * 2026-08-30, the hot-path step after PREPARE).
+ *
+ * <p>The test that matters most is the first one: a proposal without a seal encodes EXACTLY as
+ * upstream does. The block codec is mocked and contributes zero bytes on both sides of the round
+ * trip, which is what lets the surrounding list structure be compared against a hand-built
+ * expected form instead of against a run of the code under test.
+ *
+ * <p>The strictness tests close the malleability door this file's javadoc names: an authenticated
+ * payload whose decoder silently ignored trailing elements would let two different byte strings
+ * authenticate to the same proposer.
+ */
+@ExtendWith(MockitoExtension.class)
+public class ProposalPayloadPqTest {
+
+ private static final ConsensusRoundIdentifier ROUND_ID = new ConsensusRoundIdentifier(7, 3);
+
+ @Mock private QbftBlockCodec blockEncoder;
+ @Mock private QbftBlock block;
+
+ @BeforeEach
+ void wireCodec() {
+ // The mock codec writes nothing and reads nothing: the block contributes zero elements on both
+ // sides, so the tests compare the STRUCTURE around it, which is what this file changed.
+ lenient().when(blockEncoder.readFrom(any())).thenReturn(block);
+ }
+
+ /** The old form with the mocked block: RLP[ sequence, round, null-BAL ]. Built by hand. */
+ private static Bytes oldForm() {
+ final BytesValueRLPOutput out = new BytesValueRLPOutput();
+ out.startList();
+ out.writeLongScalar(ROUND_ID.getSequenceNumber());
+ out.writeIntScalar(ROUND_ID.getRoundNumber());
+ out.writeNull();
+ out.endList();
+ return out.encoded();
+ }
+
+ @Test
+ public void aProposalWithoutASealEncodesEXACTLYAsBefore() {
+ final ProposalPayload p = new ProposalPayload(ROUND_ID, block, blockEncoder, Optional.empty());
+ assertThat(p.encoded()).isEqualTo(oldForm());
+ // and the signature hash, which is precisely what binds the proposer to the message
+ assertThat(p.hashForSignature())
+ .isEqualTo(
+ new ProposalPayload(ROUND_ID, block, blockEncoder, Optional.empty(), Optional.empty())
+ .hashForSignature());
+ }
+
+ @Test
+ public void aProposalWithoutASealReadsBackIdentical() {
+ final Bytes encoded = new ProposalPayload(ROUND_ID, block, blockEncoder, Optional.empty()).encoded();
+ final ProposalPayload read =
+ ProposalPayload.readFrom(new BytesValueRLPInput(encoded, false), blockEncoder);
+ assertThat(read.getFalconSeal()).isEmpty();
+ assertThat(read.getRoundIdentifier()).isEqualTo(ROUND_ID);
+ assertThat(read.encoded()).isEqualTo(encoded);
+ }
+
+ @Test
+ public void aProposalWithASealReadsBackIdentical() {
+ final FalconSeal seal = new FalconSeal(4, Bytes.fromHexString("0xdeadbeef"));
+ final ProposalPayload p =
+ new ProposalPayload(ROUND_ID, block, blockEncoder, Optional.empty(), Optional.of(seal));
+ final Bytes encoded = p.encoded();
+
+ // it is longer than the old form, and CONTAINS it as a prefix of the content
+ assertThat(encoded.size()).isGreaterThan(oldForm().size());
+
+ final ProposalPayload read =
+ ProposalPayload.readFrom(new BytesValueRLPInput(encoded, false), blockEncoder);
+ assertThat(read.getFalconSeal()).isPresent();
+ assertThat(read.getFalconSeal().get().getValidatorIndex()).isEqualTo(4);
+ assertThat(read.getFalconSeal().get().getSignature())
+ .isEqualTo(Bytes.fromHexString("0xdeadbeef"));
+ assertThat(read.encoded()).isEqualTo(encoded);
+ }
+
+ @Test
+ public void aSealChangesTheSignatureHash() {
+ // If it did not change it, the proposer's ECDSA signature would not cover the seal, and anyone
+ // could paste a foreign index onto an otherwise valid proposal.
+ final ProposalPayload without = new ProposalPayload(ROUND_ID, block, blockEncoder, Optional.empty());
+ final ProposalPayload with =
+ new ProposalPayload(
+ ROUND_ID,
+ block,
+ blockEncoder,
+ Optional.empty(),
+ Optional.of(new FalconSeal(4, Bytes.fromHexString("0xdeadbeef"))));
+ assertThat(with.hashForSignature()).isNotEqualTo(without.hashForSignature());
+ }
+
+ @Test
+ public void anElementAfterTheSealIsRefused() {
+ // A decoder that ignored it would re-encode without it: two different byte strings would
+ // authenticate to the same proposer. It is refused.
+ final BytesValueRLPOutput out = new BytesValueRLPOutput();
+ out.startList();
+ out.writeLongScalar(ROUND_ID.getSequenceNumber());
+ out.writeIntScalar(ROUND_ID.getRoundNumber());
+ out.writeNull();
+ out.startList();
+ out.writeIntScalar(4);
+ out.writeBytes(Bytes.fromHexString("0xdeadbeef"));
+ out.endList();
+ out.writeIntScalar(1); // the trailing element nothing accounts for
+ out.endList();
+
+ assertThatThrownBy(
+ () -> ProposalPayload.readFrom(new BytesValueRLPInput(out.encoded(), false), blockEncoder))
+ .isInstanceOf(RLPException.class);
+ }
+
+ @Test
+ public void aFifthElementThatIsNotASealIsRefused() {
+ final BytesValueRLPOutput out = new BytesValueRLPOutput();
+ out.startList();
+ out.writeLongScalar(ROUND_ID.getSequenceNumber());
+ out.writeIntScalar(ROUND_ID.getRoundNumber());
+ out.writeNull();
+ out.writeBytes(Bytes.fromHexString("0x01")); // not a [index, signature] list
+ out.endList();
+
+ assertThatThrownBy(
+ () -> ProposalPayload.readFrom(new BytesValueRLPInput(out.encoded(), false), blockEncoder))
+ .isInstanceOf(RLPException.class);
+ }
+
+ // ---- domain separation: the security part of the design --------------------------------------
+
+ private static final Bytes32 DIGEST =
+ Bytes32.fromHexString("0x000000000000000000000000000000000000000000000000000000000000002a");
+
+ @Test
+ public void theProposalMessageIsNeitherThePrepareNorTheCommitMessage() {
+ // If any two were the same, a seal given HONESTLY in one role could be replayed in the other:
+ // an offer counted as a vote, or a vote replayed as an offer.
+ final Bytes32 proposal = PqAnchor.proposalMessage(2800L, 100L, 3, DIGEST);
+ assertThat(proposal).isNotEqualTo(PqAnchor.prepareMessage(2800L, 100L, 3, DIGEST));
+ assertThat(proposal).isNotEqualTo(PqAnchor.commitMessage(2800L, 100L, DIGEST));
+ }
+
+ @Test
+ public void theProposalMessageDependsOnROUNDChainAndHeight() {
+ final Bytes32 base = PqAnchor.proposalMessage(2800L, 100L, 3, DIGEST);
+ assertThat(PqAnchor.proposalMessage(2800L, 100L, 4, DIGEST)).isNotEqualTo(base);
+ assertThat(PqAnchor.proposalMessage(2801L, 100L, 3, DIGEST)).isNotEqualTo(base);
+ assertThat(PqAnchor.proposalMessage(2800L, 101L, 3, DIGEST)).isNotEqualTo(base);
+ }
+
+ @Test
+ public void theProposalMessageRefusesImpossibleInputs() {
+ assertThatThrownBy(() -> PqAnchor.proposalMessage(2800L, -1L, 3, DIGEST))
+ .isInstanceOf(IllegalArgumentException.class);
+ assertThatThrownBy(() -> PqAnchor.proposalMessage(2800L, 100L, -1, DIGEST))
+ .isInstanceOf(IllegalArgumentException.class);
+ assertThatThrownBy(() -> PqAnchor.proposalMessage(2800L, 100L, 3, Bytes.fromHexString("0x00")))
+ .isInstanceOf(IllegalArgumentException.class);
+ }
+}
diff --git a/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/payload/RoundChangePayloadPqTest.java b/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/payload/RoundChangePayloadPqTest.java
new file mode 100755
index 000000000..efbf51766
--- /dev/null
+++ b/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/payload/RoundChangePayloadPqTest.java
@@ -0,0 +1,236 @@
+/*
+ * Copyright contributors to Besu.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.qbft.core.payload;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+import org.hyperledger.besu.consensus.common.bft.ConsensusRoundIdentifier;
+import org.hyperledger.besu.consensus.common.bft.FalconSeal;
+import org.hyperledger.besu.consensus.common.bft.PqAnchor;
+import org.hyperledger.besu.datatypes.Hash;
+import org.hyperledger.besu.ethereum.rlp.BytesValueRLPInput;
+import org.hyperledger.besu.ethereum.rlp.BytesValueRLPOutput;
+import org.hyperledger.besu.ethereum.rlp.RLPException;
+
+import java.util.Optional;
+
+import org.apache.tuweni.bytes.Bytes;
+import org.apache.tuweni.bytes.Bytes32;
+import org.junit.jupiter.api.Test;
+
+/**
+ * The wire can carry a post-quantum seal on a ROUND-CHANGE, and NOTHING emits one yet (AERE PQ,
+ * 2026-08-31, the last hot-path message).
+ *
+ * <p>The test that matters most is the first one: a round-change without a seal encodes EXACTLY as
+ * upstream does, compared against a hand-built expected form instead of against a run of the code
+ * under test.
+ *
+ * <p>The strictness tests close the malleability door the payload's javadoc names: an
+ * authenticated payload whose decoder silently ignored trailing elements would let two different
+ * byte strings authenticate to the same author.
+ */
+public class RoundChangePayloadPqTest {
+
+ private static final ConsensusRoundIdentifier ROUND_ID = new ConsensusRoundIdentifier(7, 3);
+ private static final Hash PREPARED_HASH = Hash.hash(Bytes.of(1, 2, 3));
+
+ /** The old bare form: RLP[ sequence, round, [] ]. Built by hand. */
+ private static Bytes oldBareForm() {
+ final BytesValueRLPOutput out = new BytesValueRLPOutput();
+ out.startList();
+ out.writeLongScalar(ROUND_ID.getSequenceNumber());
+ out.writeIntScalar(ROUND_ID.getRoundNumber());
+ out.startList();
+ out.endList();
+ out.endList();
+ return out.encoded();
+ }
+
+ @Test
+ public void aRoundChangeWithoutASealEncodesEXACTLYAsBefore() {
+ final RoundChangePayload p = new RoundChangePayload(ROUND_ID, Optional.empty());
+ assertThat(p.encoded()).isEqualTo(oldBareForm());
+ // and the signature hash, which is precisely what binds the author to the message
+ assertThat(p.hashForSignature())
+ .isEqualTo(
+ new RoundChangePayload(ROUND_ID, Optional.empty(), Optional.empty()).hashForSignature());
+ }
+
+ @Test
+ public void aRoundChangeWithPreparedMetadataAndNoSealReadsBackIdentical() {
+ final RoundChangePayload p =
+ new RoundChangePayload(
+ ROUND_ID, Optional.of(new PreparedRoundMetadata(PREPARED_HASH, 1)));
+ final Bytes encoded = p.encoded();
+ final RoundChangePayload read =
+ RoundChangePayload.readFrom(new BytesValueRLPInput(encoded, false));
+ assertThat(read.getFalconSeal()).isEmpty();
+ assertThat(read.getPreparedRoundMetadata()).isPresent();
+ assertThat(read.getPreparedRoundMetadata().get().getPreparedRound()).isEqualTo(1);
+ assertThat(read.getPreparedRoundMetadata().get().getPreparedBlockHash())
+ .isEqualTo(PREPARED_HASH);
+ assertThat(read.encoded()).isEqualTo(encoded);
+ }
+
+ @Test
+ public void aRoundChangeWithASealReadsBackIdentical() {
+ final FalconSeal seal = new FalconSeal(4, Bytes.fromHexString("0xdeadbeef"));
+ final RoundChangePayload p =
+ new RoundChangePayload(ROUND_ID, Optional.empty(), Optional.of(seal));
+ final Bytes encoded = p.encoded();
+
+ // it is longer than the old form, and CONTAINS it as a prefix of the content
+ assertThat(encoded.size()).isGreaterThan(oldBareForm().size());
+
+ final RoundChangePayload read =
+ RoundChangePayload.readFrom(new BytesValueRLPInput(encoded, false));
+ assertThat(read.getFalconSeal()).isPresent();
+ assertThat(read.getFalconSeal().get().getValidatorIndex()).isEqualTo(4);
+ assertThat(read.getFalconSeal().get().getSignature())
+ .isEqualTo(Bytes.fromHexString("0xdeadbeef"));
+ assertThat(read.encoded()).isEqualTo(encoded);
+ }
+
+ @Test
+ public void aSealedRoundChangeWithPreparedMetadataReadsBackIdentical() {
+ final FalconSeal seal = new FalconSeal(2, Bytes.fromHexString("0xfeedface"));
+ final RoundChangePayload p =
+ new RoundChangePayload(
+ ROUND_ID, Optional.of(new PreparedRoundMetadata(PREPARED_HASH, 2)), Optional.of(seal));
+ final Bytes encoded = p.encoded();
+ final RoundChangePayload read =
+ RoundChangePayload.readFrom(new BytesValueRLPInput(encoded, false));
+ assertThat(read.getFalconSeal()).isPresent();
+ assertThat(read.getPreparedRoundMetadata()).isPresent();
+ assertThat(read.encoded()).isEqualTo(encoded);
+ }
+
+ @Test
+ public void theGoldenBytesMatchTheSecondClient() {
+ // The SAME two hex strings are asserted by the second client (AereQbftPrepareSealWireProofTests,
+ // AurRcFaraSigiliu / AurRcCuSigiliu) for the same sequence/round/seal. If either implementation
+ // moves, one of the two tests goes red - the cross-implementation link. A round trip through our
+ // own encoder would only prove that we agree with ourselves.
+ assertThat(new RoundChangePayload(ROUND_ID, Optional.empty()).encoded().toUnprefixedHexString())
+ .isEqualTo("c30703c0");
+ assertThat(
+ new RoundChangePayload(
+ ROUND_ID,
+ Optional.empty(),
+ Optional.of(new FalconSeal(4, Bytes.fromHexString("0xdeadbeef"))))
+ .encoded()
+ .toUnprefixedHexString())
+ .isEqualTo("ca0703c0c60484deadbeef");
+ }
+
+ @Test
+ public void aSealChangesTheSignatureHash() {
+ // If it did not change it, the author's ECDSA signature would not cover the seal, and anyone
+ // could paste a foreign index onto an otherwise valid round-change.
+ final RoundChangePayload without = new RoundChangePayload(ROUND_ID, Optional.empty());
+ final RoundChangePayload with =
+ new RoundChangePayload(
+ ROUND_ID,
+ Optional.empty(),
+ Optional.of(new FalconSeal(4, Bytes.fromHexString("0xdeadbeef"))));
+ assertThat(with.hashForSignature()).isNotEqualTo(without.hashForSignature());
+ }
+
+ @Test
+ public void anElementAfterTheSealIsRefused() {
+ // A decoder that ignored it would re-encode without it: two different byte strings would
+ // authenticate to the same author. It is refused.
+ final BytesValueRLPOutput out = new BytesValueRLPOutput();
+ out.startList();
+ out.writeLongScalar(ROUND_ID.getSequenceNumber());
+ out.writeIntScalar(ROUND_ID.getRoundNumber());
+ out.startList();
+ out.endList();
+ out.startList();
+ out.writeIntScalar(4);
+ out.writeBytes(Bytes.fromHexString("0xdeadbeef"));
+ out.endList();
+ out.writeIntScalar(1); // the trailing element nothing accounts for
+ out.endList();
+
+ assertThatThrownBy(
+ () -> RoundChangePayload.readFrom(new BytesValueRLPInput(out.encoded(), false)))
+ .isInstanceOf(RLPException.class);
+ }
+
+ @Test
+ public void aFourthElementThatIsNotASealIsRefused() {
+ final BytesValueRLPOutput out = new BytesValueRLPOutput();
+ out.startList();
+ out.writeLongScalar(ROUND_ID.getSequenceNumber());
+ out.writeIntScalar(ROUND_ID.getRoundNumber());
+ out.startList();
+ out.endList();
+ out.writeBytes(Bytes.fromHexString("0x01")); // not a [index, signature] list
+ out.endList();
+
+ assertThatThrownBy(
+ () -> RoundChangePayload.readFrom(new BytesValueRLPInput(out.encoded(), false)))
+ .isInstanceOf(RLPException.class);
+ }
+
+ // ---- domain separation: the security part of the design --------------------------------------
+
+ private static final Bytes32 DIGEST =
+ Bytes32.fromHexString("0x000000000000000000000000000000000000000000000000000000000000002a");
+
+ @Test
+ public void theRoundChangeMessageIsNoneOfItsThreeSiblings() {
+ // If any two were the same, a seal given HONESTLY in one role could be replayed in the other:
+ // "move on" counted as a vote, an offer, or the other way around.
+ final Bytes32 rc = PqAnchor.roundChangeMessage(2800L, 100L, 3);
+ assertThat(rc).isNotEqualTo(PqAnchor.prepareMessage(2800L, 100L, 3, DIGEST));
+ assertThat(rc).isNotEqualTo(PqAnchor.proposalMessage(2800L, 100L, 3, DIGEST));
+ assertThat(rc).isNotEqualTo(PqAnchor.commitMessage(2800L, 100L, DIGEST));
+ }
+
+ @Test
+ public void theRoundChangeMessageDependsOnTargetRoundChainAndHeight() {
+ final Bytes32 base = PqAnchor.roundChangeMessage(2800L, 100L, 3);
+ assertThat(PqAnchor.roundChangeMessage(2800L, 100L, 4)).isNotEqualTo(base);
+ assertThat(PqAnchor.roundChangeMessage(2801L, 100L, 3)).isNotEqualTo(base);
+ assertThat(PqAnchor.roundChangeMessage(2800L, 101L, 3)).isNotEqualTo(base);
+ }
+
+ @Test
+ public void aBareAndAPreparedRoundChangeMessageDiffer() {
+ // The metadata is in the preimage: "move on" and "move on and re-propose THIS block" are two
+ // different assertions, and their seals must not be interchangeable.
+ final Bytes32 bare = PqAnchor.roundChangeMessage(2800L, 100L, 3);
+ final Bytes32 prepared = PqAnchor.roundChangeMessage(2800L, 100L, 3, 1, DIGEST);
+ assertThat(prepared).isNotEqualTo(bare);
+ assertThat(PqAnchor.roundChangeMessage(2800L, 100L, 3, 2, DIGEST)).isNotEqualTo(prepared);
+ }
+
+ @Test
+ public void theRoundChangeMessageRefusesImpossibleInputs() {
+ assertThatThrownBy(() -> PqAnchor.roundChangeMessage(2800L, -1L, 3))
+ .isInstanceOf(IllegalArgumentException.class);
+ assertThatThrownBy(() -> PqAnchor.roundChangeMessage(2800L, 100L, -1))
+ .isInstanceOf(IllegalArgumentException.class);
+ assertThatThrownBy(() -> PqAnchor.roundChangeMessage(2800L, 100L, 3, -1, DIGEST))
+ .isInstanceOf(IllegalArgumentException.class);
+ assertThatThrownBy(
+ () -> PqAnchor.roundChangeMessage(2800L, 100L, 3, 1, Bytes.fromHexString("0x00")))
+ .isInstanceOf(IllegalArgumentException.class);
+ }
+}
diff --git a/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/statemachine/PqHybridExtrasNeverThrowTest.java b/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/statemachine/PqHybridExtrasNeverThrowTest.java
new file mode 100755
index 000000000..2efccf985
--- /dev/null
+++ b/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/statemachine/PqHybridExtrasNeverThrowTest.java
@@ -0,0 +1,69 @@
+/*
+ * Copyright contributors to Hyperledger Besu.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.qbft.core.statemachine;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+import org.hyperledger.besu.consensus.common.bft.HybridSealSupport;
+
+import org.apache.tuweni.bytes.Bytes32;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+/**
+ * D-334 (2026-09-03): a hybrid configuration the node cannot read must cost the node its SLH-DSA
+ * contribution, never its vote. The loader throws (the defect is real and named); the state
+ * machine's helper returns an empty list instead of letting that exception reach the QBFT event
+ * loop. Both halves are asserted, so the test cannot pass by the configuration being silently
+ * ignored.
+ */
+public class PqHybridExtrasNeverThrowTest {
+
+ private static final String[] PROPS = {
+ HybridSealSupport.PROPERTY_SCHEDULE,
+ HybridSealSupport.PROPERTY_REGISTRY,
+ HybridSealSupport.PROPERTY_ATTACH_BLOCK
+ };
+
+ @BeforeEach
+ public void plantAnUnreadableRegistry() {
+ HybridSealSupport.resetForTesting();
+ System.setProperty(HybridSealSupport.PROPERTY_SCHEDULE, "10:falcon-512+slh-dsa-sha2-128s");
+ System.setProperty(
+ HybridSealSupport.PROPERTY_REGISTRY, "/nonexistent/aere-d334/hibrid-1.properties");
+ }
+
+ @AfterEach
+ public void cleanUp() {
+ for (final String p : PROPS) {
+ System.clearProperty(p);
+ }
+ HybridSealSupport.resetForTesting();
+ }
+
+ @Test
+ public void theLoaderNamesTheDefect() {
+ assertThatThrownBy(HybridSealSupport::instance)
+ .isInstanceOf(IllegalStateException.class)
+ .hasMessageContaining("AERE-PQC-HYBRID-CONF-04");
+ }
+
+ @Test
+ public void theStateMachineHelperReturnsEmptyInsteadOfThrowing() {
+ assertThat(QbftRound.hybridExtrasOrEmpty(31L, Bytes32.ZERO)).isEmpty();
+ }
+}
diff --git a/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/statemachine/PqLateSealSalvageTest.java b/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/statemachine/PqLateSealSalvageTest.java
new file mode 100755
index 000000000..82586ae25
--- /dev/null
+++ b/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/statemachine/PqLateSealSalvageTest.java
@@ -0,0 +1,195 @@
+/*
+ * Copyright contributors to Besu.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.qbft.core.statemachine;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+import org.hyperledger.besu.consensus.common.bft.ConsensusRoundIdentifier;
+import org.hyperledger.besu.consensus.common.bft.FalconSeal;
+import org.hyperledger.besu.consensus.common.bft.MessageTracker;
+import org.hyperledger.besu.consensus.common.bft.PqSealCache;
+import org.hyperledger.besu.consensus.common.bft.statemachine.FutureMessageBuffer;
+import org.hyperledger.besu.consensus.qbft.core.QbftMessageFixture;
+import org.hyperledger.besu.consensus.qbft.core.QbftReceivedMessageEventFixture;
+import org.hyperledger.besu.consensus.qbft.core.messagedata.CommitMessageData;
+import org.hyperledger.besu.consensus.qbft.core.messagedata.QbftV1;
+import org.hyperledger.besu.consensus.qbft.core.messagewrappers.Commit;
+import org.hyperledger.besu.consensus.qbft.core.types.QbftBlockCodec;
+import org.hyperledger.besu.consensus.qbft.core.types.QbftBlockHeader;
+import org.hyperledger.besu.consensus.qbft.core.types.QbftBlockchain;
+import org.hyperledger.besu.consensus.qbft.core.types.QbftFinalState;
+import org.hyperledger.besu.consensus.qbft.core.types.QbftGossiper;
+import org.hyperledger.besu.consensus.qbft.core.types.QbftMessage;
+import org.hyperledger.besu.datatypes.Address;
+import org.hyperledger.besu.datatypes.Hash;
+
+import java.util.List;
+import java.util.Optional;
+
+import com.google.common.collect.ImmutableList;
+import org.apache.tuweni.bytes.Bytes;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+import org.mockito.junit.jupiter.MockitoSettings;
+import org.mockito.quality.Strictness;
+
+/**
+ * AERE D-227 (2026-08-14): a Commit that arrives AFTER its block was imported is discarded by the
+ * height gate in {@link QbftController#consumeMessage}, and before this patch its Falcon seal died
+ * with it. Measured on chain 2800: the block imports on the quorum-th Commit, the slowest
+ * validators' Commits consistently arrive after that moment, and their seals appeared in 3% and
+ * 14% of other proposers' certificates while appearing in 100% of their own.
+ *
+ * <p>Every claim here has its pair: the one case that salvages, and the five refusals around it.
+ * The refusals are not decoration - each one guards a real path (an older seal nobody can ask for
+ * again, a fork sibling's seal, a non-validator author, a seal-less commit, and the message itself
+ * staying dead).
+ */
+@ExtendWith(MockitoExtension.class)
+@MockitoSettings(strictness = Strictness.LENIENT)
+public class PqLateSealSalvageTest {
+
+ @Mock private QbftBlockchain blockChain;
+ @Mock private QbftFinalState qbftFinalState;
+ @Mock private QbftBlockHeightManagerFactory blockHeightManagerFactory;
+ @Mock private QbftBlockHeader chainHeadBlockHeader;
+ @Mock private BaseQbftBlockHeightManager blockHeightManager;
+ @Mock private Commit commit;
+ @Mock private CommitMessageData commitMessageData;
+ @Mock private MessageTracker messageTracker;
+ @Mock private FutureMessageBuffer<QbftMessage> futureMessageBuffer;
+ @Mock private QbftGossiper qbftGossiper;
+ @Mock private QbftBlockCodec blockEncoder;
+
+ private static final long HEAD = 3L;
+ private static final Hash HEAD_HASH = Hash.hash(Bytes.fromHexString("0xaa"));
+ private static final Hash OTHER_HASH = Hash.hash(Bytes.fromHexString("0xbb"));
+ private final Address validator = Address.fromHexString("0x1");
+ private final Address nonValidator = Address.fromHexString("0x2");
+ private final FalconSeal seal = new FalconSeal(4, Bytes.fromHexString("0x29aabbcc"));
+
+ private QbftController qbftController;
+
+ @BeforeEach
+ public void setup() {
+ PqSealCache.instance().clear();
+ when(blockChain.getChainHeadHeader()).thenReturn(chainHeadBlockHeader);
+ when(blockChain.getChainHeadBlockNumber()).thenReturn(HEAD);
+ when(blockHeightManagerFactory.create(any())).thenReturn(blockHeightManager);
+ when(qbftFinalState.getValidators()).thenReturn(ImmutableList.of(validator));
+ when(chainHeadBlockHeader.getNumber()).thenReturn(HEAD);
+ when(chainHeadBlockHeader.getHash()).thenReturn(HEAD_HASH);
+ when(blockHeightManager.getParentBlockHeader()).thenReturn(chainHeadBlockHeader);
+ when(blockHeightManager.getChainHeight()).thenReturn(HEAD + 1);
+ when(qbftFinalState.isLocalNodeValidator()).thenReturn(true);
+ when(messageTracker.hasSeenMessage(any())).thenReturn(false);
+ qbftController =
+ new QbftController(
+ blockChain,
+ qbftFinalState,
+ blockHeightManagerFactory,
+ qbftGossiper,
+ messageTracker,
+ futureMessageBuffer,
+ blockEncoder);
+ qbftController.start();
+ }
+
+ @AfterEach
+ public void cleanup() {
+ // The cache is a singleton: a seal left behind would leak into unrelated tests and buy them
+ // an unearned green.
+ PqSealCache.instance().clear();
+ }
+
+ private void deliverCommit(
+ final long height, final Hash digest, final Address author, final Optional<FalconSeal> fs) {
+ when(commit.getAuthor()).thenReturn(author);
+ when(commit.getRoundIdentifier()).thenReturn(new ConsensusRoundIdentifier(height, 0));
+ when(commit.getDigest()).thenReturn(digest);
+ when(commit.getFalconSeal()).thenReturn(fs);
+ when(commitMessageData.getCode()).thenReturn(QbftV1.COMMIT);
+ when(commitMessageData.decode()).thenReturn(commit);
+ qbftController.handleMessageEvent(
+ new QbftReceivedMessageEventFixture(new QbftMessageFixture(commitMessageData)));
+ }
+
+ private List<FalconSeal> cached() {
+ return PqSealCache.instance().sealsFor(HEAD, HEAD_HASH);
+ }
+
+ @Test
+ public void lateCommitSealForImportedHeadIsSalvaged() {
+ deliverCommit(HEAD, HEAD_HASH, validator, Optional.of(seal));
+ assertThat(cached()).containsExactly(seal);
+ }
+
+ @Test
+ public void salvagedMessageStillDies() {
+ // The pair of the test above, on the same delivery: only the seal survives. Resurrecting the
+ // message would reopen the very height gate the upstream code closed on purpose.
+ deliverCommit(HEAD, HEAD_HASH, validator, Optional.of(seal));
+ verify(blockHeightManager, never()).handleCommitPayload(any());
+ }
+
+ @Test
+ public void sealOlderThanHeadIsNotSalvaged() {
+ // The proposer of block HEAD+1 carries a certificate over HEAD. A seal for HEAD-1 can never
+ // be asked for again; keeping it would only grow the cache.
+ deliverCommit(HEAD - 1, HEAD_HASH, validator, Optional.of(seal));
+ assertThat(cached()).isEmpty();
+ assertThat(PqSealCache.instance().entryCount()).isZero();
+ }
+
+ @Test
+ public void sealOverDifferentBlockAtHeadHeightIsNotSalvaged() {
+ // A losing round or a fork sibling: same height, different digest. Its seal is over a block
+ // hash the fleet did not import, so carrying it would fail verification anyway - refusing it
+ // here keeps the cache honest instead of relying on the later check.
+ deliverCommit(HEAD, OTHER_HASH, validator, Optional.of(seal));
+ assertThat(cached()).isEmpty();
+ }
+
+ @Test
+ public void sealFromNonValidatorIsNotSalvaged() {
+ // Without this refusal any peer could write into the cache of every node it is connected to.
+ deliverCommit(HEAD, HEAD_HASH, nonValidator, Optional.of(seal));
+ assertThat(cached()).isEmpty();
+ }
+
+ @Test
+ public void commitWithoutSealChangesNothing() {
+ deliverCommit(HEAD, HEAD_HASH, validator, Optional.empty());
+ assertThat(cached()).isEmpty();
+ assertThat(PqSealCache.instance().entryCount()).isZero();
+ }
+
+ @Test
+ public void currentHeightCommitIsUntouchedByTheSalvagePath() {
+ // CONTROL: a commit for the CURRENT height (head+1) must take the normal path - handled,
+ // not salvaged. If this fails, the patch moved the gate instead of adding a side-exit.
+ deliverCommit(HEAD + 1, HEAD_HASH, validator, Optional.of(seal));
+ verify(blockHeightManager).handleCommitPayload(commit);
+ assertThat(cached()).isEmpty();
+ }
+}
diff --git a/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/statemachine/PqSealsWithoutProposalTest.java b/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/statemachine/PqSealsWithoutProposalTest.java
new file mode 100755
index 000000000..47a2256c4
--- /dev/null
+++ b/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/statemachine/PqSealsWithoutProposalTest.java
@@ -0,0 +1,168 @@
+/*
+ * Copyright contributors to Aere Network.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.qbft.core.statemachine;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.mockito.Mockito.when;
+
+import java.util.List;
+import java.util.Optional;
+import org.apache.tuweni.bytes.Bytes;
+import org.hyperledger.besu.consensus.common.bft.ConsensusRoundIdentifier;
+import org.hyperledger.besu.consensus.common.bft.FalconSeal;
+import org.hyperledger.besu.consensus.common.bft.PqSealCache;
+import org.hyperledger.besu.consensus.common.bft.RoundTimer;
+import org.hyperledger.besu.consensus.common.bft.SchemeSeal;
+import org.hyperledger.besu.consensus.qbft.core.network.QbftMessageTransmitter;
+import org.hyperledger.besu.consensus.qbft.core.payload.MessageFactory;
+import org.hyperledger.besu.consensus.qbft.core.types.QbftBlockCreator;
+import org.hyperledger.besu.consensus.qbft.core.types.QbftBlockHeader;
+import org.hyperledger.besu.consensus.qbft.core.types.QbftBlockInterface;
+import org.hyperledger.besu.consensus.qbft.core.types.QbftMinedBlockObserver;
+import org.hyperledger.besu.consensus.qbft.core.types.QbftProtocolSchedule;
+import org.hyperledger.besu.consensus.qbft.core.validation.MessageValidator;
+import org.hyperledger.besu.consensus.qbft.core.validation.QbftBlockHeaderTestFixture;
+import org.hyperledger.besu.cryptoservices.NodeKey;
+import org.hyperledger.besu.cryptoservices.NodeKeyUtils;
+import org.hyperledger.besu.datatypes.Address;
+import org.hyperledger.besu.datatypes.Hash;
+import org.hyperledger.besu.util.Subscribers;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+import org.mockito.junit.jupiter.MockitoSettings;
+import org.mockito.quality.Strictness;
+
+/**
+ * D-339 (2026-09-04): a Commit teaches this node the seals of its block even when this node holds NO
+ * proposal for that round.
+ *
+ * <p>The measured defect, on chain 2800 the same evening: anchor proposers kept refusing with "this
+ * node holds 1 valid eligible Falcon seal ... 0 rejected" - they were not rejecting seals, they had
+ * never heard them. The cache was fed only from a round that held the proposed block, so a node that
+ * missed the proposal of the parent's round collected the Commits and dropped their seals; it then
+ * could not build the next anchor's certificate, the round expired, and every 32nd height paid the
+ * round-change timeout (eleven of twelve anchors before this fix).
+ *
+ * <p>What is pinned here: with no proposal in the round, a Commit's Falcon seal AND its hybrid extra
+ * seals land in the cache under the digest the Commit names; and the negative control, a Commit
+ * carrying no seals, leaves the cache empty.
+ */
+@ExtendWith(MockitoExtension.class)
+@MockitoSettings(strictness = Strictness.LENIENT)
+public class PqSealsWithoutProposalTest {
+
+ private final NodeKey nodeKey = NodeKeyUtils.generate();
+ private final Address localAddress = Address.extract(nodeKey.getPublicKey());
+ private final NodeKey peerKey = NodeKeyUtils.generate();
+ private final ConsensusRoundIdentifier roundIdentifier = new ConsensusRoundIdentifier(7, 0);
+ private final Subscribers<QbftMinedBlockObserver> subscribers = Subscribers.create();
+ private final Hash digest = Hash.hash(Bytes.fromHexString("0xdeadbeef"));
+ private final FalconSeal falcon = new FalconSeal(4, Bytes.fromHexString("0x29aabbcc"));
+ private final SchemeSeal slh = new SchemeSeal((byte) 0x02, 4, Bytes.fromHexString("0x0102030405"));
+
+ private MessageFactory localFactory;
+ private MessageFactory peerFactory;
+
+ @Mock private org.hyperledger.besu.consensus.qbft.core.types.QbftBlockCodec blockEncoder;
+
+ @Mock private QbftProtocolSchedule protocolSchedule;
+ @Mock private QbftMessageTransmitter transmitter;
+ @Mock private MessageValidator messageValidator;
+ @Mock private RoundTimer roundTimer;
+ @Mock private QbftBlockCreator blockCreator;
+ @Mock private QbftBlockInterface blockInterface;
+
+ private final QbftBlockHeader parentHeader =
+ new QbftBlockHeaderTestFixture().number(6).buildHeader();
+
+ @BeforeEach
+ public void setup() {
+ PqSealCache.instance().clear();
+ localFactory = new MessageFactory(nodeKey, blockEncoder);
+ peerFactory = new MessageFactory(peerKey, blockEncoder);
+ when(messageValidator.validateCommit(org.mockito.ArgumentMatchers.any())).thenReturn(true);
+ }
+
+ @AfterEach
+ public void clean() {
+ PqSealCache.instance().clear();
+ }
+
+ private QbftRound roundWithoutProposal() {
+ final RoundState roundState = new RoundState(roundIdentifier, 3, messageValidator);
+ assertThat(roundState.getProposedBlock()).isEmpty();
+ return new QbftRound(
+ roundState,
+ blockCreator,
+ blockInterface,
+ protocolSchedule,
+ subscribers,
+ nodeKey,
+ localAddress,
+ localFactory,
+ transmitter,
+ roundTimer,
+ parentHeader);
+ }
+
+ @Test
+ public void aCommitWithoutAProposalStillTeachesItsSeals() {
+ final QbftRound round = roundWithoutProposal();
+ round.handleCommitMessage(
+ peerFactory.createCommit(
+ roundIdentifier,
+ digest,
+ peerKey.sign(org.apache.tuweni.bytes.Bytes32.ZERO),
+ Optional.of(falcon),
+ List.of(slh)));
+
+ assertThat(PqSealCache.instance().sealsFor(roundIdentifier.getSequenceNumber(), digest))
+ .containsExactly(falcon);
+ assertThat(PqSealCache.instance().extrasFor(roundIdentifier.getSequenceNumber(), digest))
+ .containsExactly(slh);
+ }
+
+ @Test
+ public void aCommitWithoutSealsLeavesTheCacheEmpty() {
+ // the negative control: the path must not write an entry just because a Commit arrived
+ final QbftRound round = roundWithoutProposal();
+ round.handleCommitMessage(
+ peerFactory.createCommit(roundIdentifier, digest, peerKey.sign(org.apache.tuweni.bytes.Bytes32.ZERO)));
+
+ assertThat(PqSealCache.instance().sealsFor(roundIdentifier.getSequenceNumber(), digest))
+ .isEmpty();
+ assertThat(PqSealCache.instance().extrasFor(roundIdentifier.getSequenceNumber(), digest))
+ .isEmpty();
+ assertThat(PqSealCache.instance().entryCount()).isZero();
+ }
+
+ @Test
+ public void sealsLandUnderTheDigestTheCommitNames() {
+ // a seal must never be filed under some other block's hash: the producer looks up by the
+ // parent's on-chain hash, and a mis-filed seal would be an invisible way to poison a lookup
+ final QbftRound round = roundWithoutProposal();
+ round.handleCommitMessage(
+ peerFactory.createCommit(
+ roundIdentifier, digest, peerKey.sign(org.apache.tuweni.bytes.Bytes32.ZERO), Optional.of(falcon), List.of(slh)));
+
+ final Hash altul = Hash.hash(Bytes.fromHexString("0xfeedface"));
+ assertThat(PqSealCache.instance().sealsFor(roundIdentifier.getSequenceNumber(), altul)).isEmpty();
+ }
+}
diff --git a/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/validation/CommitValidatorAnchorFormTest.java b/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/validation/CommitValidatorAnchorFormTest.java
new file mode 100755
index 000000000..4d055a04f
--- /dev/null
+++ b/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/validation/CommitValidatorAnchorFormTest.java
@@ -0,0 +1,216 @@
+/*
+ * Copyright contributors to the Aere Network.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.qbft.core.validation;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import org.hyperledger.besu.consensus.common.bft.ConsensusRoundIdentifier;
+import org.hyperledger.besu.consensus.common.bft.FalconSeal;
+import org.hyperledger.besu.consensus.common.bft.PqAnchorConfig;
+import org.hyperledger.besu.consensus.common.bft.PqSignerRegistry;
+import org.hyperledger.besu.consensus.common.bft.SealScheme;
+import org.hyperledger.besu.consensus.common.bft.SealSchemes;
+import org.hyperledger.besu.consensus.common.bft.blockcreation.PqAnchorProducer;
+import org.hyperledger.besu.consensus.qbft.core.messagewrappers.Commit;
+import org.hyperledger.besu.consensus.qbft.core.types.QbftBlockCodec;
+import org.hyperledger.besu.crypto.SECPSignature;
+import org.hyperledger.besu.crypto.SecureRandomProvider;
+import org.hyperledger.besu.datatypes.Address;
+import org.hyperledger.besu.datatypes.Hash;
+
+import java.security.SecureRandom;
+import java.util.HashMap;
+import java.util.Map;
+import java.util.Optional;
+import java.util.OptionalInt;
+
+import org.apache.tuweni.bytes.Bytes;
+import org.apache.tuweni.bytes.Bytes32;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+
+/**
+ * AERE D-311 (2026-09-02). Found by the public testnet 28001 on its first day, with the options of
+ * fleet 2800: at {@code aere.pq.commitPq.forkBlock} every validator refused every commit ("post-quantum
+ * seal of index i does NOT verify over the commit digest") and the chain stopped. The emitter signs
+ * the ANCHOR form of the commit message as soon as the anchor is armed (on 2800 since 13,014,000);
+ * the verifier checked the ECDSA committed-seal digest. Two copies of one rule, and they drifted. The
+ * F95 rehearsal could not see it: its kit runs without the anchor armed.
+ *
+ * <p>What this proves, with real Falcon-512 signatures and nothing mocked on the cryptographic path:
+ *
+ * <ul>
+ * <li>anchor armed: a seal made exactly as the emitter makes it (over {@code
+ * PqAnchorProducer.commitSealMessage}) COUNTS through the production message;
+ * <li>CONTROL NEGATIV: the SAME seal fed to a validator that still verifies over the commit digest
+ * (the pre-D-311 behaviour, kept by the upstream-shaped constructors) is REFUZAT. This is the
+ * bug itself, reproduced; if this test ever goes green the fix has been undone somewhere else;
+ * <li>anchor armed, an emitter that kept signing the digest is REFUZAT by the fixed verifier;
+ * <li>anchor never armed: the message IS the commit digest, so old and new verifiers agree.
+ * </ul>
+ */
+@ExtendWith(MockitoExtension.class)
+public class CommitValidatorAnchorFormTest {
+ private static final int VALIDATOR_COUNT = 3;
+ private static final long CHAIN_ID = 28001L;
+ private static final long HEIGHT = 5_000L;
+ private final ConsensusRoundIdentifier round = new ConsensusRoundIdentifier(HEIGHT, 0);
+ /** The ECDSA committed-seal digest (round-specific). */
+ private final Hash commitDigest = Hash.fromHexStringLenient("0x1");
+ /** The round-independent on-chain hash of the same block (round forced to 0). */
+ private final Hash onchainHash = Hash.fromHexStringLenient("0x2");
+ private QbftNodeList validators;
+ private @Mock QbftBlockCodec qbftBlockCodec;
+ private final SecureRandom random = SecureRandomProvider.createSecureRandom();
+ private final Map<Integer, Address> bindings = new HashMap<>();
+ private final Map<Integer, byte[]> cheiPublice = new HashMap<>();
+ private final Map<Integer, SealScheme.PrivateHandle> cheiPrivate = new HashMap<>();
+
+ private final PqSignerRegistry registry =
+ new PqSignerRegistry() {
+ @Override
+ public Address addressForIndexAtHistoric(final long blockNumber, final int validatorIndex) {
+ return bindings.get(validatorIndex);
+ }
+
+ @Override
+ public Address addressForIndexAtOwnHead(final long blockNumber, final int validatorIndex) {
+ return bindings.get(validatorIndex);
+ }
+
+ @Override
+ public boolean verifyAtHistoric(
+ final long blockNumber,
+ final int validatorIndex,
+ final Bytes message,
+ final Bytes signature) {
+ return verifyAtOwnHead(blockNumber, validatorIndex, message, signature);
+ }
+
+ @Override
+ public boolean verifyAtOwnHead(
+ final long blockNumber,
+ final int validatorIndex,
+ final Bytes message,
+ final Bytes signature) {
+ final byte[] pk = cheiPublice.get(validatorIndex);
+ return pk != null
+ && SealSchemes.FALCON_512.verifyRaw(pk, message.toArray(), signature.toArray());
+ }
+ };
+
+ @BeforeEach
+ public void setup() {
+ validators = QbftNodeList.createNodes(VALIDATOR_COUNT, qbftBlockCodec);
+ for (int i = 0; i < VALIDATOR_COUNT; i++) {
+ final SealScheme.GeneratedPair pereche = SealSchemes.FALCON_512.generate(random);
+ bindings.put(i, validators.getNode(i).getAddress());
+ cheiPublice.put(i, pereche.publicRegistryForm());
+ cheiPrivate.put(i, pereche.privateKey());
+ }
+ }
+
+ @AfterEach
+ public void forgetAnchorConfig() {
+ PqAnchorProducer.useConfigForTesting(null);
+ }
+
+ private void armAnchorAt(final long anchorBlock) {
+ PqAnchorProducer.useConfigForTesting(
+ new PqAnchorConfig(
+ CHAIN_ID, anchorBlock, Map.of(anchorBlock, 0), OptionalInt.empty(), false));
+ }
+
+ /** Exactly what the emitter (QbftRound.pqSealMessageFor) signs at HEIGHT. */
+ private Bytes32 emitterMessage() {
+ return PqAnchorProducer.commitSealMessage(HEIGHT, onchainHash.getBytes(), commitDigest);
+ }
+
+ /** The fixed production shape: the verifier is handed the same message the emitter signs. */
+ private CommitValidator verificatorReparat(final Bytes32 expectedPqSealMessage) {
+ return new CommitValidator(
+ validators.getNodeAddresses(),
+ round,
+ commitDigest,
+ commitDigest,
+ Hash.wrap(expectedPqSealMessage),
+ new PqCommitEnforcement(HEIGHT, registry));
+ }
+
+ /** The pre-D-311 shape: enforcement verifies over the commit digest, whatever the emitter signed. */
+ private CommitValidator verificatorVechi() {
+ return new CommitValidator(
+ validators.getNodeAddresses(),
+ round,
+ commitDigest,
+ commitDigest,
+ new PqCommitEnforcement(HEIGHT, registry));
+ }
+
+ private Commit commitSealedOver(final int nod, final Bytes32 message) {
+ final SECPSignature ecdsa =
+ validators.getNode(nod).getNodeKey().sign(Bytes32.wrap(commitDigest.getBytes()));
+ final byte[] sig =
+ SealSchemes.FALCON_512.sign(cheiPrivate.get(nod), message.toArray()).orElseThrow();
+ return validators
+ .getMessageFactory(nod)
+ .createCommit(round, commitDigest, ecdsa, Optional.of(new FalconSeal(nod, Bytes.wrap(sig))));
+ }
+
+ @Test
+ public void anchorArmedTheMessageIsTheAnchorFormNotTheDigest() {
+ armAnchorAt(HEIGHT);
+ assertThat(PqAnchorProducer.sealMessageIsAnchorForm(HEIGHT)).isTrue();
+ assertThat(emitterMessage()).isNotEqualTo(Bytes32.wrap(commitDigest.getBytes()));
+ }
+
+ @Test
+ public void anchorArmedSealMadeLikeTheEmitterCountsThroughTheFixedVerifier() {
+ armAnchorAt(HEIGHT);
+ final Bytes32 message = emitterMessage();
+ assertThat(verificatorReparat(message).validate(commitSealedOver(0, message))).isTrue();
+ }
+
+ @Test
+ public void controlNegativTheOldVerifierRefusesTheVerySameSeal() {
+ // This is D-311 itself: the seal the emitter really produces, judged over the commit digest.
+ // On the testnet this line was the whole chain stopping at the fork height.
+ armAnchorAt(HEIGHT);
+ final Bytes32 message = emitterMessage();
+ assertThat(verificatorVechi().validate(commitSealedOver(0, message))).isFalse();
+ }
+
+ @Test
+ public void anchorArmedAnEmitterStillSigningTheDigestIsRefused() {
+ armAnchorAt(HEIGHT);
+ final Bytes32 sealedOverDigest = Bytes32.wrap(commitDigest.getBytes());
+ assertThat(verificatorReparat(emitterMessage()).validate(commitSealedOver(1, sealedOverDigest)))
+ .isFalse();
+ }
+
+ @Test
+ public void anchorNeverArmedTheMessageIsTheDigestAndBothVerifiersAgree() {
+ PqAnchorProducer.useConfigForTesting(PqAnchorConfig.never(CHAIN_ID));
+ final Bytes32 message = emitterMessage();
+ assertThat(message).isEqualTo(Bytes32.wrap(commitDigest.getBytes()));
+ assertThat(verificatorReparat(message).validate(commitSealedOver(2, message))).isTrue();
+ assertThat(verificatorVechi().validate(commitSealedOver(2, message))).isTrue();
+ }
+}
diff --git a/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/validation/CommitValidatorPqEnforcementTest.java b/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/validation/CommitValidatorPqEnforcementTest.java
new file mode 100755
index 000000000..b3269194f
--- /dev/null
+++ b/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/validation/CommitValidatorPqEnforcementTest.java
@@ -0,0 +1,152 @@
+/* AERE full-PQ, the WIRING step: enforcement bound into CommitValidator itself.
+ *
+ * What each case proves:
+ * - disarmed (the old constructor) = upstream behaviour, untouched -- the baseline control;
+ * - armed + commit WITHOUT a PQ seal = the vote does NOT count;
+ * - armed + a REAL Falcon seal over the commit digest = the vote counts;
+ * - armed + another validator's seal (index bound to another address) = refused;
+ * - armed + the same message below the arming height = passes (the gate is the height itself).
+ *
+ * Mesajele sunt semnate ECDSA cu uneltele de amonte (QbftNodeList/MessageFactory), sigiliile
+ * sunt Falcon-512 REAL prin stratul de scheme; nimic mockuit pe drumul criptografic. */
+package org.hyperledger.besu.consensus.qbft.core.validation;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import org.hyperledger.besu.consensus.common.bft.ConsensusRoundIdentifier;
+import org.hyperledger.besu.consensus.common.bft.FalconSeal;
+import org.hyperledger.besu.consensus.common.bft.PqSignerRegistry;
+import org.hyperledger.besu.consensus.common.bft.SealScheme;
+import org.hyperledger.besu.consensus.common.bft.SealSchemes;
+import org.hyperledger.besu.consensus.qbft.core.messagewrappers.Commit;
+import org.hyperledger.besu.consensus.qbft.core.types.QbftBlockCodec;
+import org.hyperledger.besu.crypto.SECPSignature;
+import org.hyperledger.besu.crypto.SecureRandomProvider;
+import org.hyperledger.besu.datatypes.Address;
+import org.hyperledger.besu.datatypes.Hash;
+
+import java.security.SecureRandom;
+import java.util.HashMap;
+import java.util.Map;
+import java.util.Optional;
+
+import org.apache.tuweni.bytes.Bytes;
+import org.apache.tuweni.bytes.Bytes32;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+
+@ExtendWith(MockitoExtension.class)
+public class CommitValidatorPqEnforcementTest {
+
+ private static final int VALIDATOR_COUNT = 3;
+ private static final long HEIGHT = 5_000L;
+
+ private final ConsensusRoundIdentifier round = new ConsensusRoundIdentifier(HEIGHT, 0);
+ private final Hash expectedHash = Hash.fromHexStringLenient("0x1");
+ private QbftNodeList validators;
+ private @Mock QbftBlockCodec qbftBlockCodec;
+
+ private final SecureRandom random = SecureRandomProvider.createSecureRandom();
+ private final Map<Integer, Address> bindings = new HashMap<>();
+ private final Map<Integer, byte[]> cheiPublice = new HashMap<>();
+ private final Map<Integer, SealScheme.PrivateHandle> cheiPrivate = new HashMap<>();
+
+ /** Registru de test cu legaturi index->adresa si verificare prin schema REALA. */
+ private final PqSignerRegistry registry =
+ new PqSignerRegistry() {
+ @Override
+ public Address addressForIndexAtHistoric(final long blockNumber, final int validatorIndex) {
+ return bindings.get(validatorIndex);
+ }
+
+ @Override
+ public Address addressForIndexAtOwnHead(final long blockNumber, final int validatorIndex) {
+ return bindings.get(validatorIndex);
+ }
+
+ @Override
+ public boolean verifyAtHistoric(
+ final long blockNumber, final int validatorIndex, final Bytes message, final Bytes signature) {
+ return verifyAtOwnHead(blockNumber, validatorIndex, message, signature);
+ }
+
+ @Override
+ public boolean verifyAtOwnHead(
+ final long blockNumber, final int validatorIndex, final Bytes message, final Bytes signature) {
+ final byte[] pk = cheiPublice.get(validatorIndex);
+ return pk != null
+ && SealSchemes.FALCON_512.verifyRaw(pk, message.toArray(), signature.toArray());
+ }
+ };
+
+ @BeforeEach
+ public void setup() {
+ validators = QbftNodeList.createNodes(VALIDATOR_COUNT, qbftBlockCodec);
+ for (int i = 0; i < VALIDATOR_COUNT; i++) {
+ final SealScheme.GeneratedPair pereche = SealSchemes.FALCON_512.generate(random);
+ bindings.put(i, validators.getNode(i).getAddress());
+ cheiPublice.put(i, pereche.publicRegistryForm());
+ cheiPrivate.put(i, pereche.privateKey());
+ }
+ }
+
+ private CommitValidator armat(final long armedFrom) {
+ return new CommitValidator(
+ validators.getNodeAddresses(),
+ round,
+ expectedHash,
+ expectedHash,
+ new PqCommitEnforcement(armedFrom, registry));
+ }
+
+ private Commit commitWithoutSeal(final int nod) {
+ final SECPSignature ecdsa =
+ validators.getNode(nod).getNodeKey().sign(Bytes32.wrap(expectedHash.getBytes()));
+ return validators.getMessageFactory(nod).createCommit(round, expectedHash, ecdsa);
+ }
+
+ private Commit commitWithSeal(final int nodEcdsa, final int indexFalcon) {
+ final SECPSignature ecdsa =
+ validators.getNode(nodEcdsa).getNodeKey().sign(Bytes32.wrap(expectedHash.getBytes()));
+ final byte[] sig =
+ SealSchemes.FALCON_512
+ .sign(cheiPrivate.get(indexFalcon), expectedHash.getBytes().toArray())
+ .orElseThrow();
+ return validators
+ .getMessageFactory(nodEcdsa)
+ .createCommit(round, expectedHash, ecdsa, Optional.of(new FalconSeal(indexFalcon, Bytes.wrap(sig))));
+ }
+
+ @Test
+ public void disarmedOldConstructorIsUpstreamBehaviour() {
+ final CommitValidator old =
+ new CommitValidator(validators.getNodeAddresses(), round, expectedHash, expectedHash);
+ assertThat(old.validate(commitWithoutSeal(0))).isTrue();
+ }
+
+ @Test
+ public void armedRejectsCommitWithoutPqSeal() {
+ assertThat(armat(HEIGHT).validate(commitWithoutSeal(0))).isFalse();
+ }
+
+ @Test
+ public void armedAcceptsCommitWithRealPqSeal() {
+ for (int i = 0; i < VALIDATOR_COUNT; i++) {
+ assertThat(armat(HEIGHT).validate(commitWithSeal(i, i))).isTrue();
+ }
+ }
+
+ @Test
+ public void armedRejectsSealOfAnotherValidator() {
+ // node 0's ECDSA message, index 1's Falcon seal: the author binding fails
+ assertThat(armat(HEIGHT).validate(commitWithSeal(0, 1))).isFalse();
+ }
+
+ @Test
+ public void belowArmingHeightSealIsNotRequired() {
+ assertThat(armat(HEIGHT + 1).validate(commitWithoutSeal(0))).isTrue();
+ }
+}
diff --git a/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/validation/MessageValidatorAnchorFormPlumbingTest.java b/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/validation/MessageValidatorAnchorFormPlumbingTest.java
new file mode 100755
index 000000000..a5a78d58e
--- /dev/null
+++ b/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/validation/MessageValidatorAnchorFormPlumbingTest.java
@@ -0,0 +1,109 @@
+/*
+ * Copyright contributors to the Aere Network.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.qbft.core.validation;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+import org.hyperledger.besu.consensus.common.bft.ConsensusRoundIdentifier;
+import org.hyperledger.besu.consensus.common.bft.PqAnchor;
+import org.hyperledger.besu.consensus.common.bft.PqAnchorConfig;
+import org.hyperledger.besu.consensus.common.bft.blockcreation.PqAnchorProducer;
+import org.hyperledger.besu.consensus.qbft.core.types.QbftBlock;
+import org.hyperledger.besu.consensus.qbft.core.types.QbftBlockInterface;
+import org.hyperledger.besu.datatypes.Address;
+import org.hyperledger.besu.datatypes.Hash;
+
+import java.util.List;
+import java.util.Map;
+import java.util.OptionalInt;
+
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+
+/**
+ * AERE D-311, the PRODUCTION wiring. {@link CommitValidatorAnchorFormTest} proves the verifier accepts
+ * the emitter's seal when it is handed the emitter's message; this proves that {@link
+ * MessageValidator.SubsequentMessageValidator}, the only production caller, hands it exactly that
+ * message: the anchor form over the ROUND-INDEPENDENT on-chain hash (round forced to 0) once the
+ * anchor is armed, and the plain committed-seal digest before, computed through the one shared helper
+ * and touching the block interface for round 0 only when the anchor form needs it.
+ */
+@ExtendWith(MockitoExtension.class)
+public class MessageValidatorAnchorFormPlumbingTest {
+ private static final long CHAIN_ID = 28001L;
+ private static final long HEIGHT = 7_000L;
+ private static final int ROUND = 2;
+ private final ConsensusRoundIdentifier round = new ConsensusRoundIdentifier(HEIGHT, ROUND);
+ private final Hash proposalHash = Hash.fromHexStringLenient("0x11");
+ private final Hash commitHash = Hash.fromHexStringLenient("0x22");
+ private final Hash onchainHash = Hash.fromHexStringLenient("0x33");
+
+ private @Mock QbftBlockInterface blockInterface;
+ private @Mock QbftBlock proposalBlock;
+ private @Mock QbftBlock commitBlock;
+ private @Mock QbftBlock roundZeroBlock;
+
+ @BeforeEach
+ public void setup() {
+ when(proposalBlock.getHash()).thenReturn(proposalHash);
+ when(blockInterface.replaceRoundForCommitBlock(proposalBlock, ROUND)).thenReturn(commitBlock);
+ when(commitBlock.getHash()).thenReturn(commitHash);
+ }
+
+ @AfterEach
+ public void forgetAnchorConfig() {
+ PqAnchorProducer.useConfigForTesting(null);
+ }
+
+ private MessageValidator.SubsequentMessageValidator build() {
+ return new MessageValidator.SubsequentMessageValidator(
+ List.of(Address.fromHexString("0x1")), round, proposalBlock, blockInterface);
+ }
+
+ @Test
+ public void anchorArmedTheVerifierIsHandedTheAnchorFormOverTheRoundZeroHash() {
+ PqAnchorProducer.useConfigForTesting(
+ new PqAnchorConfig(CHAIN_ID, HEIGHT, Map.of(HEIGHT, 0), OptionalInt.empty(), false));
+ when(blockInterface.replaceRoundForCommitBlock(proposalBlock, 0)).thenReturn(roundZeroBlock);
+ when(roundZeroBlock.getHash()).thenReturn(onchainHash);
+
+ final Hash handed = build().commitValidatorForTesting().expectedPqSealMessageForTesting();
+
+ assertThat(handed)
+ .isEqualTo(Hash.wrap(PqAnchor.commitMessage(CHAIN_ID, HEIGHT, onchainHash.getBytes())));
+ assertThat(handed).isNotEqualTo(commitHash);
+ verify(blockInterface).replaceRoundForCommitBlock(proposalBlock, 0);
+ }
+
+ @Test
+ public void anchorNeverArmedTheVerifierIsHandedTheCommitDigestAndRoundZeroIsNeverAsked() {
+ PqAnchorProducer.useConfigForTesting(PqAnchorConfig.never(CHAIN_ID));
+
+ final Hash handed = build().commitValidatorForTesting().expectedPqSealMessageForTesting();
+
+ assertThat(handed).isEqualTo(commitHash);
+ verify(blockInterface, never()).replaceRoundForCommitBlock(any(), eq(0));
+ }
+}
diff --git a/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/validation/PqCommitEnforcementTest.java b/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/validation/PqCommitEnforcementTest.java
new file mode 100755
index 000000000..8124b0c1f
--- /dev/null
+++ b/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/validation/PqCommitEnforcementTest.java
@@ -0,0 +1,159 @@
+/* AERE full-PQ, step 1, the core's proofs. The key case is integration with REAL
+ * cryptography: a true Falcon seal over the commit digest passes, one with a flipped bit
+ * does not, and a seal bound to a DIFFERENT author cannot vouch for anyone else's vote.
+ * The registry is a test double implementing the whole interface (the compiler is the
+ * control: without a height no answer is possible -- the D2 inheritance). */
+package org.hyperledger.besu.consensus.qbft.core.validation;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import java.security.SecureRandom;
+import java.util.Map;
+import java.util.Optional;
+
+import org.apache.tuweni.bytes.Bytes;
+import org.hyperledger.besu.consensus.common.bft.FalconSeal;
+import org.hyperledger.besu.consensus.common.bft.PqSignerRegistry;
+import org.hyperledger.besu.consensus.common.bft.SealScheme;
+import org.hyperledger.besu.consensus.common.bft.SealSchemes;
+import org.hyperledger.besu.crypto.SecureRandomProvider;
+import org.hyperledger.besu.datatypes.Address;
+import org.hyperledger.besu.datatypes.Hash;
+import org.junit.jupiter.api.Test;
+
+class PqCommitEnforcementTest {
+
+ private static final long H_ARMARE = 1_000_000L;
+ private static final Address VALIDATOR_0 = Address.fromHexString("0x" + "aa".repeat(20));
+ private static final Address VALIDATOR_1 = Address.fromHexString("0x" + "bb".repeat(20));
+ private static final Hash DIGEST = Hash.hash(Bytes.of(7, 7, 7));
+
+ private final SecureRandom random = SecureRandomProvider.createSecureRandom();
+
+ /** Registru de test: legaturi index->adresa programate + verificare prin schema REALA. */
+ private static final class RegistruDeTest implements PqSignerRegistry {
+ final Map<Integer, Address> bindings;
+ final Map<Integer, byte[]> keys;
+
+ RegistruDeTest(final Map<Integer, Address> bindings, final Map<Integer, byte[]> keys) {
+ this.bindings = bindings;
+ this.keys = keys;
+ }
+
+ @Override
+ public Address addressForIndexAtHistoric(final long blockNumber, final int validatorIndex) {
+ return bindings.get(validatorIndex);
+ }
+
+ @Override
+ public Address addressForIndexAtOwnHead(final long blockNumber, final int validatorIndex) {
+ return bindings.get(validatorIndex);
+ }
+
+ @Override
+ public boolean verifyAtHistoric(
+ final long blockNumber, final int validatorIndex, final Bytes message, final Bytes signature) {
+ return verifyAtOwnHead(blockNumber, validatorIndex, message, signature);
+ }
+
+ @Override
+ public boolean verifyAtOwnHead(
+ final long blockNumber, final int validatorIndex, final Bytes message, final Bytes signature) {
+ final byte[] pk = keys.get(validatorIndex);
+ if (pk == null) {
+ return false;
+ }
+ return SealSchemes.FALCON_512.verifyRaw(pk, message.toArray(), signature.toArray());
+ }
+ }
+
+ private record World(PqCommitEnforcement enforcement, FalconSeal sigiliuValid0) {}
+
+ /** O lume cu 2 validatori cu chei Falcon reale; sigiliul validatorului 0 peste DIGEST. */
+ private World world() {
+ final SealScheme.GeneratedPair k0 = SealSchemes.FALCON_512.generate(random);
+ final SealScheme.GeneratedPair k1 = SealSchemes.FALCON_512.generate(random);
+ final byte[] sig0 = SealSchemes.FALCON_512.sign(k0.privateKey(), DIGEST.getBytes().toArray()).orElseThrow();
+ final RegistruDeTest reg =
+ new RegistruDeTest(
+ Map.of(0, VALIDATOR_0, 1, VALIDATOR_1),
+ Map.of(0, k0.publicRegistryForm(), 1, k1.publicRegistryForm()));
+ return new World(new PqCommitEnforcement(H_ARMARE, reg), new FalconSeal(0, Bytes.wrap(sig0)));
+ }
+
+ // ------------------------------------------------------------------ sub si la granita
+
+ @Test
+ void belowArmingHeightEverythingCountsEvenWithoutSeal() {
+ final World l = world();
+ assertThat(l.enforcement().refusal(H_ARMARE - 1, VALIDATOR_0, DIGEST, Optional.empty())).isEmpty();
+ assertThat(l.enforcement().armedAt(H_ARMARE - 1)).isFalse();
+ }
+
+ @Test
+ void disarmedNeverEnforces() {
+ final World l = world();
+ final PqCommitEnforcement dezarmat =
+ new PqCommitEnforcement(PqCommitEnforcement.DISARMED, new RegistruDeTest(Map.of(), Map.of()));
+ assertThat(dezarmat.refusal(Long.MAX_VALUE - 1, VALIDATOR_0, DIGEST, Optional.empty())).isEmpty();
+ assertThat(l).isNotNull();
+ }
+
+ @Test
+ void atTheExactArmingHeightEnforcementBites() {
+ final World l = world();
+ final Optional<String> refusal = l.enforcement().refusal(H_ARMARE, VALIDATOR_0, DIGEST, Optional.empty());
+ assertThat(refusal).isPresent();
+ assertThat(refusal.get()).contains("NO post-quantum seal").contains(String.valueOf(H_ARMARE));
+ }
+
+ // ------------------------------------------------------------------ drumul fericit + negative
+
+ @Test
+ void validRealSealCounts() {
+ final World l = world();
+ assertThat(l.enforcement().refusal(H_ARMARE, VALIDATOR_0, DIGEST, Optional.of(l.sigiliuValid0())))
+ .isEmpty();
+ }
+
+ @Test
+ void sealBoundToAnotherAuthorCannotVouch() {
+ final World l = world();
+ // sigiliul indexului 0 (legat de VALIDATOR_0) pe un mesaj SEMNAT de VALIDATOR_1
+ final Optional<String> refusal =
+ l.enforcement().refusal(H_ARMARE, VALIDATOR_1, DIGEST, Optional.of(l.sigiliuValid0()));
+ assertThat(refusal).isPresent();
+ assertThat(refusal.get()).contains("someone else");
+ }
+
+ @Test
+ void corruptedSignatureIsRefusedWithTheIndexNamed() {
+ final World l = world();
+ final byte[] stricat = l.sigiliuValid0().getSignature().toArray().clone();
+ stricat[stricat.length / 2] ^= 0x01;
+ final Optional<String> refusal =
+ l.enforcement()
+ .refusal(H_ARMARE, VALIDATOR_0, DIGEST, Optional.of(new FalconSeal(0, Bytes.wrap(stricat))));
+ assertThat(refusal).isPresent();
+ assertThat(refusal.get()).contains("does NOT verify").contains("index 0");
+ }
+
+ @Test
+ void unknownIndexIsRefusedNotTrusted() {
+ final World l = world();
+ final Optional<String> refusal =
+ l.enforcement()
+ .refusal(H_ARMARE, VALIDATOR_0, DIGEST, Optional.of(new FalconSeal(7, l.sigiliuValid0().getSignature())));
+ assertThat(refusal).isPresent(); // a missing binding (null) is never "fine"
+ }
+
+ @Test
+ void sealOverADifferentDigestDoesNotCount() {
+ final World l = world();
+ final Hash altDigest = Hash.hash(Bytes.of(9, 9, 9));
+ final Optional<String> refusal =
+ l.enforcement().refusal(H_ARMARE, VALIDATOR_0, altDigest, Optional.of(l.sigiliuValid0()));
+ assertThat(refusal).isPresent();
+ assertThat(refusal.get()).contains("does NOT verify");
+ }
+}
diff --git a/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/validation/PqCommitPlumbingTest.java b/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/validation/PqCommitPlumbingTest.java
new file mode 100755
index 000000000..c697e69dc
--- /dev/null
+++ b/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/validation/PqCommitPlumbingTest.java
@@ -0,0 +1,108 @@
+/* AERE full-PQ, the PLUMBING: CommitValidator's production constructor (the 4-argument one,
+ * the only one MessageValidator calls) self-installs from the system property. The
+ * differential is the proof itself: same message, same constructor, the only difference is
+ * the property -- disarmed passes, armed below the height passes, armed at the height
+ * refuses. And the loud refusal: a broken value throws AERE-PQC-COMMIT-CONF-01 at
+ * construction, because a mistyped comma must not silently boot the node disarmed. The
+ * property is cleaned in finally so it cannot poison other classes in the same JVM (the
+ * order-dependent-green lesson). */
+package org.hyperledger.besu.consensus.qbft.core.validation;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+import org.hyperledger.besu.consensus.common.bft.ConsensusRoundIdentifier;
+import org.hyperledger.besu.consensus.qbft.core.messagewrappers.Commit;
+import org.hyperledger.besu.consensus.qbft.core.types.QbftBlockCodec;
+import org.hyperledger.besu.crypto.SECPSignature;
+import org.hyperledger.besu.datatypes.Hash;
+
+import org.apache.tuweni.bytes.Bytes32;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+
+@ExtendWith(MockitoExtension.class)
+public class PqCommitPlumbingTest {
+
+ private static final long HEIGHT = 7_777L;
+
+ private final ConsensusRoundIdentifier round = new ConsensusRoundIdentifier(HEIGHT, 0);
+ private final Hash expectedHash = Hash.fromHexStringLenient("0x1");
+ private QbftNodeList validators;
+ private @Mock QbftBlockCodec qbftBlockCodec;
+
+ @BeforeEach
+ public void setup() {
+ validators = QbftNodeList.createNodes(3, qbftBlockCodec);
+ }
+
+ @AfterEach
+ public void curataProprietatea() {
+ System.clearProperty(PqCommitEnforcement.PROPERTY_FORK_BLOCK);
+ }
+
+ private CommitValidator validatorDeProductie() {
+ // constructorul de 4 argumente: EXACT ce cheama MessageValidator.SubsequentMessageValidator
+ return new CommitValidator(validators.getNodeAddresses(), round, expectedHash, expectedHash);
+ }
+
+ private Commit commitWithoutSeal() {
+ final SECPSignature ecdsa =
+ validators.getNode(0).getNodeKey().sign(Bytes32.wrap(expectedHash.getBytes()));
+ return validators.getMessageFactory(0).createCommit(round, expectedHash, ecdsa);
+ }
+
+ @Test
+ public void withoutThePropertyProductionConstructorIsUpstream() {
+ System.clearProperty(PqCommitEnforcement.PROPERTY_FORK_BLOCK);
+ assertThat(validatorDeProductie().validate(commitWithoutSeal())).isTrue();
+ }
+
+ @Test
+ public void withThePropertyAtHeightUnsealedCommitStopsCounting() {
+ try {
+ System.setProperty(PqCommitEnforcement.PROPERTY_FORK_BLOCK, String.valueOf(HEIGHT));
+ assertThat(validatorDeProductie().validate(commitWithoutSeal())).isFalse();
+ } finally {
+ System.clearProperty(PqCommitEnforcement.PROPERTY_FORK_BLOCK);
+ }
+ }
+
+ @Test
+ public void withThePropertyAboveHeightNothingChangesYet() {
+ try {
+ System.setProperty(PqCommitEnforcement.PROPERTY_FORK_BLOCK, String.valueOf(HEIGHT + 1));
+ assertThat(validatorDeProductie().validate(commitWithoutSeal())).isTrue();
+ } finally {
+ System.clearProperty(PqCommitEnforcement.PROPERTY_FORK_BLOCK);
+ }
+ }
+
+ @Test
+ public void brokenValueRefusesLoudlyInsteadOfDisarming() {
+ try {
+ System.setProperty(PqCommitEnforcement.PROPERTY_FORK_BLOCK, "14,050,000");
+ assertThatThrownBy(this::validatorDeProductie)
+ .isInstanceOf(IllegalStateException.class)
+ .hasMessageContaining("AERE-PQC-COMMIT-CONF-01");
+ } finally {
+ System.clearProperty(PqCommitEnforcement.PROPERTY_FORK_BLOCK);
+ }
+ }
+
+ @Test
+ public void negativeValueRefusesLoudly() {
+ try {
+ System.setProperty(PqCommitEnforcement.PROPERTY_FORK_BLOCK, "-1");
+ assertThatThrownBy(this::validatorDeProductie)
+ .isInstanceOf(IllegalStateException.class)
+ .hasMessageContaining("AERE-PQC-COMMIT-CONF-01");
+ } finally {
+ System.clearProperty(PqCommitEnforcement.PROPERTY_FORK_BLOCK);
+ }
+ }
+}
diff --git a/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/validation/PqHybridEnforcementTest.java b/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/validation/PqHybridEnforcementTest.java
new file mode 100755
index 000000000..cf8c683f0
--- /dev/null
+++ b/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/validation/PqHybridEnforcementTest.java
@@ -0,0 +1,312 @@
+/* AERE HYBRID, step 2: HYBRID CERTIFICATE enforcement at the commit quorum.
+ *
+ * Everything measured here uses REAL cryptography (Falcon-512 + SLH-DSA-128s generated on
+ * every run, TEST keys) and a REAL hybrid registry built from properties, i.e. exactly the
+ * production loading path. The validators' REAL keys are not generated here and are not
+ * generated at all without the founder's ceremony and signature.
+ *
+ * The thesis it proves: above the height where the schedule requires two families, a vote
+ * carrying only one does NOT count. A half hybrid is worth the weakest family present,
+ * so a missing scheme refuses, it does not degrade. */
+package org.hyperledger.besu.consensus.qbft.core.validation;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+import org.hyperledger.besu.consensus.common.bft.FalconSeal;
+import org.hyperledger.besu.consensus.common.bft.HybridSignerRegistry;
+import org.hyperledger.besu.consensus.common.bft.PqSchemeSchedule;
+import org.hyperledger.besu.consensus.common.bft.PqSignerRegistry;
+import org.hyperledger.besu.consensus.common.bft.SchemeSeal;
+import org.hyperledger.besu.consensus.common.bft.SealScheme;
+import org.hyperledger.besu.consensus.common.bft.SealSchemes;
+import org.hyperledger.besu.crypto.SecureRandomProvider;
+import org.hyperledger.besu.datatypes.Address;
+import org.hyperledger.besu.datatypes.Hash;
+
+import java.security.SecureRandom;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.Properties;
+
+import org.apache.tuweni.bytes.Bytes;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+public class PqHybridEnforcementTest {
+
+ private static final long H_ARMARE = 1_000L;
+ private static final long H_HIBRID = 2_000L;
+ private static final Address VALIDATOR_0 = Address.fromHexString("0x" + "aa".repeat(20));
+ private static final Address VALIDATOR_1 = Address.fromHexString("0x" + "bb".repeat(20));
+ private static final Hash DIGEST = Hash.hash(Bytes.of(4, 2));
+
+ private final SecureRandom random = SecureRandomProvider.createSecureRandom();
+
+ private SealScheme.GeneratedPair falcon0;
+ private SealScheme.GeneratedPair slh0;
+ private HybridSignerRegistry registry;
+ private PqSchemeSchedule orar;
+
+ /** Registrul Falcon vechi: leaga indexul 0 de VALIDATOR_0 si verifica cu schema reala. */
+ private PqSignerRegistry registruFalcon() {
+ return new PqSignerRegistry() {
+ @Override
+ public Address addressForIndexAtHistoric(final long blockNumber, final int validatorIndex) {
+ return addressForIndexAtOwnHead(blockNumber, validatorIndex);
+ }
+
+ @Override
+ public Address addressForIndexAtOwnHead(final long blockNumber, final int validatorIndex) {
+ return validatorIndex == 0 ? VALIDATOR_0 : null;
+ }
+
+ @Override
+ public boolean verifyAtHistoric(
+ final long b, final int i, final Bytes message, final Bytes signature) {
+ return verifyAtOwnHead(b, i, message, signature);
+ }
+
+ @Override
+ public boolean verifyAtOwnHead(
+ final long b, final int i, final Bytes message, final Bytes signature) {
+ return i == 0
+ && SealSchemes.FALCON_512.verifyRaw(
+ falcon0.publicRegistryForm(), message.toArray(), signature.toArray());
+ }
+ };
+ }
+
+ @BeforeEach
+ public void setup() {
+ falcon0 = SealSchemes.FALCON_512.generate(random);
+ slh0 = SealSchemes.SLH_DSA_128S.generate(random);
+
+ final Properties p = new Properties();
+ p.setProperty("formatVersion", HybridSignerRegistry.FORMAT_VERSION);
+ p.setProperty("chainId", "2800");
+ p.setProperty("count", "1");
+ p.setProperty("0.addr", VALIDATOR_0.toHexString());
+ p.setProperty(
+ "0.key." + SealSchemes.FALCON_512.id(),
+ Bytes.wrap(falcon0.publicRegistryForm()).toHexString());
+ p.setProperty(
+ "0.key." + SealSchemes.SLH_DSA_128S.id(),
+ Bytes.wrap(slh0.publicRegistryForm()).toHexString());
+ registry = HybridSignerRegistry.fromProperties(p, "proba");
+
+ // pana la H_HIBRID doar Falcon; de acolo AMANDOUA familiile
+ orar =
+ PqSchemeSchedule.parse(
+ H_ARMARE
+ + ":"
+ + SealSchemes.FALCON_512.id()
+ + ","
+ + H_HIBRID
+ + ":"
+ + SealSchemes.FALCON_512.id()
+ + "+"
+ + SealSchemes.SLH_DSA_128S.id());
+ }
+
+ private PqCommitEnforcement hibrid() {
+ // every height counts as an anchor parent here, so the refusals below keep their meaning
+ return new PqCommitEnforcement(H_ARMARE, registruFalcon(), orar, registry, h -> true);
+ }
+
+ private FalconSeal sigiliuFalcon(final int index) {
+ return new FalconSeal(
+ index,
+ Bytes.wrap(
+ SealSchemes.FALCON_512
+ .sign(falcon0.privateKey(), DIGEST.getBytes().toArray())
+ .orElseThrow()));
+ }
+
+ private SchemeSeal sigiliuSlh(final int index, final Hash peste) {
+ return new SchemeSeal(
+ SealSchemes.SLH_DSA_128S.wireId(),
+ index,
+ Bytes.wrap(
+ SealSchemes.SLH_DSA_128S
+ .sign(slh0.privateKey(), peste.getBytes().toArray())
+ .orElseThrow()));
+ }
+
+ // ============================================================ configuratia
+
+ @Test
+ public void halfAHybridConfigurationRefusesAtConstruction() {
+ assertThatThrownBy(
+ () -> new PqCommitEnforcement(H_ARMARE, registruFalcon(), orar, null))
+ .isInstanceOf(IllegalStateException.class)
+ .hasMessageContaining("AERE-PQC-COMMIT-CONF-03");
+ assertThatThrownBy(
+ () -> new PqCommitEnforcement(H_ARMARE, registruFalcon(), null, registry))
+ .isInstanceOf(IllegalStateException.class)
+ .hasMessageContaining("AERE-PQC-COMMIT-CONF-03");
+ }
+
+ @Test
+ public void falconOnlyModeIgnoresExtrasEntirely() {
+ final PqCommitEnforcement doarFalcon = new PqCommitEnforcement(H_ARMARE, registruFalcon());
+ assertThat(
+ doarFalcon.refusal(
+ H_HIBRID, VALIDATOR_0, DIGEST, Optional.of(sigiliuFalcon(0)), List.of()))
+ .isEmpty();
+ }
+
+ // ============================================================ sub si peste treapta hibrida
+
+ @Test
+ public void belowTheHybridStepFalconAloneIsEnough() {
+ assertThat(
+ hibrid()
+ .refusal(
+ H_HIBRID - 1, VALIDATOR_0, DIGEST, Optional.of(sigiliuFalcon(0)), List.of()))
+ .isEmpty();
+ }
+
+ @Test
+ public void atTheHybridStepFalconAloneNoLongerCounts() {
+ final Optional<String> refusal =
+ hibrid()
+ .refusal(H_HIBRID, VALIDATOR_0, DIGEST, Optional.of(sigiliuFalcon(0)), List.of());
+ assertThat(refusal).isPresent();
+ assertThat(refusal.get()).contains("carries no").contains(SealSchemes.SLH_DSA_128S.id());
+ }
+
+ @Test
+ public void aFullHybridCertificateCounts() {
+ assertThat(
+ hibrid()
+ .refusal(
+ H_HIBRID,
+ VALIDATOR_0,
+ DIGEST,
+ Optional.of(sigiliuFalcon(0)),
+ List.of(sigiliuSlh(0, DIGEST))))
+ .isEmpty();
+ }
+
+ // ============================================================ controalele negative
+
+ @Test
+ public void aHybridSealOverAnotherDigestDoesNotCount() {
+ final Hash altul = Hash.hash(Bytes.of(9, 9));
+ final Optional<String> refusal =
+ hibrid()
+ .refusal(
+ H_HIBRID,
+ VALIDATOR_0,
+ DIGEST,
+ Optional.of(sigiliuFalcon(0)),
+ List.of(sigiliuSlh(0, altul)));
+ assertThat(refusal).isPresent();
+ assertThat(refusal.get()).contains("does NOT verify");
+ }
+
+ @Test
+ public void aHybridSealForAnotherIndexIsRefused() {
+ final Optional<String> refusal =
+ hibrid()
+ .refusal(
+ H_HIBRID,
+ VALIDATOR_0,
+ DIGEST,
+ Optional.of(sigiliuFalcon(0)),
+ List.of(sigiliuSlh(1, DIGEST)));
+ assertThat(refusal).isPresent();
+ assertThat(refusal.get()).contains("one commit, one signer");
+ }
+
+ @Test
+ public void aCorruptedHybridSealIsRefusedWithTheSchemeNamed() {
+ final SchemeSeal bun = sigiliuSlh(0, DIGEST);
+ final byte[] stricat = bun.getSignature().toArray().clone();
+ stricat[stricat.length / 3] ^= 0x01;
+ final Optional<String> refusal =
+ hibrid()
+ .refusal(
+ H_HIBRID,
+ VALIDATOR_0,
+ DIGEST,
+ Optional.of(sigiliuFalcon(0)),
+ List.of(
+ new SchemeSeal(
+ SealSchemes.SLH_DSA_128S.wireId(), 0, Bytes.wrap(stricat))));
+ assertThat(refusal).isPresent();
+ assertThat(refusal.get())
+ .contains("does NOT verify")
+ .contains(SealSchemes.SLH_DSA_128S.id());
+ }
+
+ @Test
+ public void anIndexNotBoundToTheAuthorInTheHybridRegistryIsRefused() {
+ // the Falcon registry binds index 0 to VALIDATOR_0; we ask for the verdict as if the
+ // author were VALIDATOR_1: the Falcon path refuses first, so the hybrid is never touched
+ final Optional<String> refusal =
+ hibrid()
+ .refusal(
+ H_HIBRID,
+ VALIDATOR_1,
+ DIGEST,
+ Optional.of(sigiliuFalcon(0)),
+ List.of(sigiliuSlh(0, DIGEST)));
+ assertThat(refusal).isPresent();
+ assertThat(refusal.get()).contains("someone else");
+ }
+
+ @Test
+ public void theTwoFamiliesAreIndependentAndTheProofSaysSo() {
+ // the control that gives the hybrid its meaning: a Falcon signature does not pass as
+ // SLH-DSA and vice versa. If it did, "hybrid" would be the same leg twice.
+ final byte[] message = DIGEST.getBytes().toArray();
+ final byte[] sigF =
+ SealSchemes.FALCON_512.sign(falcon0.privateKey(), message).orElseThrow();
+ final byte[] sigS =
+ SealSchemes.SLH_DSA_128S.sign(slh0.privateKey(), message).orElseThrow();
+ assertThat(SealSchemes.SLH_DSA_128S.verifyRaw(slh0.publicRegistryForm(), message, sigF))
+ .isFalse();
+ assertThat(SealSchemes.FALCON_512.verifyRaw(falcon0.publicRegistryForm(), message, sigS))
+ .isFalse();
+ // and an SLH-DSA seal presented under the Falcon label cannot enter the hybrid slot,
+ // because lookup there goes by scheme label
+ final Optional<String> refusal =
+ hibrid()
+ .refusal(
+ H_HIBRID,
+ VALIDATOR_0,
+ DIGEST,
+ Optional.of(sigiliuFalcon(0)),
+ List.of(new SchemeSeal(SealSchemes.FALCON_512.wireId(), 0, Bytes.wrap(sigS))));
+ assertThat(refusal).isPresent();
+ assertThat(refusal.get()).contains("carries no");
+ }
+
+ @Test
+ public void theRegistryItselfHoldsBothFamiliesForTheSameValidator() {
+ assertThat(registry.publicKey(0, SealSchemes.FALCON_512.id())).isPresent();
+ assertThat(registry.publicKey(0, SealSchemes.SLH_DSA_128S.id())).isPresent();
+ assertThat(registry.coverage(SealSchemes.SLH_DSA_128S.id())).isEqualTo(1);
+ assertThat(registry.address(0)).isPresent();
+ assertThat(Map.of()).isEmpty();
+ }
+
+ /** D-329 (2026-09-03): off the anchor parents the extra seals are neither demanded nor emitted. */
+ @Test
+ void offTheAnchorParentsACommitWithoutExtrasStillCounts() {
+ final PqCommitEnforcement pe =
+ new PqCommitEnforcement(H_ARMARE, registruFalcon(), orar, registry, h -> false);
+ final FalconSeal falcon = sigiliuFalcon(0);
+ assertThat(pe.refusal(H_HIBRID, VALIDATOR_0, DIGEST, java.util.Optional.of(falcon), java.util.List.of()))
+ .describedAs("no extras demanded where the successor is not an anchor")
+ .isEmpty();
+ final PqCommitEnforcement peOn =
+ new PqCommitEnforcement(H_ARMARE, registruFalcon(), orar, registry, h -> true);
+ assertThat(peOn.refusal(H_HIBRID, VALIDATOR_0, DIGEST, java.util.Optional.of(falcon), java.util.List.of()))
+ .describedAs("the same commit IS refused where the successor is an anchor")
+ .isPresent();
+ }
+}
diff --git a/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/validation/PqMessageAgilityTest.java b/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/validation/PqMessageAgilityTest.java
new file mode 100755
index 000000000..cb51fed29
--- /dev/null
+++ b/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/validation/PqMessageAgilityTest.java
@@ -0,0 +1,198 @@
+/*
+ * Copyright contributors to Besu.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.qbft.core.validation;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import org.hyperledger.besu.consensus.common.bft.FalconSeal;
+import org.hyperledger.besu.consensus.common.bft.PqAnchor;
+import org.hyperledger.besu.consensus.common.bft.PqSignerRegistry;
+import org.hyperledger.besu.consensus.common.bft.SealScheme;
+import org.hyperledger.besu.consensus.common.bft.SealSchemes;
+import org.hyperledger.besu.consensus.qbft.core.payload.PreparedRoundMetadata;
+import org.hyperledger.besu.crypto.SecureRandomProvider;
+import org.hyperledger.besu.datatypes.Address;
+import org.hyperledger.besu.datatypes.Hash;
+
+import java.security.SecureRandom;
+import java.util.Map;
+import java.util.Optional;
+
+import org.apache.tuweni.bytes.Bytes;
+import org.apache.tuweni.bytes.Bytes32;
+import org.junit.jupiter.api.Test;
+
+/**
+ * CRYPTOGRAPHIC AGILITY of the PROPOSAL and ROUND-CHANGE enforcements: the same consensus code,
+ * UNTOUCHED, accepts a seal made with a DIFFERENT post-quantum scheme.
+ *
+ * <p>The question and the method are {@link PqPrepareAgilityTest}'s, asked of the two surfaces
+ * built after it (PROPOSAL on 2026-08-30, ROUND-CHANGE on 2026-08-31): both enforcements receive
+ * the registry through their constructor and name no scheme, so the Falcon nail must sit only in
+ * the production wiring ({@code PqSignerRegistry.falconSealSupport()}), never in the enforcement
+ * class. If any of these tests fails, a change of maths would mean opening consensus code rather
+ * than adding a binding - a far more expensive finding than the test.
+ *
+ * <p>ONE class for both surfaces on purpose: the twin-class finding (D-293, consolidated
+ * 2026-08-31) measured what per-surface copies of the same idea cost - one gets a repair, the
+ * other silently does not. The shared harness here is the fix applied in advance.
+ *
+ * <p>WHAT THIS DOES NOT PROVE: that the fleet can run this way today. The production wiring stays
+ * Falcon-only, recorded as such in the findings register (D-285).
+ */
+class PqMessageAgilityTest {
+
+ private static final long H_ARMARE = 1_000L;
+ private static final int ROUND = 2;
+ private static final long CHAIN_ID = 2800L;
+ private static final Address VALIDATOR_0 = Address.fromHexString("0x" + "cc".repeat(20));
+ private static final Hash DIGEST = Hash.hash(Bytes.of(9, 9, 9));
+
+ private final SecureRandom random = SecureRandomProvider.createSecureRandom();
+
+ /** A registry that verifies under A GIVEN SCHEME, whichever it is. Nothing Falcon inside. */
+ private static final class RegistryPerScheme implements PqSignerRegistry {
+ private final SealScheme scheme;
+ private final Map<Integer, Address> bindings;
+ private final Map<Integer, byte[]> keys;
+
+ RegistryPerScheme(
+ final SealScheme scheme, final Map<Integer, Address> bindings, final Map<Integer, byte[]> keys) {
+ this.scheme = scheme;
+ this.bindings = bindings;
+ this.keys = keys;
+ }
+
+ @Override
+ public Address addressForIndexAtHistoric(final long blockNumber, final int validatorIndex) {
+ return bindings.get(validatorIndex);
+ }
+
+ @Override
+ public Address addressForIndexAtOwnHead(final long blockNumber, final int validatorIndex) {
+ return bindings.get(validatorIndex);
+ }
+
+ @Override
+ public boolean verifyAtHistoric(
+ final long blockNumber, final int validatorIndex, final Bytes message, final Bytes signature) {
+ return verifyAtOwnHead(blockNumber, validatorIndex, message, signature);
+ }
+
+ @Override
+ public boolean verifyAtOwnHead(
+ final long blockNumber, final int validatorIndex, final Bytes message, final Bytes signature) {
+ final byte[] pk = keys.get(validatorIndex);
+ return pk != null && scheme.verifyRaw(pk, message.toArray(), signature.toArray());
+ }
+ }
+
+ private RegistryPerScheme registryFor(final SealScheme scheme, final SealScheme.GeneratedPair k) {
+ return new RegistryPerScheme(scheme, Map.of(0, VALIDATOR_0), Map.of(0, k.publicRegistryForm()));
+ }
+
+ /** A PROPOSAL signed with the given scheme, enforced over a registry on that same scheme. */
+ private boolean proposalPassesUnder(final SealScheme scheme) {
+ final SealScheme.GeneratedPair k = scheme.generate(random);
+ final Bytes32 message = PqAnchor.proposalMessage(CHAIN_ID, H_ARMARE, ROUND, DIGEST.getBytes());
+ final byte[] sig = scheme.sign(k.privateKey(), message.toArray()).orElseThrow();
+ final PqProposalEnforcement enforcement =
+ new PqProposalEnforcement(H_ARMARE, registryFor(scheme, k), CHAIN_ID);
+ return enforcement
+ .refusal(H_ARMARE, ROUND, VALIDATOR_0, DIGEST, Optional.of(new FalconSeal(0, Bytes.wrap(sig))))
+ .isEmpty();
+ }
+
+ /**
+ * A ROUND-CHANGE signed with the given scheme, enforced over a registry on that same scheme -
+ * bare or claiming a prepared block, because the two preimages differ and both must stay
+ * scheme-free.
+ */
+ private boolean roundChangePassesUnder(final SealScheme scheme, final boolean withPrepared) {
+ final SealScheme.GeneratedPair k = scheme.generate(random);
+ final Bytes32 message =
+ withPrepared
+ ? PqAnchor.roundChangeMessage(CHAIN_ID, H_ARMARE, ROUND, 1, DIGEST.getBytes())
+ : PqAnchor.roundChangeMessage(CHAIN_ID, H_ARMARE, ROUND);
+ final byte[] sig = scheme.sign(k.privateKey(), message.toArray()).orElseThrow();
+ final PqRoundChangeEnforcement enforcement =
+ new PqRoundChangeEnforcement(H_ARMARE, registryFor(scheme, k), CHAIN_ID);
+ final Optional<PreparedRoundMetadata> prm =
+ withPrepared ? Optional.of(new PreparedRoundMetadata(DIGEST, 1)) : Optional.empty();
+ return enforcement
+ .refusal(H_ARMARE, ROUND, VALIDATOR_0, prm, Optional.of(new FalconSeal(0, Bytes.wrap(sig))))
+ .isEmpty();
+ }
+
+ @Test
+ void aProposalSignedWithFALCONPasses() {
+ // THE WITNESS. Without it, a "passes" for SLH-DSA would not say whether the enforcement
+ // verifies anything at all.
+ assertThat(proposalPassesUnder(SealSchemes.FALCON_512)).isTrue();
+ }
+
+ @Test
+ void aProposalSignedWithSLHDSAPassesTHESAMEWay() {
+ // The same enforcement class, the same message, THE SAME consensus code - different maths.
+ assertThat(proposalPassesUnder(SealSchemes.SLH_DSA_128S)).isTrue();
+ }
+
+ @Test
+ void aRoundChangeSignedWithFALCONPasses() {
+ assertThat(roundChangePassesUnder(SealSchemes.FALCON_512, false)).isTrue();
+ assertThat(roundChangePassesUnder(SealSchemes.FALCON_512, true)).isTrue();
+ }
+
+ @Test
+ void aRoundChangeSignedWithSLHDSAPassesTHESAMEWay() {
+ assertThat(roundChangePassesUnder(SealSchemes.SLH_DSA_128S, false)).isTrue();
+ assertThat(roundChangePassesUnder(SealSchemes.SLH_DSA_128S, true)).isTrue();
+ }
+
+ @Test
+ void neitherEnforcementNAMESASchemeAtAll() {
+ // The control that makes "passes" mean something: a Falcon seal against an SLH-DSA registry
+ // must be REFUSED on both surfaces. Otherwise "passes" could just mean "does not verify".
+ final SealScheme.GeneratedPair falcon = SealSchemes.FALCON_512.generate(random);
+ final SealScheme.GeneratedPair slh = SealSchemes.SLH_DSA_128S.generate(random);
+ final RegistryPerScheme slhRegistry = registryFor(SealSchemes.SLH_DSA_128S, slh);
+
+ final Bytes32 propMsg = PqAnchor.proposalMessage(CHAIN_ID, H_ARMARE, ROUND, DIGEST.getBytes());
+ final byte[] propSigFalcon =
+ SealSchemes.FALCON_512.sign(falcon.privateKey(), propMsg.toArray()).orElseThrow();
+ assertThat(
+ new PqProposalEnforcement(H_ARMARE, slhRegistry, CHAIN_ID)
+ .refusal(
+ H_ARMARE,
+ ROUND,
+ VALIDATOR_0,
+ DIGEST,
+ Optional.of(new FalconSeal(0, Bytes.wrap(propSigFalcon)))))
+ .isPresent();
+
+ final Bytes32 rcMsg = PqAnchor.roundChangeMessage(CHAIN_ID, H_ARMARE, ROUND);
+ final byte[] rcSigFalcon =
+ SealSchemes.FALCON_512.sign(falcon.privateKey(), rcMsg.toArray()).orElseThrow();
+ assertThat(
+ new PqRoundChangeEnforcement(H_ARMARE, slhRegistry, CHAIN_ID)
+ .refusal(
+ H_ARMARE,
+ ROUND,
+ VALIDATOR_0,
+ Optional.empty(),
+ Optional.of(new FalconSeal(0, Bytes.wrap(rcSigFalcon)))))
+ .isPresent();
+ }
+}
diff --git a/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/validation/PqPrepareAgilityTest.java b/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/validation/PqPrepareAgilityTest.java
new file mode 100755
index 000000000..ce7fb371a
--- /dev/null
+++ b/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/validation/PqPrepareAgilityTest.java
@@ -0,0 +1,180 @@
+/*
+ * Copyright contributors to Besu.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.qbft.core.validation;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import org.hyperledger.besu.consensus.common.bft.FalconSeal;
+import org.hyperledger.besu.consensus.common.bft.PqAnchor;
+import org.hyperledger.besu.consensus.common.bft.PqSignerRegistry;
+import org.hyperledger.besu.consensus.common.bft.SealScheme;
+import org.hyperledger.besu.consensus.common.bft.SealSchemes;
+import org.hyperledger.besu.crypto.SecureRandomProvider;
+import org.hyperledger.besu.datatypes.Address;
+import org.hyperledger.besu.datatypes.Hash;
+
+import java.security.SecureRandom;
+import java.util.Map;
+import java.util.Optional;
+
+import org.apache.tuweni.bytes.Bytes;
+import org.apache.tuweni.bytes.Bytes32;
+import org.junit.jupiter.api.Test;
+
+/**
+ * CRYPTOGRAPHIC AGILITY of the PREPARE enforcement: the same consensus code, UNTOUCHED, accepts a
+ * seal made with a DIFFERENT post-quantum scheme.
+ *
+ * <p>WHY THIS EXISTS - it is a question asked of my own work from the night of the 28th to the
+ * 29th. The anchor has been scheme-agile since 2026-08-28 (finding D-266): the hybrid registry
+ * holds keys PER SCHEME and dispatches through {@code SealSchemes.byId}. The new surface, PREPARE,
+ * reads at first sight as nailed to Falcon: the production wiring goes through
+ * {@code PqSignerRegistry.falconSealSupport()}, and that lands in {@code verifyWithKey}, which
+ * names {@code SealSchemes.FALCON_512} literally. The question that matters is not "is the wiring
+ * agile?" - plainly it is not - but <b>where exactly the nail is: in the enforcement class, or only
+ * in the wiring?</b>
+ *
+ * <p>This test answers by measurement. {@link PqPrepareEnforcement} receives the registry through
+ * its constructor and names no scheme at all; so if it is given a registry that verifies under
+ * SLH-DSA, a PREPARE signed with SLH-DSA must pass <b>without touching one line of consensus
+ * code</b>. If it passes, the nail is only in the wiring and comes out with a new binding rather
+ * than a rewrite. If it does not pass, the enforcement itself has to be opened up - and that would
+ * be a far more expensive finding.
+ *
+ * <p>SLH-DSA is the very second scheme the founder chose on 7 August for the hybrid certificate,
+ * and it is already live as a precompile on the chain from block 9,189,161. It is not a scheme
+ * invented for this test.
+ *
+ * <p>WHAT THIS DOES NOT PROVE: it does not say the fleet can run this way today. The production
+ * wiring stays Falcon-only, and that is written as such in the findings register. What is measured
+ * here is only where the limit sits.
+ */
+class PqPrepareAgilityTest {
+
+ private static final long H_ARMARE = 1_000L;
+ private static final int ROUND = 2;
+ private static final long CHAIN_ID = 2800L;
+ private static final Address VALIDATOR_0 = Address.fromHexString("0x" + "cc".repeat(20));
+ private static final Hash DIGEST = Hash.hash(Bytes.of(9, 9, 9));
+
+ private final SecureRandom random = SecureRandomProvider.createSecureRandom();
+
+ /** A registry that verifies under A GIVEN SCHEME, whichever it is. Nothing Falcon inside. */
+ private static final class RegistryPerScheme implements PqSignerRegistry {
+ private final SealScheme scheme;
+ private final Map<Integer, Address> bindings;
+ private final Map<Integer, byte[]> keys;
+
+ RegistryPerScheme(
+ final SealScheme scheme, final Map<Integer, Address> bindings, final Map<Integer, byte[]> keys) {
+ this.scheme = scheme;
+ this.bindings = bindings;
+ this.keys = keys;
+ }
+
+ @Override
+ public Address addressForIndexAtHistoric(final long blockNumber, final int validatorIndex) {
+ return bindings.get(validatorIndex);
+ }
+
+ @Override
+ public Address addressForIndexAtOwnHead(final long blockNumber, final int validatorIndex) {
+ return bindings.get(validatorIndex);
+ }
+
+ @Override
+ public boolean verifyAtHistoric(
+ final long blockNumber, final int validatorIndex, final Bytes message, final Bytes signature) {
+ return verifyAtOwnHead(blockNumber, validatorIndex, message, signature);
+ }
+
+ @Override
+ public boolean verifyAtOwnHead(
+ final long blockNumber, final int validatorIndex, final Bytes message, final Bytes signature) {
+ final byte[] pk = keys.get(validatorIndex);
+ return pk != null && scheme.verifyRaw(pk, message.toArray(), signature.toArray());
+ }
+ }
+
+ private Bytes32 message() {
+ return PqAnchor.prepareMessage(CHAIN_ID, H_ARMARE, ROUND, DIGEST.getBytes());
+ }
+
+ /** A PREPARE signed with the given scheme, enforced over a registry on that same scheme. */
+ private boolean passesUnder(final SealScheme scheme) {
+ final SealScheme.GeneratedPair k = scheme.generate(random);
+ final byte[] sig = scheme.sign(k.privateKey(), message().toArray()).orElseThrow();
+ final PqPrepareEnforcement enforcement =
+ new PqPrepareEnforcement(
+ H_ARMARE,
+ new RegistryPerScheme(
+ scheme, Map.of(0, VALIDATOR_0), Map.of(0, k.publicRegistryForm())),
+ CHAIN_ID);
+ final Optional<String> refusal =
+ enforcement.refusal(
+ H_ARMARE, ROUND, VALIDATOR_0, DIGEST, Optional.of(new FalconSeal(0, Bytes.wrap(sig))));
+ return refusal.isEmpty();
+ }
+
+ @Test
+ void aPrepareSignedWithFALCONPasses() {
+ // THE WITNESS. Without it, a "passes" for SLH-DSA would not say whether the enforcement
+ // verifies anything at all.
+ assertThat(passesUnder(SealSchemes.FALCON_512)).isTrue();
+ }
+
+ @Test
+ void aPrepareSignedWithSLHDSAPassesTHESAMEWay() {
+ // The same enforcement class, the same message, THE SAME consensus code - different maths.
+ assertThat(passesUnder(SealSchemes.SLH_DSA_128S)).isTrue();
+ }
+
+ @Test
+ void theEnforcementNAMESNoSchemeAtAll() {
+ // The control that makes the test above mean something: if the registry verifies under SLH-DSA
+ // but the seal was made with Falcon, it must be REFUSED. Otherwise "passes" could just mean
+ // "does not verify".
+ final SealScheme.GeneratedPair falcon = SealSchemes.FALCON_512.generate(random);
+ final SealScheme.GeneratedPair slh = SealSchemes.SLH_DSA_128S.generate(random);
+ final byte[] sigFalcon =
+ SealSchemes.FALCON_512.sign(falcon.privateKey(), message().toArray()).orElseThrow();
+
+ final PqPrepareEnforcement enforcement =
+ new PqPrepareEnforcement(
+ H_ARMARE,
+ new RegistryPerScheme(
+ SealSchemes.SLH_DSA_128S,
+ Map.of(0, VALIDATOR_0),
+ Map.of(0, slh.publicRegistryForm())),
+ CHAIN_ID);
+ final Optional<String> refusal =
+ enforcement.refusal(
+ H_ARMARE,
+ ROUND,
+ VALIDATOR_0,
+ DIGEST,
+ Optional.of(new FalconSeal(0, Bytes.wrap(sigFalcon))));
+ assertThat(refusal).isPresent();
+ }
+
+ @Test
+ void theTwoSchemesReallyAreDIFFERENT() {
+ // The second control of the method: if the two schemes happened to be the same implementation,
+ // the agility test would be a tautology. Their identities and key lengths must differ.
+ assertThat(SealSchemes.FALCON_512.id()).isNotEqualTo(SealSchemes.SLH_DSA_128S.id());
+ assertThat(SealSchemes.FALCON_512.publicKeyLength())
+ .isNotEqualTo(SealSchemes.SLH_DSA_128S.publicKeyLength());
+ }
+}
diff --git a/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/validation/PqPrepareEnforcementTest.java b/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/validation/PqPrepareEnforcementTest.java
new file mode 100755
index 000000000..620f0713c
--- /dev/null
+++ b/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/validation/PqPrepareEnforcementTest.java
@@ -0,0 +1,266 @@
+/*
+ * Copyright contributors to Besu.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.qbft.core.validation;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+import org.hyperledger.besu.consensus.common.bft.FalconSeal;
+import org.hyperledger.besu.consensus.common.bft.PqAnchor;
+import org.hyperledger.besu.consensus.common.bft.PqSignerRegistry;
+import org.hyperledger.besu.consensus.common.bft.SealScheme;
+import org.hyperledger.besu.consensus.common.bft.SealSchemes;
+import org.hyperledger.besu.crypto.SecureRandomProvider;
+import org.hyperledger.besu.datatypes.Address;
+import org.hyperledger.besu.datatypes.Hash;
+
+import java.security.SecureRandom;
+import java.util.Map;
+import java.util.Optional;
+
+import org.apache.tuweni.bytes.Bytes;
+import org.apache.tuweni.bytes.Bytes32;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.Test;
+
+/**
+ * PREPARE ENFORCEMENT, step 4. The structure follows PqCommitEnforcementTest deliberately.
+ *
+ * <p>What is proven here, each item closing one way of being wrong:
+ *
+ * <ol>
+ * <li>below the arming height NOTHING changes - the condition for the binary to sit on the fleet;
+ * <li>above it, a PREPARE without a seal does NOT count;
+ * <li>a seal from ANOTHER validator does not vouch for this author;
+ * <li>a seal over a DIFFERENT MESSAGE does not pass - in particular one over the COMMIT message,
+ * which is exactly the attack that domain separation closes;
+ * <li>a seal from a DIFFERENT ROUND does not pass;
+ * <li>a mistyped configuration REFUSES, it does not disarm.
+ * </ol>
+ *
+ * <p>The keys are REAL Falcon keys, generated in-process, and verification goes through the real
+ * scheme. A test with fake signatures would prove that we can compare strings, not that the
+ * enforcement enforces.
+ */
+class PqPrepareEnforcementTest {
+
+ private static final long H_ARMARE = 1_000_000L;
+ private static final int ROUND = 3;
+ private static final Address VALIDATOR_0 = Address.fromHexString("0x" + "aa".repeat(20));
+ private static final Address VALIDATOR_1 = Address.fromHexString("0x" + "bb".repeat(20));
+ private static final Hash DIGEST = Hash.hash(Bytes.of(7, 7, 7));
+ private static final long CHAIN_ID = 2800L;
+
+ private final SecureRandom random = SecureRandomProvider.createSecureRandom();
+
+ @AfterEach
+ void curata() {
+ System.clearProperty(PqPrepareEnforcement.PROPERTY_FORK_BLOCK);
+ }
+
+ /** Registru de test: legaturi index->adresa programate + verificare prin schema REALA. */
+ private static final class RegistruDeTest implements PqSignerRegistry {
+ final Map<Integer, Address> bindings;
+ final Map<Integer, byte[]> keys;
+
+ RegistruDeTest(final Map<Integer, Address> bindings, final Map<Integer, byte[]> keys) {
+ this.bindings = bindings;
+ this.keys = keys;
+ }
+
+ @Override
+ public Address addressForIndexAtHistoric(final long blockNumber, final int validatorIndex) {
+ return bindings.get(validatorIndex);
+ }
+
+ @Override
+ public Address addressForIndexAtOwnHead(final long blockNumber, final int validatorIndex) {
+ return bindings.get(validatorIndex);
+ }
+
+ @Override
+ public boolean verifyAtHistoric(
+ final long blockNumber, final int validatorIndex, final Bytes message, final Bytes signature) {
+ return verifyAtOwnHead(blockNumber, validatorIndex, message, signature);
+ }
+
+ @Override
+ public boolean verifyAtOwnHead(
+ final long blockNumber, final int validatorIndex, final Bytes message, final Bytes signature) {
+ final byte[] pk = keys.get(validatorIndex);
+ if (pk == null) {
+ return false;
+ }
+ return SealSchemes.FALCON_512.verifyRaw(pk, message.toArray(), signature.toArray());
+ }
+ }
+
+ private record World(
+ PqPrepareEnforcement enforcement,
+ FalconSeal valid0,
+ SealScheme.GeneratedPair k0,
+ SealScheme.GeneratedPair k1) {}
+
+ private Bytes32 mesajPrepare(final long h, final int round) {
+ return PqAnchor.prepareMessage(CHAIN_ID, h, round, DIGEST.getBytes());
+ }
+
+ /** Two validators with real Falcon keys; validator 0's seal over the PREPARE message at H_ARMARE. */
+ private World world() {
+ final SealScheme.GeneratedPair k0 = SealSchemes.FALCON_512.generate(random);
+ final SealScheme.GeneratedPair k1 = SealSchemes.FALCON_512.generate(random);
+ final byte[] sig0 =
+ SealSchemes.FALCON_512
+ .sign(k0.privateKey(), mesajPrepare(H_ARMARE, ROUND).toArray())
+ .orElseThrow();
+ final RegistruDeTest reg =
+ new RegistruDeTest(
+ Map.of(0, VALIDATOR_0, 1, VALIDATOR_1),
+ Map.of(0, k0.publicRegistryForm(), 1, k1.publicRegistryForm()));
+ return new World(
+ new PqPrepareEnforcement(H_ARMARE, reg, CHAIN_ID), new FalconSeal(0, Bytes.wrap(sig0)), k0, k1);
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // 1. BELOW the arming height NOTHING changes. The condition for the binary to sit on the fleet.
+ // ---------------------------------------------------------------------------------------------
+ @Test
+ void belowTheArmingHeightAnUnsealedPrepareDOESCount() {
+ final World l = world();
+ assertThat(l.enforcement().armedAt(H_ARMARE - 1)).isFalse();
+ assertThat(l.enforcement().refusal(H_ARMARE - 1, ROUND, VALIDATOR_0, DIGEST, Optional.empty()))
+ .isEmpty();
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // 2. ABOVE it, a PREPARE without a seal does not count.
+ // ---------------------------------------------------------------------------------------------
+ @Test
+ void aboveTheHeightAnUnsealedPrepareDoesNOTCount() {
+ final World l = world();
+ final Optional<String> refusal =
+ l.enforcement().refusal(H_ARMARE, ROUND, VALIDATOR_0, DIGEST, Optional.empty());
+ assertThat(refusal).isPresent();
+ assertThat(refusal.get()).contains("carries NO post-quantum seal");
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // 3. A GOOD seal from the author passes.
+ // ---------------------------------------------------------------------------------------------
+ @Test
+ void aGoodSealFromTheAuthorPasses() {
+ final World l = world();
+ assertThat(l.enforcement().refusal(H_ARMARE, ROUND, VALIDATOR_0, DIGEST, Optional.of(l.valid0())))
+ .isEmpty();
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // 4. The same seal, a different author: it does not vouch for somebody else.
+ // ---------------------------------------------------------------------------------------------
+ @Test
+ void aSealDoesNotVouchForAnotherAuthor() {
+ final World l = world();
+ final Optional<String> refusal =
+ l.enforcement().refusal(H_ARMARE, ROUND, VALIDATOR_1, DIGEST, Optional.of(l.valid0()));
+ assertThat(refusal).isPresent();
+ assertThat(refusal.get()).contains("cannot vouch for someone else's vote");
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // 5. DOMAIN SEPARATION, and this is the security test of the whole step: a seal given HONESTLY
+ // over the COMMIT message must not pass as a PREPARE seal.
+ // ---------------------------------------------------------------------------------------------
+ @Test
+ void aSealOverTheCOMMITMessageDoesNotPassAsPREPARE() {
+ final World l = world();
+ final Bytes32 mesajCommit = PqAnchor.commitMessage(CHAIN_ID, H_ARMARE, DIGEST.getBytes());
+ final byte[] sigCommit =
+ SealSchemes.FALCON_512.sign(l.k0().privateKey(), mesajCommit.toArray()).orElseThrow();
+
+ final Optional<String> refusal =
+ l.enforcement()
+ .refusal(
+ H_ARMARE, ROUND, VALIDATOR_0, DIGEST, Optional.of(new FalconSeal(0, Bytes.wrap(sigCommit))));
+ assertThat(refusal).isPresent();
+ assertThat(refusal.get()).contains("does NOT verify over the prepare message");
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // 6. The ROUND is in the preimage: a seal from a failed round does not justify another one.
+ // ---------------------------------------------------------------------------------------------
+ @Test
+ void aSealFromAnotherROUNDDoesNotPass() {
+ final World l = world();
+ final byte[] sigAltaRunda =
+ SealSchemes.FALCON_512
+ .sign(l.k0().privateKey(), mesajPrepare(H_ARMARE, ROUND + 1).toArray())
+ .orElseThrow();
+ final Optional<String> refusal =
+ l.enforcement()
+ .refusal(
+ H_ARMARE, ROUND, VALIDATOR_0, DIGEST, Optional.of(new FalconSeal(0, Bytes.wrap(sigAltaRunda))));
+ assertThat(refusal).isPresent();
+ assertThat(refusal.get()).contains("does NOT verify over the prepare message");
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // 7. An index the registry binds to nobody.
+ // ---------------------------------------------------------------------------------------------
+ @Test
+ void anUNBOUNDIndexDoesNotPass() {
+ final World l = world();
+ final Optional<String> refusal =
+ l.enforcement()
+ .refusal(H_ARMARE, ROUND, VALIDATOR_0, DIGEST, Optional.of(new FalconSeal(99, l.valid0().getSignature())));
+ assertThat(refusal).isPresent();
+ assertThat(refusal.get()).contains("is bound to null");
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // 8. CONFIGURATION: absent = disarmed; a mistyped value = REFUSAL, never a silent disarming.
+ // ---------------------------------------------------------------------------------------------
+ @Test
+ void withoutThePropertyTheEnforcementIsNULL() {
+ assertThat(PqPrepareEnforcement.fromSystemConfig()).isNull();
+ }
+
+ @Test
+ void oValoareBunaArmeaza() {
+ System.setProperty(PqPrepareEnforcement.PROPERTY_FORK_BLOCK, "1234567");
+ final PqPrepareEnforcement e = PqPrepareEnforcement.fromSystemConfig();
+ assertThat(e).isNotNull();
+ assertThat(e.armedAt(1_234_566L)).isFalse();
+ assertThat(e.armedAt(1_234_567L)).isTrue();
+ }
+
+ @Test
+ void aMISTYPEDValueRefusesLoudly() {
+ for (final String bad : new String[] {"nu-e-numar", "1_234_567", "-1", "1e6"}) {
+ System.setProperty(PqPrepareEnforcement.PROPERTY_FORK_BLOCK, bad);
+ assertThatThrownBy(PqPrepareEnforcement::fromSystemConfig)
+ .as("valoarea '%s'", bad)
+ .isInstanceOf(IllegalStateException.class)
+ .hasMessageContaining("AERE-PQC-PREPARE-ENF-01");
+ }
+ }
+
+ @Test
+ void theENFORCEMENTGateIsNotTheEMISSIONGate() {
+ // Doua proprietati distincte: se poate EMITE luni de zile fara sa se IMPUNA nimic. Daca ar fi
+ // una singura, primul nod care incepe sa emita ar incepe si sa refuze, si aia e o zi de flag.
+ assertThat(PqPrepareEnforcement.PROPERTY_FORK_BLOCK)
+ .isNotEqualTo("aere.pq.preparePq.attachBlock");
+ }
+}
diff --git a/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/validation/PqProposalEnforcementTest.java b/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/validation/PqProposalEnforcementTest.java
new file mode 100755
index 000000000..c4853f624
--- /dev/null
+++ b/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/validation/PqProposalEnforcementTest.java
@@ -0,0 +1,297 @@
+/*
+ * Copyright contributors to Besu.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.qbft.core.validation;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+import org.hyperledger.besu.consensus.common.bft.FalconSeal;
+import org.hyperledger.besu.consensus.common.bft.PqAnchor;
+import org.hyperledger.besu.consensus.common.bft.PqSignerRegistry;
+import org.hyperledger.besu.consensus.common.bft.SealScheme;
+import org.hyperledger.besu.consensus.common.bft.SealSchemes;
+import org.hyperledger.besu.crypto.SecureRandomProvider;
+import org.hyperledger.besu.datatypes.Address;
+import org.hyperledger.besu.datatypes.Hash;
+
+import java.security.SecureRandom;
+import java.util.Map;
+import java.util.Optional;
+
+import org.apache.tuweni.bytes.Bytes;
+import org.apache.tuweni.bytes.Bytes32;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.Test;
+
+/**
+ * PROPOSAL ENFORCEMENT. The structure follows PqPrepareEnforcementTest deliberately - the same
+ * eight ways of being wrong, each with the test that closes it.
+ *
+ * <ol>
+ * <li>below the arming height NOTHING changes - the condition for the binary to sit on the fleet;
+ * <li>above it, a PROPOSAL without a seal is refused;
+ * <li>a seal from ANOTHER validator does not vouch for this proposer;
+ * <li>a seal over a DIFFERENT MESSAGE does not pass - tested against BOTH the PREPARE and the
+ * COMMIT messages, because a proposal seal that passed under either domain would let an
+ * honest proposal seal be replayed as a vote, or an honest vote seal be replayed as a
+ * proposal;
+ * <li>a seal from a DIFFERENT ROUND does not pass;
+ * <li>an index the registry binds to nobody does not pass;
+ * <li>a mistyped configuration REFUSES, it does not disarm;
+ * <li>the enforcement gate and the emission gate are two different switches.
+ * </ol>
+ *
+ * <p>The keys are REAL Falcon keys, generated in-process, and verification goes through the real
+ * scheme. A test with fake signatures would prove that we can compare strings, not that the
+ * enforcement enforces.
+ */
+class PqProposalEnforcementTest {
+
+ private static final long ARMED_FROM = 1_000_000L;
+ private static final int ROUND = 3;
+ private static final Address PROPOSER_0 = Address.fromHexString("0x" + "aa".repeat(20));
+ private static final Address VALIDATOR_1 = Address.fromHexString("0x" + "bb".repeat(20));
+ private static final Hash DIGEST = Hash.hash(Bytes.of(8, 8, 8));
+ private static final long CHAIN_ID = 2800L;
+
+ private final SecureRandom random = SecureRandomProvider.createSecureRandom();
+
+ @AfterEach
+ void clearProperty() {
+ System.clearProperty(PqProposalEnforcement.PROPERTY_FORK_BLOCK);
+ }
+
+ /** Test registry: programmed index-to-address bindings + verification through the REAL scheme. */
+ private static final class TestRegistry implements PqSignerRegistry {
+ final Map<Integer, Address> bindings;
+ final Map<Integer, byte[]> keys;
+
+ TestRegistry(final Map<Integer, Address> bindings, final Map<Integer, byte[]> keys) {
+ this.bindings = bindings;
+ this.keys = keys;
+ }
+
+ @Override
+ public Address addressForIndexAtHistoric(final long blockNumber, final int validatorIndex) {
+ return bindings.get(validatorIndex);
+ }
+
+ @Override
+ public Address addressForIndexAtOwnHead(final long blockNumber, final int validatorIndex) {
+ return bindings.get(validatorIndex);
+ }
+
+ @Override
+ public boolean verifyAtHistoric(
+ final long blockNumber, final int validatorIndex, final Bytes message, final Bytes signature) {
+ return verifyAtOwnHead(blockNumber, validatorIndex, message, signature);
+ }
+
+ @Override
+ public boolean verifyAtOwnHead(
+ final long blockNumber, final int validatorIndex, final Bytes message, final Bytes signature) {
+ final byte[] pk = keys.get(validatorIndex);
+ if (pk == null) {
+ return false;
+ }
+ return SealSchemes.FALCON_512.verifyRaw(pk, message.toArray(), signature.toArray());
+ }
+ }
+
+ private record World(
+ PqProposalEnforcement enforcement,
+ FalconSeal valid0,
+ SealScheme.GeneratedPair k0,
+ SealScheme.GeneratedPair k1) {}
+
+ private Bytes32 proposalMessage(final long h, final int round) {
+ return PqAnchor.proposalMessage(CHAIN_ID, h, round, DIGEST.getBytes());
+ }
+
+ /** Two validators with real Falcon keys; validator 0's seal over the PROPOSAL message. */
+ private World world() {
+ final SealScheme.GeneratedPair k0 = SealSchemes.FALCON_512.generate(random);
+ final SealScheme.GeneratedPair k1 = SealSchemes.FALCON_512.generate(random);
+ final byte[] sig0 =
+ SealSchemes.FALCON_512
+ .sign(k0.privateKey(), proposalMessage(ARMED_FROM, ROUND).toArray())
+ .orElseThrow();
+ final TestRegistry reg =
+ new TestRegistry(
+ Map.of(0, PROPOSER_0, 1, VALIDATOR_1),
+ Map.of(0, k0.publicRegistryForm(), 1, k1.publicRegistryForm()));
+ return new World(
+ new PqProposalEnforcement(ARMED_FROM, reg, CHAIN_ID),
+ new FalconSeal(0, Bytes.wrap(sig0)),
+ k0,
+ k1);
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // 1. BELOW the arming height NOTHING changes. The condition for the binary to sit on the fleet.
+ // ---------------------------------------------------------------------------------------------
+ @Test
+ void belowTheArmingHeightAnUnsealedProposalIsAccepted() {
+ final World w = world();
+ assertThat(w.enforcement().armedAt(ARMED_FROM - 1)).isFalse();
+ assertThat(w.enforcement().refusal(ARMED_FROM - 1, ROUND, PROPOSER_0, DIGEST, Optional.empty()))
+ .isEmpty();
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // 2. ABOVE it, a PROPOSAL without a seal is refused.
+ // ---------------------------------------------------------------------------------------------
+ @Test
+ void aboveTheHeightAnUnsealedProposalIsRefused() {
+ final World w = world();
+ final Optional<String> refusal =
+ w.enforcement().refusal(ARMED_FROM, ROUND, PROPOSER_0, DIGEST, Optional.empty());
+ assertThat(refusal).isPresent();
+ assertThat(refusal.get()).contains("carries NO post-quantum seal");
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // 3. A GOOD seal from the proposer passes.
+ // ---------------------------------------------------------------------------------------------
+ @Test
+ void aGoodSealFromTheProposerPasses() {
+ final World w = world();
+ assertThat(w.enforcement().refusal(ARMED_FROM, ROUND, PROPOSER_0, DIGEST, Optional.of(w.valid0())))
+ .isEmpty();
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // 4. The same seal, a different author: it does not vouch for somebody else.
+ // ---------------------------------------------------------------------------------------------
+ @Test
+ void aSealDoesNotVouchForAnotherProposer() {
+ final World w = world();
+ final Optional<String> refusal =
+ w.enforcement().refusal(ARMED_FROM, ROUND, VALIDATOR_1, DIGEST, Optional.of(w.valid0()));
+ assertThat(refusal).isPresent();
+ assertThat(refusal.get()).contains("cannot vouch for someone else's proposal");
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // 5. DOMAIN SEPARATION, in both directions that matter here: a seal given HONESTLY over the
+ // PREPARE message, and one over the COMMIT message, must not pass as a PROPOSAL seal. Either
+ // passing would make honest seals transferable between an offer and a vote.
+ // ---------------------------------------------------------------------------------------------
+ @Test
+ void aSealOverThePREPAREMessageDoesNotPassAsPROPOSAL() {
+ final World w = world();
+ final Bytes32 prepareMsg = PqAnchor.prepareMessage(CHAIN_ID, ARMED_FROM, ROUND, DIGEST.getBytes());
+ final byte[] sig =
+ SealSchemes.FALCON_512.sign(w.k0().privateKey(), prepareMsg.toArray()).orElseThrow();
+
+ final Optional<String> refusal =
+ w.enforcement()
+ .refusal(
+ ARMED_FROM, ROUND, PROPOSER_0, DIGEST, Optional.of(new FalconSeal(0, Bytes.wrap(sig))));
+ assertThat(refusal).isPresent();
+ assertThat(refusal.get()).contains("does NOT verify over the proposal message");
+ }
+
+ @Test
+ void aSealOverTheCOMMITMessageDoesNotPassAsPROPOSAL() {
+ final World w = world();
+ final Bytes32 commitMsg = PqAnchor.commitMessage(CHAIN_ID, ARMED_FROM, DIGEST.getBytes());
+ final byte[] sig =
+ SealSchemes.FALCON_512.sign(w.k0().privateKey(), commitMsg.toArray()).orElseThrow();
+
+ final Optional<String> refusal =
+ w.enforcement()
+ .refusal(
+ ARMED_FROM, ROUND, PROPOSER_0, DIGEST, Optional.of(new FalconSeal(0, Bytes.wrap(sig))));
+ assertThat(refusal).isPresent();
+ assertThat(refusal.get()).contains("does NOT verify over the proposal message");
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // 6. The ROUND is in the preimage: a seal from a failed round does not open another one.
+ // ---------------------------------------------------------------------------------------------
+ @Test
+ void aSealFromAnotherROUNDDoesNotPass() {
+ final World w = world();
+ final byte[] sigOtherRound =
+ SealSchemes.FALCON_512
+ .sign(w.k0().privateKey(), proposalMessage(ARMED_FROM, ROUND + 1).toArray())
+ .orElseThrow();
+ final Optional<String> refusal =
+ w.enforcement()
+ .refusal(
+ ARMED_FROM,
+ ROUND,
+ PROPOSER_0,
+ DIGEST,
+ Optional.of(new FalconSeal(0, Bytes.wrap(sigOtherRound))));
+ assertThat(refusal).isPresent();
+ assertThat(refusal.get()).contains("does NOT verify over the proposal message");
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // 7. An index the registry binds to nobody.
+ // ---------------------------------------------------------------------------------------------
+ @Test
+ void anUNBOUNDIndexDoesNotPass() {
+ final World w = world();
+ final Optional<String> refusal =
+ w.enforcement()
+ .refusal(
+ ARMED_FROM,
+ ROUND,
+ PROPOSER_0,
+ DIGEST,
+ Optional.of(new FalconSeal(99, w.valid0().getSignature())));
+ assertThat(refusal).isPresent();
+ assertThat(refusal.get()).contains("is bound to null");
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // 8. CONFIGURATION: absent = disarmed; a mistyped value = REFUSAL, never a silent disarming.
+ // ---------------------------------------------------------------------------------------------
+ @Test
+ void withoutThePropertyTheEnforcementIsNULL() {
+ assertThat(PqProposalEnforcement.fromSystemConfig()).isNull();
+ }
+
+ @Test
+ void aGoodValueArms() {
+ System.setProperty(PqProposalEnforcement.PROPERTY_FORK_BLOCK, "1234567");
+ final PqProposalEnforcement e = PqProposalEnforcement.fromSystemConfig();
+ assertThat(e).isNotNull();
+ assertThat(e.armedAt(1_234_566L)).isFalse();
+ assertThat(e.armedAt(1_234_567L)).isTrue();
+ }
+
+ @Test
+ void aMISTYPEDValueRefusesLoudly() {
+ for (final String bad : new String[] {"not-a-number", "1_234_567", "-1", "1e6"}) {
+ System.setProperty(PqProposalEnforcement.PROPERTY_FORK_BLOCK, bad);
+ assertThatThrownBy(PqProposalEnforcement::fromSystemConfig)
+ .as("the value '%s'", bad)
+ .isInstanceOf(IllegalStateException.class)
+ .hasMessageContaining("AERE-PQC-PROPOSAL-ENF-01");
+ }
+ }
+
+ @Test
+ void theENFORCEMENTGateIsNotTheEMISSIONGate() {
+ // Two distinct properties: a fleet can EMIT for months before anything ENFORCES. If they were
+ // one switch, the first node that started emitting would also start refusing - a flag day.
+ assertThat(PqProposalEnforcement.PROPERTY_FORK_BLOCK)
+ .isNotEqualTo("aere.pq.proposalPq.attachBlock");
+ }
+}
diff --git a/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/validation/PqRoundChangeEnforcementTest.java b/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/validation/PqRoundChangeEnforcementTest.java
new file mode 100755
index 000000000..5e6b486ab
--- /dev/null
+++ b/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/validation/PqRoundChangeEnforcementTest.java
@@ -0,0 +1,422 @@
+/*
+ * Copyright contributors to Besu.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.qbft.core.validation;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+import org.hyperledger.besu.consensus.common.bft.FalconSeal;
+import org.hyperledger.besu.consensus.common.bft.PqAnchor;
+import org.hyperledger.besu.consensus.common.bft.PqSignerRegistry;
+import org.hyperledger.besu.consensus.common.bft.SealScheme;
+import org.hyperledger.besu.consensus.common.bft.SealSchemes;
+import org.hyperledger.besu.consensus.qbft.core.payload.PreparedRoundMetadata;
+import org.hyperledger.besu.crypto.SecureRandomProvider;
+import org.hyperledger.besu.datatypes.Address;
+import org.hyperledger.besu.datatypes.Hash;
+
+import java.security.SecureRandom;
+import java.util.Map;
+import java.util.Optional;
+
+import org.apache.tuweni.bytes.Bytes;
+import org.apache.tuweni.bytes.Bytes32;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.Test;
+
+/**
+ * ROUND-CHANGE ENFORCEMENT. The structure follows PqProposalEnforcementTest deliberately - the
+ * same ways of being wrong, each with the test that closes it, plus the one that is round-change
+ * specific: the PREPARED METADATA is in the preimage, so a seal from a bare round-change cannot be
+ * replayed onto one that claims a prepared block, in either direction.
+ *
+ * <ol>
+ * <li>below the arming height NOTHING changes - the condition for the binary to sit on the fleet;
+ * <li>above it, a ROUND-CHANGE without a seal is refused;
+ * <li>a seal from ANOTHER validator does not vouch for this author;
+ * <li>a seal over a DIFFERENT MESSAGE does not pass - tested against the PREPARE, COMMIT and
+ * PROPOSAL messages, because a round-change seal that passed under any of those domains
+ * would let an honest seal be replayed as a different kind of assertion;
+ * <li>a seal from a DIFFERENT TARGET ROUND does not pass;
+ * <li>a seal from a BARE round-change does not pass on one claiming a prepared block, and vice
+ * versa;
+ * <li>an index the registry binds to nobody does not pass;
+ * <li>a mistyped configuration REFUSES, it does not disarm;
+ * <li>the enforcement gate and the emission gate are two different switches.
+ * </ol>
+ *
+ * <p>The keys are REAL Falcon keys, generated in-process, and verification goes through the real
+ * scheme. A test with fake signatures would prove that we can compare strings, not that the
+ * enforcement enforces.
+ */
+class PqRoundChangeEnforcementTest {
+
+ private static final long ARMED_FROM = 1_000_000L;
+ private static final int TARGET_ROUND = 3;
+ private static final Address AUTHOR_0 = Address.fromHexString("0x" + "aa".repeat(20));
+ private static final Address VALIDATOR_1 = Address.fromHexString("0x" + "bb".repeat(20));
+ private static final Hash PREPARED_DIGEST = Hash.hash(Bytes.of(8, 8, 8));
+ private static final long CHAIN_ID = 2800L;
+
+ private final SecureRandom random = SecureRandomProvider.createSecureRandom();
+
+ @AfterEach
+ void clearProperty() {
+ System.clearProperty(PqRoundChangeEnforcement.PROPERTY_FORK_BLOCK);
+ }
+
+ /** Test registry: programmed index-to-address bindings + verification through the REAL scheme. */
+ private static final class TestRegistry implements PqSignerRegistry {
+ final Map<Integer, Address> bindings;
+ final Map<Integer, byte[]> keys;
+
+ TestRegistry(final Map<Integer, Address> bindings, final Map<Integer, byte[]> keys) {
+ this.bindings = bindings;
+ this.keys = keys;
+ }
+
+ @Override
+ public Address addressForIndexAtHistoric(final long blockNumber, final int validatorIndex) {
+ return bindings.get(validatorIndex);
+ }
+
+ @Override
+ public Address addressForIndexAtOwnHead(final long blockNumber, final int validatorIndex) {
+ return bindings.get(validatorIndex);
+ }
+
+ @Override
+ public boolean verifyAtHistoric(
+ final long blockNumber, final int validatorIndex, final Bytes message, final Bytes signature) {
+ return verifyAtOwnHead(blockNumber, validatorIndex, message, signature);
+ }
+
+ @Override
+ public boolean verifyAtOwnHead(
+ final long blockNumber, final int validatorIndex, final Bytes message, final Bytes signature) {
+ final byte[] pk = keys.get(validatorIndex);
+ if (pk == null) {
+ return false;
+ }
+ return SealSchemes.FALCON_512.verifyRaw(pk, message.toArray(), signature.toArray());
+ }
+ }
+
+ private record World(
+ PqRoundChangeEnforcement enforcement,
+ FalconSeal validBare0,
+ SealScheme.GeneratedPair k0,
+ SealScheme.GeneratedPair k1) {}
+
+ private Bytes32 bareMessage(final long h, final int targetRound) {
+ return PqAnchor.roundChangeMessage(CHAIN_ID, h, targetRound);
+ }
+
+ private Bytes32 preparedMessage(final long h, final int targetRound, final int preparedRound) {
+ return PqAnchor.roundChangeMessage(
+ CHAIN_ID, h, targetRound, preparedRound, PREPARED_DIGEST.getBytes());
+ }
+
+ private static Optional<PreparedRoundMetadata> preparedMetadata(final int preparedRound) {
+ return Optional.of(new PreparedRoundMetadata(PREPARED_DIGEST, preparedRound));
+ }
+
+ /** Two validators with real Falcon keys; validator 0's seal over the BARE round-change message. */
+ private World world() {
+ final SealScheme.GeneratedPair k0 = SealSchemes.FALCON_512.generate(random);
+ final SealScheme.GeneratedPair k1 = SealSchemes.FALCON_512.generate(random);
+ final byte[] sig0 =
+ SealSchemes.FALCON_512
+ .sign(k0.privateKey(), bareMessage(ARMED_FROM, TARGET_ROUND).toArray())
+ .orElseThrow();
+ final TestRegistry reg =
+ new TestRegistry(
+ Map.of(0, AUTHOR_0, 1, VALIDATOR_1),
+ Map.of(0, k0.publicRegistryForm(), 1, k1.publicRegistryForm()));
+ return new World(
+ new PqRoundChangeEnforcement(ARMED_FROM, reg, CHAIN_ID),
+ new FalconSeal(0, Bytes.wrap(sig0)),
+ k0,
+ k1);
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // 1. BELOW the arming height NOTHING changes. The condition for the binary to sit on the fleet.
+ // ---------------------------------------------------------------------------------------------
+ @Test
+ void belowTheArmingHeightAnUnsealedRoundChangeIsAccepted() {
+ final World w = world();
+ assertThat(w.enforcement().armedAt(ARMED_FROM - 1)).isFalse();
+ assertThat(
+ w.enforcement()
+ .refusal(ARMED_FROM - 1, TARGET_ROUND, AUTHOR_0, Optional.empty(), Optional.empty()))
+ .isEmpty();
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // 2. ABOVE it, a ROUND-CHANGE without a seal is refused.
+ // ---------------------------------------------------------------------------------------------
+ @Test
+ void aboveTheHeightAnUnsealedRoundChangeIsRefused() {
+ final World w = world();
+ final Optional<String> refusal =
+ w.enforcement()
+ .refusal(ARMED_FROM, TARGET_ROUND, AUTHOR_0, Optional.empty(), Optional.empty());
+ assertThat(refusal).isPresent();
+ assertThat(refusal.get()).contains("carries NO post-quantum seal");
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // 3. A GOOD seal from the author passes - bare, and with prepared metadata.
+ // ---------------------------------------------------------------------------------------------
+ @Test
+ void aGoodSealFromTheAuthorPasses() {
+ final World w = world();
+ assertThat(
+ w.enforcement()
+ .refusal(
+ ARMED_FROM,
+ TARGET_ROUND,
+ AUTHOR_0,
+ Optional.empty(),
+ Optional.of(w.validBare0())))
+ .isEmpty();
+ }
+
+ @Test
+ void aGoodSealOverPreparedMetadataPasses() {
+ final World w = world();
+ final byte[] sig =
+ SealSchemes.FALCON_512
+ .sign(w.k0().privateKey(), preparedMessage(ARMED_FROM, TARGET_ROUND, 1).toArray())
+ .orElseThrow();
+ assertThat(
+ w.enforcement()
+ .refusal(
+ ARMED_FROM,
+ TARGET_ROUND,
+ AUTHOR_0,
+ preparedMetadata(1),
+ Optional.of(new FalconSeal(0, Bytes.wrap(sig)))))
+ .isEmpty();
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // 4. The same seal, a different author: it does not vouch for somebody else.
+ // ---------------------------------------------------------------------------------------------
+ @Test
+ void aSealDoesNotVouchForAnotherAuthor() {
+ final World w = world();
+ final Optional<String> refusal =
+ w.enforcement()
+ .refusal(
+ ARMED_FROM, TARGET_ROUND, VALIDATOR_1, Optional.empty(), Optional.of(w.validBare0()));
+ assertThat(refusal).isPresent();
+ assertThat(refusal.get()).contains("cannot vouch for someone else's round-change");
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // 5. DOMAIN SEPARATION against all three sibling domains: a seal given HONESTLY over the
+ // PREPARE, COMMIT or PROPOSAL message must not pass as a ROUND-CHANGE seal.
+ // ---------------------------------------------------------------------------------------------
+ @Test
+ void aSealOverThePREPAREMessageDoesNotPassAsROUNDCHANGE() {
+ final World w = world();
+ final Bytes32 prepareMsg =
+ PqAnchor.prepareMessage(CHAIN_ID, ARMED_FROM, TARGET_ROUND, PREPARED_DIGEST.getBytes());
+ final byte[] sig =
+ SealSchemes.FALCON_512.sign(w.k0().privateKey(), prepareMsg.toArray()).orElseThrow();
+
+ final Optional<String> refusal =
+ w.enforcement()
+ .refusal(
+ ARMED_FROM,
+ TARGET_ROUND,
+ AUTHOR_0,
+ Optional.empty(),
+ Optional.of(new FalconSeal(0, Bytes.wrap(sig))));
+ assertThat(refusal).isPresent();
+ assertThat(refusal.get()).contains("does NOT verify over the round-change message");
+ }
+
+ @Test
+ void aSealOverTheCOMMITMessageDoesNotPassAsROUNDCHANGE() {
+ final World w = world();
+ final Bytes32 commitMsg = PqAnchor.commitMessage(CHAIN_ID, ARMED_FROM, PREPARED_DIGEST.getBytes());
+ final byte[] sig =
+ SealSchemes.FALCON_512.sign(w.k0().privateKey(), commitMsg.toArray()).orElseThrow();
+
+ final Optional<String> refusal =
+ w.enforcement()
+ .refusal(
+ ARMED_FROM,
+ TARGET_ROUND,
+ AUTHOR_0,
+ Optional.empty(),
+ Optional.of(new FalconSeal(0, Bytes.wrap(sig))));
+ assertThat(refusal).isPresent();
+ assertThat(refusal.get()).contains("does NOT verify over the round-change message");
+ }
+
+ @Test
+ void aSealOverThePROPOSALMessageDoesNotPassAsROUNDCHANGE() {
+ final World w = world();
+ final Bytes32 proposalMsg =
+ PqAnchor.proposalMessage(CHAIN_ID, ARMED_FROM, TARGET_ROUND, PREPARED_DIGEST.getBytes());
+ final byte[] sig =
+ SealSchemes.FALCON_512.sign(w.k0().privateKey(), proposalMsg.toArray()).orElseThrow();
+
+ final Optional<String> refusal =
+ w.enforcement()
+ .refusal(
+ ARMED_FROM,
+ TARGET_ROUND,
+ AUTHOR_0,
+ Optional.empty(),
+ Optional.of(new FalconSeal(0, Bytes.wrap(sig))));
+ assertThat(refusal).isPresent();
+ assertThat(refusal.get()).contains("does NOT verify over the round-change message");
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // 6. The TARGET ROUND is in the preimage: a seal towards one round does not open another.
+ // ---------------------------------------------------------------------------------------------
+ @Test
+ void aSealTowardsAnotherTARGETROUNDDoesNotPass() {
+ final World w = world();
+ final byte[] sigOtherRound =
+ SealSchemes.FALCON_512
+ .sign(w.k0().privateKey(), bareMessage(ARMED_FROM, TARGET_ROUND + 1).toArray())
+ .orElseThrow();
+ final Optional<String> refusal =
+ w.enforcement()
+ .refusal(
+ ARMED_FROM,
+ TARGET_ROUND,
+ AUTHOR_0,
+ Optional.empty(),
+ Optional.of(new FalconSeal(0, Bytes.wrap(sigOtherRound))));
+ assertThat(refusal).isPresent();
+ assertThat(refusal.get()).contains("does NOT verify over the round-change message");
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // 7. THE ROUND-CHANGE-SPECIFIC CASE: the prepared metadata is in the preimage, in BOTH
+ // directions. A bare seal on a message claiming a prepared block would let an adversary take
+ // an honest "just move on" and turn it into "move on AND re-propose THIS block".
+ // ---------------------------------------------------------------------------------------------
+ @Test
+ void aBareSealDoesNotPassOnARoundChangeClaimingAPreparedBlock() {
+ final World w = world();
+ final Optional<String> refusal =
+ w.enforcement()
+ .refusal(
+ ARMED_FROM, TARGET_ROUND, AUTHOR_0, preparedMetadata(1), Optional.of(w.validBare0()));
+ assertThat(refusal).isPresent();
+ assertThat(refusal.get()).contains("does NOT verify over the round-change message");
+ }
+
+ @Test
+ void aPreparedSealDoesNotPassOnABareRoundChange() {
+ final World w = world();
+ final byte[] sigPrepared =
+ SealSchemes.FALCON_512
+ .sign(w.k0().privateKey(), preparedMessage(ARMED_FROM, TARGET_ROUND, 1).toArray())
+ .orElseThrow();
+ final Optional<String> refusal =
+ w.enforcement()
+ .refusal(
+ ARMED_FROM,
+ TARGET_ROUND,
+ AUTHOR_0,
+ Optional.empty(),
+ Optional.of(new FalconSeal(0, Bytes.wrap(sigPrepared))));
+ assertThat(refusal).isPresent();
+ assertThat(refusal.get()).contains("does NOT verify over the round-change message");
+ }
+
+ @Test
+ void aSealOverDifferentPreparedMetadataDoesNotPass() {
+ final World w = world();
+ final byte[] sigRound1 =
+ SealSchemes.FALCON_512
+ .sign(w.k0().privateKey(), preparedMessage(ARMED_FROM, TARGET_ROUND, 1).toArray())
+ .orElseThrow();
+ final Optional<String> refusal =
+ w.enforcement()
+ .refusal(
+ ARMED_FROM,
+ TARGET_ROUND,
+ AUTHOR_0,
+ preparedMetadata(2),
+ Optional.of(new FalconSeal(0, Bytes.wrap(sigRound1))));
+ assertThat(refusal).isPresent();
+ assertThat(refusal.get()).contains("does NOT verify over the round-change message");
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // 8. An index the registry binds to nobody.
+ // ---------------------------------------------------------------------------------------------
+ @Test
+ void anUNBOUNDIndexDoesNotPass() {
+ final World w = world();
+ final Optional<String> refusal =
+ w.enforcement()
+ .refusal(
+ ARMED_FROM,
+ TARGET_ROUND,
+ AUTHOR_0,
+ Optional.empty(),
+ Optional.of(new FalconSeal(99, w.validBare0().getSignature())));
+ assertThat(refusal).isPresent();
+ assertThat(refusal.get()).contains("is bound to null");
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // 9. CONFIGURATION: absent = disarmed; a mistyped value = REFUSAL, never a silent disarming.
+ // ---------------------------------------------------------------------------------------------
+ @Test
+ void withoutThePropertyTheEnforcementIsNULL() {
+ assertThat(PqRoundChangeEnforcement.fromSystemConfig()).isNull();
+ }
+
+ @Test
+ void aGoodValueArms() {
+ System.setProperty(PqRoundChangeEnforcement.PROPERTY_FORK_BLOCK, "1234567");
+ final PqRoundChangeEnforcement e = PqRoundChangeEnforcement.fromSystemConfig();
+ assertThat(e).isNotNull();
+ assertThat(e.armedAt(1_234_566L)).isFalse();
+ assertThat(e.armedAt(1_234_567L)).isTrue();
+ }
+
+ @Test
+ void aMISTYPEDValueRefusesLoudly() {
+ for (final String bad : new String[] {"not-a-number", "1_234_567", "-1", "1e6"}) {
+ System.setProperty(PqRoundChangeEnforcement.PROPERTY_FORK_BLOCK, bad);
+ assertThatThrownBy(PqRoundChangeEnforcement::fromSystemConfig)
+ .as("the value '%s'", bad)
+ .isInstanceOf(IllegalStateException.class)
+ .hasMessageContaining("AERE-PQC-ROUNDCHANGE-ENF-01");
+ }
+ }
+
+ @Test
+ void theENFORCEMENTGateIsNotTheEMISSIONGate() {
+ // Two distinct properties: a fleet can EMIT for months before anything ENFORCES. If they were
+ // one switch, the first node that started emitting would also start refusing - a flag day.
+ assertThat(PqRoundChangeEnforcement.PROPERTY_FORK_BLOCK)
+ .isNotEqualTo("aere.pq.roundChangePq.attachBlock");
+ }
+}
diff --git a/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/validation/PqTransportIndependenceTest.java b/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/validation/PqTransportIndependenceTest.java
new file mode 100755
index 000000000..a276d30f5
--- /dev/null
+++ b/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/validation/PqTransportIndependenceTest.java
@@ -0,0 +1,437 @@
+/*
+ * Copyright contributors to Besu.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.qbft.core.validation;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import org.hyperledger.besu.consensus.common.bft.ConsensusRoundIdentifier;
+import org.hyperledger.besu.consensus.common.bft.FalconSeal;
+import org.hyperledger.besu.consensus.common.bft.PqAnchor;
+import org.hyperledger.besu.consensus.common.bft.PqSignerRegistry;
+import org.hyperledger.besu.consensus.common.bft.SealScheme;
+import org.hyperledger.besu.consensus.common.bft.SealSchemes;
+import org.hyperledger.besu.consensus.qbft.core.payload.PreparedRoundMetadata;
+import org.hyperledger.besu.crypto.SecureRandomProvider;
+import org.hyperledger.besu.datatypes.Address;
+import org.hyperledger.besu.datatypes.Hash;
+
+import java.security.SecureRandom;
+import java.util.Map;
+import java.util.Optional;
+
+import org.apache.tuweni.bytes.Bytes;
+import org.apache.tuweni.bytes.Bytes32;
+import org.junit.jupiter.api.Test;
+
+/**
+ * THE ADVERSARY WHO ALREADY HAS THE VALIDATOR'S ECDSA KEY, and still cannot move the chain.
+ *
+ * <p><b>WHY THIS TEST IS THE ONE THAT MATTERS.</b> The network transport (RLPx/ECIES) authenticates
+ * a peer by its secp256k1 node key, and {@code ValidatorPeers} routes consensus messages by the
+ * address derived from that same key. A quantum adversary who recovers a validator's ECDSA key
+ * therefore gets EVERYTHING the transport can give: it completes the handshake as that validator,
+ * is routed consensus traffic as that validator, and signs syntactically perfect QBFT messages that
+ * recover to that validator's address. Every check that predates the post-quantum layers passes for
+ * it.
+ *
+ * <p>The question this test answers, by measurement rather than by argument: <b>with the
+ * post-quantum enforcement armed, does that adversary gain anything at all?</b> It models exactly
+ * that adversary - full ECDSA compromise, no Falcon key - and requires all four hot-path messages
+ * to be refused. That is what "consensus safety does not depend on the transport" means concretely,
+ * and it is the honest form of the claim: not that the transport is post-quantum (it is not), but
+ * that breaking it does not buy a break of safety.
+ *
+ * <p><b>THE CONTROLS, without which the refusals would prove nothing:</b>
+ *
+ * <ol>
+ * <li>DISARMED: the very same messages from the very same adversary are ACCEPTED when the
+ * enforcement is not armed. Without this, the refusals could come from any unrelated defect
+ * in the fixture and the test would be measuring its own mistake.
+ * <li>THE HONEST VALIDATOR: a message carrying a VALID Falcon seal is accepted while armed. So
+ * the refusal is caused by the missing seal, not by arming per se - otherwise an enforcement
+ * that refuses everything would look identical to one that enforces.
+ * <li>THE HARVESTED SEAL, in four flavours, because a broken transport hands the adversary the
+ * victim's entire message history to replay: a seal from another message KIND, one for
+ * another BLOCK at the same height and round, one from another HEIGHT, ROUND or CHAIN, and
+ * one belonging to ANOTHER VALIDATOR entirely, stapled onto the adversary's own message.
+ * </ol>
+ *
+ * <p><b>TWO OF THOSE CONTROLS EXIST BECAUSE THE NEGATIVE CONTROL CAUGHT THEIR ABSENCE</b>
+ * (2026-08-31, {@code PROBA-CONTROL-INDEPENDENTA-TRANSPORT.sh}). The first version of this test
+ * passed with 8 green assertions, and stayed green under two planted defects: the digest removed
+ * from the signed preimage, and the index-to-author binding removed. Both were invisible because
+ * every replay it tried crossed a domain boundary, and because its registry held a single
+ * validator - so the two attacks a broken transport most directly enables could not even be
+ * expressed. Green, running, and blind. That is the whole reason a proof has to be shown red.
+ *
+ * <p><b>WHAT THIS DOES NOT PROVE, said plainly:</b> nothing here is about LIVENESS. An adversary
+ * with a validator's ECDSA key can still occupy the connection slot, eclipse a peer, or flood it;
+ * those are denial-of-service questions and this test says nothing about them. It also says
+ * nothing about the fleet as configured today, where the enforcement heights are unset - the
+ * property proven is the property of the ARMED configuration.
+ */
+class PqTransportIndependenceTest {
+
+ private static final long H = 1_000L;
+ private static final int ROUND = 2;
+ private static final long CHAIN_ID = 2800L;
+
+ /** The validator whose ECDSA key the adversary has stolen. */
+ private static final Address VICTIM = Address.fromHexString("0x" + "dd".repeat(20));
+
+ /**
+ * A SECOND, uncompromised validator. It exists because of what the negative control measured:
+ * with a single-validator registry, the scenario "the adversary staples someone else's seal -
+ * one it overheard on the broken wire - onto its own message" cannot even be expressed, and the
+ * planted removal of the index-to-author binding left the whole test GREEN. A test that cannot
+ * express the attack does not measure it.
+ */
+ private static final Address OTHER = Address.fromHexString("0x" + "ee".repeat(20));
+
+ private static final Hash DIGEST = Hash.hash(Bytes.of(4, 2));
+
+ /**
+ * A DIFFERENT block digest at the same height and round. Also added after the negative control:
+ * every replay the first version tried crossed a DOMAIN boundary, so nothing required the
+ * digest itself to be under the seal - and the planted removal of the digest from the preimage
+ * went unnoticed. That removal is the difference between "this validator voted" and "this
+ * validator voted FOR THIS BLOCK".
+ */
+ private static final Hash OTHER_DIGEST = Hash.hash(Bytes.of(7, 7));
+
+ private static final Hash COMMIT_DIGEST = Hash.hash(Bytes.of(4, 3));
+
+ private final SecureRandom random = SecureRandomProvider.createSecureRandom();
+
+ /** The victim's Falcon key pair - held by the HONEST node, never by the adversary. */
+ private final SealScheme.GeneratedPair victimPq = SealSchemes.FALCON_512.generate(random);
+
+ /** The second validator's Falcon key pair - likewise never in the adversary's hands. */
+ private final SealScheme.GeneratedPair otherPq = SealSchemes.FALCON_512.generate(random);
+
+ /** A registry binding index 0 to the victim and index 1 to the other validator. */
+ private final PqSignerRegistry registry =
+ new PqSignerRegistry() {
+ private final Map<Integer, Address> bindings = Map.of(0, VICTIM, 1, OTHER);
+ private final Map<Integer, byte[]> keys =
+ Map.of(0, victimPq.publicRegistryForm(), 1, otherPq.publicRegistryForm());
+
+ @Override
+ public Address addressForIndexAtHistoric(final long blockNumber, final int validatorIndex) {
+ return bindings.get(validatorIndex);
+ }
+
+ @Override
+ public Address addressForIndexAtOwnHead(final long blockNumber, final int validatorIndex) {
+ return bindings.get(validatorIndex);
+ }
+
+ @Override
+ public boolean verifyAtHistoric(
+ final long blockNumber, final int validatorIndex, final Bytes message, final Bytes signature) {
+ return verifyAtOwnHead(blockNumber, validatorIndex, message, signature);
+ }
+
+ @Override
+ public boolean verifyAtOwnHead(
+ final long blockNumber, final int validatorIndex, final Bytes message, final Bytes signature) {
+ final byte[] pk = keys.get(validatorIndex);
+ return pk != null
+ && SealSchemes.FALCON_512.verifyRaw(pk, message.toArray(), signature.toArray());
+ }
+ };
+
+ /** A seal the HONEST victim would produce for the given message. */
+ private FalconSeal honestSeal(final Bytes32 message) {
+ final byte[] sig =
+ SealSchemes.FALCON_512.sign(victimPq.privateKey(), message.toArray()).orElseThrow();
+ return new FalconSeal(0, Bytes.wrap(sig));
+ }
+
+ /**
+ * A seal the OTHER honest validator would produce - the kind the adversary can hear on a broken
+ * wire and would like to reuse as its own.
+ */
+ private FalconSeal otherValidatorSeal(final Bytes32 message) {
+ final byte[] sig =
+ SealSchemes.FALCON_512.sign(otherPq.privateKey(), message.toArray()).orElseThrow();
+ return new FalconSeal(1, Bytes.wrap(sig));
+ }
+
+ private Bytes32 prepareMsg() {
+ return PqAnchor.prepareMessage(CHAIN_ID, H, ROUND, DIGEST.getBytes());
+ }
+
+ private Bytes32 proposalMsg() {
+ return PqAnchor.proposalMessage(CHAIN_ID, H, ROUND, DIGEST.getBytes());
+ }
+
+ /**
+ * The commit layer is the OLDEST of the four and its seal covers the commit digest DIRECTLY,
+ * without a domain-separated preimage - measured in {@code PqCommitEnforcement.falconRefusal},
+ * not assumed. It is written out here rather than papered over: a test that signed a
+ * domain-separated message for commit would be testing a layer we do not have, and would fail
+ * for a reason that has nothing to do with the adversary being modelled.
+ */
+ private Bytes32 commitMsg() {
+ return Bytes32.wrap(COMMIT_DIGEST.getBytes());
+ }
+
+ private Bytes32 roundChangeMsg() {
+ return PqAnchor.roundChangeMessage(CHAIN_ID, H, ROUND);
+ }
+
+ // The four enforcements, armed at H. The adversary's messages recover to VICTIM, because the
+ // adversary holds VICTIM's ECDSA key: the author argument below is deliberately VICTIM.
+ private PqPrepareEnforcement prepareArmed() {
+ return new PqPrepareEnforcement(H, registry, CHAIN_ID);
+ }
+
+ private PqProposalEnforcement proposalArmed() {
+ return new PqProposalEnforcement(H, registry, CHAIN_ID);
+ }
+
+ private PqCommitEnforcement commitArmed() {
+ return new PqCommitEnforcement(H, registry);
+ }
+
+ private PqRoundChangeEnforcement roundChangeArmed() {
+ return new PqRoundChangeEnforcement(H, registry, CHAIN_ID);
+ }
+
+ // -----------------------------------------------------------------------------------------
+ // THE MEASUREMENT: full ECDSA compromise, no Falcon key. All four messages refused.
+ // -----------------------------------------------------------------------------------------
+
+ @Test
+ void aStolenECDSAKeyBuysNOPrepare() {
+ final Optional<String> refusal =
+ prepareArmed().refusal(H, ROUND, VICTIM, DIGEST, Optional.empty());
+ assertThat(refusal)
+ .describedAs("an adversary holding the victim's ECDSA key must not be able to vote")
+ .isPresent();
+ assertThat(refusal.get()).contains("carries NO post-quantum seal");
+ }
+
+ @Test
+ void aStolenECDSAKeyBuysNOProposal() {
+ final Optional<String> refusal =
+ proposalArmed().refusal(H, ROUND, VICTIM, DIGEST, Optional.empty());
+ assertThat(refusal).isPresent();
+ assertThat(refusal.get()).contains("carries NO post-quantum seal");
+ }
+
+ @Test
+ void aStolenECDSAKeyBuysNOCommit() {
+ final Optional<String> refusal =
+ commitArmed().refusal(H, VICTIM, COMMIT_DIGEST, Optional.empty());
+ assertThat(refusal).isPresent();
+ }
+
+ @Test
+ void aStolenECDSAKeyBuysNORoundChange() {
+ final Optional<String> refusal =
+ roundChangeArmed().refusal(H, ROUND, VICTIM, Optional.empty(), Optional.empty());
+ assertThat(refusal).isPresent();
+ assertThat(refusal.get()).contains("carries NO post-quantum seal");
+ }
+
+ // -----------------------------------------------------------------------------------------
+ // CONTROL 1 - DISARMED: the very same messages pass. The refusals above are caused by the
+ // arming, not by something broken in this fixture.
+ // -----------------------------------------------------------------------------------------
+
+ @Test
+ void controlDISARMEDtheSameMessagesArePerfectlyValid() {
+ final long never = Long.MAX_VALUE;
+ assertThat(
+ new PqPrepareEnforcement(never, registry, CHAIN_ID)
+ .refusal(H, ROUND, VICTIM, DIGEST, Optional.empty()))
+ .isEmpty();
+ assertThat(
+ new PqProposalEnforcement(never, registry, CHAIN_ID)
+ .refusal(H, ROUND, VICTIM, DIGEST, Optional.empty()))
+ .isEmpty();
+ assertThat(
+ new PqCommitEnforcement(never, registry)
+ .refusal(H, VICTIM, COMMIT_DIGEST, Optional.empty()))
+ .isEmpty();
+ assertThat(
+ new PqRoundChangeEnforcement(never, registry, CHAIN_ID)
+ .refusal(H, ROUND, VICTIM, Optional.empty(), Optional.empty()))
+ .isEmpty();
+ }
+
+ // -----------------------------------------------------------------------------------------
+ // CONTROL 2 - THE HONEST VALIDATOR still works while armed. Otherwise "refuses everything"
+ // would be indistinguishable from "enforces".
+ // -----------------------------------------------------------------------------------------
+
+ @Test
+ void controlTheHONESTvalidatorPassesOnAllFourMessagesWhileArmed() {
+ assertThat(
+ prepareArmed().refusal(H, ROUND, VICTIM, DIGEST, Optional.of(honestSeal(prepareMsg()))))
+ .isEmpty();
+ assertThat(
+ proposalArmed()
+ .refusal(H, ROUND, VICTIM, DIGEST, Optional.of(honestSeal(proposalMsg()))))
+ .isEmpty();
+ assertThat(commitArmed().refusal(H, VICTIM, COMMIT_DIGEST, Optional.of(honestSeal(commitMsg()))))
+ .isEmpty();
+ assertThat(
+ roundChangeArmed()
+ .refusal(
+ H, ROUND, VICTIM, Optional.empty(), Optional.of(honestSeal(roundChangeMsg()))))
+ .isEmpty();
+ }
+
+ // -----------------------------------------------------------------------------------------
+ // CONTROL 3 - THE STOLEN SEAL. A broken transport lets the adversary READ every message the
+ // victim ever sent, so it can replay any seal it has seen. Each seal is bound to its own
+ // message, so a seal harvested from one message must not authenticate another. This is the
+ // control that turns "the adversary has no key" into "eavesdropping does not substitute for
+ // one" - and it is checked ACROSS message kinds (domain separation) and WITHIN a kind
+ // (a round-change seal replayed onto a claim of a prepared block).
+ // -----------------------------------------------------------------------------------------
+
+ @Test
+ void controlASealHARVESTEDfromAnotherMessageDoesNotAuthenticateThisOne() {
+ // a PREPARE seal, replayed on a PROPOSAL and on a ROUND-CHANGE
+ final FalconSeal harvestedPrepare = honestSeal(prepareMsg());
+ assertThat(proposalArmed().refusal(H, ROUND, VICTIM, DIGEST, Optional.of(harvestedPrepare)))
+ .isPresent();
+ assertThat(
+ roundChangeArmed()
+ .refusal(H, ROUND, VICTIM, Optional.empty(), Optional.of(harvestedPrepare)))
+ .isPresent();
+
+ // a PROPOSAL seal, replayed as a vote
+ final FalconSeal harvestedProposal = honestSeal(proposalMsg());
+ assertThat(prepareArmed().refusal(H, ROUND, VICTIM, DIGEST, Optional.of(harvestedProposal)))
+ .isPresent();
+
+ // a bare ROUND-CHANGE seal, replayed on one that claims a prepared block: same kind, different
+ // assertion, and the metadata is in the preimage precisely so this fails
+ final FalconSeal harvestedRoundChange = honestSeal(roundChangeMsg());
+ assertThat(
+ roundChangeArmed()
+ .refusal(
+ H,
+ ROUND,
+ VICTIM,
+ Optional.of(new PreparedRoundMetadata(DIGEST, 1)),
+ Optional.of(harvestedRoundChange)))
+ .isPresent();
+ }
+
+ // -----------------------------------------------------------------------------------------
+ // CONTROL 3b - THE SEAL OF ANOTHER BLOCK, same kind, same height, same round. This is the
+ // difference between "this validator voted" and "this validator voted FOR THIS BLOCK", and it
+ // is the one an eavesdropper is best placed to exploit: on a broken wire it hears the victim's
+ // honest vote for block A and wants to turn it into a vote for block B.
+ //
+ // ADDED after the negative control caught its absence: every replay above crosses a DOMAIN
+ // boundary, so with the digest planted OUT of the signed message the whole test stayed GREEN.
+ // -----------------------------------------------------------------------------------------
+
+ @Test
+ void controlASealForANOTHERBLOCKDoesNotAuthenticateThisOne() {
+ final FalconSeal forOtherBlock =
+ honestSeal(PqAnchor.prepareMessage(CHAIN_ID, H, ROUND, OTHER_DIGEST.getBytes()));
+ assertThat(prepareArmed().refusal(H, ROUND, VICTIM, DIGEST, Optional.of(forOtherBlock)))
+ .describedAs("a vote for one block must not authenticate a vote for another")
+ .isPresent();
+
+ final FalconSeal proposalForOtherBlock =
+ honestSeal(PqAnchor.proposalMessage(CHAIN_ID, H, ROUND, OTHER_DIGEST.getBytes()));
+ assertThat(proposalArmed().refusal(H, ROUND, VICTIM, DIGEST, Optional.of(proposalForOtherBlock)))
+ .isPresent();
+
+ // and the commit layer, whose seal covers the commit digest directly
+ final FalconSeal commitForOtherBlock = honestSeal(Bytes32.wrap(OTHER_DIGEST.getBytes()));
+ assertThat(commitArmed().refusal(H, VICTIM, COMMIT_DIGEST, Optional.of(commitForOtherBlock)))
+ .isPresent();
+ }
+
+ // -----------------------------------------------------------------------------------------
+ // CONTROL 3c - SOMEONE ELSE'S SEAL, stapled on. The adversary hears validator 1's perfectly
+ // valid seal for the very message it wants to send, and attaches it to its own message - which
+ // recovers to the VICTIM, because that is the ECDSA key it stole. The seal is valid, the
+ // signature is valid, the author is a real validator: only the index-to-author binding stands
+ // between that and a counted vote.
+ //
+ // ADDED after the negative control: with a single-validator registry this attack could not even
+ // be written, and the planted removal of that binding left the test GREEN.
+ // -----------------------------------------------------------------------------------------
+
+ @Test
+ void controlSOMEONEELSESsealDoesNotAuthenticateTheAdversarysMessage() {
+ final FalconSeal theirs = otherValidatorSeal(prepareMsg());
+
+ // sanity: that seal really is valid FOR ITS OWN AUTHOR, or the refusal below would prove
+ // nothing about the binding and everything about a broken fixture
+ assertThat(prepareArmed().refusal(H, ROUND, OTHER, DIGEST, Optional.of(theirs)))
+ .describedAs("validator 1's own seal must work for validator 1")
+ .isEmpty();
+
+ // the attack: the same valid seal, on a message authored with the victim's stolen key
+ assertThat(prepareArmed().refusal(H, ROUND, VICTIM, DIGEST, Optional.of(theirs)))
+ .describedAs("a seal must not vouch for a message someone else authored")
+ .isPresent();
+
+ // the same, on the other three surfaces
+ assertThat(
+ proposalArmed()
+ .refusal(H, ROUND, VICTIM, DIGEST, Optional.of(otherValidatorSeal(proposalMsg()))))
+ .isPresent();
+ assertThat(
+ commitArmed()
+ .refusal(H, VICTIM, COMMIT_DIGEST, Optional.of(otherValidatorSeal(commitMsg()))))
+ .isPresent();
+ assertThat(
+ roundChangeArmed()
+ .refusal(
+ H,
+ ROUND,
+ VICTIM,
+ Optional.empty(),
+ Optional.of(otherValidatorSeal(roundChangeMsg()))))
+ .isPresent();
+ }
+
+ // -----------------------------------------------------------------------------------------
+ // CONTROL 4 - A SEAL FROM ANOTHER HEIGHT OR ROUND. The transport gives the adversary the
+ // victim's whole message history, so the seals it can replay are not only from other kinds but
+ // from other positions in the chain.
+ // -----------------------------------------------------------------------------------------
+
+ @Test
+ void controlASealFromAnotherHEIGHTorROUNDDoesNotAuthenticateThisOne() {
+ final FalconSeal otherHeight =
+ honestSeal(PqAnchor.prepareMessage(CHAIN_ID, H + 1, ROUND, DIGEST.getBytes()));
+ assertThat(prepareArmed().refusal(H, ROUND, VICTIM, DIGEST, Optional.of(otherHeight)))
+ .isPresent();
+
+ final FalconSeal otherRound =
+ honestSeal(PqAnchor.prepareMessage(CHAIN_ID, H, ROUND + 1, DIGEST.getBytes()));
+ assertThat(prepareArmed().refusal(H, ROUND, VICTIM, DIGEST, Optional.of(otherRound)))
+ .isPresent();
+
+ final FalconSeal otherChain =
+ honestSeal(PqAnchor.prepareMessage(CHAIN_ID + 1, H, ROUND, DIGEST.getBytes()));
+ assertThat(prepareArmed().refusal(H, ROUND, VICTIM, DIGEST, Optional.of(otherChain)))
+ .isPresent();
+ }
+}
diff --git a/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/validation/PrepareValidatorPqWiringTest.java b/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/validation/PrepareValidatorPqWiringTest.java
new file mode 100755
index 000000000..4ea938d39
--- /dev/null
+++ b/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/validation/PrepareValidatorPqWiringTest.java
@@ -0,0 +1,118 @@
+/*
+ * Copyright contributors to Besu.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.qbft.core.validation;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import org.hyperledger.besu.consensus.common.bft.ConsensusRoundIdentifier;
+import org.hyperledger.besu.consensus.common.bft.PqSignerRegistry;
+import org.hyperledger.besu.consensus.qbft.core.messagewrappers.Prepare;
+import org.hyperledger.besu.consensus.qbft.core.types.QbftBlockCodec;
+import org.hyperledger.besu.datatypes.Address;
+import org.hyperledger.besu.datatypes.Hash;
+
+import org.apache.tuweni.bytes.Bytes;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.mockito.Mock;
+
+/**
+ * THE WIRING, not the class: does {@link PrepareValidator} actually CALL the enforcement?
+ *
+ * <p>Without this test we would have exactly the situation paid for on 2026-08-28 at the restore
+ * step - a class present in the binary, environment variables visible to the process, and code that
+ * never runs. "I checked what I added" does not mean "I checked that it is wired".
+ *
+ * <p>The registry here REFUSES everything, so this does not measure cryptography (that has its own
+ * test), only whether the decision passes through the hook at all. The pair below is all it takes:
+ * the same message, once with enforcement and once without.
+ */
+public class PrepareValidatorPqWiringTest {
+
+ private static final int VALIDATOR_COUNT = 4;
+ private static final long HEIGHT = 1L;
+
+ private final ConsensusRoundIdentifier round = new ConsensusRoundIdentifier((int) HEIGHT, 0);
+ private final Hash expectedHash = Hash.fromHexStringLenient("0x1");
+ @Mock private QbftBlockCodec blockEncoder;
+ private QbftNodeList validators;
+
+ @BeforeEach
+ public void setup() {
+ validators = QbftNodeList.createNodes(VALIDATOR_COUNT, blockEncoder);
+ }
+
+ /** A registry that binds no index and verifies nothing. */
+ private static final class RegistruGol implements PqSignerRegistry {
+ @Override
+ public Address addressForIndexAtHistoric(final long blockNumber, final int validatorIndex) {
+ return null;
+ }
+
+ @Override
+ public Address addressForIndexAtOwnHead(final long blockNumber, final int validatorIndex) {
+ return null;
+ }
+
+ @Override
+ public boolean verifyAtHistoric(
+ final long blockNumber, final int validatorIndex, final Bytes message, final Bytes signature) {
+ return false;
+ }
+
+ @Override
+ public boolean verifyAtOwnHead(
+ final long blockNumber, final int validatorIndex, final Bytes message, final Bytes signature) {
+ return false;
+ }
+ }
+
+ @Test
+ public void withoutEnforcementAnUnsealedPrepareISValid() {
+ final PrepareValidator validator =
+ new PrepareValidator(validators.getNodeAddresses(), round, expectedHash, null);
+ final Prepare msg = validators.getMessageFactory(0).createPrepare(round, expectedHash);
+ assertThat(validator.validate(msg)).isTrue();
+ }
+
+ @Test
+ public void withTheEnforcementARMEDTheSamePrepareISRefused() {
+ // THE SAME message as above. The only difference is the hook, so a different result means it
+ // really is called. If this still returned true, the enforcement would be dead code.
+ final PrepareValidator validator =
+ new PrepareValidator(
+ validators.getNodeAddresses(),
+ round,
+ expectedHash,
+ new PqPrepareEnforcement(HEIGHT, new RegistruGol(), 2800L));
+ final Prepare msg = validators.getMessageFactory(0).createPrepare(round, expectedHash);
+ assertThat(validator.validate(msg)).isFalse();
+ }
+
+ @Test
+ public void withTheEnforcementBELOWItsHeightTheSamePrepareISValid() {
+ // The third state, closing the last way of being wrong: a hook that refused regardless of
+ // height would make the binary impossible to deploy. Here the enforcement exists but does not
+ // apply yet.
+ final PrepareValidator validator =
+ new PrepareValidator(
+ validators.getNodeAddresses(),
+ round,
+ expectedHash,
+ new PqPrepareEnforcement(HEIGHT + 1, new RegistruGol(), 2800L));
+ final Prepare msg = validators.getMessageFactory(0).createPrepare(round, expectedHash);
+ assertThat(validator.validate(msg)).isTrue();
+ }
+}
diff --git a/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/validation/ProposalPayloadValidatorPqWiringTest.java b/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/validation/ProposalPayloadValidatorPqWiringTest.java
new file mode 100755
index 000000000..b9bea2210
--- /dev/null
+++ b/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/validation/ProposalPayloadValidatorPqWiringTest.java
@@ -0,0 +1,133 @@
+/*
+ * Copyright contributors to Besu.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.qbft.core.validation;
+
+import static java.util.Collections.emptyList;
+import static org.assertj.core.api.Assertions.assertThat;
+
+import org.hyperledger.besu.consensus.common.bft.ConsensusRoundIdentifier;
+import org.hyperledger.besu.consensus.common.bft.PqSignerRegistry;
+import org.hyperledger.besu.consensus.qbft.core.QbftBlockTestFixture;
+import org.hyperledger.besu.consensus.qbft.core.messagewrappers.Proposal;
+import org.hyperledger.besu.consensus.qbft.core.payload.MessageFactory;
+import org.hyperledger.besu.consensus.qbft.core.types.QbftBlock;
+import org.hyperledger.besu.consensus.qbft.core.types.QbftBlockCodec;
+import org.hyperledger.besu.consensus.qbft.core.types.QbftBlockHeader;
+import org.hyperledger.besu.cryptoservices.NodeKey;
+import org.hyperledger.besu.cryptoservices.NodeKeyUtils;
+import org.hyperledger.besu.datatypes.Address;
+import org.hyperledger.besu.ethereum.core.Util;
+
+import java.util.Optional;
+
+import org.apache.tuweni.bytes.Bytes;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+
+/**
+ * THE WIRING, not the class: does {@link ProposalPayloadValidator} actually CALL the enforcement?
+ *
+ * <p>Same reason the PREPARE twin exists: a class present in the binary, environment variables
+ * visible to the process, and code that never runs is exactly the failure paid for on 2026-08-28.
+ * The registry here REFUSES everything, so this does not measure cryptography (that has its own
+ * test), only whether the decision passes through the hook. The pair is all it takes: the same
+ * signed proposal, once with enforcement and once without.
+ */
+@ExtendWith(MockitoExtension.class)
+public class ProposalPayloadValidatorPqWiringTest {
+
+ private static final long HEIGHT = 1L;
+
+ private final ConsensusRoundIdentifier round = new ConsensusRoundIdentifier((int) HEIGHT, 0);
+ @Mock private QbftBlockCodec blockEncoder;
+
+ private final NodeKey nodeKey = NodeKeyUtils.generate();
+ private final Address proposer = Util.publicKeyToAddress(nodeKey.getPublicKey());
+ private MessageFactory messageFactory;
+
+ @BeforeEach
+ public void setup() {
+ messageFactory = new MessageFactory(nodeKey, blockEncoder);
+ }
+
+ /** A registry that binds no index and verifies nothing. */
+ private static final class EmptyRegistry implements PqSignerRegistry {
+ @Override
+ public Address addressForIndexAtHistoric(final long blockNumber, final int validatorIndex) {
+ return null;
+ }
+
+ @Override
+ public Address addressForIndexAtOwnHead(final long blockNumber, final int validatorIndex) {
+ return null;
+ }
+
+ @Override
+ public boolean verifyAtHistoric(
+ final long blockNumber, final int validatorIndex, final Bytes message, final Bytes signature) {
+ return false;
+ }
+
+ @Override
+ public boolean verifyAtOwnHead(
+ final long blockNumber, final int validatorIndex, final Bytes message, final Bytes signature) {
+ return false;
+ }
+ }
+
+ private Proposal unsealedProposal() {
+ final QbftBlockHeader header =
+ new QbftBlockHeaderTestFixture().number(round.getSequenceNumber()).buildHeader();
+ final QbftBlock block = new QbftBlockTestFixture().blockHeader(header).build();
+ return messageFactory.createProposal(round, block, Optional.empty(), emptyList(), emptyList());
+ }
+
+ @Test
+ public void withoutEnforcementAnUnsealedProposalISValid() {
+ final ProposalPayloadValidator validator =
+ new ProposalPayloadValidator(proposer, round, null, null);
+ assertThat(validator.validateWithoutBlockValidation(unsealedProposal().getSignedPayload()))
+ .isTrue();
+ }
+
+ @Test
+ public void withTheEnforcementARMEDTheSameProposalISRefused() {
+ // THE SAME message as above. The only difference is the hook, so a different result means it
+ // really is called. If this still returned true, the enforcement would be dead code.
+ final ProposalPayloadValidator validator =
+ new ProposalPayloadValidator(
+ proposer, round, null, new PqProposalEnforcement(HEIGHT, new EmptyRegistry(), 2800L));
+ assertThat(validator.validateWithoutBlockValidation(unsealedProposal().getSignedPayload()))
+ .isFalse();
+ }
+
+ @Test
+ public void withTheEnforcementBELOWItsHeightTheSameProposalISValid() {
+ // The third state, closing the last way of being wrong: a hook that refused regardless of
+ // height would make the binary impossible to deploy. Here the enforcement exists but does not
+ // apply yet.
+ final ProposalPayloadValidator validator =
+ new ProposalPayloadValidator(
+ proposer,
+ round,
+ null,
+ new PqProposalEnforcement(HEIGHT + 1, new EmptyRegistry(), 2800L));
+ assertThat(validator.validateWithoutBlockValidation(unsealedProposal().getSignedPayload()))
+ .isTrue();
+ }
+}
diff --git a/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/validation/RoundChangeJustificationPqTest.java b/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/validation/RoundChangeJustificationPqTest.java
new file mode 100755
index 000000000..848ad4c09
--- /dev/null
+++ b/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/validation/RoundChangeJustificationPqTest.java
@@ -0,0 +1,298 @@
+/*
+ * Copyright contributors to Besu.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.qbft.core.validation;
+
+import static com.google.common.collect.Iterables.toArray;
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.hyperledger.besu.consensus.qbft.core.validation.ValidationTestHelpers.createEmptyRoundChangePayloads;
+import static org.hyperledger.besu.consensus.qbft.core.validation.ValidationTestHelpers.createPreparePayloads;
+import static org.hyperledger.besu.consensus.qbft.core.validation.ValidationTestHelpers.createPreparedCertificate;
+import static org.mockito.Mockito.any;
+import static org.mockito.Mockito.lenient;
+import static org.mockito.Mockito.when;
+
+import org.hyperledger.besu.consensus.common.bft.BftHelpers;
+import org.hyperledger.besu.consensus.common.bft.ConsensusRoundHelpers;
+import org.hyperledger.besu.consensus.common.bft.ConsensusRoundIdentifier;
+import org.hyperledger.besu.consensus.common.bft.blockcreation.ProposerSelector;
+import org.hyperledger.besu.consensus.common.bft.payload.SignedData;
+import org.hyperledger.besu.consensus.qbft.core.QbftBlockTestFixture;
+import org.hyperledger.besu.consensus.qbft.core.messagewrappers.Proposal;
+import org.hyperledger.besu.consensus.qbft.core.messagewrappers.RoundChange;
+import org.hyperledger.besu.consensus.qbft.core.payload.PreparedRoundMetadata;
+import org.hyperledger.besu.consensus.qbft.core.payload.RoundChangePayload;
+import org.hyperledger.besu.consensus.qbft.core.statemachine.PreparedCertificate;
+import org.hyperledger.besu.consensus.qbft.core.types.QbftBlock;
+import org.hyperledger.besu.consensus.qbft.core.types.QbftBlockCodec;
+import org.hyperledger.besu.consensus.qbft.core.types.QbftBlockHeader;
+import org.hyperledger.besu.consensus.qbft.core.types.QbftBlockInterface;
+import org.hyperledger.besu.consensus.qbft.core.types.QbftBlockValidator;
+import org.hyperledger.besu.consensus.qbft.core.types.QbftBlockValidator.ValidationResult;
+import org.hyperledger.besu.consensus.qbft.core.types.QbftProtocolSchedule;
+
+import java.util.List;
+import java.util.Optional;
+
+import org.apache.tuweni.bytes.Bytes32;
+
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+
+/**
+ * THE COUPLING of round-change justifications to the PREPARE enforcement.
+ *
+ * <p>WHY THIS FILE EXISTS - it is an hour-long scar, from 2026-08-29. The step-6 design asked for a
+ * SEPARATE gate for justifications, armed later than the PREPARE one, so as not to invalidate "old
+ * justifications". Two things read in the code overturned that request:
+ *
+ * <ol>
+ * <li>a justification cannot be old: {@code validatePrepares} uses
+ * {@code new ConsensusRoundIdentifier(chainHeight, metadata.getPreparedRound())}, so every
+ * attached PREPARE is from the height being decided NOW, only from an earlier round;
+ * <li>the coupling already exists: {@code RoundChangeMessageValidator} builds a
+ * {@link PrepareValidator} with the three-argument constructor, and that one <b>wires its own
+ * enforcement</b> from the system configuration.
+ * </ol>
+ *
+ * <p>So a gate armed later would not be a precaution, it would be a BACK DOOR: the same unsealed
+ * PREPARE, refused when it arrives on its own, would be accepted when it arrives wrapped in a round
+ * change. The coupling is the security property itself - but until today it followed from an
+ * implicit constructor and NOTHING guarded it. Anyone "tidying up" that constructor six months from
+ * now would open the back door without a single test failing. From here on, this one fails.
+ *
+ * <p>WHAT IT DOES NOT PROVE, written down because the gap is visible: it does not prove that a
+ * justification with VALID seals passes, because the self-wired enforcement uses the live registry
+ * of the process and a test one cannot be injected along that path. That case is covered by
+ * {@link PqPrepareEnforcementTest} at the message level and by the network run (F81, scenario A) at
+ * the chain level. What is proven here is the coupling, in both directions, and that the gate is
+ * bound to HEIGHT inside the justifications too.
+ */
+@ExtendWith(MockitoExtension.class)
+public class RoundChangeJustificationPqTest {
+
+ @Mock private RoundChangePayloadValidator payloadValidator;
+ @Mock private QbftProtocolSchedule protocolSchedule;
+ @Mock private QbftBlockValidator blockValidator;
+ @Mock private QbftBlockCodec blockEncoder;
+ @Mock private QbftBlockInterface blockInterface;
+ @Mock private ProposerSelector proposerSelector;
+
+ private static final int VALIDATOR_COUNT = 4;
+ private static final int CHAIN_HEIGHT = 3;
+
+ private final ConsensusRoundIdentifier targetRound =
+ new ConsensusRoundIdentifier(CHAIN_HEIGHT, 3);
+ private final ConsensusRoundIdentifier roundIdentifier =
+ ConsensusRoundHelpers.createFrom(targetRound, 0, -1);
+
+ private QbftNodeList validators;
+
+ @BeforeEach
+ public void setup() {
+ validators = QbftNodeList.createNodes(VALIDATOR_COUNT, blockEncoder);
+ lenient().when(protocolSchedule.getBlockValidator(any())).thenReturn(blockValidator);
+ }
+
+ @AfterEach
+ public void curata() {
+ System.clearProperty(PqPrepareEnforcement.PROPERTY_FORK_BLOCK);
+ }
+
+ private RoundChangeMessageValidator validator() {
+ return new RoundChangeMessageValidator(
+ payloadValidator,
+ BftHelpers.calculateRequiredValidatorQuorum(VALIDATOR_COUNT),
+ CHAIN_HEIGHT,
+ validators.getNodeAddresses(),
+ protocolSchedule);
+ }
+
+ /** A round change with a prepared block and a justification made of UNSEALED PREPAREs. */
+ private RoundChange roundChangeWithUnsealedJustification() {
+ when(payloadValidator.validate(any())).thenReturn(true);
+ when(blockValidator.validateBlock(any(), any()))
+ .thenReturn(new ValidationResult(true, Optional.empty()));
+
+ final QbftBlockHeader header =
+ new QbftBlockHeaderTestFixture().number(roundIdentifier.getSequenceNumber()).buildHeader();
+ final QbftBlock block = new QbftBlockTestFixture().blockHeader(header).build();
+ final PreparedCertificate prepCert =
+ createPreparedCertificate(
+ block, roundIdentifier, toArray(validators.getNodes(), QbftNode.class));
+ return validators.getMessageFactory(0).createRoundChange(targetRound, Optional.of(prepCert));
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // THE PAIR. The same message, once with the enforcement disarmed and once with it armed. A
+ // different result means justifications really do pass through the enforcement; the same result
+ // would mean the back door.
+ // ---------------------------------------------------------------------------------------------
+ @Test
+ public void withoutEnforcementAnUNSEALEDJustificationIsVALID() {
+ System.clearProperty(PqPrepareEnforcement.PROPERTY_FORK_BLOCK);
+ assertThat(validator().validate(roundChangeWithUnsealedJustification())).isTrue();
+ }
+
+ @Test
+ public void withTheEnforcementARMEDTheSameJustificationISRefused() {
+ System.setProperty(PqPrepareEnforcement.PROPERTY_FORK_BLOCK, "0");
+ assertThat(validator().validate(roundChangeWithUnsealedJustification())).isFalse();
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // The third state: the enforcement EXISTS but its height is in the future. Without this test, an
+ // enforcement that refused regardless of height would pass as correct, and the binary could not
+ // be rolled onto the fleet before the activation height.
+ // ---------------------------------------------------------------------------------------------
+ @Test
+ public void withTheEnforcementBELOWItsHeightTheJustificationISVALID() {
+ System.setProperty(
+ PqPrepareEnforcement.PROPERTY_FORK_BLOCK, Long.toString(CHAIN_HEIGHT + 1L));
+ assertThat(validator().validate(roundChangeWithUnsealedJustification())).isTrue();
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // THE OTHER DIRECTION, and it is the very piece that keeps the way back open: a round change
+ // WITHOUT a prepared block has no justification to validate, so it never touches the enforcement
+ // at all. That explains why a chain stalled by the enforcement still advances its rounds
+ // (measured, finding D-280), and it has to stay true: if it broke, the stall would no longer be
+ // recoverable along that same road.
+ // ---------------------------------------------------------------------------------------------
+ @Test
+ public void withTheEnforcementARMEDARoundChangeWITHOUTAPreparedBlockPASSES() {
+ System.setProperty(PqPrepareEnforcement.PROPERTY_FORK_BLOCK, "0");
+ when(payloadValidator.validate(any())).thenReturn(true);
+ for (int i = 0; i < VALIDATOR_COUNT; i++) {
+ final RoundChange without =
+ validators.getMessageFactory(i).createRoundChange(targetRound, Optional.empty());
+ assertThat(validator().validate(without)).isTrue();
+ }
+ }
+
+ // =============================================================================================
+ // THE SECOND PATH, found 2026-08-29 by searching for EVERY place that builds a PrepareValidator
+ // in production code, not just the one I happened to be looking at. There are three:
+ // MessageValidator (ordinary PREPAREs), RoundChangeMessageValidator (the justification of a round
+ // change) and ProposalValidator (the justification of a PROPOSAL for a new round).
+ //
+ // Without that search I would have reported "the coupling is guarded" with only one of the two
+ // justification paths guarded - and the second one is precisely how a prepared block gets
+ // RE-PROPOSED in a new round. The same back door, a different file.
+ // =============================================================================================
+
+ private static final int INALTIME_PROPUNERE = 1;
+
+ private final ConsensusRoundIdentifier roundZero =
+ new ConsensusRoundIdentifier(INALTIME_PROPUNERE, 0);
+ private final ConsensusRoundIdentifier roundOne =
+ new ConsensusRoundIdentifier(INALTIME_PROPUNERE, 1);
+
+ private QbftBlock blocPentru(final ConsensusRoundIdentifier rid, final int autor) {
+ final QbftBlockHeader h =
+ new QbftBlockHeaderTestFixture()
+ .number(rid.getSequenceNumber())
+ .coinbase(validators.getNode(autor).getAddress())
+ .buildHeader();
+ return new QbftBlockTestFixture().blockHeader(h).build();
+ }
+
+ private ProposalValidator validatorulPropunerii() {
+ return new ProposalValidator(
+ blockInterface,
+ protocolSchedule,
+ BftHelpers.calculateRequiredValidatorQuorum(VALIDATOR_COUNT),
+ validators.getNodeAddresses(),
+ roundOne,
+ proposerSelector);
+ }
+
+ /**
+ * A round-1 proposal that carries forward a block PREPARED in round 0, with the justification
+ * made of UNSEALED PREPAREs. The scenario is the upstream one that passes; the only question from
+ * here on is whether the enforcement changes it.
+ */
+ private Proposal proposalWithUnsealedJustification() {
+ lenient()
+ .when(blockValidator.validateBlock(any(), any()))
+ .thenReturn(new ValidationResult(true, Optional.empty()));
+ lenient()
+ .when(proposerSelector.selectProposerForRound(roundZero))
+ .thenReturn(validators.getNode(0).getAddress());
+ lenient()
+ .when(proposerSelector.selectProposerForRound(roundOne))
+ .thenReturn(validators.getNode(1).getAddress());
+
+ final QbftBlock blocRundaZero = blocPentru(roundZero, 0);
+ final QbftBlock blocRundaUnu = blocPentru(roundOne, 1);
+
+ lenient()
+ .when(
+ blockInterface.replaceRoundAndProposerForProposalBlock(
+ blocRundaUnu, 0, validators.getNode(0).getAddress()))
+ .thenReturn(blocRundaZero);
+
+ final List<SignedData<RoundChangePayload>> schimbari =
+ createEmptyRoundChangePayloads(roundOne, validators.getNode(0), validators.getNode(1));
+
+ final RoundChangePayload cuPregatit =
+ new RoundChangePayload(
+ roundOne,
+ Optional.of(
+ new PreparedRoundMetadata(blocRundaZero.getHash(), roundZero.getRoundNumber())));
+ schimbari.add(
+ SignedData.create(
+ cuPregatit,
+ validators
+ .getNode(2)
+ .getNodeKey()
+ .sign(Bytes32.wrap(cuPregatit.hashForSignature().getBytes()))));
+
+ return validators
+ .getMessageFactory(1)
+ .createProposal(
+ roundOne,
+ blocRundaUnu,
+ schimbari,
+ createPreparePayloads(
+ roundZero,
+ blocRundaZero.getHash(),
+ validators.getNode(0),
+ validators.getNode(1),
+ validators.getNode(2)));
+ }
+
+ @Test
+ public void withoutEnforcementAPROPOSALWithAnUNSEALEDJustificationIsVALID() {
+ System.clearProperty(PqPrepareEnforcement.PROPERTY_FORK_BLOCK);
+ assertThat(validatorulPropunerii().validate(proposalWithUnsealedJustification())).isTrue();
+ }
+
+ @Test
+ public void withTheEnforcementARMEDTheSamePROPOSALISRefused() {
+ System.setProperty(PqPrepareEnforcement.PROPERTY_FORK_BLOCK, "0");
+ assertThat(validatorulPropunerii().validate(proposalWithUnsealedJustification())).isFalse();
+ }
+
+ @Test
+ public void withTheEnforcementBELOWItsHeightThePROPOSALISVALID() {
+ System.setProperty(
+ PqPrepareEnforcement.PROPERTY_FORK_BLOCK, Long.toString(INALTIME_PROPUNERE + 1L));
+ assertThat(validatorulPropunerii().validate(proposalWithUnsealedJustification())).isTrue();
+ }
+}
diff --git a/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/validation/RoundChangePayloadValidatorPqWiringTest.java b/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/validation/RoundChangePayloadValidatorPqWiringTest.java
new file mode 100755
index 000000000..b906ec016
--- /dev/null
+++ b/consensus/qbft-core/src/test/java/org/hyperledger/besu/consensus/qbft/core/validation/RoundChangePayloadValidatorPqWiringTest.java
@@ -0,0 +1,125 @@
+/*
+ * Copyright contributors to Besu.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.qbft.core.validation;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import org.hyperledger.besu.consensus.common.bft.ConsensusRoundIdentifier;
+import org.hyperledger.besu.consensus.common.bft.PqSignerRegistry;
+import org.hyperledger.besu.consensus.qbft.core.messagewrappers.RoundChange;
+import org.hyperledger.besu.consensus.qbft.core.payload.MessageFactory;
+import org.hyperledger.besu.consensus.qbft.core.types.QbftBlockCodec;
+import org.hyperledger.besu.cryptoservices.NodeKey;
+import org.hyperledger.besu.cryptoservices.NodeKeyUtils;
+import org.hyperledger.besu.datatypes.Address;
+import org.hyperledger.besu.ethereum.core.Util;
+
+import java.util.List;
+import java.util.Optional;
+
+import org.apache.tuweni.bytes.Bytes;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+
+/**
+ * THE WIRING, not the class: does {@link RoundChangePayloadValidator} actually CALL the
+ * enforcement?
+ *
+ * <p>Same reason the PREPARE and PROPOSAL twins exist: a class present in the binary, environment
+ * variables visible to the process, and code that never runs is exactly the failure paid for on
+ * 2026-08-28. The registry here REFUSES everything, so this does not measure cryptography (that has
+ * its own test), only whether the decision passes through the hook. The pair is all it takes: the
+ * same signed round-change, once with enforcement and once without.
+ */
+@ExtendWith(MockitoExtension.class)
+public class RoundChangePayloadValidatorPqWiringTest {
+
+ private static final long HEIGHT = 1L;
+
+ // A round-change must target a POSITIVE round, so the identifier moves to round 1.
+ private final ConsensusRoundIdentifier targetRound = new ConsensusRoundIdentifier((int) HEIGHT, 1);
+ @Mock private QbftBlockCodec blockEncoder;
+
+ private final NodeKey nodeKey = NodeKeyUtils.generate();
+ private final Address author = Util.publicKeyToAddress(nodeKey.getPublicKey());
+ private MessageFactory messageFactory;
+
+ @BeforeEach
+ public void setup() {
+ messageFactory = new MessageFactory(nodeKey, blockEncoder);
+ }
+
+ /** A registry that binds no index and verifies nothing. */
+ private static final class EmptyRegistry implements PqSignerRegistry {
+ @Override
+ public Address addressForIndexAtHistoric(final long blockNumber, final int validatorIndex) {
+ return null;
+ }
+
+ @Override
+ public Address addressForIndexAtOwnHead(final long blockNumber, final int validatorIndex) {
+ return null;
+ }
+
+ @Override
+ public boolean verifyAtHistoric(
+ final long blockNumber, final int validatorIndex, final Bytes message, final Bytes signature) {
+ return false;
+ }
+
+ @Override
+ public boolean verifyAtOwnHead(
+ final long blockNumber, final int validatorIndex, final Bytes message, final Bytes signature) {
+ return false;
+ }
+ }
+
+ private RoundChange unsealedRoundChange() {
+ return messageFactory.createRoundChange(targetRound, Optional.empty());
+ }
+
+ @Test
+ public void withoutEnforcementAnUnsealedRoundChangeISValid() {
+ final RoundChangePayloadValidator validator =
+ new RoundChangePayloadValidator(List.of(author), HEIGHT, null);
+ assertThat(validator.validate(unsealedRoundChange().getSignedPayload())).isTrue();
+ }
+
+ @Test
+ public void withTheEnforcementARMEDTheSameRoundChangeISRefused() {
+ // THE SAME message as above. The only difference is the hook, so a different result means it
+ // really is called. If this still returned true, the enforcement would be dead code.
+ final RoundChangePayloadValidator validator =
+ new RoundChangePayloadValidator(
+ List.of(author), HEIGHT, new PqRoundChangeEnforcement(HEIGHT, new EmptyRegistry(), 2800L));
+ assertThat(validator.validate(unsealedRoundChange().getSignedPayload())).isFalse();
+ }
+
+ @Test
+ public void withTheEnforcementBELOWItsHeightTheSameRoundChangeISValid() {
+ // The third state, closing the last way of being wrong: a hook that refused regardless of
+ // height would make the binary impossible to deploy. Here the enforcement exists but does not
+ // apply yet.
+ final RoundChangePayloadValidator validator =
+ new RoundChangePayloadValidator(
+ List.of(author),
+ HEIGHT,
+ new PqRoundChangeEnforcement(HEIGHT + 1, new EmptyRegistry(), 2800L));
+ assertThat(validator.validate(unsealedRoundChange().getSignedPayload())).isTrue();
+ }
+}
diff --git a/consensus/qbft/src/main/java/org/hyperledger/besu/consensus/qbft/QbftBlockHeaderValidationRulesetFactory.java b/consensus/qbft/src/main/java/org/hyperledger/besu/consensus/qbft/QbftBlockHeaderValidationRulesetFactory.java
index f54d7bfcd..cfc67a900 100644
--- a/consensus/qbft/src/main/java/org/hyperledger/besu/consensus/qbft/QbftBlockHeaderValidationRulesetFactory.java
+++ b/consensus/qbft/src/main/java/org/hyperledger/besu/consensus/qbft/QbftBlockHeaderValidationRulesetFactory.java
@@ -11,6 +11,12 @@
* specific language governing permissions and limitations under the License.
*
* SPDX-License-Identifier: Apache-2.0
+ *
+ * Modifications Copyright contributors to the Aere Network.
+ *
+ * This file was modified by contributors to the Aere Network, as required by section 4(b) of the
+ * Apache License 2.0. The copyright header above is the upstream one and is left exactly as it was
+ * found, as section 4(c) requires. The change itself is in patches/0003-aere-pq-anchor.patch.
*/
package org.hyperledger.besu.consensus.qbft;
@@ -18,8 +24,17 @@ import static org.hyperledger.besu.ethereum.mainnet.AbstractGasLimitSpecificatio
import static org.hyperledger.besu.ethereum.mainnet.AbstractGasLimitSpecification.DEFAULT_MIN_GAS_LIMIT;
import org.hyperledger.besu.consensus.common.bft.BftHelpers;
+import org.hyperledger.besu.consensus.common.bft.FalconSealSupport;
+import org.hyperledger.besu.consensus.common.bft.PqAnchorConfig;
import org.hyperledger.besu.consensus.common.bft.headervalidationrules.BftCoinbaseValidationRule;
import org.hyperledger.besu.consensus.common.bft.headervalidationrules.BftCommitSealsValidationRule;
+import org.hyperledger.besu.consensus.qbft.headervalidationrules.AereBaseFeeImportRule;
+import org.hyperledger.besu.consensus.qbft.headervalidationrules.FalconSealValidationRule;
+import org.hyperledger.besu.consensus.qbft.headervalidationrules.PqAnchorDigestAttachedRule;
+import org.hyperledger.besu.consensus.qbft.headervalidationrules.PqAnchorDigestRule;
+import org.hyperledger.besu.consensus.qbft.headervalidationrules.PqAnchorSealsRule;
+import org.hyperledger.besu.consensus.qbft.headervalidationrules.PqEmergencyShoutRule;
+import org.hyperledger.besu.consensus.qbft.headervalidationrules.PqRegistryBindingRule;
import org.hyperledger.besu.consensus.qbft.headervalidationrules.QbftValidatorsValidationRule;
import org.hyperledger.besu.ethereum.core.BlockHeader;
import org.hyperledger.besu.ethereum.mainnet.BlockHeaderValidator;
@@ -54,14 +69,90 @@ public class QbftBlockHeaderValidationRulesetFactory {
final Duration minimumTimeBetweenBlocks,
final boolean useValidatorContract,
final Optional<BaseFeeMarket> baseFeeMarket) {
+ return blockHeaderValidator(
+ minimumTimeBetweenBlocks,
+ useValidatorContract,
+ baseFeeMarket,
+ PqAnchorConfig.fromSystemConfiguration());
+ }
+
+ /**
+ * Produces a BlockHeaderValidator configured for assessing bft block headers, with an explicit V2
+ * certificate-anchor configuration.
+ *
+ * <p>AERE ANCORA-V2 (2026-08-01). Two rules are added and one is retired, all indexed on the BLOCK
+ * NUMBER:
+ *
+ * <ul>
+ * <li>{@link PqAnchorDigestRule} (R1), DETACHED and part of LIGHT validation: recomputes the
+ * anchor digest D from the header's own parent hash, its own height minus one, the chain id
+ * and the certificate the header itself carries, and requires it to equal vanityData. One
+ * keccak, no state. This is what makes a stripped or swapped certificate detectable, and
+ * detectable on a node that is fast-syncing headers.
+ * <li>{@link PqAnchorSealsRule} (R2), ATTACHED and full validation only: threshold, strictly
+ * increasing indices, eligibility in the PARENT's validator set, and k Falcon verifications
+ * over M(parent).
+ * <li>{@link FalconSealValidationRule} retires at the same height. It is replaced, not promoted:
+ * it is excluded from light validation, it returns true on every path including its
+ * exception path, and it reads historical world state over a window that does not exist on a
+ * syncing node.
+ * </ul>
+ *
+ * <p>Below the activation height H the two new rules return true as their FIRST statement, before
+ * any decode, and the legacy rule behaves exactly as before. A binary built from this code is
+ * therefore bit-for-bit equivalent to today's on the whole existing chain, which is the condition
+ * for warming it on a live node.
+ *
+ * <p>The rule COUNT goes from 11 to 16 (A8 adds the registry-binding rule, was 13; SINCRONIZARE
+ * adds the attached copy of the digest rule, was 14; OPTIUNI-URGENTA adds the emergency
+ * announcement rule, which can never reject, was 15) (14 unconditional plus the conditional timestamp rule). The
+ * design note said 12 because it assumed the legacy Falcon rule would be deleted; retiring it by
+ * height instead is what keeps behaviour below H identical, so it stays in the list.
+ *
+ * @param minimumTimeBetweenBlocks the minimum amount of time that must elapse between blocks.
+ * @param useValidatorContract whether validator selection is using a validator contract
+ * @param baseFeeMarket an {@link Optional} wrapping {@link BaseFeeMarket} class if appropriate.
+ * @param pqAnchorConfig the height-indexed V2 certificate-anchor configuration
+ * @return BlockHeaderValidator configured for assessing bft block headers
+ */
+ public static BlockHeaderValidator.Builder blockHeaderValidator(
+ final Duration minimumTimeBetweenBlocks,
+ final boolean useValidatorContract,
+ final Optional<BaseFeeMarket> baseFeeMarket,
+ final PqAnchorConfig pqAnchorConfig) {
+ // AERE FIX-OPRIRE-CONSENS (b): force EAGER initialisation of FalconSealSupport here, while the
+ // protocol schedule is being built at node startup and before the network is up. The class runs
+ // its fail-closed configuration guards in its constructor; leaving it lazily initialised meant a
+ // node with an unsafe Falcon activation config started normally and only discovered the problem
+ // the first time a QBFT round touched the singleton, i.e. ON the consensus path. Touching it
+ // here moves every refusal back to config time, which is the only safe place for it.
+ FalconSealSupport.instance();
+
BlockHeaderValidator.Builder ruleBuilder =
new BlockHeaderValidator.Builder()
+ // AERE OPTIUNI-URGENTA (2026-08-02): FIRST, and it can never reject. Its whole job is
+ // to make an emergency override impossible to run on without noticing, by writing one
+ // complete ERROR line at every height for as long as one is in force. First in the list
+ // because a rule that always returns true cannot change the verdict of a conjunction,
+ // and because the moment an operator most needs to know a control was overridden is
+ // when a LATER rule is rejecting headers.
+ .addRule(new PqEmergencyShoutRule(pqAnchorConfig))
.addRule(new AncestryValidationRule())
.addRule(new GasUsageValidationRule())
.addRule(
new GasLimitRangeAndDeltaValidationRule(
DEFAULT_MIN_GAS_LIMIT, DEFAULT_MAX_GAS_LIMIT, baseFeeMarket))
.addRule(new TimestampBoundedByFutureParameter(1))
+ // AERE D-AMONTE-02: the base-fee rule every non-BFT factory in this jar wires and the
+ // QBFT one upstream forgot. Height-gated (disarmed = today's behaviour, byte for byte):
+ // the chain's HISTORY contains blocks this validation would reject (the two floor-less
+ // days, the lost-threshold window where the fee was not a function of the parent), so
+ // it must never look below its arming height. Delegates to THIS node's fee market, so
+ // the AERE 1 Gwei floor is validated too - the check that closes the empty-block
+ // one-wei divergence measured on the mixed network (STARE-PRODUCATOR 1bis).
+ .addRule(
+ new AereBaseFeeImportRule(
+ AereBaseFeeImportRule.armedFromSystemConfig(), baseFeeMarket))
.addRule(
new ConstantFieldValidationRule<>(
"MixHash", BlockHeader::getMixHash, BftHelpers.EXPECTED_MIX_HASH))
@@ -70,7 +161,34 @@ public class QbftBlockHeaderValidationRulesetFactory {
"Difficulty", BlockHeader::getDifficulty, UInt256.ONE))
.addRule(new QbftValidatorsValidationRule(useValidatorContract))
.addRule(new BftCoinbaseValidationRule())
- .addRule(new BftCommitSealsValidationRule());
+ .addRule(new BftCommitSealsValidationRule())
+ // AERE ANCORA-V2: the legacy log-only Falcon rule now stands down at H. With an
+ // unconfigured anchor this is Long.MAX_VALUE, i.e. it never stands down and behaviour is
+ // unchanged.
+ .addRule(
+ new FalconSealValidationRule(pqAnchorConfig.legacyFalconRuleRetirementBlock()))
+ // AERE ANCORA-V2 R1: cheap, detached, IN LIGHT VALIDATION. Ordered before R2 so the one
+ // keccak that binds the certificate to the block hash runs before k Falcon
+ // verifications are spent on it.
+ .addRule(new PqAnchorDigestRule(pqAnchorConfig))
+ // AERE SINCRONIZARE R1A (2026-08-02): the SAME digest verdict, on the ATTACHED side.
+ // Measured cause it repairs: SKIP_DETACHED, the mode FullImportBlockStep passes to
+ // importBlock for every block acquired by sync, keeps exactly the rules that are NOT
+ // detached, so R1 does not run at import; and DETACHED_ONLY, the mode under which R1
+ // does run, is only applied by DownloadHeaderSequenceTask, i.e. only on ranges with a
+ // closed end. The open-ended range at the tip of a recovery, 199 blocks by default, was
+ // therefore checked by neither. Ordered immediately before R2 so the one keccak still
+ // runs before k Falcon verifications are spent. Delegates to R1, so there is one
+ // definition of the digest and the two paths cannot drift.
+ .addRule(new PqAnchorDigestAttachedRule(pqAnchorConfig))
+ // AERE ANCORA-V2 R2: attached, full validation only.
+ .addRule(new PqAnchorSealsRule(pqAnchorConfig))
+ // AERE A8 per-block half: the registry this node runs must be the registry
+ // config.pqRegistryHash requires AT THIS HEIGHT. The startup guard answers
+ // that once, against the head that existed at startup; a rotation entry in
+ // the schedule can pass underneath a running node and never be noticed.
+ // Inert when no schedule is configured, which is chain 2800 today.
+ .addRule(new PqRegistryBindingRule());
// Currently the minimum acceptable time between blocks is 1 second. The timestamp of an
// Ethereum header is stored as seconds since Unix epoch so blocks being produced more
diff --git a/consensus/qbft/src/main/java/org/hyperledger/besu/consensus/qbft/QbftExtraDataCodec.java b/consensus/qbft/src/main/java/org/hyperledger/besu/consensus/qbft/QbftExtraDataCodec.java
index 39c7aa300..b3096d331 100644
--- a/consensus/qbft/src/main/java/org/hyperledger/besu/consensus/qbft/QbftExtraDataCodec.java
+++ b/consensus/qbft/src/main/java/org/hyperledger/besu/consensus/qbft/QbftExtraDataCodec.java
@@ -11,6 +11,12 @@
* specific language governing permissions and limitations under the License.
*
* SPDX-License-Identifier: Apache-2.0
+ *
+ * Modifications Copyright contributors to the Aere Network.
+ *
+ * This file was modified by contributors to the Aere Network, as required by section 4(b) of the
+ * Apache License 2.0. The copyright header above is the upstream one and is left exactly as it was
+ * found, as section 4(c) requires. The change itself is in patches/0003-aere-pq-anchor.patch.
*/
package org.hyperledger.besu.consensus.qbft;
@@ -19,6 +25,9 @@ import static org.hyperledger.besu.consensus.common.bft.Vote.DROP_BYTE_VALUE;
import org.hyperledger.besu.consensus.common.bft.BftExtraData;
import org.hyperledger.besu.consensus.common.bft.BftExtraDataCodec;
+import org.hyperledger.besu.consensus.common.bft.FalconSeal;
+import org.hyperledger.besu.consensus.common.bft.PqAnchorV2;
+import org.hyperledger.besu.consensus.common.bft.SchemeSeal;
import org.hyperledger.besu.consensus.common.bft.Vote;
import org.hyperledger.besu.consensus.common.validator.VoteType;
import org.hyperledger.besu.crypto.SECPSignature;
@@ -41,6 +50,15 @@ import org.apache.tuweni.bytes.Bytes;
/**
* Represents the data structure stored in the extraData field of the BlockHeader used when
* operating under an BFT consensus mechanism.
+ *
+ * <p>AERE hybrid PQC extension: an OPTIONAL, PARALLEL Falcon-512 seal list (a per-block post-quantum
+ * quorum certificate) is appended after the ECDSA committed-seal list, but ONLY in the {@link
+ * EncodingType#ALL} (stored-header) encoding AND only when at least one Falcon seal is present. The
+ * two "exclude" encodings used for the committed-seal hash and the on-chain block hash omit the
+ * Falcon list entirely, and a header with no Falcon seals omits it too, so in every case the bytes
+ * are identical to upstream Besu whenever no post-quantum certificate is carried. This guarantees
+ * the Falcon seals never disturb the ECDSA committed seals or any signed pre-image. Decoding is
+ * backward-tolerant: headers with no Falcon list decode to an empty Falcon-seal collection.
*/
public class QbftExtraDataCodec extends BftExtraDataCodec {
private static final ImmutableBiMap<VoteType, Byte> voteToValue =
@@ -102,9 +120,91 @@ public class QbftExtraDataCodec extends BftExtraDataCodec {
final List<SECPSignature> seals =
rlpInput.readList(
rlp -> SignatureAlgorithmFactory.getInstance().decodeSignature(rlp.readBytes()));
- rlpInput.leaveListLenient();
- return new BftExtraData(vanityData, seals, vote, round, validators);
+ // AERE hybrid PQC: an OPTIONAL parallel Falcon-512 seal list may follow the ECDSA seals.
+ // Backward-tolerant: older/exclude/no-certificate encodings without this element decode to an
+ // empty list.
+ final List<FalconSeal> falconSeals;
+ final List<SchemeSeal> hybridSeals;
+ if (!rlpInput.isEndOfCurrentList()) {
+ // AERE ANCHOR V2 (2026-09-03): the sixth element is EITHER the v1 Falcon list
+ // RLP[[idx,sig],...] OR the scheme-tagged v2 certificate RLP[2,[[scheme,idx,sig],...]].
+ // They cannot be confused: v1 opens with a LIST, v2 with the SCALAR 2. The raw bytes are
+ // taken first so the v2 decoder can enforce its canonical round trip on exactly what the
+ // header carried; the codec's own round trip (gate 2 below) then covers both forms.
+ final Bytes certificateRaw = rlpInput.readAsRlp().raw();
+ final RLPInput probe = new BytesValueRLPInput(certificateRaw, false);
+ probe.enterList();
+ final boolean v2 = !probe.isEndOfCurrentList() && !probe.nextIsList();
+ if (v2) {
+ falconSeals = Collections.emptyList();
+ try {
+ hybridSeals = PqAnchorV2.decode(certificateRaw);
+ } catch (final RuntimeException e) {
+ throw new RLPException(
+ "AERE ANCHOR V2: the header's certificate does not decode as a canonical v2"
+ + " certificate: "
+ + e.getMessage());
+ }
+ } else {
+ hybridSeals = Collections.emptyList();
+ falconSeals =
+ new BytesValueRLPInput(certificateRaw, false)
+ .readList(
+ rlp -> {
+ rlp.enterList();
+ final int idx = rlp.readIntScalar();
+ final Bytes sig = rlp.readBytes();
+ rlp.leaveList();
+ return new FalconSeal(idx, sig);
+ });
+ }
+ } else {
+ falconSeals = Collections.emptyList();
+ hybridSeals = Collections.emptyList();
+ }
+
+ // AERE FIX-MALEABILITATE-BLOC (2026-08-01), gate 1 of 2: the leave is STRICT.
+ //
+ // Upstream ends this decode with leaveListLenient(), which silently discards anything still
+ // left in the outer list. That is not survivable here, because the QBFT block hash and the
+ // committed-seal pre-image are BOTH computed from a RE-ENCODE of the decoded BftExtraData
+ // (BftBlockHashing.calculateHashOfBftBlockOnchain line 84-91, calculateDataHashForCommittedSeal
+ // line 53-75). Anything the decoder discards is therefore dropped before hashing, so two
+ // different header byte strings carry the same block hash and the same genuine validator
+ // seals. leaveList() rejects exactly the inputs that have content left over, and is
+ // byte-for-byte identical to the lenient leave on every input that has not.
+ rlpInput.leaveList();
+
+ final BftExtraData decoded =
+ new BftExtraData(vanityData, seals, vote, round, validators, falconSeals, hybridSeals);
+
+ // AERE FIX-MALEABILITATE-BLOC (2026-08-01), gate 2 of 2: CANONICAL ROUND TRIP.
+ //
+ // The strict leave alone does not close the hole. The Falcon element is OPTIONAL on the wire
+ // and the encoder omits it when the certificate is empty, so a header carrying an explicit
+ // EMPTY Falcon list decodes to exactly the same value as a header carrying no Falcon element
+ // at all: the trailing 0xc0 is CONSUMED, not left over, so no leave, strict or lenient, can
+ // see it. Requiring the full re-encode to reproduce the received bytes makes the accepted
+ // encoding unique by construction, and closes every present and future shape of this defect
+ // rather than the one instance of it we happened to look for.
+ //
+ // Backward compatibility: the re-encode used here is the same EncodingType.ALL the block
+ // producer uses, so every header any Aere or stock Besu node has ever produced round trips
+ // unchanged. Headers with no Falcon element re-encode with no Falcon element, which is why
+ // the whole pre-Falcon history of the chain still decodes.
+ final Bytes canonical = encode(decoded, EncodingType.ALL);
+ if (!canonical.equals(input)) {
+ throw new RLPException(
+ "Non-canonical BFT extra data: the header's extraData is "
+ + input.size()
+ + " bytes but its canonical re-encoding is "
+ + canonical.size()
+ + " bytes. A QBFT block hash is computed over the re-encoded form, so a non-canonical"
+ + " encoding would give two header byte strings one block hash. Rejected.");
+ }
+
+ return decoded;
}
@Override
@@ -126,6 +226,24 @@ public class QbftExtraDataCodec extends BftExtraDataCodec {
if (encodingType != EncodingType.EXCLUDE_COMMIT_SEALS) {
encoder.writeList(
bftExtraData.getSeals(), (committer, rlp) -> rlp.writeBytes(committer.encodedBytes()));
+ // AERE hybrid PQC: only the full (stored-header) encoding carries the parallel Falcon
+ // quorum certificate, and only when it is non-empty. The exclude encodings omit it so the
+ // committed-seal hash and the on-chain block hash are byte-identical to upstream Besu, and a
+ // header with no certificate is byte-identical to upstream too, so the Falcon seals are
+ // never part of any signed pre-image and never disturb the block hash.
+ if (!bftExtraData.getHybridSeals().isEmpty()) {
+ // AERE ANCHOR V2: the scheme-tagged certificate, canonical bytes, in the same slot.
+ encoder.writeRaw(PqAnchorV2.encode(bftExtraData.getHybridSeals()));
+ } else if (!bftExtraData.getFalconSeals().isEmpty()) {
+ encoder.writeList(
+ bftExtraData.getFalconSeals(),
+ (falconSeal, rlp) -> {
+ rlp.startList();
+ rlp.writeIntScalar(falconSeal.getValidatorIndex());
+ rlp.writeBytes(falconSeal.getSignature());
+ rlp.endList();
+ });
+ }
} else {
encoder.writeEmptyList();
}
diff --git a/consensus/qbft/src/main/java/org/hyperledger/besu/consensus/qbft/adaptor/QbftBlockCreatorAdaptor.java b/consensus/qbft/src/main/java/org/hyperledger/besu/consensus/qbft/adaptor/QbftBlockCreatorAdaptor.java
index 594fe83e4..dd67707b1 100644
--- a/consensus/qbft/src/main/java/org/hyperledger/besu/consensus/qbft/adaptor/QbftBlockCreatorAdaptor.java
+++ b/consensus/qbft/src/main/java/org/hyperledger/besu/consensus/qbft/adaptor/QbftBlockCreatorAdaptor.java
@@ -11,26 +11,51 @@
* specific language governing permissions and limitations under the License.
*
* SPDX-License-Identifier: Apache-2.0
+ *
+ * Modifications Copyright contributors to the Aere Network.
+ *
+ * This file was modified by contributors to the Aere Network, as required by section 4(b) of the
+ * Apache License 2.0. The copyright header above is the upstream one and is left exactly as it was
+ * found, as section 4(c) requires. The change itself is in patches/0003-aere-pq-anchor.patch.
*/
package org.hyperledger.besu.consensus.qbft.adaptor;
+import org.hyperledger.besu.consensus.common.bft.BftBlockHashing;
import org.hyperledger.besu.consensus.common.bft.BftBlockHeaderFunctions;
import org.hyperledger.besu.consensus.common.bft.BftExtraData;
import org.hyperledger.besu.consensus.common.bft.BftExtraDataCodec;
+import org.hyperledger.besu.consensus.common.bft.FalconSeal;
+import org.hyperledger.besu.consensus.common.bft.FalconSealSupport;
+import org.hyperledger.besu.consensus.common.bft.blockcreation.PqAnchorProducer;
import org.hyperledger.besu.consensus.qbft.core.types.QbftBlock;
import org.hyperledger.besu.consensus.qbft.core.types.QbftBlockCreator;
import org.hyperledger.besu.consensus.qbft.core.types.QbftBlockHeader;
import org.hyperledger.besu.crypto.SECPSignature;
+import org.hyperledger.besu.datatypes.Address;
+import org.hyperledger.besu.datatypes.Hash;
import org.hyperledger.besu.ethereum.blockcreation.BlockCreator;
import org.hyperledger.besu.ethereum.core.Block;
import org.hyperledger.besu.ethereum.core.BlockHeader;
import org.hyperledger.besu.ethereum.core.BlockHeaderBuilder;
+import java.util.ArrayList;
import java.util.Collection;
+import java.util.Collections;
+import java.util.LinkedHashSet;
+import java.util.List;
+import java.util.Optional;
+import java.util.OptionalInt;
+import java.util.Set;
+
+import org.apache.tuweni.bytes.Bytes32;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
/** Adaptor class to allow a {@link BlockCreator} to be used as a {@link QbftBlockCreator}. */
public class QbftBlockCreatorAdaptor implements QbftBlockCreator {
+ private static final Logger LOG = LoggerFactory.getLogger(QbftBlockCreatorAdaptor.class);
+
private final BlockCreator besuBlockCreator;
private final BftExtraDataCodec bftExtraDataCodec;
@@ -59,11 +84,60 @@ public class QbftBlockCreatorAdaptor implements QbftBlockCreator {
@Override
public QbftBlock createSealedBlock(
final QbftBlock block, final int roundNumber, final Collection<SECPSignature> commitSeals) {
+ return createSealedBlock(block, roundNumber, commitSeals, Collections.emptyList());
+ }
+
+ @Override
+ public QbftBlock createSealedBlock(
+ final QbftBlock block,
+ final int roundNumber,
+ final Collection<SECPSignature> commitSeals,
+ final Collection<FalconSeal> collectedFalconSeals) {
final Block besuBlock = AdaptorUtil.toBesuBlock(block);
final QbftBlockHeader initialHeader = block.getHeader();
final BftExtraData initialExtraData =
bftExtraDataCodec.decode(AdaptorUtil.toBesuBlockHeader(initialHeader));
+ // AERE ANCHOR V2, THE MEASURED TRAP, CLOSED HERE. Above the activation height element 6 is no
+ // longer "the seals I heard for THIS block": it is the quorum certificate over the PARENT,
+ // CHOSEN BY THE PROPOSER, and vanityData carries its digest D. Every node that seals this block
+ // must therefore carry the proposer's bytes across UNCHANGED. The legacy assembly below would
+ // overwrite them with what this node heard for the current block, which would leave a header
+ // whose vanity D no longer matches its own element 6, i.e. a header this node's own digest rule
+ // rejects. So above the activation height the assembler is skipped outright.
+ //
+ // Note what is NOT done here: no re-verification, no re-selection, no comparison against what
+ // this node heard. That is the whole point of V2. The proposer's certificate has already been
+ // checked by the header rules on the proposal, and re-deriving it locally is exactly the
+ // dependency on "what I heard" that killed the earlier design.
+ if (PqAnchorProducer.config().activeAt(initialHeader.getNumber())) {
+ final BftExtraData anchoredExtraData =
+ new BftExtraData(
+ initialExtraData.getVanityData(),
+ commitSeals,
+ initialExtraData.getVote(),
+ roundNumber,
+ initialExtraData.getValidators(),
+ initialExtraData.getFalconSeals(),
+ // AERE ANCHOR V2 (2026-09-03, D-328): the sealed block keeps the proposer's v2 certificate
+ // verbatim, exactly as it keeps the v1 one; dropping it here is what stalled the testnet.
+ initialExtraData.getHybridSeals());
+ final BlockHeader anchoredHeader =
+ BlockHeaderBuilder.fromHeader(AdaptorUtil.toBesuBlockHeader(initialHeader))
+ .extraData(bftExtraDataCodec.encode(anchoredExtraData))
+ .blockHeaderFunctions(BftBlockHeaderFunctions.forOnchainBlock(bftExtraDataCodec))
+ .buildBlockHeader();
+ LOG.debug(
+ "AERE PQ-ANCHOR: sealed block {} keeping the proposer's {}-seal parent certificate "
+ + "verbatim ({} seal(s) heard locally for this block were deliberately ignored)",
+ anchoredHeader.getNumber(),
+ initialExtraData.getFalconSeals().size(),
+ collectedFalconSeals == null ? 0 : collectedFalconSeals.size());
+ return new QbftBlockAdaptor(new Block(anchoredHeader, besuBlock.getBody()));
+ }
+
+ // Step 1: build the sealed header exactly as upstream, with the decisive ECDSA committed seals
+ // and (for now) no Falcon seals. The ECDSA path is byte-for-byte unchanged.
final BftExtraData sealedExtraData =
new BftExtraData(
initialExtraData.getVanityData(),
@@ -72,12 +146,149 @@ public class QbftBlockCreatorAdaptor implements QbftBlockCreator {
roundNumber,
initialExtraData.getValidators());
- final BlockHeader sealedHeader =
+ BlockHeader sealedHeader =
BlockHeaderBuilder.fromHeader(AdaptorUtil.toBesuBlockHeader(initialHeader))
.extraData(bftExtraDataCodec.encode(sealedExtraData))
.blockHeaderFunctions(BftBlockHeaderFunctions.forOnchainBlock(bftExtraDataCodec))
.buildBlockHeader();
+
+ // Step 2 (AERE hybrid PQC): assemble a parallel Falcon-512 QUORUM CERTIFICATE from the seals
+ // gossiped on the commit messages. Each seal is re-verified against the registry over the SAME
+ // commit hash the ECDSA committed seal signs, and de-duplicated by validator index, so the
+ // embedded certificate is exactly the set of distinct, valid post-quantum seals. Falcon seals
+ // are excluded from every signed pre-image (committed-seal hash and on-chain block hash), so the
+ // block hash is identical whether or not the certificate is present. Any failure here leaves the
+ // ECDSA-sealed header untouched and valid.
+ try {
+ final FalconSealSupport pqc = FalconSealSupport.instance();
+ final Hash commitHash =
+ new BftBlockHashing(bftExtraDataCodec).calculateDataHashForCommittedSeal(sealedHeader);
+
+ // AERE audit fix (AUD-CONSENSUS-1 / -2): restrict the embedded certificate to ELIGIBLE
+ // signers (current validators carried in extraData INTERSECT the address-bound registry), so
+ // the assembler never embeds a seal the header rule would later reject as ineligible.
+ final Set<Address> registered = pqc.registeredValidatorAddresses();
+ final Set<Address> eligible = new LinkedHashSet<>();
+ for (final Address v : initialExtraData.getValidators()) {
+ if (registered.contains(v)) {
+ eligible.add(v);
+ }
+ }
+
+ // AERE DISC 2026-08-08: the interval gate. Measured on chain 2800 the same day: with all
+ // seven validators attaching, this assembler wrote FIVE seals into EVERY header, 525 -> 3844
+ // bytes, about 200 GB per node per year against 12 GB free on the tightest host.
+ //
+ // The anchor producer has had an interval and a cap since 7 August. This assembler, the one
+ // that runs BEFORE the activation height, had neither, so the controls were unreachable
+ // exactly during the window they were needed. Skipping the whole attach block, rather than
+ // assembling and then discarding, also saves the Falcon verification of every heard seal.
+ if (!pqc.attachesCertificateAt(sealedHeader.getNumber())) {
+ LOG.debug(
+ "AERE PQC: block {} is not an attachment height (interval {}), leaving the header "
+ + "ECDSA-only at {} bytes",
+ sealedHeader.getNumber(),
+ pqc.attachInterval().isPresent() ? pqc.attachInterval().getAsInt() : 1,
+ sealedHeader.getExtraData().size());
+ return new QbftBlockAdaptor(new Block(sealedHeader, besuBlock.getBody()));
+ }
+
+ final List<FalconSeal> quorumCert =
+ verifiedDistinctSeals(
+ pqc,
+ sealedHeader.getNumber(),
+ commitHash,
+ collectedFalconSeals,
+ eligible,
+ pqc.attachMaxSeals());
+
+ // Fallback self-seal: if nothing was gossiped (e.g. the pre-gossip 3-arg path) but this node
+ // can sign AND is itself an eligible signer, attach its own seal so a single-signer
+ // certificate is still produced.
+ if (quorumCert.isEmpty() && pqc.signingEnabled()) {
+ // D2 (2026-08-06): this is the ONE registry question in the stack with no honest height -
+ // "am I, right now, an eligible signer", asked before signing with the single private key
+ // this process holds. It gets its own name rather than a fabricated height, so that no
+ // future reader mistakes it for a verification path. See FalconSealSupport#localSigningAddress.
+ final Address self = pqc.localSigningAddress();
+ if (self != null && eligible.contains(self)) {
+ // AERE FIX-OPRIRE-CONSENS (b): height-gated like every other attachment point.
+ final Optional<FalconSeal> selfSeal =
+ pqc.sign(sealedHeader.getNumber(), Bytes32.wrap(commitHash.getBytes()));
+ selfSeal.ifPresent(quorumCert::add);
+ }
+ }
+
+ if (!quorumCert.isEmpty()) {
+ final BftExtraData hybridExtraData =
+ new BftExtraData(
+ initialExtraData.getVanityData(),
+ commitSeals,
+ initialExtraData.getVote(),
+ roundNumber,
+ initialExtraData.getValidators(),
+ quorumCert);
+ sealedHeader =
+ BlockHeaderBuilder.fromHeader(AdaptorUtil.toBesuBlockHeader(initialHeader))
+ .extraData(bftExtraDataCodec.encode(hybridExtraData))
+ .blockHeaderFunctions(BftBlockHeaderFunctions.forOnchainBlock(bftExtraDataCodec))
+ .buildBlockHeader();
+ LOG.debug(
+ "AERE PQC: attached Falcon-512 quorum certificate ({} distinct valid seal(s)) to block {}",
+ quorumCert.size(),
+ sealedHeader.getNumber());
+ }
+ } catch (final RuntimeException e) {
+ LOG.warn(
+ "AERE PQC: failed to attach Falcon quorum certificate; keeping ECDSA-only sealed block "
+ + "(block still valid and final): {}",
+ e.toString());
+ }
+
final Block sealedBesuBlock = new Block(sealedHeader, besuBlock.getBody());
return new QbftBlockAdaptor(sealedBesuBlock);
}
+
+ // D2 (2026-08-06): takes the height of the block being sealed. The seals gathered here are over
+ // THIS block's committed-seal hash, so the height is this block's own and is known at the call
+ // site. It matters at exactly one moment - a rotation height - where assembling a certificate
+ // under the head key set while every validator checks it under the scheduled one produces a block
+ // the fleet rejects, with nothing in any log naming the reason.
+ private static List<FalconSeal> verifiedDistinctSeals(
+ final FalconSealSupport pqc,
+ final long blockNumber,
+ final Hash commitHash,
+ final Collection<FalconSeal> seals,
+ final Set<Address> eligible,
+ final OptionalInt cap) {
+ final List<FalconSeal> out = new ArrayList<>();
+ final Set<Address> seen = new LinkedHashSet<>();
+ final int limit = cap.orElse(Integer.MAX_VALUE);
+ for (final FalconSeal seal : seals) {
+ // The cap is read HERE, at the top of each turn, so it counts only seals that have already
+ // survived eligibility and Falcon verification below. Placed before verification it would
+ // stop at the cap while holding seals that turn out to be bad, and a short certificate made
+ // of unchecked seals is worse than a long one. Same ordering, and same reason, as the anchor
+ // producer's own cap.
+ if (out.size() >= limit) {
+ break;
+ }
+ if (seal == null) {
+ continue;
+ }
+ // Bind each seal to its registered validator address and keep it only if that address is an
+ // eligible signer (a current validator with a registered key), de-duplicated by address.
+ // D2 (b-v2): the OWN-HEAD door. This is the block this node is sealing right now.
+ final Address signer = pqc.addressForIndexAtOwnHead(blockNumber, seal.getValidatorIndex());
+ if (signer == null || !eligible.contains(signer) || seen.contains(signer)) {
+ continue;
+ }
+ if (pqc.verifyAtOwnHead(
+ blockNumber, seal.getValidatorIndex(), commitHash.getBytes(), seal.getSignature())) {
+ seen.add(signer);
+ out.add(seal);
+ }
+ }
+ return out;
+ }
}
diff --git a/consensus/qbft/src/main/java/org/hyperledger/besu/consensus/qbft/blockcreation/QbftBlockCreatorFactory.java b/consensus/qbft/src/main/java/org/hyperledger/besu/consensus/qbft/blockcreation/QbftBlockCreatorFactory.java
index 5e6de291b..cabeba99c 100644
--- a/consensus/qbft/src/main/java/org/hyperledger/besu/consensus/qbft/blockcreation/QbftBlockCreatorFactory.java
+++ b/consensus/qbft/src/main/java/org/hyperledger/besu/consensus/qbft/blockcreation/QbftBlockCreatorFactory.java
@@ -11,6 +11,12 @@
* specific language governing permissions and limitations under the License.
*
* SPDX-License-Identifier: Apache-2.0
+ *
+ * Modifications Copyright contributors to the Aere Network.
+ *
+ * This file was modified by contributors to the Aere Network, as required by section 4(b) of the
+ * Apache License 2.0. The copyright header above is the upstream one and is left exactly as it was
+ * found, as section 4(c) requires. The change itself is in patches/0003-aere-pq-anchor.patch.
*/
package org.hyperledger.besu.consensus.qbft.blockcreation;
@@ -20,6 +26,7 @@ import org.hyperledger.besu.consensus.common.ForksSchedule;
import org.hyperledger.besu.consensus.common.bft.BftExtraData;
import org.hyperledger.besu.consensus.common.bft.BftExtraDataCodec;
import org.hyperledger.besu.consensus.common.bft.blockcreation.BftBlockCreatorFactory;
+import org.hyperledger.besu.consensus.common.bft.blockcreation.PqAnchorProducer;
import org.hyperledger.besu.datatypes.Address;
import org.hyperledger.besu.ethereum.ProtocolContext;
import org.hyperledger.besu.ethereum.core.BlockHeader;
@@ -67,14 +74,34 @@ public class QbftBlockCreatorFactory extends BftBlockCreatorFactory<QbftConfigOp
ethScheduler);
}
+ /**
+ * AERE ANCHOR V2: the QBFT proposer writes the anchor.
+ *
+ * <p>Both paths are covered on purpose. The validator-contract path builds its own extra data and
+ * does NOT go through the shared base method, so a change made only in the base class would leave
+ * that path writing the old vanity and no certificate, which post-fork means every block it
+ * proposes is rejected. This is the second of the two measured traps in the producer chain; the
+ * other is in {@code QbftBlockCreatorAdaptor.createSealedBlock}.
+ *
+ * <p>Below the activation height {@link PqAnchorProducer#apply} returns its input unchanged, so
+ * this method is byte-for-byte the old one until a height is named.
+ *
+ * @param round the round
+ * @param parentHeader the parent header
+ * @return the encoded extra data
+ * @throws org.hyperledger.besu.consensus.common.bft.PqAnchorNotReadyException when this node
+ * cannot back the block with a certificate that reaches the staged threshold; callers must
+ * catch it and simply not propose this round
+ */
@Override
public Bytes createExtraData(final int round, final BlockHeader parentHeader) {
+ final BftExtraData base;
if (forksSchedule
.getFork(parentHeader.getNumber() + 1L, parentHeader.getTimestamp())
.getValue()
.isValidatorContractMode()) {
// vote and validators will come from contract instead of block
- final BftExtraData extraData =
+ base =
new BftExtraData(
ConsensusHelpers.zeroLeftPad(
miningConfiguration.getExtraData(), BftExtraDataCodec.EXTRA_VANITY_LENGTH),
@@ -82,9 +109,11 @@ public class QbftBlockCreatorFactory extends BftBlockCreatorFactory<QbftConfigOp
Optional.empty(),
round,
Collections.emptyList());
- return bftExtraDataCodec.encode(extraData);
+ } else {
+ base = buildExtraData(round, parentHeader);
}
- return super.createExtraData(round, parentHeader);
+ return bftExtraDataCodec.encode(
+ PqAnchorProducer.apply(base, parentHeader, protocolContext));
}
}
diff --git a/consensus/qbft/src/main/java/org/hyperledger/besu/consensus/qbft/headervalidationrules/AereBaseFeeImportRule.java b/consensus/qbft/src/main/java/org/hyperledger/besu/consensus/qbft/headervalidationrules/AereBaseFeeImportRule.java
new file mode 100755
index 000000000..6741e292d
--- /dev/null
+++ b/consensus/qbft/src/main/java/org/hyperledger/besu/consensus/qbft/headervalidationrules/AereBaseFeeImportRule.java
@@ -0,0 +1,135 @@
+/*
+ * AERE D-AMONTE-02 (found 2026-07-17, built 2026-08-25): base-fee enforcement at QBFT block
+ * IMPORT, armed by height.
+ *
+ * WHY IT EXISTS. The upstream QBFT factory does not contain
+ * BaseFeeMarketBlockHeaderGasPriceValidationRule, which the clique, merge and mainnet
+ * factories in the SAME jar all name. Besu catches a wrong fee only indirectly, by
+ * re-executing the body (a different state root); an EMPTY block has no body for that defence
+ * to bite into, and 98.3% of chain 2800's blocks are empty. Measured on mixed network 91777
+ * (STARE-PRODUCATOR-2026-08-02.md, 1bis): a single validator proposing an empty header with
+ * the fee wrong by ONE WEI permanently detaches client 2 (which validates correctly, as a
+ * pure function of the parent), while the Besu quorum makes it canonical and nothing shouts.
+ * Our own 1 Gwei floor is itself unenforced at import for empty blocks.
+ *
+ * WHY BY HEIGHT, AND NEVER OVER HISTORY. Chain 2800's history CONTAINS blocks that fail this
+ * validation: for two days (2026-08-09..11) the fleet ran with the floor fork LOST and wrote
+ * fees below the floor; and inside the lost-threshold window (around 12,978,617) the fee is
+ * NOT a function of the parent but of the validator that won the round. A rule not armed by
+ * height would reject those blocks on every resync and break the chain. That is why below
+ * the arming height the rule returns true as its FIRST statement, before any computation.
+ *
+ * WHY IT DELEGATES TO THE FEE MARKET INSTEAD OF RECOMPUTING. LondonFeeMarket in this tree
+ * applies the AERE floor in computeBaseFee on ALL paths, so the upstream rule, fed with the
+ * node's fee market, validates exactly the FLOORED fee producers write. One source of truth,
+ * not two: if the floor ever changes, validation follows it by itself.
+ *
+ * CONFIG. -Daere.basefee.validate.forkBlock=<H> (env AERE_BASEFEE_VALIDATE_FORKBLOCK).
+ * Absent = DISARMED (today's behaviour, byte for byte). A broken value = loud refusal
+ * AERE-BASEFEE-VALIDATE-CONF-01 at factory construction, i.e. at node startup, never a
+ * silent disarm. There is no consensus binding on the value: the fleet coordinates on it
+ * exactly as on the anchor heights. REGISTRY ORDER: first walk the history on the archive
+ * node (~1.77M unmeasured blocks), only then choose H; activation is the founder's.
+ */
+package org.hyperledger.besu.consensus.qbft.headervalidationrules;
+
+import org.hyperledger.besu.ethereum.core.BlockHeader;
+import org.hyperledger.besu.ethereum.mainnet.DetachedBlockHeaderValidationRule;
+import org.hyperledger.besu.ethereum.mainnet.feemarket.BaseFeeMarket;
+import org.hyperledger.besu.ethereum.mainnet.headervalidationrules.BaseFeeMarketBlockHeaderGasPriceValidationRule;
+
+import java.util.Optional;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+/** Height-gated base-fee validation at QBFT import: the missing rule, armed only above H. */
+public class AereBaseFeeImportRule implements DetachedBlockHeaderValidationRule {
+
+ private static final Logger LOG = LoggerFactory.getLogger(AereBaseFeeImportRule.class);
+
+ /** The disarmed height: no block ever reaches it, upstream behaviour everywhere. */
+ public static final long DISARMED = Long.MAX_VALUE;
+
+ /** System property naming the first height at which the rule bites. Absent = disarmed. */
+ public static final String PROPERTY_FORK_BLOCK = "aere.basefee.validate.forkBlock";
+
+ /** Environment fallback for {@link #PROPERTY_FORK_BLOCK}. */
+ public static final String ENV_FORK_BLOCK = "AERE_BASEFEE_VALIDATE_FORKBLOCK";
+
+ private final long armedFromBlock;
+ private final BaseFeeMarketBlockHeaderGasPriceValidationRule delegate;
+
+ /**
+ * @param armedFromBlock first height (inclusive) at which the rule bites; {@link #DISARMED}
+ * for today's behaviour
+ * @param baseFeeMarket the fee market THIS NODE runs (carries the AERE floor fork), empty on
+ * a pre-London chain
+ * @throws IllegalStateException AERE-BASEFEE-VALIDATE-CONF-02 when armed without a fee market:
+ * an armed rule with nothing to compute against must refuse at startup, not skip silently
+ */
+ public AereBaseFeeImportRule(
+ final long armedFromBlock, final Optional<BaseFeeMarket> baseFeeMarket) {
+ this.armedFromBlock = armedFromBlock;
+ if (armedFromBlock != DISARMED && baseFeeMarket.isEmpty()) {
+ throw new IllegalStateException(
+ "AERE-BASEFEE-VALIDATE-CONF-02: " + PROPERTY_FORK_BLOCK + " is armed at "
+ + armedFromBlock + " but this chain has no base-fee market to validate against."
+ + " An armed rule must refuse at startup, never skip silently.");
+ }
+ this.delegate =
+ baseFeeMarket.map(BaseFeeMarketBlockHeaderGasPriceValidationRule::new).orElse(null);
+ }
+
+ /**
+ * The arming height the production factory wires in, read from system configuration.
+ *
+ * @return the height, or {@link #DISARMED} when the property is not set anywhere
+ * @throws IllegalStateException AERE-BASEFEE-VALIDATE-CONF-01 on a present but unparseable
+ * value; the factory runs at node startup, so the refusal lands at config time
+ */
+ public static long armedFromSystemConfig() {
+ String raw = System.getProperty(PROPERTY_FORK_BLOCK);
+ if (raw == null) {
+ raw = System.getenv(ENV_FORK_BLOCK);
+ }
+ if (raw == null) {
+ return DISARMED;
+ }
+ try {
+ final long h = Long.parseLong(raw.trim());
+ if (h < 0) {
+ throw new NumberFormatException("negative");
+ }
+ return h;
+ } catch (final NumberFormatException e) {
+ throw new IllegalStateException(
+ "AERE-BASEFEE-VALIDATE-CONF-01: " + PROPERTY_FORK_BLOCK
+ + " is set but not a non-negative block height: '" + raw
+ + "'. A mistyped value must refuse, never silently disarm.");
+ }
+ }
+
+ @Override
+ public boolean validate(final BlockHeader header, final BlockHeader parent) {
+ // History stays untouched: below H this rule does not exist, first statement, no compute.
+ if (header.getNumber() < armedFromBlock) {
+ return true;
+ }
+ final boolean ok = delegate.validate(header, parent);
+ if (!ok) {
+ LOG.info(
+ "AERE BASEFEE-VALIDATE: header {} carries a base fee the fee market of this node"
+ + " (floor included) does not reproduce from its parent - rejected at import",
+ header.getNumber());
+ }
+ return ok;
+ }
+
+ @Override
+ public boolean includeInLightValidation() {
+ // Same stance as the anchor digest rule: cheap, stateless, and exactly the check a
+ // header-syncing node can and should make.
+ return true;
+ }
+}
diff --git a/consensus/qbft/src/main/java/org/hyperledger/besu/consensus/qbft/headervalidationrules/FalconSealValidationRule.java b/consensus/qbft/src/main/java/org/hyperledger/besu/consensus/qbft/headervalidationrules/FalconSealValidationRule.java
new file mode 100755
index 000000000..1b8bed196
--- /dev/null
+++ b/consensus/qbft/src/main/java/org/hyperledger/besu/consensus/qbft/headervalidationrules/FalconSealValidationRule.java
@@ -0,0 +1,513 @@
+/*
+ * Copyright contributors to Besu / AERE Network.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.qbft.headervalidationrules;
+
+import static org.hyperledger.besu.consensus.common.bft.BftHelpers.calculateRequiredValidatorQuorum;
+
+import org.hyperledger.besu.consensus.common.bft.BftBlockHashing;
+import org.hyperledger.besu.consensus.common.bft.BftContext;
+import org.hyperledger.besu.consensus.common.bft.BftExtraData;
+import org.hyperledger.besu.consensus.common.bft.FalconSeal;
+import org.hyperledger.besu.consensus.common.bft.FalconSealSupport;
+import org.hyperledger.besu.consensus.qbft.QbftExtraDataCodec;
+import org.hyperledger.besu.datatypes.Address;
+import org.hyperledger.besu.datatypes.Hash;
+import org.hyperledger.besu.ethereum.ProtocolContext;
+import org.hyperledger.besu.ethereum.core.BlockHeader;
+import org.hyperledger.besu.ethereum.mainnet.AttachedBlockHeaderValidationRule;
+import org.hyperledger.besu.evm.account.Account;
+import org.hyperledger.besu.evm.worldstate.WorldState;
+
+import java.util.Collection;
+import java.util.HashSet;
+import java.util.LinkedHashSet;
+import java.util.Optional;
+import java.util.Set;
+
+import org.apache.tuweni.units.bigints.UInt256;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+/**
+ * Verifies the PARALLEL Falcon-512 post-quantum QUORUM CERTIFICATE embedded in a QBFT block header.
+ *
+ * <p><b>RETIRED ON CHAIN 2800, AND EVERYTHING BELOW DESCRIBES A RULE THAT NO LONGER APPLIES THERE
+ * (finding D-235, corrected 2026-08-19).</b> This rule stands down at
+ * {@code PqAnchorConfig.legacyFalconRuleRetirementBlock()}, which is the anchor block itself
+ * ({@code everActive() ? anchorBlock : NEVER}). On chain 2800 the anchor block is 13,014,000 and
+ * {@code aere.falcon.forkBlock} is 14,050,000 - the arming height is ABOVE the retirement height,
+ * so this rule has never once been in force there, and arming that property changes nothing. What
+ * actually carries the post-quantum verdict on 2800 is the pair of V2 anchor rules: at every 32nd
+ * height, a certificate of at least K valid Falcon-512 seals under the block hash.
+ *
+ * <p>The text below is kept because the rule is real code and can be armed on a chain that never
+ * reached an anchor block; it is not kept as a description of 2800. Until 2026-08-19 the site, the
+ * whitepaper and seven press releases said a per-block 2f+1 Falcon quorum had been blocking since
+ * 14,050,000. That claim was withdrawn in public the same day, and the withdrawal is the reason
+ * this paragraph exists: an auditor reading the code must not find here the claim we retracted.
+ *
+ * <p>A Falcon quorum certificate is the set of Falcon-512 seals gossiped by validators on their QBFT
+ * commit messages (each a signature over the same commit hash the ECDSA committed seal signs),
+ * aggregated by the block assembler into the header's parallel Falcon-seal list.
+ *
+ * <p><b>AERE audit fix (AUD-CONSENSUS-1 / AUD-CONSENSUS-2, 2026-07-18).</b> Both the Falcon quorum
+ * threshold AND the counted-seal set are now bound to ONE well-defined set:
+ *
+ * <pre>
+ * eligibleSigners = currentValidators (getValidatorsAfterBlock(parent))
+ * INTERSECT registeredValidatorAddresses (address-bound registry)
+ * quorum = ceil(2 * |eligibleSigners| / 3)
+ * valid = # distinct eligible validator addresses whose Falcon seal verifies
+ * accept (blocking) iff eligibleSigners is well-formed AND valid >= quorum
+ * </pre>
+ *
+ * <p>This closes the previous decoupling, where the quorum tracked the DYNAMIC validator-set size N
+ * (so a routine add-validator vote raised the quorum above the FIXED registry key count and halted
+ * the chain), while seals were counted by REGISTRY membership (so a removed validator's key kept
+ * counting). Binding both sides to {@code currentValidators INTERSECT registry} makes a
+ * validator-set change LIVE-SAFE (an added-but-unkeyed validator neither raises the Falcon quorum
+ * nor contributes to it, so the chain does not halt) and REMOVAL-SAFE (an ex-validator's key is not
+ * in the current validator set, so it is excluded from both eligibility and the count).
+ *
+ * <p><b>ECDSA stays decisive.</b> This rule runs AFTER {@code BftCommitSealsValidationRule}, which
+ * independently requires an ECDSA committed-seal quorum of {@code ceil(2N/3)} over the FULL current
+ * validator set N. A block is valid iff BOTH quorums pass, so the hybrid chain is a strict subset of
+ * the ECDSA-only chain and can never be weaker than ECDSA-only. The Falcon eligible-quorum over a
+ * subset of validators is the decisive post-quantum seal in the regime where ECDSA is forgeable; the
+ * arming invariant below keeps that subset equal to the full validator set at arm time.
+ *
+ * <p>Behaviour is fork-gated by {@code aere.falcon.forkBlock} / {@code AERE_FALCON_FORKBLOCK}:
+ *
+ * <ul>
+ * <li>Before the fork block (or when unconfigured, i.e. fork = Long.MAX_VALUE): the rule is
+ * LOG-ONLY and always returns {@code true}. The decisive seal remains the ECDSA committed-seal
+ * quorum, so a Falcon fault can never halt or split the chain. This preserves the additive,
+ * non-blocking baseline exactly.
+ * <li>At and after the fork block: the rule is BLOCKING. A block is REJECTED unless it carries a
+ * Falcon quorum certificate of at least {@code ceil(2 * |eligibleSigners| / 3)} distinct valid
+ * eligible-signer Falcon seals over the correct commit hash. A registry that is not
+ * address-bound, or an empty eligible set, is a fail-closed REJECT (surfaced at the fork
+ * boundary, i.e. arm time), NEVER an implicit accept.
+ * </ul>
+ *
+ * <p>ARMING INVARIANT (AUD-CONSENSUS-1): blocking should be armed only when the registry COVERS the
+ * validator set (every current validator has a Falcon key), so that {@code eligibleSigners ==
+ * currentValidators} and the Falcon quorum equals the ECDSA quorum with full fault margin. When
+ * coverage is incomplete the rule stays LIVE on the intersection (it does not halt) but logs a LOUD
+ * warning that the margin is reduced and a registry re-anchor is required. This is the "either the
+ * intersection keeps it live, or it fail-closes at arm time, never as a silent halt" contract.
+ *
+ * <p>STAGE-2 LATE-ANCHOR activation: when the node is configured with a late-anchor manifest
+ * ({@code aere.falcon.manifest} + {@code aere.falcon.anchor.address}) on a chain that launched
+ * WITHOUT a genesis manifest, this rule additionally polls the parent block's world state for the
+ * anchor contract. Once the contract exists and its storage slot 0 carries a hash equal to
+ * keccak256 of the local manifest, the registry activates ({@link
+ * FalconSealSupport#activateLateAnchor}); any mismatch is terminal and fail-closed. This is the
+ * no-re-genesis activation path for an already-live chain.
+ */
+public class FalconSealValidationRule implements AttachedBlockHeaderValidationRule {
+
+ private static final Logger LOG = LoggerFactory.getLogger(FalconSealValidationRule.class);
+
+ /**
+ * AERE 2026-08-07: how often the LOG-ONLY summary repeats when NOTHING has changed.
+ *
+ * <p>WHY THIS EXISTS, measured on a live node. The summary was written at INFO on EVERY imported
+ * block. On chain 2800 at ~523 ms per block that is <b>2295 lines in twenty minutes, about 165.000
+ * a day per node</b>, and every one of them said the same thing: {@code 0 of 0 seals,
+ * |eligible|=0, no-eligible-signers}. A line that cannot change carries no information, and seven
+ * validators had just come out of a disk emergency.
+ *
+ * <p>WHAT IS KEPT. Every CHANGE of outcome still logs at INFO immediately, so an operator sees the
+ * transition into and out of quorum on the block it happens. Unchanged state logs once per
+ * heartbeat, so the line never disappears entirely from a quiet log. Everything else drops to
+ * DEBUG, where it is still available on demand.
+ *
+ * <p>10.000 blocks is about 87 minutes at 523 ms.
+ */
+ static final long LOG_HEARTBEAT_BLOCKS = 10_000L;
+
+ /**
+ * Last outcome logged at INFO, and the height it was logged at. Written from several import
+ * threads, so both are volatile and are only ever used to decide a LOG LEVEL. Nothing here can
+ * change what this rule returns: the throttle is applied strictly after the verdict is computed.
+ */
+ private volatile String lastLoggedOutcome = null;
+
+ private volatile long lastLoggedBlock = Long.MIN_VALUE;
+
+ private final QbftExtraDataCodec extraDataCodec = new QbftExtraDataCodec();
+
+ /**
+ * AERE ANCORA-V2 (2026-08-01): the height at and after which this rule RETIRES.
+ *
+ * <p>The V2 anchor scheme replaces this rule; it does not promote it. The reasons are measured and
+ * are properties of this file: {@code includeInLightValidation()} returns FALSE, so it never runs
+ * on a node that is fast-syncing headers; it returns {@code true} on every path including the
+ * exception path, so it has never been able to reject anything below the fork height; and its
+ * late-anchor lookup reads historical world state over a window of roughly 510 blocks, which does
+ * not exist on a syncing node. Retiring it at exactly the height the two anchor rules take over
+ * means exactly one regime is in force at any height, with no overlap and no gap.
+ *
+ * <p>{@link Long#MAX_VALUE} means "never retire", which is what the no-argument constructor gives,
+ * so every existing call site and test keeps today's behaviour unchanged.
+ */
+ private final long retirementBlock;
+
+ /** Default constructor: the rule never retires, i.e. exactly today's behaviour. */
+ public FalconSealValidationRule() {
+ this(Long.MAX_VALUE);
+ }
+
+ /**
+ * Decides whether the LOG-ONLY summary goes out at INFO, and records it if so.
+ *
+ * <p>Extracted so the throttle can be PROVEN without a log appender: a test that counts real log
+ * lines proves the plumbing, but a test on this method proves the rule, and the rule is what can
+ * be wrong. The end-to-end count is measured separately, on a live node.
+ *
+ * <p>Two reasons to log at INFO, and no others:
+ *
+ * <ul>
+ * <li>the outcome CHANGED since the last INFO, so an operator sees every transition on the block
+ * it happens
+ * <li>{@link #LOG_HEARTBEAT_BLOCKS} have passed, so the line never vanishes from a quiet log
+ * </ul>
+ *
+ * <p>This can only pick a log level. It is called strictly after the verdict is computed and its
+ * result is never read by anything that decides validity.
+ *
+ * @param rezumat a stable key for the outcome; equal keys mean nothing an operator cares about has
+ * changed
+ * @param blockNumber the height being validated
+ * @return true to log at INFO, false to drop to DEBUG
+ */
+ boolean shouldLogAtInfo(final String rezumat, final long blockNumber) {
+ final boolean hasChanged = !rezumat.equals(lastLoggedOutcome);
+ // Long.MIN_VALUE as "never logged" cannot be subtracted from without overflowing, and an
+ // overflow here would silently invert the comparison: the first block would take the DEBUG
+ // branch and the very first line, the one that tells an operator the rule is alive at all,
+ // would never appear.
+ final boolean bataieDeInima =
+ lastLoggedBlock == Long.MIN_VALUE || blockNumber - lastLoggedBlock >= LOG_HEARTBEAT_BLOCKS;
+ if (hasChanged || bataieDeInima) {
+ lastLoggedOutcome = rezumat;
+ lastLoggedBlock = blockNumber;
+ return true;
+ }
+ return false;
+ }
+
+ /**
+ * Constructor with an explicit retirement height.
+ *
+ * @param retirementBlock the height at and after which this rule stands down in favour of the V2
+ * anchor rules; {@link Long#MAX_VALUE} to never retire
+ */
+ public FalconSealValidationRule(final long retirementBlock) {
+ this.retirementBlock = retirementBlock;
+ }
+
+ @Override
+ public boolean validate(
+ final BlockHeader header, final BlockHeader parent, final ProtocolContext protocolContext) {
+ // AERE ANCORA-V2: RETIREMENT GATE FIRST, before any singleton touch, any world-state lookup and
+ // any decode. From H this rule contributes nothing, and the two anchor rules carry the whole
+ // post-quantum verdict. Below H this branch is not taken and behaviour is bit-for-bit as before.
+ if (header.getNumber() >= retirementBlock) {
+ return true;
+ }
+
+ final FalconSealSupport pqc = FalconSealSupport.instance();
+
+ // STAGE-2: opportunistic late-anchor activation from the parent block's world state. Never
+ // throws; pre-activation this is a cheap account lookup per imported block until the anchor
+ // contract appears on-chain.
+ if (pqc.lateAnchorPending()) {
+ tryActivateLateAnchor(pqc, parent, protocolContext);
+ }
+
+ // AERE FIX-OPRIRE-CONSENS (c): a TERMINALLY FAILED late anchor (an on-chain anchor was observed
+ // and did NOT match the local manifest) is a tamper signal, not a "not yet" signal. The old code
+ // could not tell the two apart: both left genesisAnchored()==false and lateAnchored()==false, so
+ // BLOCKING was simply never armed and the whole PQC layer degraded to LOG-ONLY - it failed OPEN
+ // on exactly the input an attacker controls. FAILED now fails CLOSED at and after the fork
+ // block, while PENDING keeps the deliberate log-only behaviour that lets a legitimate anchor
+ // transaction still land (see AUD-CONSENSUS-4 below).
+ final long forkBlock = pqc.forkBlock();
+ if (header.getNumber() >= forkBlock && pqc.lateAnchorFailed()) {
+ LOG.error(
+ "AERE PQC (BLOCKING, FAIL-CLOSED): block {} REJECTED - the late-anchor manifest is "
+ + "TERMINALLY FAILED. keccak256(local manifest) did not match the hash in the "
+ + "on-chain anchor contract {} slot 0, so the Falcon registry is permanently empty. "
+ + "This is a tampered or mismatched anchor, NOT an anchor that has yet to land, and "
+ + "it must not silently degrade PQC enforcement to log-only. Re-anchor with the "
+ + "correct manifest, or restart the node with the manifest that matches the chain.",
+ header.getNumber(),
+ pqc.anchorAddress());
+ return false;
+ }
+ // AUD-CONSENSUS-4: entering BLOCKING mode requires BOTH the fork height AND an ACTIVE anchored
+ // registry (genesis-anchored, or a late anchor already activated by tryActivateLateAnchor
+ // above). If forkBlock is armed at or before the late-anchor observation height, the registry is
+ // not yet active when the fork block is validated; blocking there rejects every block (empty
+ // registry => no eligible seal) and permanently HALTS the chain before the anchor-deploy
+ // transaction can settle. Staying LOG-ONLY until the registry is anchored lets the chain reach
+ // the anchor-deploy height, activate just-in-time at validate(D+1), and only THEN enforce the
+ // Falcon quorum. This never loses PQC enforcement: with no active registry there are no keys to
+ // verify against, so blocking would provide zero safety, only a halt.
+ final boolean forkReached = header.getNumber() >= forkBlock;
+ final boolean registryActive = pqc.genesisAnchored() || pqc.lateAnchored();
+ final boolean blocking = forkReached && registryActive;
+ // AERE D-079: leave a MARK, not only a line. The log-only answer below is the right answer for a
+ // header rule, and it is also how this condition used to vanish: the node was configured to
+ // enforce a post-quantum quorum, enforced nothing, and said so once per block into a file. The
+ // counter is readable from a test and from a JMX/diagnostic path; the WARN is emitted only on
+ // the first occurrence, because one line per block at a sub-second block period is itself a
+ // hazard on this fleet.
+ if (forkReached
+ && !registryActive
+ && pqc.noteBlockingArmedWithoutActiveRegistry(header.getNumber())) {
+ LOG.warn(
+ "AERE PQC: block {} is at/after the Falcon fork block ({}) but the anchored registry is "
+ + "NOT yet active (genesisAnchored={}, lateAnchored={}, lateAnchorPending={}). Staying "
+ + "LOG-ONLY so the chain can reach the anchor height and activate; the Falcon quorum "
+ + "becomes BLOCKING only once the registry is anchored. If this persists, the "
+ + "late-anchor contract has not settled - deploy/observe it before relying on PQC "
+ + "enforcement.",
+ header.getNumber(),
+ forkBlock,
+ pqc.genesisAnchored(),
+ pqc.lateAnchored(),
+ pqc.lateAnchorPending());
+ }
+
+ try {
+ final BftExtraData extraData = extraDataCodec.decodeRaw(header.getExtraData());
+ final Collection<FalconSeal> falconSeals = extraData.getFalconSeals();
+
+ final BftContext bftContext = protocolContext.getConsensusContext(BftContext.class);
+ final Collection<Address> validators =
+ bftContext.getValidatorProvider().getValidatorsAfterBlock(parent);
+
+ // AERE FIX-OPRIRE-CONSENS (b): feed the authoritative validator set to the seal-ATTACHMENT
+ // gate. This is the only place in the QBFT stack that already holds a validator set bound to a
+ // height, and it runs on every imported block, i.e. always before the next round's commit.
+ // The gate refuses to attach until the anchored registry covers ALL of these addresses.
+ pqc.observeValidators(header.getNumber(), validators);
+
+ // AERE audit fix (AUD-CONSENSUS-1 / -2): the eligible-signer set is the intersection of the
+ // CURRENT validator set with the address-bound signer registry. BOTH the quorum and the
+ // counted-seal set are derived from this ONE set, so neither can drift from the other.
+ final Set<Address> registered = pqc.registeredValidatorAddresses();
+ final Set<Address> eligible = new LinkedHashSet<>();
+ for (final Address v : validators) {
+ if (registered.contains(v)) {
+ eligible.add(v);
+ }
+ }
+ final int quorum = calculateRequiredValidatorQuorum(eligible.size());
+
+ final Hash commitHash =
+ new BftBlockHashing(extraDataCodec).calculateDataHashForCommittedSeal(header);
+
+ // Count DISTINCT ELIGIBLE validator addresses whose Falcon seal verifies over the commit hash.
+ // A seal counts only if its registry-bound address is an eligible signer (i.e. a current
+ // validator with a registered key); seals from registered-but-removed validators, or from
+ // unregistered indices, are excluded.
+ // D2 (2026-08-06): resolve the key set AT THE HEIGHT OF THE HEADER CARRYING THE SEAL, not at
+ // this node's head. These seals are over THIS header's committed-seal hash, so the height is
+ // this header's own - unlike R2, whose certificate commits to the PARENT. The adversarial
+ // review measured this rule asking a height-less registry; below the arming height the
+ // resolver still answers from the head registry, so the 11.8 million blocks already on chain
+ // 2800 are checked exactly as before, but the rule can no longer be the reason a rotation
+ // makes history unverifiable.
+ final Set<Address> counted = new HashSet<>();
+ for (final FalconSeal seal : falconSeals) {
+ // D2 (b-v2): the HISTORY door. R1's seals are over THIS header's committed-seal hash,
+ // so the height is the header's own; the header still came from outside.
+ final Address signer =
+ pqc.addressForIndexAtHistoric(header.getNumber(), seal.getValidatorIndex());
+ if (signer == null || !eligible.contains(signer) || counted.contains(signer)) {
+ continue;
+ }
+ if (pqc.verifyAtHistoric(
+ header.getNumber(),
+ seal.getValidatorIndex(),
+ commitHash.getBytes(),
+ seal.getSignature())) {
+ counted.add(signer);
+ } else if (blocking) {
+ LOG.warn(
+ "AERE PQC (BLOCKING): block {} carried a Falcon seal from validator index {} "
+ + "(address {}) that did NOT verify. It does not count toward the quorum.",
+ header.getNumber(),
+ seal.getValidatorIndex(),
+ signer);
+ }
+ }
+ final int valid = counted.size();
+
+ if (blocking) {
+ // Fail-closed (arm-time surfaced): a registry that is not address-bound, or a validator set
+ // that shares no keyed signer with the registry, cannot carry a genuine eligible Falcon
+ // quorum. Reject rather than let ceil(2*0/3)=0 be trivially met (that would be fail-OPEN).
+ if (!pqc.addressBound() || eligible.isEmpty()) {
+ LOG.error(
+ "AERE PQC (BLOCKING): block {} REJECTED (fail-closed): no eligible Falcon signer set "
+ + "(addressBound={}, |eligible|={}, N={}, registrySize={}). Blocking requires an "
+ + "ADDRESS-BOUND registry that covers current validators; re-anchor before arming.",
+ header.getNumber(),
+ pqc.addressBound(),
+ eligible.size(),
+ validators.size(),
+ pqc.registrySize());
+ return false;
+ }
+
+ // ARMING INVARIANT (loud, non-halting): if the registry does not cover the full validator
+ // set, the chain stays LIVE on the intersection but the two-fault margin is reduced. This is
+ // the signal that a validator was added without re-anchoring; it is never a silent halt.
+ if (!pqc.registryCoversValidators(validators)) {
+ LOG.warn(
+ "AERE PQC (BLOCKING): block {} - registry does NOT cover the validator set "
+ + "(|eligible|={} < N={}). Running on the eligible intersection (LIVE, quorum={}), "
+ + "but two-fault liveness margin is reduced. A validator was added without an "
+ + "atomic registry re-anchor: RE-ANCHOR the Falcon manifest for the full validator "
+ + "set (see PQ-CONSENSUS-LIVE-READINESS validator-expansion procedure).",
+ header.getNumber(),
+ eligible.size(),
+ validators.size(),
+ quorum);
+ }
+
+ if (valid >= quorum) {
+ LOG.info(
+ "AERE PQC (BLOCKING): block {} Falcon quorum certificate OK: {} distinct valid "
+ + "eligible seal(s) >= quorum {} of |eligible|={} (N={}). Post-quantum seal is "
+ + "consensus-enforced alongside ECDSA.",
+ header.getNumber(),
+ valid,
+ quorum,
+ eligible.size(),
+ validators.size());
+ return true;
+ }
+ LOG.warn(
+ "AERE PQC (BLOCKING): block {} REJECTED: only {} distinct valid eligible Falcon seal(s) "
+ + "< quorum {} of |eligible|={} (N={}). A post-fork block MUST carry a Falcon quorum "
+ + "certificate over the eligible-signer set.",
+ header.getNumber(),
+ valid,
+ quorum,
+ eligible.size(),
+ validators.size());
+ return false;
+ }
+
+ // Pre-fork: log-only, never blocks.
+ final String state =
+ eligible.isEmpty()
+ ? "no-eligible-signers"
+ : (valid >= quorum ? "PQC-QUORUM-MET" : "PQC-quorum-not-yet");
+ // The verdict is already decided above. Everything below only picks a LOG LEVEL.
+ final String rezumat =
+ state + "|" + valid + "|" + falconSeals.size() + "|" + eligible.size() + "|" + validators.size();
+ final boolean laInfo = shouldLogAtInfo(rezumat, header.getNumber());
+ final String message =
+ "AERE PQC (LOG-ONLY): block {} -> {} of {} Falcon seal(s) verified over |eligible|={} "
+ + "(N={}); 2/3 eligible quorum would be {} [{}]. This check never blocks pre-fork; "
+ + "ECDSA committed seals remain decisive.";
+ if (laInfo) {
+ lastLoggedOutcome = rezumat;
+ lastLoggedBlock = header.getNumber();
+ LOG.info(
+ message,
+ header.getNumber(),
+ valid,
+ falconSeals.size(),
+ eligible.size(),
+ validators.size(),
+ quorum,
+ state);
+ } else {
+ LOG.debug(
+ message,
+ header.getNumber(),
+ valid,
+ falconSeals.size(),
+ eligible.size(),
+ validators.size(),
+ quorum,
+ state);
+ }
+ return true;
+ } catch (final Exception e) {
+ if (blocking) {
+ LOG.warn(
+ "AERE PQC (BLOCKING): block {} REJECTED due to a Falcon quorum check error: {}",
+ header.getNumber(),
+ e.toString());
+ return false;
+ }
+ // Pre-fork: NEVER block on a Falcon fault. Log and accept; ECDSA remains decisive.
+ LOG.debug("AERE PQC (LOG-ONLY): skipped Falcon check for a block: {}", e.toString());
+ return true;
+ }
+ }
+
+ /**
+ * STAGE-2: look up the anchor contract in the parent block's world state; if its storage slot 0
+ * is non-zero, attempt registry activation against that hash. Defensive: never throws, never
+ * blocks; until the contract exists this is a single account lookup per imported block.
+ */
+ private void tryActivateLateAnchor(
+ final FalconSealSupport pqc, final BlockHeader parent, final ProtocolContext protocolContext) {
+ try {
+ final Optional<WorldState> ws =
+ protocolContext.getWorldStateArchive().get(parent.getStateRoot(), parent.getHash());
+ if (ws.isEmpty()) {
+ return;
+ }
+ final Account account = ws.get().get(Address.fromHexString(pqc.anchorAddress()));
+ if (account == null) {
+ return;
+ }
+ final UInt256 slot0 = account.getStorageValue(UInt256.ZERO);
+ if (slot0 == null || slot0.isZero()) {
+ return;
+ }
+ pqc.activateLateAnchor(slot0.toBytes().toUnprefixedHexString());
+ } catch (final Exception e) {
+ LOG.debug(
+ "AERE PQC: late-anchor lookup skipped at parent {}: {}",
+ parent.getNumber(),
+ e.toString());
+ }
+ }
+
+ @Override
+ public boolean includeInLightValidation() {
+ return false;
+ }
+
+ @Override
+ public String toString() {
+ return "FalconSealValidation(fork-gated blocking, eligible-signer intersection, late-anchor "
+ + "capable, retiresAt="
+ + (retirementBlock == Long.MAX_VALUE ? "NEVER" : retirementBlock)
+ + ")";
+ }
+}
diff --git a/consensus/qbft/src/main/java/org/hyperledger/besu/consensus/qbft/headervalidationrules/PqAnchorDigestAttachedRule.java b/consensus/qbft/src/main/java/org/hyperledger/besu/consensus/qbft/headervalidationrules/PqAnchorDigestAttachedRule.java
new file mode 100755
index 000000000..896f0f477
--- /dev/null
+++ b/consensus/qbft/src/main/java/org/hyperledger/besu/consensus/qbft/headervalidationrules/PqAnchorDigestAttachedRule.java
@@ -0,0 +1,115 @@
+/*
+ * Copyright contributors to Besu / AERE Network.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.qbft.headervalidationrules;
+
+import org.hyperledger.besu.consensus.common.bft.PqAnchorConfig;
+import org.hyperledger.besu.ethereum.ProtocolContext;
+import org.hyperledger.besu.ethereum.core.BlockHeader;
+import org.hyperledger.besu.ethereum.mainnet.AttachedBlockHeaderValidationRule;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+/**
+ * R1A: the anchor digest rule again, on the ATTACHED side of the validator.
+ *
+ * <p><b>Why a second copy of a rule that already exists.</b> {@link PqAnchorDigestRule} is DETACHED.
+ * Besu decides which rules run from the {@code HeaderValidationMode}, and the two facts that matter
+ * were measured, not assumed:
+ *
+ * <ul>
+ * <li>{@code HeaderValidationMode.SKIP_DETACHED} keeps exactly the rules for which {@code
+ * isDetachedSupported()} is false. That is the mode {@code FullImportBlockStep} passes to
+ * {@code BlockImporter.importBlock} for every block acquired by full sync. So a detached rule
+ * does NOT run at import.
+ * <li>{@code DETACHED_ONLY}, the mode under which a detached rule does run during download, is
+ * applied by {@code DownloadHeaderSequenceTask} and therefore only on ranges that {@code
+ * SyncTargetRange.hasEnd()} reports as closed. The open-ended range at the tip of a recovery
+ * took the other branch of {@code DownloadHeadersStep} and was validated by nothing.
+ * </ul>
+ *
+ * <p>Together those two facts left a hole of the last {@code downloader-header-request-size} minus
+ * one blocks, 199 by default, of every catch-up: on those the certificate binding was checked by no
+ * rule at all. A node that had been down for under about 103 seconds recovered its entire gap
+ * through that window. This rule closes it from the other side: since it is ATTACHED it survives
+ * {@code SKIP_DETACHED}, so the binding is now enforced on every block that enters the database, by
+ * whichever path it arrived.
+ *
+ * <p><b>It is the same verdict, not a second opinion.</b> The check is delegated to the one {@link
+ * PqAnchorDigestRule} instance rather than reimplemented, so there is exactly one definition of the
+ * anchor digest and no way for the two paths to drift apart. The delegate ignores its {@code parent}
+ * argument entirely - the digest is computed from {@code header.getParentHash()}, {@code
+ * header.getNumber() - 1}, the configured chain id and element 6 of the header's own extraData - so
+ * running it from an attached position is not merely permissible, it is the same pure function of
+ * the same header.
+ *
+ * <p><b>Deliberately NOT in light validation.</b> {@link PqAnchorDigestRule} already covers every
+ * light mode. Returning false here keeps this rule out of proposal-time validation and confines it
+ * to {@code FULL} and {@code SKIP_DETACHED}, which is the import path. That is the smallest change
+ * that closes the hole, and it means the cost added to a path that was already paying for the check
+ * is nil.
+ *
+ * <p><b>Inactive below H.</b> The delegate's height gate is its first statement, before any decode,
+ * so below the activation height this rule is one virtual call and a comparison. A binary carrying
+ * it behaves exactly as today on the whole existing chain.
+ */
+public class PqAnchorDigestAttachedRule implements AttachedBlockHeaderValidationRule {
+
+ private static final Logger LOG = LoggerFactory.getLogger(PqAnchorDigestAttachedRule.class);
+
+ private final PqAnchorConfig config;
+ private final PqAnchorDigestRule delegate;
+
+ /**
+ * Instantiates the attached half of the anchor digest rule.
+ *
+ * @param config the height-indexed activation configuration
+ */
+ public PqAnchorDigestAttachedRule(final PqAnchorConfig config) {
+ this.config = config;
+ this.delegate = new PqAnchorDigestRule(config);
+ }
+
+ @Override
+ public boolean validate(
+ final BlockHeader header, final BlockHeader parent, final ProtocolContext protocolContext) {
+ final boolean ok = delegate.validate(header, parent);
+ if (!ok) {
+ // The delegate has already logged WHY. This line exists so that the path can be told apart in
+ // a log: a rejection carrying R1A was caught while the block was being imported, which is the
+ // window that used to be open, whereas R1 alone means it was caught while headers were being
+ // downloaded.
+ LOG.warn(
+ "AERE PQ ANCHOR (R1A): block {} REJECTED on the ATTACHED path. This is the import-time "
+ + "copy of the digest binding; it is what catches a stripped or swapped certificate "
+ + "on the open-ended range at the tip of a sync, which detached validation never "
+ + "reaches.",
+ header.getNumber());
+ }
+ return ok;
+ }
+
+ @Override
+ public boolean includeInLightValidation() {
+ return false;
+ }
+
+ @Override
+ public String toString() {
+ return "PqAnchorDigestAttached(attached, not-light, "
+ + (config.everActive() ? "H=" + config.anchorBlock() : "INACTIVE")
+ + ")";
+ }
+}
diff --git a/consensus/qbft/src/main/java/org/hyperledger/besu/consensus/qbft/headervalidationrules/PqAnchorDigestRule.java b/consensus/qbft/src/main/java/org/hyperledger/besu/consensus/qbft/headervalidationrules/PqAnchorDigestRule.java
new file mode 100755
index 000000000..3b80c4302
--- /dev/null
+++ b/consensus/qbft/src/main/java/org/hyperledger/besu/consensus/qbft/headervalidationrules/PqAnchorDigestRule.java
@@ -0,0 +1,310 @@
+/*
+ * Copyright contributors to Besu / AERE Network.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.qbft.headervalidationrules;
+
+import org.hyperledger.besu.consensus.common.bft.BftExtraData;
+import org.hyperledger.besu.consensus.common.bft.BftExtraDataCodec;
+import org.hyperledger.besu.consensus.common.bft.FalconSeal;
+import org.hyperledger.besu.consensus.common.bft.PqAnchor;
+import org.hyperledger.besu.consensus.common.bft.PqAnchorConfig;
+import org.hyperledger.besu.consensus.common.bft.PqAnchorLapse;
+import org.hyperledger.besu.consensus.common.bft.PqAnchorV2;
+import org.hyperledger.besu.consensus.common.bft.SchemeSeal;
+import org.hyperledger.besu.consensus.qbft.QbftExtraDataCodec;
+import org.hyperledger.besu.ethereum.core.BlockHeader;
+import org.hyperledger.besu.ethereum.mainnet.DetachedBlockHeaderValidationRule;
+
+import java.util.List;
+
+import org.apache.tuweni.bytes.Bytes;
+import org.apache.tuweni.bytes.Bytes32;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+/**
+ * R1: the anchor DIGEST rule. DETACHED, and deliberately part of LIGHT validation.
+ *
+ * <p>This rule is the whole point of the V2 scheme. It is what makes the sentence "the post-quantum
+ * signature protects the block" true rather than decorative: the block's own vanityData, which IS in
+ * the block-hash pre-image, carries the digest of the certificate the block carries for its parent.
+ * Strip the certificate, swap it for a different but equally valid one, or reorder it, and the digest
+ * no longer matches and the header is refused.
+ *
+ * <p><b>Pure function of the header.</b> It reads {@code header.getParentHash()}, {@code
+ * header.getNumber() - 1}, the configured chain id, and element 6 of the header's OWN extraData. No
+ * state, no registry, no loaded parent, no Falcon. One keccak. That is why it is cheap enough to be
+ * declared part of light validation, and it is so declared.
+ *
+ * <p><b>WHERE IT ACTUALLY RUNS. MEASURED 2026-08-02, and this paragraph CORRECTS an earlier claim in
+ * this same file.</b> The earlier text read "a node that fast-syncs headers still catches a stripped
+ * or swapped certificate". That sentence is false in every configuration this binary can reach, and
+ * it was re-measured against the compiled jars of this tree:
+ *
+ * <ul>
+ * <li>{@code SyncMode} in this Besu has exactly TWO values, {@code FULL} and {@code SNAP}. There is
+ * no fast sync here to speak of. [MEASURED: enumerated from the compiled {@code SyncMode}.]
+ * <li>With the anchor armed, {@code PqAnchorSyncModeGuard} REFUSES TO START any node whose mode is
+ * not {@code FULL}. {@code SNAP}, null, blank and unrecognised all abort. Refusing to start is
+ * not catching anything. [MEASURED: 7 of 7 assertions against the compiled guard, and on a
+ * real node in {@code dovezi-sincronizare-2026-08-02/evidence/SNAP-AFTER-armed.txt}.]
+ * <li>With the anchor NOT armed, or disarmed by the emergency option, every mode starts again and
+ * this rule is inert by its own height gate. [MEASURED: both negative controls of the same
+ * probe, which is what shows the probe is measuring the anchor and not the mode string.]
+ * </ul>
+ *
+ * <p>So do not read the light-validation flag on this rule as a statement about a syncing node. What
+ * makes this rule reach the history a node ACCEPTS is two other things, in two other files: {@code
+ * DownloadHeadersStep} now applying the same validation policy to OPEN-ENDED ranges that it already
+ * applied to closed ones, and {@link PqAnchorDigestAttachedRule}, which carries the identical verdict
+ * on the ATTACHED side so that it survives {@code SKIP_DETACHED} at import. Before those two existed
+ * an honest node with its data directory deleted imported stripped-certificate headers in silence and
+ * reached head 350 with ZERO occurrences of this rule. [MEASURED:
+ * {@code dovezi-sincronizare-2026-08-02/evidence/OBS-BEFORE.txt}; and the negative control
+ * {@code OBS-CONTROL-STUBBED.txt} reproduces exactly that silence once the two guards are stubbed.]
+ *
+ * <p><b>includeInLightValidation, measured.</b> Both {@code DetachedBlockHeaderValidationRule} and
+ * {@code AttachedBlockHeaderValidationRule} declare {@code includeInLightValidation()} with a DEFAULT
+ * of {@code true}. {@code BlockHeaderValidator.Builder.addRule(DetachedBlockHeaderValidationRule)}
+ * snapshots that value at build time into the wrapping {@code Rule}, and the modes {@code
+ * LIGHT_DETACHED_ONLY}, {@code LIGHT} and {@code DETACHED_ONLY} all admit a detached rule whose flag
+ * is true. This rule overrides the method anyway, explicitly returning true, so the property is
+ * asserted by this file rather than inherited silently from an upstream default that a Besu rebase
+ * could change under us.
+ *
+ * <p><b>Inactive below H.</b> The height gate is the FIRST statement, before any decode. Below H this
+ * rule does not even parse the header, so a binary carrying it behaves exactly as today on the whole
+ * existing chain. That is the condition under which such a binary can be warmed on a live node.
+ *
+ * <p><b>Fail-closed above H.</b> At or above H, anything that prevents the digest from being computed
+ * and matched is a REJECT: a non-canonical or undecodable extraData, a vanity field that is not 32
+ * bytes, a certificate whose indices are not strictly increasing, or a mismatching digest. Never an
+ * implicit accept, and specifically never "true on exception", which is the defect that made the
+ * legacy {@code FalconSealValidationRule} unable to catch anything.
+ *
+ * <p>The residual exposure this does NOT close, stated plainly: the certificate is outside the
+ * block-hash pre-image, so a hostile peer can serve a header with the certificate mangled and that
+ * header becomes unimportable although its block hash is unchanged. That is denial of service at
+ * header service, not forgery, and it is the same exposure the ECDSA committed seals already carry
+ * today.
+ */
+public class PqAnchorDigestRule implements DetachedBlockHeaderValidationRule {
+
+ private static final Logger LOG = LoggerFactory.getLogger(PqAnchorDigestRule.class);
+
+ private final PqAnchorConfig config;
+ private final QbftExtraDataCodec extraDataCodec = new QbftExtraDataCodec();
+
+ /**
+ * Instantiates the anchor digest rule.
+ *
+ * @param config the height-indexed activation configuration
+ */
+ public PqAnchorDigestRule(final PqAnchorConfig config) {
+ this.config = config;
+ }
+
+ @Override
+ public boolean validate(final BlockHeader header, final BlockHeader parent) {
+ final long number = header.getNumber();
+
+ // HEIGHT GATE FIRST. Below H nothing at all happens: no decode, no allocation, no log. This is
+ // the property that lets a binary built from this code run on a live node before activation and
+ // behave bit-for-bit as today. From 2026-08-07 the gate also covers the interval: at a height
+ // that carries no certificate there is nothing to bind, so there is nothing to judge.
+ //
+ // THE SAME METHOD AS R2, and not two questions that merely resemble each other. See the note in
+ // PqAnchorSealsRule.
+ if (!config.anchorAppliesAt(number)) {
+ return true;
+ }
+
+ // SECOND GATE: the named historical windows in which these rules were not in force. Inside one
+ // of them vanityData carries the client's version string rather than a digest, so there is no
+ // digest to match and no recomputation can produce one; refusing would stop this node forever
+ // at a height the whole network holds. See PqAnchorLapse for what happened, how the bounds were
+ // measured, and why an exception written anywhere other than validation moves the error instead
+ // of ending it.
+ if (PqAnchorLapse.isDisarmed(number)) {
+ return acceptAsWrittenInsideLapse(header, number);
+ }
+
+ try {
+ final BftExtraData extraData = extraDataCodec.decodeRaw(header.getExtraData());
+
+ final Bytes vanity = extraData.getVanityData();
+ if (vanity.size() != BftExtraDataCodec.EXTRA_VANITY_LENGTH) {
+ LOG.warn(
+ "AERE PQ ANCHOR (R1): block {} REJECTED - vanityData is {} bytes, expected {}. From H "
+ + "the whole vanity field is the anchor digest D.",
+ number,
+ vanity.size(),
+ BftExtraDataCodec.EXTRA_VANITY_LENGTH);
+ return false;
+ }
+
+ // AERE ANCHOR V2 (2026-09-03): from the v2 height the ONLY accepted form is the scheme-tagged
+ // certificate under the v2 digest; below it a v2 certificate is refused. Both directions
+ // are checked so the switch is a clean fork and never a header two nodes read differently.
+ if (config.anchorV2AppliesAt(number)) {
+ return judgeV2(number, header, extraData, vanity);
+ }
+ if (!extraData.getHybridSeals().isEmpty()) {
+ LOG.warn(
+ "AERE PQ ANCHOR (R1): block {} REJECTED - carries a v2 (scheme-tagged) certificate below"
+ + " the v2 activation height {}.",
+ number,
+ config.anchorV2Block());
+ return false;
+ }
+ final List<FalconSeal> certificate = List.copyOf(extraData.getFalconSeals());
+ // Height aware since 2026-08-11. Inside the one measured historical window the ordering
+ // requirement relaxes from SORTED to DISTINCT, because 36 canonical headers were written
+ // unsorted during a production interruption and a node syncing from genesis would otherwise
+ // stop at the first of them and never pass it. Distinctness is not relaxed at any height, so a
+ // repeated index stays unrepresentable everywhere. See PqAnchor.hasAcceptableIndices.
+ if (!PqAnchor.hasAcceptableIndices(certificate, number)) {
+ // Checked HERE, not only in the seals rule, so reordering and duplicate indices are caught
+ // in LIGHT validation too, and so that "the order given" and "sorted" are the same list for
+ // every header this rule accepts.
+ LOG.warn(
+ "AERE PQ ANCHOR (R1): block {} REJECTED - the carried certificate's validator indices "
+ + "are not strictly increasing ({} seal(s)). Exactly one order is accepted for a "
+ + "given set, which is also what makes a repeated index unrepresentable.",
+ number,
+ certificate.size());
+ return false;
+ }
+
+ final Bytes32 expected =
+ PqAnchor.anchorDigest(
+ config.chainId(), number - 1L, header.getParentHash().getBytes(), certificate);
+
+ if (!expected.equals(Bytes32.wrap(vanity))) {
+ LOG.warn(
+ "AERE PQ ANCHOR (R1): block {} REJECTED - anchor digest mismatch. vanityData carries "
+ + "{} but the certificate actually carried in this header ({} seal(s), over parent "
+ + "{} at height {}) digests to {}. The certificate was stripped, replaced or "
+ + "reordered after the proposer wrote it.",
+ number,
+ vanity,
+ certificate.size(),
+ header.getParentHash(),
+ number - 1L,
+ expected);
+ return false;
+ }
+
+ return true;
+ } catch (final Exception e) {
+ // FAIL CLOSED. The legacy Falcon rule returned true on every path including this one, which is
+ // why it could never catch anything. A rule that cannot compute its verdict has not proved the
+ // header good.
+ LOG.warn(
+ "AERE PQ ANCHOR (R1): block {} REJECTED - the anchor digest could not be computed: {}",
+ number,
+ e.toString());
+ return false;
+ }
+ }
+
+ /** AERE ANCHOR V2: vanityData must be the v2 digest over the carried scheme-tagged certificate. */
+ private boolean judgeV2(
+ final long number, final BlockHeader header, final BftExtraData extraData, final Bytes vanity) {
+ final List<SchemeSeal> seals = extraData.getHybridSeals();
+ if (seals.isEmpty()) {
+ LOG.warn(
+ "AERE PQ ANCHOR (R1): block {} REJECTED - at or above the v2 activation height {} the header"
+ + " carries no scheme-tagged certificate ({} v1 Falcon seal(s) instead).",
+ number,
+ config.anchorV2Block(),
+ extraData.getFalconSeals().size());
+ return false;
+ }
+ final Bytes32 expected =
+ PqAnchorV2.anchorDigestV2(
+ config.chainId(), number - 1L, header.getParentHash().getBytes(), seals);
+ if (!expected.equals(Bytes32.wrap(vanity))) {
+ LOG.warn(
+ "AERE PQ ANCHOR (R1): block {} REJECTED - v2 anchor digest mismatch. vanityData carries {}"
+ + " but the {}-seal scheme-tagged certificate actually carried digests to {}. The"
+ + " certificate was stripped, replaced or reordered after the proposer wrote it.",
+ number,
+ vanity,
+ seals.size(),
+ expected);
+ return false;
+ }
+ return true;
+ }
+
+ /**
+ * Accept a header from a named unenforced window as it was written, after the one check that is
+ * not relaxed at any height.
+ *
+ * <p>Distinctness is kept and the difference is the whole reason this is not a bare {@code return
+ * true}: sortedness fixes ONE accepted order for a given set, while distinctness is what makes
+ * "repeat one seal to inflate the count" unrepresentable in the grammar of the format. Every
+ * header of the measured window has distinct, non-negative indices, so this admits exactly the
+ * history that exists and nothing weaker.
+ *
+ * <p>Decoding must still succeed. A header this rule cannot parse has not been shown to be one of
+ * the headers the window is about, so it is refused here as everywhere else in this file.
+ *
+ * @param header the header being judged
+ * @param number its height
+ * @return true iff the carried certificate decodes and its indices are distinct and non-negative
+ */
+ private boolean acceptAsWrittenInsideLapse(final BlockHeader header, final long number) {
+ try {
+ final BftExtraData extraData = extraDataCodec.decodeRaw(header.getExtraData());
+ final List<FalconSeal> certificate = List.copyOf(extraData.getFalconSeals());
+ if (!PqAnchor.hasDistinctNonNegativeIndices(certificate)) {
+ LOG.warn(
+ "AERE PQ ANCHOR (R1): block {} REJECTED - it falls inside the historical range {} in "
+ + "which the anchor rules were not in force, but its certificate repeats a "
+ + "validator index or carries a negative one. That is not a shape any header of "
+ + "that range has, and it is the one property the exception does not relax.",
+ number,
+ PqAnchorLapse.windowCovering(number).orElse(null));
+ return false;
+ }
+ LOG.debug(
+ "AERE PQ ANCHOR (R1): block {} accepted as written; it falls inside the historical range "
+ + "{} in which the anchor rules were not in force, so it carries no digest to bind.",
+ number,
+ PqAnchorLapse.windowCovering(number).orElse(null));
+ return true;
+ } catch (final Exception e) {
+ LOG.warn(
+ "AERE PQ ANCHOR (R1): block {} REJECTED - it falls inside a historical unenforced range "
+ + "but its extraData could not be decoded: {}",
+ number,
+ e.toString());
+ return false;
+ }
+ }
+
+ @Override
+ public boolean includeInLightValidation() {
+ return true;
+ }
+
+ @Override
+ public String toString() {
+ return "PqAnchorDigest(detached, light, "
+ + (config.everActive() ? "H=" + config.anchorBlock() : "INACTIVE")
+ + ")";
+ }
+}
diff --git a/consensus/qbft/src/main/java/org/hyperledger/besu/consensus/qbft/headervalidationrules/PqAnchorSealsRule.java b/consensus/qbft/src/main/java/org/hyperledger/besu/consensus/qbft/headervalidationrules/PqAnchorSealsRule.java
new file mode 100755
index 000000000..78423af47
--- /dev/null
+++ b/consensus/qbft/src/main/java/org/hyperledger/besu/consensus/qbft/headervalidationrules/PqAnchorSealsRule.java
@@ -0,0 +1,579 @@
+/*
+ * Copyright contributors to Besu / AERE Network.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.qbft.headervalidationrules;
+
+import org.hyperledger.besu.consensus.common.bft.BftContext;
+import org.hyperledger.besu.consensus.common.bft.BftExtraData;
+import org.hyperledger.besu.consensus.common.bft.FalconSeal;
+import org.hyperledger.besu.consensus.common.bft.FalconSealSupport;
+import org.hyperledger.besu.consensus.common.bft.HybridSealSupport;
+import org.hyperledger.besu.consensus.common.bft.HybridSignerRegistry;
+import org.hyperledger.besu.consensus.common.bft.PqAnchor;
+import org.hyperledger.besu.consensus.common.bft.PqAnchorConfig;
+import org.hyperledger.besu.consensus.common.bft.PqAnchorLapse;
+import org.hyperledger.besu.consensus.common.bft.PqAnchorV2;
+import org.hyperledger.besu.consensus.common.bft.PqSignerRegistry;
+import org.hyperledger.besu.consensus.common.bft.SchemeSeal;
+import org.hyperledger.besu.consensus.common.bft.SealScheme;
+import org.hyperledger.besu.consensus.common.bft.SealSchemes;
+import org.hyperledger.besu.consensus.qbft.QbftExtraDataCodec;
+import org.hyperledger.besu.datatypes.Address;
+import org.hyperledger.besu.ethereum.ProtocolContext;
+import org.hyperledger.besu.ethereum.core.BlockHeader;
+import org.hyperledger.besu.ethereum.mainnet.AttachedBlockHeaderValidationRule;
+
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.Map;
+import java.util.Optional;
+import java.util.List;
+import java.util.OptionalInt;
+import java.util.Set;
+
+import org.apache.tuweni.bytes.Bytes32;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+/**
+ * R2: the anchor SEALS rule. ATTACHED, full validation only.
+ *
+ * <p>Where R1 proves that the header commits to the certificate it carries, R2 proves the
+ * certificate is worth something. It checks exactly four things, and every one of them is a function
+ * of the header, the parent header, and configuration. NONE of them is a comparison against what
+ * this node happened to hear.
+ *
+ * <ol>
+ * <li>k = |C| is at least K(height), the staged threshold;
+ * <li>the validator indices are STRICTLY increasing, so there is one accepted order and a repeated
+ * index is unrepresentable;
+ * <li>every index maps, through the registry, to an address in the PARENT's validator set;
+ * <li>every signature verifies as Falcon-512 over M(parent).
+ * </ol>
+ *
+ * <p><b>Why the "what I heard" comparison is absent, and why that is the entire point.</b> Measured
+ * on 200 consecutive live headers read simultaneously from two of our own nodes, with the block hash
+ * identical 200/200: the seal ORDER differed on 68 and the seal SET differed on 11. Any rule that
+ * required the carried certificate to match the local view would therefore reject roughly one header
+ * in eighteen with no attacker present, and at quorum 5 of 7 that is repeated stalling. Here a node
+ * that heard 7 accepts the proposer's certificate of 5, because Falcon verification is public: the
+ * validator does not need to have heard those commit messages to check them. The same construction
+ * also removes the third divergence axis for free, the one where a node signs the same block twice
+ * (once in {@code updateStateWithProposedBlock}, once in {@code peerIsPrepared}): both signatures are
+ * valid, the proposer writes one, everyone verifies it, and whether Falcon signing is deterministic
+ * stops mattering. That question remains NOT MEASURED and, under this scheme, no longer needs to be.
+ *
+ * <p><b>Not in light validation.</b> This rule needs the consensus context and the registry, so
+ * {@code includeInLightValidation()} returns false. The split is deliberate: the part that binds the
+ * certificate to the block hash is one keccak and runs everywhere, the part that costs k Falcon
+ * verifications runs only where state exists. Measured Falcon verification is 0.068 ms median and
+ * 0.249 ms p95, so five verifications are under 1.3 ms against a measured 517 ms block interval.
+ *
+ * <p><b>Inactive below H</b>, checked as the first statement, before any decode.
+ *
+ * <p><b>Fail-closed above H</b>, on every path including exceptions and including a missing or
+ * mismatched parent.
+ *
+ * <p>LIVENESS COST, stated because it is real: the threshold makes the certificate a liveness
+ * condition. A proposer that cannot gather K seals for the parent cannot propose at all. At N=7 the
+ * quorum is 5 and N-f is 5, i.e. ZERO margin, which is why the validator set must reach N&gt;=9
+ * before this is armed with a quorum threshold. How often that stalls in practice is NOT MEASURED,
+ * because nothing has been run.
+ */
+public class PqAnchorSealsRule implements AttachedBlockHeaderValidationRule {
+
+ private static final Logger LOG = LoggerFactory.getLogger(PqAnchorSealsRule.class);
+
+ private final PqAnchorConfig config;
+ private final PqSignerRegistry registry;
+ private final QbftExtraDataCodec extraDataCodec = new QbftExtraDataCodec();
+
+ /**
+ * Instantiates the anchor seals rule against the production Falcon registry.
+ *
+ * @param config the height-indexed activation configuration
+ */
+ public PqAnchorSealsRule(final PqAnchorConfig config) {
+ this(config, PqSignerRegistry.falconSealSupport());
+ }
+
+ /**
+ * Instantiates the anchor seals rule against an explicit registry.
+ *
+ * @param config the height-indexed activation configuration
+ * @param registry the index-to-signer view used for eligibility and verification
+ */
+ public PqAnchorSealsRule(final PqAnchorConfig config, final PqSignerRegistry registry) {
+ this.config = config;
+ this.registry = registry;
+ }
+
+ @Override
+ public boolean validate(
+ final BlockHeader header, final BlockHeader parent, final ProtocolContext protocolContext) {
+ final long number = header.getNumber();
+
+ // HEIGHT GATE FIRST, same contract as R1: below H this rule does nothing at all, and from
+ // 2026-08-07 it also does nothing at a height that carries no certificate.
+ //
+ // BOTH RULES ASK THE SAME QUESTION, THROUGH THE SAME METHOD, and that is deliberate.
+ // anchorAppliesAt() = activeAt() AND isAnchorHeight(). If R1 and R2 each asked it their own
+ // way, a header accepted by one and refused by the other would be a chain break, appearing at
+ // exactly the first height that is not an anchor height, i.e. the day after activation.
+ if (!config.anchorAppliesAt(number)) {
+ return true;
+ }
+
+ // SECOND GATE, and the SAME method R1 asks, for the same reason both rules share
+ // anchorAppliesAt: if the two rules each decided this boundary their own way, a header accepted
+ // by one and refused by the other would be a chain break. Inside a named window the threshold
+ // was not in force when the header was written and the indices were written in arrival order,
+ // so neither can be required of it now.
+ if (PqAnchorLapse.isDisarmed(number)) {
+ return acceptAsWrittenInsideLapse(header, number);
+ }
+
+ try {
+ if (parent == null) {
+ LOG.warn(
+ "AERE PQ ANCHOR (R2): block {} REJECTED - no parent header available, so the "
+ + "certificate cannot be checked against the parent it claims to attest to.",
+ number);
+ return false;
+ }
+ // The certificate attests to the parent by NUMBER and HASH, and R1 has already bound the
+ // digest to header.getParentHash(). If the parent handed to this rule were a different header,
+ // R1 and R2 would be talking about two different objects. Cheap, and it removes any dependence
+ // on rule ordering with AncestryValidationRule.
+ if (!parent.getHash().equals(header.getParentHash())
+ || parent.getNumber() != number - 1L) {
+ LOG.warn(
+ "AERE PQ ANCHOR (R2): block {} REJECTED - the supplied parent (number {}, hash {}) is "
+ + "not the parent this header names (number {}, hash {}).",
+ number,
+ parent.getNumber(),
+ parent.getHash(),
+ number - 1L,
+ header.getParentHash());
+ return false;
+ }
+
+ // AERE D-078 (2026-08-02). DIAGNOSTIC ONLY, and deliberately before every early return below
+ // so it runs at every height from H, including the warm-up where K is 0 and the certificate is
+ // empty. It feeds FalconSealSupport's registry-coverage report, whose only previous source was
+ // FalconSealValidationRule - a rule that stands down at exactly the height THIS rule takes
+ // over. Above H nothing updated it, so the coverage report was either frozen at a set from
+ // below H or, on a node whose process started above H, never set at all. Nothing here can
+ // change this rule's verdict: the call cannot throw and its result is not read.
+ observeValidatorsForDiagnostics(parent, protocolContext);
+
+ final BftExtraData extraData = extraDataCodec.decodeRaw(header.getExtraData());
+ // AERE ANCHOR V2 (2026-09-03): one form per height, both directions refused (see R1).
+ if (config.anchorV2AppliesAt(number)) {
+ return judgeV2(number, parent, extraData, protocolContext);
+ }
+ if (!extraData.getHybridSeals().isEmpty()) {
+ LOG.warn(
+ "AERE PQ ANCHOR (R2): block {} REJECTED - carries a v2 (scheme-tagged) certificate below"
+ + " the v2 activation height {}.",
+ number,
+ config.anchorV2Block());
+ return false;
+ }
+ final List<FalconSeal> certificate = List.copyOf(extraData.getFalconSeals());
+ final int k = certificate.size();
+
+ // THE THRESHOLD THIS HEIGHT WAS ACTUALLY JUDGED BY. Normally the configured schedule. Inside
+ // a named historical range it is the LOWER of the schedule and the emergency ceiling that was
+ // in force when these headers were written, which is the same lever the fleet itself used at
+ // the time, replayed from a fixed range instead of from a runtime option. Asking a header for
+ // more than was asked of the proposer that wrote it refuses history that no node can
+ // reproduce; asking for the ceiling rather than for nothing keeps the strongest claim the
+ // range supports, and the ceiling is a measured floor, never zero. See PqAnchorLapse.
+ int required = config.minSealsAt(number);
+ final OptionalInt inForce = PqAnchorLapse.historicMinSeals(number);
+ if (inForce.isPresent() && inForce.getAsInt() < required) {
+ LOG.debug(
+ "AERE PQ ANCHOR (R2): block {} sits in the historical range {}, so the threshold "
+ + "applied is the {} that was in force then, not the {} the schedule asks for.",
+ number,
+ PqAnchorLapse.windowCovering(number).orElse(null),
+ inForce.getAsInt(),
+ required);
+ required = inForce.getAsInt();
+ }
+
+ if (k < required) {
+ LOG.warn(
+ "AERE PQ ANCHOR (R2): block {} REJECTED - the carried certificate has {} seal(s), "
+ + "below the threshold K={} in force at this height.",
+ number,
+ k,
+ required);
+ return false;
+ }
+
+ // Height aware since 2026-08-11, same measured historical window as rule R1. See
+ // PqAnchor.hasAcceptableIndices for why the exception sits at VALIDATION and nowhere else, and
+ // for what it deliberately does NOT relax.
+ if (!PqAnchor.hasAcceptableIndices(certificate, number)) {
+ LOG.warn(
+ "AERE PQ ANCHOR (R2): block {} REJECTED - the certificate's validator indices are not "
+ + "strictly increasing.",
+ number);
+ return false;
+ }
+
+ if (k == 0) {
+ // Legitimate only while K is 0, which is the warm-up stage that starts at H itself, where
+ // the parent predates the scheme and no certificate can exist. R1 has already checked that
+ // the vanity digest is the digest OF THE EMPTY certificate, so an empty certificate is not
+ // an unchecked one.
+ LOG.debug(
+ "AERE PQ ANCHOR (R2): block {} carries an empty certificate and K={} at this height.",
+ number,
+ required);
+ return true;
+ }
+
+ final BftContext bftContext = protocolContext.getConsensusContext(BftContext.class);
+ final Collection<Address> parentValidators =
+ bftContext.getValidatorProvider().getValidatorsForBlock(parent);
+ if (parentValidators == null || parentValidators.isEmpty()) {
+ LOG.warn(
+ "AERE PQ ANCHOR (R2): block {} REJECTED - the validator set of the parent block {} "
+ + "could not be resolved, so seal eligibility cannot be decided.",
+ number,
+ parent.getNumber());
+ return false;
+ }
+ final Set<Address> eligible = new HashSet<>(parentValidators);
+
+ final Bytes32 message =
+ PqAnchor.commitMessage(
+ config.chainId(), parent.getNumber(), parent.getHash().getBytes());
+
+ if (!falconSealsVerify(number, parent, eligible, message, certificate)) {
+ return false;
+ }
+ LOG.debug(
+ "AERE PQ ANCHOR (R2): block {} accepted with {} verified Falcon seal(s) over parent {} "
+ + "(threshold K={}, |parent validators|={}).",
+ number,
+ k,
+ parent.getNumber(),
+ required,
+ eligible.size());
+ return true;
+ } catch (final Exception e) {
+ LOG.warn(
+ "AERE PQ ANCHOR (R2): block {} REJECTED - the certificate could not be checked: {}",
+ number,
+ e.toString());
+ return false;
+ }
+ }
+
+ /**
+ * Accept a header from a named unenforced window as it was written, after the one check that is
+ * not relaxed at any height.
+ *
+ * <p>The threshold is not applied here and neither is sortedness, because neither was applied
+ * when these headers were written; applying them now would refuse history the whole network
+ * holds. Distinctness IS applied, for the reason set out in {@link PqAnchor#hasAcceptableIndices}
+ * and in {@link PqAnchorLapse}: it is the part that is load bearing against an attacker rather
+ * than against ambiguity, and it is measured true on every header of the window.
+ *
+ * @param header the header being judged
+ * @param number its height
+ * @return true iff the carried certificate decodes and its indices are distinct and non-negative
+ */
+ /**
+ * The Falcon half, shared by the v1 and the v2 form: every seal from an index the registry binds
+ * to a validator of the parent, no two indices on one address, each verifying over M(parent).
+ */
+ private boolean falconSealsVerify(
+ final long number,
+ final BlockHeader parent,
+ final Set<Address> eligible,
+ final Bytes32 message,
+ final List<FalconSeal> certificate) {
+ final Set<Address> counted = new HashSet<>();
+ for (final FalconSeal seal : certificate) {
+ final int index = seal.getValidatorIndex();
+ // D-081: the key set is resolved AT THE PARENT'S HEIGHT, because that is the block these
+ // seals commit to. Resolving at this block's height would be wrong by one block, and at a
+ // rotation height "wrong by one block" is a different key set and a permanent chain stop.
+ // D2 (b-v2): the HISTORY door. This rule judges a header this node received, at the
+ // PARENT's height, which is the height the certificate commits to. It must refuse a
+ // height it has no registry binding for rather than answer from its own head.
+ final Address signer =
+ registry.addressForIndexAtHistoric(parent.getNumber(), index);
+ if (signer == null) {
+ LOG.warn(
+ "AERE PQ ANCHOR (R2): block {} REJECTED - certificate carries index {}, which the "
+ + "registry does not bind to any validator address. An unbound index cannot be "
+ + "shown to be eligible, so it is refused rather than skipped.",
+ number,
+ index);
+ return false;
+ }
+ if (!eligible.contains(signer)) {
+ LOG.warn(
+ "AERE PQ ANCHOR (R2): block {} REJECTED - certificate carries index {} (address {}), "
+ + "which was NOT a validator of the parent block {}.",
+ number,
+ index,
+ signer,
+ parent.getNumber());
+ return false;
+ }
+ if (!counted.add(signer)) {
+ LOG.warn(
+ "AERE PQ ANCHOR (R2): block {} REJECTED - two distinct registry indices, including "
+ + "{}, resolve to the same validator address {}. That would let one validator be "
+ + "counted twice despite strictly increasing indices.",
+ number,
+ index,
+ signer);
+ return false;
+ }
+ if (!registry.verifyAtHistoric(
+ parent.getNumber(), index, message, seal.getSignature())) {
+ LOG.warn(
+ "AERE PQ ANCHOR (R2): block {} REJECTED - the Falcon signature from index {} "
+ + "(address {}) does not verify over M(parent {}).",
+ number,
+ index,
+ signer,
+ parent.getNumber());
+ return false;
+ }
+ }
+ return true;
+ }
+
+ /**
+ * AERE ANCHOR V2: the scheme-tagged certificate. K Falcon seals verified exactly as in v1, and for
+ * EVERY extra scheme the scheme schedule names at the parent height, K seals that (a) come from an
+ * index also carrying a Falcon seal in this certificate and (b) verify under the hybrid registry's
+ * key for that index and scheme over the same M(parent). A scheme the schedule does not name is
+ * refused, a missing registry is refused: a node that cannot verify has not proved the header good.
+ */
+ private boolean judgeV2(
+ final long number,
+ final BlockHeader parent,
+ final BftExtraData extraData,
+ final ProtocolContext protocolContext) {
+ final List<SchemeSeal> seals = extraData.getHybridSeals();
+ if (seals.isEmpty()) {
+ LOG.warn(
+ "AERE PQ ANCHOR (R2): block {} REJECTED - at or above the v2 activation height {} the header"
+ + " carries no scheme-tagged certificate.",
+ number,
+ config.anchorV2Block());
+ return false;
+ }
+ final int required = config.minSealsAt(number);
+ final List<FalconSeal> falcon = new ArrayList<>();
+ final Set<Integer> falconIndices = new HashSet<>();
+ for (final SchemeSeal s : seals) {
+ if (s.getSchemeWireId() == SealSchemes.FALCON_512.wireId()) {
+ falcon.add(new FalconSeal(s.getValidatorIndex(), s.getSignature()));
+ falconIndices.add(s.getValidatorIndex());
+ }
+ }
+ if (falcon.size() < required) {
+ LOG.warn(
+ "AERE PQ ANCHOR (R2): block {} REJECTED - the v2 certificate has {} Falcon seal(s), below"
+ + " the threshold K={} in force at this height.",
+ number,
+ falcon.size(),
+ required);
+ return false;
+ }
+ final BftContext bftContext = protocolContext.getConsensusContext(BftContext.class);
+ final Collection<Address> parentValidators =
+ bftContext.getValidatorProvider().getValidatorsForBlock(parent);
+ if (parentValidators == null || parentValidators.isEmpty()) {
+ LOG.warn(
+ "AERE PQ ANCHOR (R2): block {} REJECTED - the validator set of the parent block {} could"
+ + " not be resolved, so seal eligibility cannot be decided.",
+ number,
+ parent.getNumber());
+ return false;
+ }
+ final Set<Address> eligible = new HashSet<>(parentValidators);
+ final Bytes32 message =
+ PqAnchor.commitMessage(config.chainId(), parent.getNumber(), parent.getHash().getBytes());
+ if (!falcon.isEmpty() && !falconSealsVerify(number, parent, eligible, message, falcon)) {
+ return false;
+ }
+ final HybridSealSupport hybrid = HybridSealSupport.instance();
+ final Set<String> requiredSchemes = new HashSet<>();
+ hybrid.schedule().ifPresent(sch -> requiredSchemes.addAll(sch.schemesAt(parent.getNumber())));
+ requiredSchemes.remove(SealSchemes.FALCON_512.id());
+ final Map<String, Integer> counted = new HashMap<>();
+ for (final SchemeSeal s : seals) {
+ if (s.getSchemeWireId() == SealSchemes.FALCON_512.wireId()) {
+ continue;
+ }
+ final Optional<SealScheme> scheme = SealSchemes.byWireId(s.getSchemeWireId());
+ if (scheme.isEmpty() || !requiredSchemes.contains(scheme.get().id())) {
+ LOG.warn(
+ "AERE PQ ANCHOR (R2): block {} REJECTED - the v2 certificate carries a seal of scheme 0x{},"
+ + " which the scheme schedule does not name at the parent height {} (named: {}).",
+ number,
+ Integer.toHexString(s.getSchemeWireId() & 0xff),
+ parent.getNumber(),
+ requiredSchemes);
+ return false;
+ }
+ if (!falconIndices.contains(s.getValidatorIndex())) {
+ LOG.warn(
+ "AERE PQ ANCHOR (R2): block {} REJECTED - a {} seal from index {} is not bound to a Falcon"
+ + " seal of the same index in this certificate.",
+ number,
+ scheme.get().id(),
+ s.getValidatorIndex());
+ return false;
+ }
+ final Optional<HybridSignerRegistry> registry = hybrid.registry();
+ if (registry.isEmpty()) {
+ LOG.warn(
+ "AERE PQ ANCHOR (R2): block {} REJECTED - the certificate carries {} seals and this node"
+ + " has NO hybrid registry loaded, so it cannot verify them. A node that cannot"
+ + " verify has not proved the header good.",
+ number,
+ scheme.get().id());
+ return false;
+ }
+ final Optional<byte[]> pk = registry.get().publicKey(s.getValidatorIndex(), scheme.get().id());
+ if (pk.isEmpty()) {
+ LOG.warn(
+ "AERE PQ ANCHOR (R2): block {} REJECTED - the hybrid registry holds no {} key for index {}.",
+ number,
+ scheme.get().id(),
+ s.getValidatorIndex());
+ return false;
+ }
+ if (!scheme.get().verifyRaw(pk.get(), message.toArray(), s.getSignature().toArray())) {
+ LOG.warn(
+ "AERE PQ ANCHOR (R2): block {} REJECTED - the {} signature from index {} does not verify"
+ + " over M(parent {}).",
+ number,
+ scheme.get().id(),
+ s.getValidatorIndex(),
+ parent.getNumber());
+ return false;
+ }
+ counted.merge(scheme.get().id(), 1, Integer::sum);
+ }
+ for (final String schemeId : requiredSchemes) {
+ final int have = counted.getOrDefault(schemeId, 0);
+ if (have < required) {
+ LOG.warn(
+ "AERE PQ ANCHOR (R2): block {} REJECTED - the v2 certificate has {} valid {} seal(s), below"
+ + " the threshold K={} the schedule demands of every named scheme.",
+ number,
+ have,
+ schemeId,
+ required);
+ return false;
+ }
+ }
+ LOG.debug(
+ "AERE PQ ANCHOR (R2): block {} accepted with a {}-seal scheme-tagged certificate over parent"
+ + " {} (K={} per scheme, schemes={}).",
+ number,
+ seals.size(),
+ parent.getNumber(),
+ required,
+ requiredSchemes);
+ return true;
+ }
+
+ private boolean acceptAsWrittenInsideLapse(final BlockHeader header, final long number) {
+ try {
+ final BftExtraData extraData = extraDataCodec.decodeRaw(header.getExtraData());
+ final List<FalconSeal> certificate = List.copyOf(extraData.getFalconSeals());
+ if (!PqAnchor.hasDistinctNonNegativeIndices(certificate)) {
+ LOG.warn(
+ "AERE PQ ANCHOR (R2): block {} REJECTED - it falls inside the historical range {} in "
+ + "which the anchor rules were not in force, but its certificate repeats a "
+ + "validator index or carries a negative one, which no header of that range does.",
+ number,
+ PqAnchorLapse.windowCovering(number).orElse(null));
+ return false;
+ }
+ LOG.debug(
+ "AERE PQ ANCHOR (R2): block {} accepted as written with {} seal(s); it falls inside the "
+ + "historical range {} in which neither the threshold nor the ordering was in force.",
+ number,
+ certificate.size(),
+ PqAnchorLapse.windowCovering(number).orElse(null));
+ return true;
+ } catch (final Exception e) {
+ LOG.warn(
+ "AERE PQ ANCHOR (R2): block {} REJECTED - it falls inside a historical unenforced range "
+ + "but its extraData could not be decoded: {}",
+ number,
+ e.toString());
+ return false;
+ }
+ }
+
+ /**
+ * AERE D-078: hand the parent's validator set to {@link FalconSealSupport} so its registry-
+ * coverage report is about the height the chain is actually at. Swallows everything: a rule that
+ * rejected a header because a diagnostic threw would be a worse defect than the one this repairs.
+ *
+ * @param parent the parent header
+ * @param protocolContext the protocol context
+ */
+ private void observeValidatorsForDiagnostics(
+ final BlockHeader parent, final ProtocolContext protocolContext) {
+ try {
+ final Collection<Address> validators =
+ protocolContext
+ .getConsensusContext(BftContext.class)
+ .getValidatorProvider()
+ .getValidatorsForBlock(parent);
+ if (validators != null && !validators.isEmpty()) {
+ FalconSealSupport.instance().observeValidators(parent.getNumber(), validators);
+ }
+ } catch (final Exception e) {
+ LOG.debug(
+ "AERE PQ ANCHOR (R2): validator-set observation skipped at parent {}: {}",
+ parent.getNumber(),
+ e.toString());
+ }
+ }
+
+ @Override
+ public boolean includeInLightValidation() {
+ return false;
+ }
+
+ @Override
+ public String toString() {
+ return "PqAnchorSeals(attached, full, "
+ + (config.everActive() ? "H=" + config.anchorBlock() : "INACTIVE")
+ + ", registry="
+ + registry
+ + ")";
+ }
+}
diff --git a/consensus/qbft/src/main/java/org/hyperledger/besu/consensus/qbft/headervalidationrules/PqEmergencyShoutRule.java b/consensus/qbft/src/main/java/org/hyperledger/besu/consensus/qbft/headervalidationrules/PqEmergencyShoutRule.java
new file mode 100755
index 000000000..701f7a7a8
--- /dev/null
+++ b/consensus/qbft/src/main/java/org/hyperledger/besu/consensus/qbft/headervalidationrules/PqEmergencyShoutRule.java
@@ -0,0 +1,134 @@
+/*
+ * Copyright contributors to Besu / AERE Network.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.qbft.headervalidationrules;
+
+import org.hyperledger.besu.consensus.common.bft.PqAnchorConfig;
+import org.hyperledger.besu.ethereum.core.BlockHeader;
+import org.hyperledger.besu.ethereum.mainnet.DetachedBlockHeaderValidationRule;
+
+import java.util.concurrent.atomic.AtomicLong;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+/**
+ * AERE OPTIUNI-URGENTA (2026-08-02): the NOISE half of the emergency controls.
+ *
+ * <p><b>The rule this exists to obey.</b> A quiet way out is worse than no way out. An emergency
+ * control that silently degrades what a node checks will be set once at three in the morning by
+ * somebody who means to remove it in the morning, and will still be set six months later, on a fleet
+ * everybody believes is enforcing something it is not. So each of the three controls costs the
+ * operator a complete ERROR line at EVERY height for as long as it is in force: not a startup
+ * banner that scrolls away, not a metric nobody has a dashboard for, a line in the log of a running
+ * node that never stops.
+ *
+ * <p><b>Why a header rule.</b> The alternative is a timer, and a timer would have to invent its own
+ * idea of the current height and would drift away from the code that actually decides anything. This
+ * rule is asked once per header by the same validator that decides whether the header may enter the
+ * chain, and it reads the SAME {@link PqAnchorConfig} object the anchor rules read, so what it
+ * announces cannot disagree with what is enforced.
+ *
+ * <p><b>It cannot reject anything.</b> {@link #validate} returns true on every path, including its
+ * exception path. That is deliberate and it is what makes it safe to place FIRST in the ruleset: a
+ * rule that always returns true cannot change the verdict of a conjunction, so putting it first
+ * changes nothing except that the announcement is made even on headers a later rule goes on to
+ * reject - which is exactly when an operator most needs to know that a control was overridden.
+ *
+ * <p><b>It says nothing when nothing is overridden.</b> No line is emitted at all when no control is
+ * in force, so "the log contains no AERE-PQC-EMG line" is a measurable statement about a node, and
+ * the silence is the control case that proves the shout is caused by the override and not by the
+ * rule merely existing.
+ *
+ * <p>The registry bypass announces itself from {@code FalconSealSupport}, on the same per-height
+ * basis, because only that class knows whether the bypass is actually carrying weight at a height.
+ */
+public class PqEmergencyShoutRule implements DetachedBlockHeaderValidationRule {
+
+ private static final Logger LOG = LoggerFactory.getLogger(PqEmergencyShoutRule.class);
+
+ private final PqAnchorConfig config;
+
+ /** Highest height already announced, so one line is emitted per height and not per validation. */
+ private final AtomicLong lastShout = new AtomicLong(-1L);
+
+ /**
+ * Instantiates the emergency announcement rule.
+ *
+ * @param config the height-indexed anchor configuration the anchor rules are running on; the
+ * announcement is derived from THIS object, not from a second reading of the configuration
+ */
+ public PqEmergencyShoutRule(final PqAnchorConfig config) {
+ this.config = config;
+ }
+
+ @Override
+ public boolean validate(final BlockHeader header, final BlockHeader parent) {
+ try {
+ final long number = header.getNumber();
+
+ // A configured anchor that has been switched off is a different state from an anchor that was
+ // never configured. Only the first is worth waking somebody for.
+ final boolean disarmed = config.disabled() && config.anchorConfigured();
+ final boolean lowered = config.emergencyCeilingLowersAt(number);
+
+ if (!disarmed && !lowered) {
+ return true;
+ }
+ if (lastShout.getAndSet(number) == number) {
+ return true;
+ }
+
+ if (disarmed) {
+ LOG.error(
+ "AERE PQC EMERGENCY [AERE-PQC-EMG-DISARM-01]: height {} validated WITH THE CERTIFICATE "
+ + "ANCHOR DISARMED. An activation height ({}) is configured on this node and both "
+ + "anchor rules have been switched off by {}, so this node is NOT checking that the "
+ + "post-quantum certificate in a header is the one the proposer wrote, and is NOT "
+ + "enforcing any seal threshold. A stripped or swapped certificate is invisible to "
+ + "this node. WHAT TO DO: this is a RECOVERY setting; once the cause is fixed, "
+ + "restart WITHOUT it, together with the rest of the fleet. THIS LINE REPEATS AT "
+ + "EVERY HEIGHT, BY DESIGN.",
+ number,
+ config.anchorBlock(),
+ PqAnchorConfig.PROPERTY_DISABLE);
+ }
+ if (lowered) {
+ LOG.error(
+ "AERE PQC EMERGENCY [AERE-PQC-EMG-CEILING-01]: height {} validated WITH A LOWERED SEAL "
+ + "THRESHOLD. The schedule in force asks for K={} at this height; the emergency "
+ + "ceiling {} caps it, so the threshold actually enforced is K={}. Fewer "
+ + "post-quantum signatures stand behind every block accepted while this is set. The "
+ + "ceiling can only ever LOWER the threshold, never raise it, so this cannot be the "
+ + "cause of a stall - but it is the reason a stall stopped. WHAT TO DO: raise the "
+ + "value back, or remove the option, as soon as enough validators can seal again. "
+ + "THIS LINE REPEATS AT EVERY HEIGHT, BY DESIGN.",
+ number,
+ config.scheduledMinSealsAt(number),
+ config.minSealsCeiling().isPresent() ? config.minSealsCeiling().getAsInt() : -1,
+ config.minSealsAt(number));
+ }
+ return true;
+ } catch (final RuntimeException e) {
+ // A rule whose only job is to talk must never be the reason a header is refused.
+ LOG.warn("AERE PQC EMERGENCY: the emergency announcement itself failed: {}", e.toString());
+ return true;
+ }
+ }
+
+ @Override
+ public boolean includeInLightValidation() {
+ return true;
+ }
+}
diff --git a/consensus/qbft/src/main/java/org/hyperledger/besu/consensus/qbft/headervalidationrules/PqRegistryBindingRule.java b/consensus/qbft/src/main/java/org/hyperledger/besu/consensus/qbft/headervalidationrules/PqRegistryBindingRule.java
new file mode 100755
index 000000000..84b7d98fb
--- /dev/null
+++ b/consensus/qbft/src/main/java/org/hyperledger/besu/consensus/qbft/headervalidationrules/PqRegistryBindingRule.java
@@ -0,0 +1,90 @@
+/*
+ * Copyright contributors to Besu / AERE Network.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.qbft.headervalidationrules;
+
+import org.hyperledger.besu.consensus.common.bft.FalconSealSupport;
+import org.hyperledger.besu.ethereum.core.BlockHeader;
+import org.hyperledger.besu.ethereum.mainnet.DetachedBlockHeaderValidationRule;
+
+/**
+ * A8, the PER-BLOCK half of the registry binding.
+ *
+ * <p><b>The hole this closes, stated as the measurement that found it.</b> The A8 startup guard asks
+ * "does the registry on this node match what genesis requires" exactly once, against the chain head
+ * that existed when the process started. {@code config.pqRegistryHash} is a SCHEDULE, so it can have
+ * a second entry: a key rotation, or a validator-set change that re-anchors the manifest. A node
+ * that was already running when such a height passes underneath it is never asked the question
+ * again. It keeps verifying certificates against a registry the chain has moved off, and it keeps
+ * reporting itself healthy while it does so. That is defect A8 arriving through a different door,
+ * and the honest limits section of the A8 dossier said so in writing: "the guard runs at startup; it
+ * cannot stop a node that is already running when a rotation height passes underneath it."
+ *
+ * <p><b>Why a header rule and not a background timer.</b> A timer would have to invent its own
+ * notion of "the current height" and its own reaction, and would be a second, drifting source of
+ * truth about a consensus question. This rule is asked exactly once per header, by the code that
+ * already decides whether a header may enter this node's chain, and it answers with the same
+ * function the startup guard uses, over the same loaded registry object. There is one decision and
+ * one implementation of it.
+ *
+ * <p><b>What it does on mismatch, and why refusing is the fail-closed direction.</b> It returns
+ * false, so the header is not imported, and {@code FalconSealSupport} emits one complete ERROR line
+ * per height naming the hash required, the height it is required from, the hash found, the file in
+ * use and a fingerprint per registry row. Refusing looks harsh, and the alternative is worse: a node
+ * that imports a header whose certificate it cannot correctly verify has asserted a check it did not
+ * perform, which is precisely the behaviour the whole A8 repair exists to remove. Stopping at the
+ * first header past the rotation, loudly, is recoverable in one restart; importing 200,000 blocks
+ * under the wrong registry is not.
+ *
+ * <p><b>Inert unless somebody armed it, three times over.</b> The rule returns true when the startup
+ * guard never ran on this node, when genesis carries no {@code config.pqRegistryHash} at all, and at
+ * every height below the schedule's first entry. Chain 2800 as it stands today satisfies all three:
+ * its genesis has no such key, measured on the live genesis file. So a binary carrying this rule
+ * validates the existing 11.8 million blocks exactly as today.
+ *
+ * <p><b>DETACHED. And the light-validation flag does NOT keep it off the sync path - that claim
+ * was here and it was wrong.</b> Detached because the question is about this node's configuration
+ * at a height, not about the parent header. {@code includeInLightValidation()} returns false below,
+ * and the sentence that used to stand here said that this kept the rule away from a node that is
+ * fast-syncing headers. READ IN UPSTREAM BESU, and it does not:
+ * {@code BlockHeaderValidator.validateHeader} filters on {@code Rule::isDetachedSupported} alone
+ * for {@code DETACHED_ONLY}; only the three LIGHT modes consult {@code includeInLightValidation}.
+ * {@code DETACHED_ONLY} is exactly the mode {@code DownloadHeaderSequenceTask} validates
+ * closed-ended header ranges under, so this rule DOES run on the header-download path.
+ *
+ * <p>What that means, stated no further than it was checked: a syncing node whose registry does not
+ * satisfy the entry active at a height inside a downloaded range fails that whole range, and
+ * upstream treats a failed range as a bad peer. Whether that costs the node its peer table, and
+ * what it looks like when every honest peer serves the same headers, is NOT MEASURED.
+ *
+ * <p>The startup guard is what covers a node at the moment it is configured to matter, and since
+ * AERE CONSENS-LENS (2026-08-02) it asks about chainHead + 1, i.e. about the same height this rule
+ * will be asked about first. Before that change the two disagreed by one block, and that one block
+ * was a permanent chain stop at any scheduled rotation.
+ */
+public class PqRegistryBindingRule implements DetachedBlockHeaderValidationRule {
+
+ /** Default constructor. */
+ public PqRegistryBindingRule() {}
+
+ @Override
+ public boolean validate(final BlockHeader header, final BlockHeader parent) {
+ return FalconSealSupport.instance().registryBindingSatisfiedAt(header.getNumber());
+ }
+
+ @Override
+ public boolean includeInLightValidation() {
+ return false;
+ }
+}
diff --git a/consensus/qbft/src/test/java/org/hyperledger/besu/consensus/qbft/QbftAnchorRuleWiringTest.java b/consensus/qbft/src/test/java/org/hyperledger/besu/consensus/qbft/QbftAnchorRuleWiringTest.java
new file mode 100755
index 000000000..54ec478c0
--- /dev/null
+++ b/consensus/qbft/src/test/java/org/hyperledger/besu/consensus/qbft/QbftAnchorRuleWiringTest.java
@@ -0,0 +1,246 @@
+/*
+ * AERE D-148, 2026-08-07. The WIRING of the anchor rules into the validation chain.
+ *
+ * WHY THIS EXISTS, and it is the very gap CLAUDE.md names as the most expensive one: "a gate that
+ * has never failed cannot be believed".
+ *
+ * The three rules are registered in QbftBlockHeaderValidationRulesetFactory. The rules themselves
+ * have good and plentiful tests: 18 in PqAnchorDigestRuleTest, 25 in PqAnchorSealsRuleTest. But ALL
+ * of them build the validator themselves, with
+ * `new BlockHeaderValidator.Builder().addRule(rule).build()`, that is, a validator holding a SINGLE
+ * rule, hand-made inside the test. Measured on 2026-08-07: ZERO tests in the whole qbft tree went
+ * through the factory.
+ *
+ * THE CONSEQUENCE, concretely: delete the line that adds PqAnchorSealsRule and all 43 tests stay
+ * GREEN. The rule keeps working perfectly in isolation and is never called on a real header again.
+ * Without this class the wiring is an assertion, not a measurement, and the only thing holding
+ * it up was a run log from a day ago. Yesterday's log does not guard tomorrow's code.
+ *
+ * HOW IT MEASURES. It builds the validator THROUGH THE FACTORY and reads the rules out of the
+ * object that was built, by reflection over its fields, without assuming their names. Reflection
+ * is a technique already used in this module (see PqInertBinaryTest and the reason given there),
+ * and it fits here because the question really is "what ended up inside", not "what the rule does".
+ *
+ * THE NEGATIVE CONTROL, and it lives in this same class: with an UNARMED configuration the same
+ * three rules must still be there. They switch themselves off ON HEIGHT, not by being absent from
+ * the chain. If somebody "optimised" the factory into not adding them when the anchor is not
+ * configured, a node would start without them and would then reach the activation height with
+ * nothing to apply.
+ */
+package org.hyperledger.besu.consensus.qbft;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import java.lang.reflect.Field;
+import java.time.Duration;
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.OptionalInt;
+import org.hyperledger.besu.consensus.common.bft.PqAnchorConfig;
+import org.junit.jupiter.api.Test;
+
+class QbftAnchorRuleWiringTest {
+
+ private static final long H = 13_793_219L;
+
+ /** The simple names of the classes the factory MUST put into the validator. */
+ private static final List<String> ANCHOR_RULES =
+ List.of("PqAnchorDigestRule", "PqAnchorDigestAttachedRule", "PqAnchorSealsRule");
+
+ private static PqAnchorConfig armed() {
+ return new PqAnchorConfig(2800L, H, Map.of(H, 3), OptionalInt.empty(), false);
+ }
+
+ /**
+ * The simple names of every rule the built validator carries, whatever the fields holding them
+ * happen to be called. The object is read; its shape is not assumed.
+ */
+ private static List<String> rulesInside(final Object validator) throws Exception {
+ final List<String> found = new ArrayList<>();
+ for (Class<?> c = validator.getClass(); c != null && c != Object.class; c = c.getSuperclass()) {
+ for (final Field f : c.getDeclaredFields()) {
+ f.setAccessible(true);
+ final Object value = f.get(validator);
+ if (value instanceof Collection<?> collection) {
+ for (final Object element : collection) {
+ collectNames(element, found);
+ }
+ }
+ }
+ }
+ return found;
+ }
+
+ /**
+ * The name of the element AND of the objects it holds in its own fields, one level down.
+ *
+ * <p>MEASURED 2026-08-07, and the first form of this test failed exactly here: {@code
+ * BlockHeaderValidator} does not hold the rules directly, it WRAPS them, and its collection holds
+ * nothing but objects whose simple name is {@code "Rule"}. A test that had stopped at the first
+ * level would have reported fifteen {@code "Rule"} and nothing else, meaning it would have been
+ * green on anything and red on anything, whichever way it happened to fall. We go down one level,
+ * and only one: what this test looks for is the rule the factory put in, not the whole object
+ * graph.
+ */
+ private static void collectNames(final Object element, final List<String> into) throws Exception {
+ if (element == null) {
+ return;
+ }
+ into.add(element.getClass().getSimpleName());
+ for (final Field f : element.getClass().getDeclaredFields()) {
+ f.setAccessible(true);
+ final Object inner = f.get(element);
+ if (inner == null || f.getType().isPrimitive()) {
+ continue;
+ }
+ final String name = inner.getClass().getSimpleName();
+ into.add(name);
+ // THE THIRD LEVEL, and only for lambdas. Measured 2026-08-07, the second form of this test:
+ // the ATTACHED rules show up directly (PqAnchorSealsRule, PqAnchorDigestAttachedRule), but
+ // the DETACHED ones do not show up at all: the builder wraps them in an adapter lambda, and
+ // all that could be seen was "BlockHeaderValidator$Builder$$Lambda/0x...". So
+ // PqAnchorDigestRule, the anchor's only detached rule, was invisible, and a test happy with
+ // what it could see would have declared missing a rule that was right there.
+ //
+ // We descend ONLY into the lambda, and not into every object, so that the test does not turn
+ // into a walk through the whole graph, where it would find anything and could no longer tell
+ // anything apart.
+ if (name.contains("Lambda")) {
+ for (final Field captured : inner.getClass().getDeclaredFields()) {
+ captured.setAccessible(true);
+ final Object deep = captured.get(inner);
+ if (deep != null) {
+ into.add(deep.getClass().getSimpleName());
+ }
+ }
+ }
+ }
+ }
+
+ private static Object buildViaFactory(final PqAnchorConfig cfg) {
+ return QbftBlockHeaderValidationRulesetFactory.blockHeaderValidator(
+ Duration.ofSeconds(1), false, Optional.empty(), cfg)
+ .build();
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // 1. The three rules are REALLY inside the validator the factory produces.
+ // This is the assertion that turns red if somebody deletes a line from the factory.
+ // ---------------------------------------------------------------------------------------------
+ @Test
+ void theFactoryPutsAllThreeAnchorRulesIntoTheValidatorItBuilds() throws Exception {
+ final List<String> inside = rulesInside(buildViaFactory(armed()));
+
+ assertThat(inside)
+ .describedAs(
+ "the rules found inside the validator the factory built; if one is missing, somebody "
+ + "removed an addRule and no other test in the tree would have noticed")
+ .containsAll(ANCHOR_RULES);
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // 2. THE NEGATIVE CONTROL OF THIS TEST ITSELF. If the reflective reader returned an empty list
+ // for any reason at all, point 1 would have passed on anything at all. So we also demand that
+ // the validator carry upstream rules, which have nothing to do with the anchor.
+ // ---------------------------------------------------------------------------------------------
+ @Test
+ void theReaderActuallySeesSomethingAndNotAnEmptyList() throws Exception {
+ final List<String> inside = rulesInside(buildViaFactory(armed()));
+
+ assertThat(inside)
+ .describedAs("the reflective reader does see rules, otherwise the test above is empty")
+ .isNotEmpty();
+ assertThat(inside.size())
+ .describedAs("a QBFT validator carries far more than the three anchor rules")
+ .isGreaterThan(ANCHOR_RULES.size());
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // 3. UNARMED, the rules are STILL there. They switch off on height, not by being absent from the
+ // chain. A node that started without them would reach the activation height with nothing to
+ // apply, and the difference would not show until that very day.
+ // ---------------------------------------------------------------------------------------------
+ @Test
+ void theRulesArePresentEvenWhenTheAnchorIsNotConfigured() throws Exception {
+ final List<String> inside = rulesInside(buildViaFactory(PqAnchorConfig.never(2800L)));
+
+ assertThat(inside)
+ .describedAs(
+ "the rules switch off on HEIGHT, not by absence; an unarmed node must carry them "
+ + "anyway, so that it has them at the activation height")
+ .containsAll(ANCHOR_RULES);
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // 4. And the three-argument overload, the upstream one production code calls, ends at the same
+ // result. Without this we would have measured only the path the test itself uses.
+ // ---------------------------------------------------------------------------------------------
+ @Test
+ void theUpstreamThreeArgumentOverloadWiresTheAnchorRulesToo() throws Exception {
+ final Object validator =
+ QbftBlockHeaderValidationRulesetFactory.blockHeaderValidator(
+ Duration.ofSeconds(1), false, Optional.empty())
+ .build();
+
+ assertThat(rulesInside(validator))
+ .describedAs(
+ "the 3-argument overload is the one production calls; if it bypasses the anchor, "
+ + "nothing else matters")
+ .containsAll(ANCHOR_RULES);
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // 5. AERE D-AMONTE-02: the base-fee import rule is REALLY in the ruleset the factory builds.
+ // It is DETACHED, so without the third, lambda-only level of the reader above it would be
+ // invisible, exactly as PqAnchorDigestRule was on 2026-08-07. Disarmed-by-default: presence
+ // in the ruleset is precisely what must survive, because the rule switches on by HEIGHT.
+ // ---------------------------------------------------------------------------------------------
+ @Test
+ void theFactoryWiresTheBaseFeeImportRule() throws Exception {
+ final List<String> inside =
+ rulesInside(
+ QbftBlockHeaderValidationRulesetFactory.blockHeaderValidator(
+ Duration.ofSeconds(1),
+ false,
+ Optional.of(
+ org.hyperledger.besu.ethereum.mainnet.feemarket.FeeMarket.london(0)),
+ armed())
+ .build());
+
+ assertThat(inside)
+ .describedAs(
+ "the base-fee import rule the QBFT factory upstream forgot; if it is missing, somebody "
+ + "removed the addRule and the one-wei empty-block divergence is back")
+ .contains("AereBaseFeeImportRule");
+ // positive control of the method ON THE SAME CLASS of rule: another detached upstream rule
+ // must be visible through the same lambda peek, otherwise the assertion above proves nothing
+ assertThat(inside).contains("AncestryValidationRule");
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // 6. AERE D-AMONTE-02: arming the property while the chain has NO fee market refuses at
+ // FACTORY time (node startup), through the real production path, never silently.
+ // ---------------------------------------------------------------------------------------------
+ @Test
+ void armingTheBaseFeeRuleWithoutAFeeMarketRefusesAtFactoryTime() {
+ try {
+ System.setProperty(
+ org.hyperledger.besu.consensus.qbft.headervalidationrules.AereBaseFeeImportRule
+ .PROPERTY_FORK_BLOCK,
+ "100");
+ org.assertj.core.api.Assertions.assertThatThrownBy(
+ () ->
+ QbftBlockHeaderValidationRulesetFactory.blockHeaderValidator(
+ Duration.ofSeconds(1), false, Optional.empty(), armed()))
+ .isInstanceOf(IllegalStateException.class)
+ .hasMessageContaining("AERE-BASEFEE-VALIDATE-CONF-02");
+ } finally {
+ System.clearProperty(
+ org.hyperledger.besu.consensus.qbft.headervalidationrules.AereBaseFeeImportRule
+ .PROPERTY_FORK_BLOCK);
+ }
+ }
+}
diff --git a/consensus/qbft/src/test/java/org/hyperledger/besu/consensus/qbft/headervalidationrules/AereBaseFeeImportRuleTest.java b/consensus/qbft/src/test/java/org/hyperledger/besu/consensus/qbft/headervalidationrules/AereBaseFeeImportRuleTest.java
new file mode 100755
index 000000000..a37f63f86
--- /dev/null
+++ b/consensus/qbft/src/test/java/org/hyperledger/besu/consensus/qbft/headervalidationrules/AereBaseFeeImportRuleTest.java
@@ -0,0 +1,142 @@
+/* AERE D-AMONTE-02, the base-fee import rule's proofs.
+ *
+ * The key case REPRODUCES divergence 1bis measured on mixed network 91777: an EMPTY parent at
+ * the 1 Gwei floor, an EMPTY child claiming floor plus ONE WEI. Nethermind rejected it, Besu
+ * swallowed it; with the rule armed, Besu rejects it too. The fee market is the REAL
+ * production one (LondonFeeMarket), with the floor armed through the VERY production path:
+ * system properties read at fee-market construction, set and cleaned in try/finally (the
+ * order-dependent-green lesson). */
+package org.hyperledger.besu.consensus.qbft.headervalidationrules;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+import org.hyperledger.besu.datatypes.Wei;
+import org.hyperledger.besu.ethereum.core.BlockHeader;
+import org.hyperledger.besu.ethereum.core.BlockHeaderTestFixture;
+import org.hyperledger.besu.ethereum.mainnet.feemarket.BaseFeeMarket;
+import org.hyperledger.besu.ethereum.mainnet.feemarket.FeeMarket;
+
+import java.util.Optional;
+
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.Test;
+
+public class AereBaseFeeImportRuleTest {
+
+ private static final long H_ARMING = 10_000L;
+ private static final long FLOOR = 1_000_000_000L; // 1 Gwei, chiar valoarea de pe 2800
+ private static final long GAZ_LIMITA = 30_000_000L;
+
+ @AfterEach
+ public void curata() {
+ System.clearProperty("aere.basefee.floor.forkBlock");
+ System.clearProperty("aere.basefee.floor.value");
+ System.clearProperty(AereBaseFeeImportRule.PROPERTY_FORK_BLOCK);
+ }
+
+ /** The REAL fee market, with the AERE floor armed from block 0 through the production path. */
+ private BaseFeeMarket feeMarketWithFloor() {
+ try {
+ System.setProperty("aere.basefee.floor.forkBlock", "0");
+ System.setProperty("aere.basefee.floor.value", String.valueOf(FLOOR));
+ return FeeMarket.london(0);
+ } finally {
+ System.clearProperty("aere.basefee.floor.forkBlock");
+ System.clearProperty("aere.basefee.floor.value");
+ }
+ }
+
+ private BlockHeader header(final long numar, final long taxa, final long gazFolosit) {
+ return new BlockHeaderTestFixture()
+ .number(numar)
+ .baseFeePerGas(Wei.of(taxa))
+ .gasLimit(GAZ_LIMITA)
+ .gasUsed(gazFolosit)
+ .buildHeader();
+ }
+
+ // ------------------------------------------------------------------- dezarmat = amonte
+
+ @Test
+ public void disarmedAcceptsAnyBaseFeeAnywhere() {
+ final AereBaseFeeImportRule rule =
+ new AereBaseFeeImportRule(AereBaseFeeImportRule.DISARMED, Optional.of(feeMarketWithFloor()));
+ // empty block with a bogus fee: today it passes (the very defect), and disarmed it must pass the same
+ assertThat(rule.validate(header(H_ARMING, FLOOR + 1, 0), header(H_ARMING - 1, FLOOR, 0)))
+ .isTrue();
+ }
+
+ @Test
+ public void disarmedNeedsNoFeeMarket() {
+ // pe un lant pre-London, dezarmat, constructia nu are voie sa cada
+ assertThat(new AereBaseFeeImportRule(AereBaseFeeImportRule.DISARMED, Optional.empty()))
+ .isNotNull();
+ }
+
+ // ------------------------------------------------------------------- armat, sub si peste H
+
+ @Test
+ public void belowArmingHeightHistoryIsUntouched() {
+ final AereBaseFeeImportRule rule =
+ new AereBaseFeeImportRule(H_ARMING, Optional.of(feeMarketWithFloor()));
+ // the same header wrong by 1 wei, but BELOW H: history (the floorless days, the
+ // lost-threshold window) must pass untouched
+ assertThat(rule.validate(header(H_ARMING - 1, FLOOR + 1, 0), header(H_ARMING - 2, FLOOR, 0)))
+ .isTrue();
+ }
+
+ @Test
+ public void armedAcceptsTheFlooredEmptyBlock() {
+ final AereBaseFeeImportRule rule =
+ new AereBaseFeeImportRule(H_ARMING, Optional.of(feeMarketWithFloor()));
+ // empty parent at the floor -> EIP-1559 would decrease, the floor holds the fee at 1 Gwei: the live chain itself
+ assertThat(rule.validate(header(H_ARMING, FLOOR, 0), header(H_ARMING - 1, FLOOR, 0))).isTrue();
+ }
+
+ @Test
+ public void armedRejectsTheOneWeiEmptyBlockDivergence() {
+ final AereBaseFeeImportRule rule =
+ new AereBaseFeeImportRule(H_ARMING, Optional.of(feeMarketWithFloor()));
+ // REPRODUCEREA 1bis: bloc GOL, taxa podea+1. Nethermind o respingea, Besu o inghitea.
+ assertThat(rule.validate(header(H_ARMING, FLOOR + 1, 0), header(H_ARMING - 1, FLOOR, 0)))
+ .isFalse();
+ }
+
+ @Test
+ public void armedRejectsABelowFloorEmptyBlock() {
+ final AereBaseFeeImportRule rule =
+ new AereBaseFeeImportRule(H_ARMING, Optional.of(feeMarketWithFloor()));
+ // 875000000 = the very value the unpatched node wrote in the 17 July proof
+ assertThat(rule.validate(header(H_ARMING, 875_000_000L, 0), header(H_ARMING - 1, FLOOR, 0)))
+ .isFalse();
+ }
+
+ // ------------------------------------------------------------------- refuzurile zgomotoase
+
+ @Test
+ public void armedWithoutFeeMarketRefusesAtConstruction() {
+ assertThatThrownBy(() -> new AereBaseFeeImportRule(H_ARMING, Optional.empty()))
+ .isInstanceOf(IllegalStateException.class)
+ .hasMessageContaining("AERE-BASEFEE-VALIDATE-CONF-02");
+ }
+
+ @Test
+ public void brokenPropertyRefusesLoudly() {
+ try {
+ System.setProperty(AereBaseFeeImportRule.PROPERTY_FORK_BLOCK, "10,141,734");
+ assertThatThrownBy(AereBaseFeeImportRule::armedFromSystemConfig)
+ .isInstanceOf(IllegalStateException.class)
+ .hasMessageContaining("AERE-BASEFEE-VALIDATE-CONF-01");
+ } finally {
+ System.clearProperty(AereBaseFeeImportRule.PROPERTY_FORK_BLOCK);
+ }
+ }
+
+ @Test
+ public void absentPropertyMeansDisarmed() {
+ System.clearProperty(AereBaseFeeImportRule.PROPERTY_FORK_BLOCK);
+ assertThat(AereBaseFeeImportRule.armedFromSystemConfig())
+ .isEqualTo(AereBaseFeeImportRule.DISARMED);
+ }
+}
diff --git a/consensus/qbft/src/test/java/org/hyperledger/besu/consensus/qbft/headervalidationrules/FalconSealLogThrottleTest.java b/consensus/qbft/src/test/java/org/hyperledger/besu/consensus/qbft/headervalidationrules/FalconSealLogThrottleTest.java
new file mode 100755
index 000000000..298b43988
--- /dev/null
+++ b/consensus/qbft/src/test/java/org/hyperledger/besu/consensus/qbft/headervalidationrules/FalconSealLogThrottleTest.java
@@ -0,0 +1,181 @@
+/*
+ * Copyright contributors to Besu / AERE Network.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.qbft.headervalidationrules;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.atomic.AtomicInteger;
+
+import org.junit.jupiter.api.Test;
+
+/**
+ * AERE 2026-08-07: the LOG-ONLY summary must not write one INFO line per block.
+ *
+ * <p>MEASURED ON A LIVE NODE, and that is why this test exists. The rule wrote the summary at INFO
+ * on every imported block: <b>2295 lines in twenty minutes, about 165,000 a day per node</b>, every
+ * one of them identical, {@code 0 of 0 seals, |eligible|=0, no-eligible-signers}. On the old binary
+ * the same twenty minutes had ZERO such lines, so the spam was entirely ours. Seven validators had
+ * just come out of a disk emergency.
+ *
+ * <p>The runbook for putting this binary on the seven has, as its own item 3, "zero new log lines
+ * compared with the old binary". This test is that item, for the part a unit test can hold.
+ */
+class FalconSealLogThrottleTest {
+
+ private static final String STARE_A = "no-eligible-signers|0|0|0|7";
+ private static final String STARE_B = "PQC-quorum-not-yet|3|5|7|7";
+
+ private static int numaraInfo(
+ final FalconSealValidationRule regula, final String state, final long dePeLa, final int cate) {
+ int n = 0;
+ for (int i = 0; i < cate; i++) {
+ if (regula.shouldLogAtInfo(state, dePeLa + i)) {
+ n++;
+ }
+ }
+ return n;
+ }
+
+ @Test
+ void theFirstTimeIsAlwaysWritten() {
+ // Without this, an operator starting the node would NEVER see that the rule is alive.
+ final FalconSealValidationRule r = new FalconSealValidationRule();
+ assertThat(r.shouldLogAtInfo(STARE_A, 12_742_475L)).isTrue();
+ }
+
+ @Test
+ void aThousandBlocksInTheSAMEStateWriteASingleLine() {
+ final FalconSealValidationRule r = new FalconSealValidationRule();
+ // 1000 blocks, well below the heartbeat, so only the first one may come out at INFO
+ assertThat(numaraInfo(r, STARE_A, 1_000L, 1_000)).isEqualTo(1);
+ }
+
+ @Test
+ void aStateChangeIsSEENOnTheBlockWhereItHappens() {
+ final FalconSealValidationRule r = new FalconSealValidationRule();
+ numaraInfo(r, STARE_A, 1_000L, 500);
+ // exactly the block on which it changes, not the next one and not a heartbeat later
+ assertThat(r.shouldLogAtInfo(STARE_B, 1_500L)).isTrue();
+ // and after the change it goes quiet again
+ assertThat(numaraInfo(r, STARE_B, 1_501L, 500)).isEqualTo(0);
+ }
+
+ @Test
+ void andGoingBackToTheOldStateIsSEENToo() {
+ // A regression, that is falling OUT of quorum, matters at least as much as reaching it.
+ final FalconSealValidationRule r = new FalconSealValidationRule();
+ r.shouldLogAtInfo(STARE_A, 1_000L);
+ r.shouldLogAtInfo(STARE_B, 1_001L);
+ assertThat(r.shouldLogAtInfo(STARE_A, 1_002L)).isTrue();
+ }
+
+ @Test
+ void theHeartbeatWritesOneLinePerWindow() {
+ final FalconSealValidationRule r = new FalconSealValidationRule();
+ final long H = FalconSealValidationRule.LOG_HEARTBEAT_BLOCKS;
+ // 5 whole windows, one single state. Expected: the first line plus one per window.
+ int info = 0;
+ for (long b = 0; b < 5 * H; b++) {
+ if (r.shouldLogAtInfo(STARE_A, b)) {
+ info++;
+ }
+ }
+ assertThat(info).isEqualTo(5);
+ }
+
+ @Test
+ void theReductionIsAtLeastAThousandfold() {
+ // The number that matters for the seven hosts, as a proof rather than a claim in a comment.
+ final FalconSealValidationRule r = new FalconSealValidationRule();
+ final int blocuriPeZi = 165_000; // 86400 / 0.523
+ final int info = numaraInfo(r, STARE_A, 1_000L, blocuriPeZi);
+ assertThat(info).isLessThanOrEqualTo(20);
+ assertThat(blocuriPeZi / Math.max(info, 1)).isGreaterThanOrEqualTo(1_000);
+ }
+
+ @Test
+ void itDoesNotChokeWhenTheStateFlipsEveryBlock() {
+ // The bad case: if the state really does change on every block, the line MUST come out on every
+ // block. A throttle that smothered that too would hide exactly the moment we care about.
+ final FalconSealValidationRule r = new FalconSealValidationRule();
+ int info = 0;
+ for (int i = 0; i < 100; i++) {
+ if (r.shouldLogAtInfo(i % 2 == 0 ? STARE_A : STARE_B, 1_000L + i)) {
+ info++;
+ }
+ }
+ assertThat(info).isEqualTo(100);
+ }
+
+ @Test
+ void heightsArrivingOUTOFORDERDoNotTriggerTheHeartbeat() {
+ // Import runs on several threads, so heights do not always arrive in increasing order. A step
+ // backwards makes the difference negative; that must NOT pass the threshold and write an extra
+ // line.
+ final FalconSealValidationRule r = new FalconSealValidationRule();
+ r.shouldLogAtInfo(STARE_A, 1_000_000L);
+ int info = 0;
+ for (long b = 999_999L; b > 999_899L; b--) {
+ if (r.shouldLogAtInfo(STARE_A, b)) {
+ info++;
+ }
+ }
+ assertThat(info).isZero();
+ }
+
+ @Test
+ void underManyThreadsThereIsNeitherAFloodNorSilence() throws Exception {
+ // The rule is called from EthScheduler-Workers-N, so concurrently. I do not ask for perfect
+ // accuracy under races, but I do ask for the two things that matter: no flood, and no SILENCE.
+ final FalconSealValidationRule r = new FalconSealValidationRule();
+ final int fire = 8;
+ final int perFir = 2_000;
+ final AtomicInteger info = new AtomicInteger();
+ final ExecutorService ex = Executors.newFixedThreadPool(fire);
+ final CountDownLatch start = new CountDownLatch(1);
+ final List<Runnable> sarcini = new ArrayList<>();
+ for (int f = 0; f < fire; f++) {
+ final long baza = 1_000L + (long) f * perFir;
+ sarcini.add(
+ () -> {
+ try {
+ start.await();
+ } catch (final InterruptedException e) {
+ Thread.currentThread().interrupt();
+ return;
+ }
+ for (int i = 0; i < perFir; i++) {
+ if (r.shouldLogAtInfo(STARE_A, baza + i)) {
+ info.incrementAndGet();
+ }
+ }
+ });
+ }
+ sarcini.forEach(ex::submit);
+ start.countDown();
+ ex.shutdown();
+ assertThat(ex.awaitTermination(30, TimeUnit.SECONDS)).isTrue();
+ assertThat(info.get()).isGreaterThanOrEqualTo(1);
+ // 16,000 calls; with no throttle that would be 16,000 lines. We require under 1% even under
+ // races.
+ assertThat(info.get()).isLessThan(160);
+ }
+}
diff --git a/consensus/qbft/src/test/java/org/hyperledger/besu/consensus/qbft/headervalidationrules/FalconSealValidationRuleRetirementTest.java b/consensus/qbft/src/test/java/org/hyperledger/besu/consensus/qbft/headervalidationrules/FalconSealValidationRuleRetirementTest.java
new file mode 100755
index 000000000..c03a9489b
--- /dev/null
+++ b/consensus/qbft/src/test/java/org/hyperledger/besu/consensus/qbft/headervalidationrules/FalconSealValidationRuleRetirementTest.java
@@ -0,0 +1,85 @@
+/*
+ * Copyright contributors to Besu / AERE Network.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.qbft.headervalidationrules;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.hyperledger.besu.consensus.qbft.headervalidationrules.PqAnchorTestSupport.H;
+import static org.hyperledger.besu.consensus.qbft.headervalidationrules.PqAnchorTestSupport.extraData;
+import static org.hyperledger.besu.consensus.qbft.headervalidationrules.PqAnchorTestSupport.header;
+import static org.hyperledger.besu.consensus.qbft.headervalidationrules.PqAnchorTestSupport.parentHeader;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.atLeastOnce;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.verifyNoInteractions;
+import static org.mockito.Mockito.withSettings;
+
+import org.hyperledger.besu.ethereum.ProtocolContext;
+import org.hyperledger.besu.ethereum.core.BlockHeader;
+
+import java.util.Collections;
+
+import org.apache.tuweni.bytes.Bytes32;
+import org.junit.jupiter.api.Test;
+import org.mockito.quality.Strictness;
+
+/**
+ * The retirement of the legacy log-only Falcon rule at H.
+ *
+ * <p>The retirement is only worth anything if the gate precedes EVERY state touch, otherwise a node
+ * past H would still be paying for a rule that contributes nothing and still reading historical
+ * world state it may not have. So the test does not merely assert the return value, which is {@code
+ * true} on both sides of the gate and therefore proves nothing on its own: it asserts that above the
+ * retirement height the protocol context is never touched at all, and that below it, it is.
+ */
+public class FalconSealValidationRuleRetirementTest {
+
+ private ProtocolContext context() {
+ return mock(ProtocolContext.class, withSettings().strictness(Strictness.LENIENT));
+ }
+
+ private BlockHeader headerAt(final long number) {
+ return header(
+ number, parentHeader(number - 1L).getHash(), extraData(Bytes32.ZERO, Collections.emptyList()));
+ }
+
+ @Test
+ public void theDefaultConstructorNeverRetires() {
+ assertThat(new FalconSealValidationRule().toString()).contains("retiresAt=NEVER");
+ assertThat(new FalconSealValidationRule(H).toString()).contains("retiresAt=" + H);
+ }
+
+ @Test
+ public void atAndAboveTheRetirementHeightNothingIsTouchedAtAll() {
+ final FalconSealValidationRule rule = new FalconSealValidationRule(H);
+ for (final long number : new long[] {H, H + 1L, H + 5000L}) {
+ final ProtocolContext protocolContext = context();
+ assertThat(rule.validate(headerAt(number), parentHeader(number - 1L), protocolContext))
+ .isTrue();
+ verifyNoInteractions(protocolContext);
+ }
+ }
+
+ @Test
+ public void belowTheRetirementHeightTheRuleStillRunsExactlyAsBefore() {
+ final FalconSealValidationRule rule = new FalconSealValidationRule(H);
+ final ProtocolContext protocolContext = context();
+ // Log-only baseline: it returns true, as it always has, including on its own error paths. That
+ // is precisely why it is being replaced rather than promoted, and precisely why leaving it in
+ // place below H is safe.
+ assertThat(rule.validate(headerAt(H - 1L), parentHeader(H - 2L), protocolContext)).isTrue();
+ verify(protocolContext, atLeastOnce()).getConsensusContext(any());
+ }
+}
diff --git a/consensus/qbft/src/test/java/org/hyperledger/besu/consensus/qbft/headervalidationrules/PqAnchorDigestRuleTest.java b/consensus/qbft/src/test/java/org/hyperledger/besu/consensus/qbft/headervalidationrules/PqAnchorDigestRuleTest.java
new file mode 100755
index 000000000..64ba7f307
--- /dev/null
+++ b/consensus/qbft/src/test/java/org/hyperledger/besu/consensus/qbft/headervalidationrules/PqAnchorDigestRuleTest.java
@@ -0,0 +1,359 @@
+/*
+ * Copyright contributors to Besu / AERE Network.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.qbft.headervalidationrules;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.hyperledger.besu.consensus.qbft.headervalidationrules.PqAnchorTestSupport.CHAIN_ID;
+import static org.hyperledger.besu.consensus.qbft.headervalidationrules.PqAnchorTestSupport.H;
+import static org.hyperledger.besu.consensus.qbft.headervalidationrules.PqAnchorTestSupport.extraData;
+import static org.hyperledger.besu.consensus.qbft.headervalidationrules.PqAnchorTestSupport.header;
+import static org.hyperledger.besu.consensus.qbft.headervalidationrules.PqAnchorTestSupport.honestHeader;
+import static org.hyperledger.besu.consensus.qbft.headervalidationrules.PqAnchorTestSupport.parentHeader;
+import static org.hyperledger.besu.consensus.qbft.headervalidationrules.PqAnchorTestSupport.seal;
+
+import org.hyperledger.besu.consensus.common.bft.BftExtraData;
+import org.hyperledger.besu.consensus.common.bft.FalconSeal;
+import org.hyperledger.besu.consensus.common.bft.PqAnchor;
+import org.hyperledger.besu.consensus.common.bft.PqAnchorConfig;
+import org.hyperledger.besu.consensus.qbft.QbftExtraDataCodec;
+import org.hyperledger.besu.ethereum.core.BlockHeader;
+import org.hyperledger.besu.ethereum.mainnet.BlockHeaderValidator;
+import org.hyperledger.besu.ethereum.mainnet.HeaderValidationMode;
+
+import java.util.Collections;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.OptionalInt;
+
+import org.apache.tuweni.bytes.Bytes;
+import org.apache.tuweni.bytes.Bytes32;
+import org.junit.jupiter.api.Test;
+
+/**
+ * R1, the anchor digest rule.
+ *
+ * <p>Two of these tests are the reason the whole V2 scheme exists, and both are asserted twice: once
+ * through the rule directly, and once through a real {@link BlockHeaderValidator} running in a LIGHT
+ * validation mode, because "caught in full validation" would not be good enough.
+ *
+ * <p>READ THE SCOPE OF THAT SECOND ASSERTION EXACTLY, because an earlier version of this comment did
+ * not, and said instead that a node which fast-syncs headers must catch these too. What the assertion
+ * says is narrower: when a {@link BlockHeaderValidator} is asked to validate this header in mode
+ * LIGHT, this rule runs and refuses. It does NOT say that any Besu sync path asks in that mode, and a
+ * green suite here is not evidence that a syncing node is protected. What protects a syncing node is
+ * measured elsewhere and lives in other files: the open-ended-range fix in {@code
+ * DownloadHeadersStep}, {@code PqAnchorDigestAttachedRule} on the attached side, and {@code
+ * PqAnchorSyncModeGuard} refusing to start outside FULL sync.
+ */
+public class PqAnchorDigestRuleTest {
+
+ private final PqAnchorConfig armed =
+ new PqAnchorConfig(CHAIN_ID, H, Map.of(H, 0, H + 100L, 3), OptionalInt.empty(), false);
+ private final PqAnchorDigestRule rule = new PqAnchorDigestRule(armed);
+ private final QbftExtraDataCodec codec = new QbftExtraDataCodec();
+
+ private static final List<FalconSeal> QUORUM = List.of(seal(0), seal(1), seal(2), seal(3), seal(4));
+
+ // ---------------------------------------------------------------------------------------------
+ // The property that makes this binary safe to warm on a live node.
+ // ---------------------------------------------------------------------------------------------
+
+ @Test
+ public void belowHTheRuleIsInertEvenOnHeadersItWouldOtherwiseReject() {
+ final BlockHeader parent = parentHeader(H - 2L);
+ // Vanity is the client version string this chain actually writes today, and there is no
+ // certificate at all: precisely the shape of all 11.8 million existing blocks.
+ final Bytes legacyVanity =
+ Bytes.fromHexString(
+ "0x000000000000626573752030302e302d646576656c6f702d7878787878787878");
+ final BlockHeader legacyShaped =
+ header(H - 1L, parent.getHash(), extraData(legacyVanity, Collections.emptyList()));
+ assertThat(rule.validate(legacyShaped, parent)).isTrue();
+
+ // And a header just below H whose vanity is pure garbage relative to its certificate is still
+ // accepted, because below H the rule does not even decode.
+ final BlockHeader garbage =
+ header(H - 1L, parent.getHash(), extraData(Bytes32.random(), QUORUM));
+ assertThat(rule.validate(garbage, parent)).isTrue();
+ }
+
+ @Test
+ public void anUnconfiguredAnchorIsInertAtEveryHeight() {
+ final PqAnchorDigestRule inert = new PqAnchorDigestRule(PqAnchorConfig.never(CHAIN_ID));
+ final BlockHeader parent = parentHeader(H + 4L);
+ final BlockHeader tampered =
+ header(H + 5L, parent.getHash(), extraData(Bytes32.random(), QUORUM));
+ assertThat(inert.validate(tampered, parent)).isTrue();
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // Honest headers.
+ // ---------------------------------------------------------------------------------------------
+
+ @Test
+ public void acceptsAnHonestHeaderAtAndAboveH() {
+ final BlockHeader parent = parentHeader(H - 1L);
+ assertThat(rule.validate(honestHeader(H, parent.getHash(), QUORUM), parent)).isTrue();
+
+ final BlockHeader laterParent = parentHeader(H + 500L);
+ assertThat(rule.validate(honestHeader(H + 501L, laterParent.getHash(), QUORUM), laterParent))
+ .isTrue();
+ }
+
+ @Test
+ public void acceptsAnEmptyCertificateAtTheActivationHeightItself() {
+ // Block H's parent predates the scheme, so C is legitimately empty and D is the digest of the
+ // empty list. "Explicitly empty" and "absent" are one object because of the codec's canonical
+ // round-trip gate, so there is no second acceptable byte string here.
+ final BlockHeader parent = parentHeader(H - 1L);
+ final BlockHeader block = honestHeader(H, parent.getHash(), Collections.emptyList());
+ assertThat(rule.validate(block, parent)).isTrue();
+ assertThat(codec.decodeRaw(block.getExtraData()).getFalconSeals()).isEmpty();
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // A1: the certificate is STRIPPED. Required by the mission to be caught in LIGHT validation.
+ // ---------------------------------------------------------------------------------------------
+
+ @Test
+ public void aStrippedCertificateIsRejected() {
+ final BlockHeader parent = parentHeader(H + 9L);
+ final BlockHeader honest = honestHeader(H + 10L, parent.getHash(), QUORUM);
+ final BlockHeader stripped = stripCertificate(honest);
+
+ // The tamper is real: the certificate is gone, and vanityData is untouched.
+ assertThat(codec.decodeRaw(honest.getExtraData()).getFalconSeals()).hasSize(5);
+ assertThat(codec.decodeRaw(stripped.getExtraData()).getFalconSeals()).isEmpty();
+ assertThat(codec.decodeRaw(stripped.getExtraData()).getVanityData())
+ .isEqualTo(codec.decodeRaw(honest.getExtraData()).getVanityData());
+
+ assertThat(rule.validate(honest, parent)).isTrue();
+ assertThat(rule.validate(stripped, parent)).isFalse();
+ }
+
+ @Test
+ public void aStrippedCertificateIsCaughtInLightValidation() {
+ final BlockHeader parent = parentHeader(H + 9L);
+ final BlockHeader stripped = stripCertificate(honestHeader(H + 10L, parent.getHash(), QUORUM));
+ assertRejectedInEveryLightMode(stripped, parent);
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // A2: the certificate is REPLACED by an equally valid one over a different subset.
+ // Required by the mission to be caught in LIGHT validation.
+ // ---------------------------------------------------------------------------------------------
+
+ @Test
+ public void anEquallyValidDifferentSubsetIsRejected() {
+ final BlockHeader parent = parentHeader(H + 9L);
+ final List<FalconSeal> subsetA = List.of(seal(0), seal(1), seal(2), seal(3), seal(4));
+ final List<FalconSeal> subsetB = List.of(seal(0), seal(1), seal(2), seal(3), seal(5));
+ final BlockHeader honest = honestHeader(H + 10L, parent.getHash(), subsetA);
+ final BlockHeader swapped = replaceCertificate(honest, subsetB);
+
+ // Both certificates are well formed, both are the same size, both have strictly increasing
+ // indices, and the block hash pre-image does not contain either of them. Only D separates them.
+ assertThat(codec.decodeRaw(swapped.getExtraData()).getFalconSeals()).hasSize(5);
+ assertThat(PqAnchor.hasStrictlyIncreasingIndices(subsetB)).isTrue();
+
+ assertThat(rule.validate(honest, parent)).isTrue();
+ assertThat(rule.validate(swapped, parent)).isFalse();
+ }
+
+ @Test
+ public void anEquallyValidDifferentSubsetIsCaughtInLightValidation() {
+ final BlockHeader parent = parentHeader(H + 9L);
+ final BlockHeader swapped =
+ replaceCertificate(
+ honestHeader(H + 10L, parent.getHash(), List.of(seal(0), seal(1), seal(2), seal(3), seal(4))),
+ List.of(seal(0), seal(1), seal(2), seal(3), seal(5)));
+ assertRejectedInEveryLightMode(swapped, parent);
+ }
+
+ @Test
+ public void aSubstitutedSignatureUnderTheSameIndexIsRejected() {
+ // The subset is identical; only one signature's bytes differ. A verifier that only counted valid
+ // signatures would accept this; the digest does not.
+ final BlockHeader parent = parentHeader(H + 9L);
+ final List<FalconSeal> original = List.of(seal(0), seal(1), seal(2));
+ final List<FalconSeal> substituted =
+ List.of(seal(0), seal(1), new FalconSeal(2, PqAnchorTestSupport.signature(2, 7)));
+ final BlockHeader swapped =
+ replaceCertificate(honestHeader(H + 10L, parent.getHash(), original), substituted);
+ assertThat(rule.validate(swapped, parent)).isFalse();
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // A3 / A4: order and duplication.
+ // ---------------------------------------------------------------------------------------------
+
+ @Test
+ public void aReorderedCertificateIsRejected() {
+ final BlockHeader parent = parentHeader(H + 9L);
+ final BlockHeader honest = honestHeader(H + 10L, parent.getHash(), QUORUM);
+ final BlockHeader reordered =
+ replaceCertificate(honest, List.of(seal(4), seal(3), seal(2), seal(1), seal(0)));
+ assertThat(rule.validate(reordered, parent)).isFalse();
+ assertRejectedInEveryLightMode(reordered, parent);
+ }
+
+ @Test
+ public void aRepeatedIndexIsRejectedEvenWhenTheDigestIsRecomputedOverIt() {
+ // An attacker who controls the proposer could try to inflate k by repeating a seal AND writing
+ // the matching digest. The strictly increasing requirement refuses it before the digest is even
+ // compared, so inflation is unrepresentable rather than filtered.
+ final BlockHeader parent = parentHeader(H + 9L);
+ final List<FalconSeal> doubled =
+ List.of(seal(0), seal(1), new FalconSeal(1, PqAnchorTestSupport.signature(1, 3)));
+ final Bytes32 digest = PqAnchor.anchorDigest(CHAIN_ID, H + 9L, parent.getHash().getBytes(), doubled);
+ final BlockHeader forged = header(H + 10L, parent.getHash(), extraData(digest, doubled));
+ assertThat(rule.validate(forged, parent)).isFalse();
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // Binding, and fail-closed behaviour.
+ // ---------------------------------------------------------------------------------------------
+
+ @Test
+ public void theDigestIsBoundToTheParentThisHeaderNames() {
+ final BlockHeader parent = parentHeader(H + 9L);
+ final BlockHeader other = parentHeader(H + 9L + 1L);
+ final BlockHeader honest = honestHeader(H + 10L, parent.getHash(), QUORUM);
+ // Same certificate, same height, different parent hash: the digest no longer matches.
+ final BlockHeader rehomed =
+ header(H + 10L, other.getHash(), honest.getExtraData());
+ assertThat(rule.validate(rehomed, other)).isFalse();
+ }
+
+ @Test
+ public void theDigestIsBoundToTheChainId() {
+ // A6: the 442807 proving chain runs the same binaries and can run the same Falcon keys.
+ final BlockHeader parent = parentHeader(H + 9L);
+ final List<FalconSeal> certificate = PqAnchor.sortedByIndex(QUORUM);
+ final Bytes32 foreignDigest =
+ PqAnchor.anchorDigest(442807L, H + 9L, parent.getHash().getBytes(), certificate);
+ final BlockHeader foreign =
+ header(H + 10L, parent.getHash(), extraData(foreignDigest, certificate));
+ assertThat(rule.validate(foreign, parent)).isFalse();
+ }
+
+ @Test
+ public void aVanityFieldThatIsNotThirtyTwoBytesIsRejected() {
+ final BlockHeader parent = parentHeader(H + 9L);
+ final BlockHeader shortVanity =
+ header(H + 10L, parent.getHash(), extraData(Bytes.repeat((byte) 0x11, 31), QUORUM));
+ assertThat(rule.validate(shortVanity, parent)).isFalse();
+ }
+
+ @Test
+ public void undecodableExtraDataIsRejectedRatherThanAccepted() {
+ // BELOW its fork height, and only there, the legacy Falcon rule returned true on every path
+ // including the exception path, so in the only regime this chain has ever run it never caught
+ // anything. At and after the fork block WITH an active registry it is instead BLOCKING and does
+ // return false, on four paths including the exception path (measured by reading
+ // FalconSealValidationRule: blocking = forkReached && registryActive, then four `return false`
+ // sites inside validate). That mode has never been armed on this chain and must not be armed at
+ // the same time as the V2 anchor. A rule that cannot compute its verdict has not proved the
+ // header good.
+ final BlockHeader parent = parentHeader(H + 9L);
+ final BlockHeader broken =
+ header(H + 10L, parent.getHash(), Bytes.fromHexString("0xdeadbeef"));
+ assertThat(rule.validate(broken, parent)).isFalse();
+
+ final BlockHeader empty = header(H + 10L, parent.getHash(), Bytes.EMPTY);
+ assertThat(rule.validate(empty, parent)).isFalse();
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // The light-validation property itself.
+ // ---------------------------------------------------------------------------------------------
+
+ @Test
+ public void includeInLightValidationIsTrue() {
+ assertThat(rule.includeInLightValidation()).isTrue();
+ }
+
+ @Test
+ public void anHonestHeaderStillPassesEveryLightMode() {
+ // The negative control for assertRejectedInEveryLightMode: if the modes below rejected
+ // everything, the rejection tests would prove nothing.
+ final BlockHeader parent = parentHeader(H + 9L);
+ final BlockHeader honest = honestHeader(H + 10L, parent.getHash(), QUORUM);
+ final BlockHeaderValidator validator =
+ new BlockHeaderValidator.Builder().addRule(rule).build();
+ for (final HeaderValidationMode mode :
+ List.of(
+ HeaderValidationMode.LIGHT_DETACHED_ONLY,
+ HeaderValidationMode.LIGHT,
+ HeaderValidationMode.DETACHED_ONLY,
+ HeaderValidationMode.FULL)) {
+ assertThat(validator.validateHeader(honest, parent, null, mode))
+ .withFailMessage("honest header should pass in mode %s", mode)
+ .isTrue();
+ }
+ }
+
+ @Test
+ public void theRuleIsSkippedByTheModesThatSkipDetachedRules() {
+ // Stating the shape honestly: LIGHT_SKIP_DETACHED and SKIP_DETACHED exclude every detached rule,
+ // so R1 does not run there. Those modes are the "attached half" of a split validation whose
+ // other half already ran R1, which is why this is not a hole.
+ final BlockHeader parent = parentHeader(H + 9L);
+ final BlockHeader stripped = stripCertificate(honestHeader(H + 10L, parent.getHash(), QUORUM));
+ final BlockHeaderValidator validator =
+ new BlockHeaderValidator.Builder().addRule(rule).build();
+ assertThat(
+ validator.validateHeader(
+ stripped, parent, null, HeaderValidationMode.LIGHT_SKIP_DETACHED))
+ .isTrue();
+ assertThat(validator.validateHeader(stripped, parent, null, HeaderValidationMode.SKIP_DETACHED))
+ .isTrue();
+ }
+
+ private void assertRejectedInEveryLightMode(final BlockHeader header, final BlockHeader parent) {
+ final BlockHeaderValidator validator =
+ new BlockHeaderValidator.Builder().addRule(rule).build();
+ for (final HeaderValidationMode mode :
+ List.of(
+ HeaderValidationMode.LIGHT_DETACHED_ONLY,
+ HeaderValidationMode.LIGHT,
+ HeaderValidationMode.DETACHED_ONLY,
+ HeaderValidationMode.FULL)) {
+ assertThat(validator.validateHeader(header, parent, null, mode))
+ .withFailMessage("tampered header should be rejected in mode %s", mode)
+ .isFalse();
+ }
+ }
+
+ private BlockHeader stripCertificate(final BlockHeader honest) {
+ return replaceCertificate(honest, Collections.emptyList());
+ }
+
+ private BlockHeader replaceCertificate(
+ final BlockHeader honest, final List<FalconSeal> certificate) {
+ final BftExtraData original = codec.decodeRaw(honest.getExtraData());
+ final Bytes tampered =
+ codec.encode(
+ new BftExtraData(
+ original.getVanityData(),
+ original.getSeals(),
+ Optional.empty(),
+ original.getRound(),
+ original.getValidators(),
+ certificate));
+ return header(honest.getNumber(), honest.getParentHash(), tampered);
+ }
+}
diff --git a/consensus/qbft/src/test/java/org/hyperledger/besu/consensus/qbft/headervalidationrules/PqAnchorDisarmedWindowTest.java b/consensus/qbft/src/test/java/org/hyperledger/besu/consensus/qbft/headervalidationrules/PqAnchorDisarmedWindowTest.java
new file mode 100755
index 000000000..9451ec7b7
--- /dev/null
+++ b/consensus/qbft/src/test/java/org/hyperledger/besu/consensus/qbft/headervalidationrules/PqAnchorDisarmedWindowTest.java
@@ -0,0 +1,548 @@
+/*
+ * Copyright contributors to Besu / Aere Network.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.qbft.headervalidationrules;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.hyperledger.besu.consensus.qbft.headervalidationrules.PqAnchorTestSupport.CHAIN_ID;
+import static org.hyperledger.besu.consensus.qbft.headervalidationrules.PqAnchorTestSupport.VALIDATORS;
+import static org.hyperledger.besu.consensus.qbft.headervalidationrules.PqAnchorTestSupport.extraData;
+import static org.hyperledger.besu.consensus.qbft.headervalidationrules.PqAnchorTestSupport.header;
+import static org.hyperledger.besu.consensus.qbft.headervalidationrules.PqAnchorTestSupport.parentHeader;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+import static org.mockito.Mockito.withSettings;
+
+import org.hyperledger.besu.consensus.common.bft.BftContext;
+import org.hyperledger.besu.consensus.common.bft.FalconSeal;
+import org.hyperledger.besu.consensus.common.bft.PqAnchor;
+import org.hyperledger.besu.consensus.common.bft.PqAnchorConfig;
+import org.hyperledger.besu.consensus.common.bft.PqAnchorLapse;
+import org.hyperledger.besu.consensus.common.bft.PqSignerRegistry;
+import org.hyperledger.besu.consensus.common.validator.ValidatorProvider;
+import org.hyperledger.besu.datatypes.Address;
+import org.hyperledger.besu.ethereum.ProtocolContext;
+import org.hyperledger.besu.ethereum.core.BlockHeader;
+
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.OptionalInt;
+
+import org.apache.tuweni.bytes.Bytes;
+import org.apache.tuweni.bytes.Bytes32;
+import org.junit.jupiter.api.Test;
+import org.mockito.quality.Strictness;
+
+/**
+ * The two historical ranges in which the anchor rules were not fully in force, as the two rules see
+ * them.
+ *
+ * <p>The configuration here is the one the live chain runs, not the small synthetic one the other
+ * rule tests use, because the whole subject is a set of REAL heights: the activation height, the
+ * 32-block anchor spacing and the threshold schedule all have to be the production ones, or the
+ * heights under test are not anchor heights at all and every assertion below would pass on a rule
+ * that does nothing. {@link #everyHeightUnderTestIsAnAnchorHeightOfTheLiveConfiguration()} is the
+ * positive control for exactly that.
+ *
+ * <p>Every acceptance in this file is paired with the same header shape at a height where it must
+ * still be refused, and every refusal is paired with an honest header at that same height, which
+ * must still be accepted. Without the first pairing the tests would pass on a rule that accepts
+ * everything; without the second they would pass on a rule that refuses everything.
+ */
+public class PqAnchorDisarmedWindowTest {
+
+ /** The live activation height H. */
+ private static final long H_LIVE = 13_014_000L;
+
+ /** The live anchor spacing. */
+ private static final int INTERVAL = 32;
+
+ /** The last anchor height fully under the rules before the interruption. */
+ private static final long BEFORE = 13_267_792L;
+
+ /** First height of the range in which nothing was in force. */
+ private static final long OFF_FIRST = 13_267_824L;
+
+ /** A height in the middle of that range. */
+ private static final long OFF_MIDDLE = 13_268_016L;
+
+ /** Last height of that range. */
+ private static final long OFF_LAST = 13_268_944L;
+
+ /** First height of the range in which only the threshold was lowered. */
+ private static final long LOW_FIRST = 13_268_976L;
+
+ /** A height in the middle of that range. */
+ private static final long LOW_MIDDLE = 13_500_016L;
+
+ /** Last height of that range. */
+ private static final long LOW_LAST = 13_890_544L;
+
+ /** The first anchor height fully under the rules again. */
+ private static final long AFTER = 13_890_576L;
+
+ /**
+ * The vanityData the headers of the first range actually carry: the client's version string,
+ * which is what a node writes when the anchor is switched off. Read off a live header of the
+ * range.
+ */
+ private static final Bytes CLIENT_VANITY =
+ Bytes.fromHexString("0x00000000000000626573752032362e372d646576656c6f702d64323033323031");
+
+ /** Signer indices exactly as one header of the first range carries them: distinct, not sorted. */
+ private static final List<Integer> ARRIVAL_ORDER = List.of(2, 6, 1);
+
+ /** A second measured arrival order, from another header of the same range. */
+ private static final List<Integer> ARRIVAL_ORDER_2 = List.of(1, 3, 6, 0);
+
+ private final PqAnchorConfig live =
+ new PqAnchorConfig(
+ CHAIN_ID,
+ H_LIVE,
+ Map.of(H_LIVE, 0, 13_034_000L, 3),
+ OptionalInt.empty(),
+ false,
+ OptionalInt.empty(),
+ OptionalInt.of(INTERVAL));
+
+ private final LocalRegistry registry = new LocalRegistry();
+ private final PqAnchorDigestRule r1 = new PqAnchorDigestRule(live);
+ private final PqAnchorSealsRule r2 = new PqAnchorSealsRule(live, registry);
+
+ // -----------------------------------------------------------------------------------------------
+ // The heights under test really are anchor heights. Without this the file measures nothing.
+ // -----------------------------------------------------------------------------------------------
+
+ @Test
+ public void everyHeightUnderTestIsAnAnchorHeightOfTheLiveConfiguration() {
+ for (final long height :
+ List.of(BEFORE, OFF_FIRST, OFF_MIDDLE, OFF_LAST, LOW_FIRST, LOW_MIDDLE, LOW_LAST, AFTER)) {
+ assertThat(live.anchorAppliesAt(height))
+ .describedAs("height %d must be one the rules judge, or this file proves nothing", height)
+ .isTrue();
+ assertThat(live.minSealsAt(height))
+ .describedAs("the schedule asks for three seals at height %d", height)
+ .isEqualTo(3);
+ }
+ assertThat(PqAnchorLapse.isDisarmed(OFF_FIRST)).isTrue();
+ assertThat(PqAnchorLapse.isDisarmed(OFF_LAST)).isTrue();
+ assertThat(PqAnchorLapse.isDisarmed(BEFORE)).isFalse();
+ assertThat(PqAnchorLapse.isDisarmed(LOW_FIRST)).isFalse();
+ assertThat(PqAnchorLapse.historicMinSeals(LOW_FIRST)).hasValue(1);
+ assertThat(PqAnchorLapse.historicMinSeals(AFTER)).isEmpty();
+ }
+
+ // -----------------------------------------------------------------------------------------------
+ // RANGE 1, nothing in force: a header of the shape the chain holds is accepted by both rules.
+ // -----------------------------------------------------------------------------------------------
+
+ @Test
+ public void r1AcceptsAHeaderOfTheFirstRangeAsWritten() {
+ for (final long height : List.of(OFF_FIRST, OFF_MIDDLE, OFF_LAST)) {
+ final BlockHeader parent = parentHeader(height - 1L);
+ final BlockHeader block = unenforcedHeader(height, parent, ARRIVAL_ORDER);
+ assertThat(r1.validate(block, parent))
+ .describedAs(
+ "height %d carries the client version string in vanityData and a certificate in "
+ + "arrival order; that is what the chain holds, and a node syncing from genesis "
+ + "must be able to pass it",
+ height)
+ .isTrue();
+ }
+ }
+
+ @Test
+ public void r2AcceptsAHeaderOfTheFirstRangeAsWritten() {
+ for (final long height : List.of(OFF_FIRST, OFF_MIDDLE, OFF_LAST)) {
+ final BlockHeader parent = parentHeader(height - 1L);
+ final BlockHeader block = unenforcedHeader(height, parent, ARRIVAL_ORDER);
+ assertThat(r2.validate(block, parent, contextWith(VALIDATORS)))
+ .describedAs("height %d must pass the seals rule too, or the node stops 32 blocks on", height)
+ .isTrue();
+ }
+ }
+
+ @Test
+ public void bothRulesAcceptTheSecondMeasuredArrivalOrder() {
+ final BlockHeader parent = parentHeader(OFF_MIDDLE - 1L);
+ final BlockHeader block = unenforcedHeader(OFF_MIDDLE, parent, ARRIVAL_ORDER_2);
+ assertThat(r1.validate(block, parent)).isTrue();
+ assertThat(r2.validate(block, parent, contextWith(VALIDATORS))).isTrue();
+ }
+
+ @Test
+ public void insideTheFirstRangeTheThresholdIsNotAppliedEither() {
+ // The threshold is one of the things that was switched off, so a header of this range may carry
+ // fewer seals than K. The schedule asks three; this certificate carries one.
+ final BlockHeader parent = parentHeader(OFF_FIRST - 1L);
+ final BlockHeader block = unenforcedHeader(OFF_FIRST, parent, List.of(4));
+ assertThat(r2.validate(block, parent, contextWith(VALIDATORS))).isTrue();
+ }
+
+ @Test
+ public void insideTheFirstRangeAnHonestHeaderIsStillAccepted() {
+ // The exception must not break the ordinary case: a correctly written header that happens to
+ // fall inside the range is accepted too, so nothing has to be re-produced.
+ final BlockHeader parent = parentHeader(OFF_FIRST - 1L);
+ final BlockHeader block = honestBlock(OFF_FIRST, parent, List.of(0, 1, 2));
+ assertThat(r1.validate(block, parent)).isTrue();
+ assertThat(r2.validate(block, parent, contextWith(VALIDATORS))).isTrue();
+ }
+
+ // -----------------------------------------------------------------------------------------------
+ // RANGE 2, only the threshold lowered: the digest and the ordering are STILL required, and the
+ // short certificate is accepted down to the floor that was really in force, and no further.
+ // -----------------------------------------------------------------------------------------------
+
+ @Test
+ public void insideTheSecondRangeTheDigestIsStillRequired() {
+ // This is the assertion that stops the first range's relaxation from leaking into the second.
+ // If it ever passes, the binding has been thrown away on 19,425 anchor heights.
+ for (final long height : List.of(LOW_FIRST, LOW_MIDDLE, LOW_LAST)) {
+ final BlockHeader parent = parentHeader(height - 1L);
+ final BlockHeader noDigest = unenforcedHeader(height, parent, List.of(0, 1, 2));
+ assertThat(r1.validate(noDigest, parent))
+ .describedAs("height %d is inside the lowered-threshold range, where the digest DID hold", height)
+ .isFalse();
+
+ // Positive control at the same height.
+ assertThat(r1.validate(honestBlock(height, parent, List.of(0, 1, 2)), parent)).isTrue();
+ }
+ }
+
+ @Test
+ public void insideTheSecondRangeTheOrderingIsStillRequired() {
+ final BlockHeader parent = parentHeader(LOW_MIDDLE - 1L);
+ final ProtocolContext context = contextWith(VALIDATORS);
+ final BlockHeader unsorted = digestBoundButUnsorted(LOW_MIDDLE, parent, ARRIVAL_ORDER);
+ assertThat(r2.validate(unsorted, parent, context)).isFalse();
+ assertThat(r2.validate(honestBlock(LOW_MIDDLE, parent, List.of(1, 2, 6)), parent, context))
+ .isTrue();
+ }
+
+ @Test
+ public void insideTheSecondRangeAShortCertificateIsAccepted() {
+ // Measured: 2,926 of the 19,425 anchor heights of this range carry one or two seals where the
+ // schedule asks three, because the fleet was running with the emergency ceiling lowered.
+ for (final long height : List.of(LOW_FIRST, LOW_MIDDLE, LOW_LAST)) {
+ final BlockHeader parent = parentHeader(height - 1L);
+ final ProtocolContext context = contextWith(VALIDATORS);
+ assertThat(live.minSealsAt(height)).isEqualTo(3);
+
+ assertThat(r2.validate(honestBlock(height, parent, List.of(0, 1)), parent, context))
+ .describedAs("two seals at height %d, the count actually written there", height)
+ .isTrue();
+ assertThat(r2.validate(honestBlock(height, parent, List.of(5)), parent, context))
+ .describedAs("one seal at height %d, the lowest count measured anywhere in the range", height)
+ .isTrue();
+ }
+ }
+
+ @Test
+ public void insideTheSecondRangeAnEmptyCertificateIsStillRefused() {
+ // The floor is ONE, not zero, because one is the ceiling that was actually in force and no
+ // header of the range carries zero. A floor of zero would accept an empty certificate where a
+ // certificate was in fact required, which is weaker than the history needs.
+ final BlockHeader parent = parentHeader(LOW_MIDDLE - 1L);
+ final ProtocolContext context = contextWith(VALIDATORS);
+ assertThat(r2.validate(honestBlock(LOW_MIDDLE, parent, List.of()), parent, context)).isFalse();
+ assertThat(r2.validate(honestBlock(LOW_MIDDLE, parent, List.of(0)), parent, context)).isTrue();
+ }
+
+ @Test
+ public void insideTheSecondRangeAnInvalidSignatureIsStillRefused() {
+ // Only the COUNT moves. Every seal still has to verify, and still has to belong to a validator
+ // of the parent.
+ final BlockHeader parent = parentHeader(LOW_MIDDLE - 1L);
+ final ProtocolContext context = contextWith(VALIDATORS);
+ final List<FalconSeal> bad = List.of(new FalconSeal(0, Bytes.repeat((byte) 0x5a, 655)));
+ final Bytes32 digest =
+ PqAnchor.anchorDigest(CHAIN_ID, parent.getNumber(), parent.getHash().getBytes(), bad);
+ final BlockHeader block = header(LOW_MIDDLE, parent.getHash(), extraData(digest, bad));
+ assertThat(r2.validate(block, parent, context)).isFalse();
+ assertThat(r2.validate(honestBlock(LOW_MIDDLE, parent, List.of(0)), parent, context)).isTrue();
+ }
+
+ // -----------------------------------------------------------------------------------------------
+ // OUTSIDE both ranges: nothing changed at all.
+ // -----------------------------------------------------------------------------------------------
+
+ @Test
+ public void outsideBothRangesAHeaderWithNoDigestIsStillRefusedByR1() {
+ for (final long height : List.of(BEFORE, LOW_FIRST, AFTER)) {
+ final BlockHeader parent = parentHeader(height - 1L);
+ final BlockHeader block = unenforcedHeader(height, parent, ARRIVAL_ORDER);
+ assertThat(r1.validate(block, parent))
+ .describedAs(
+ "height %d is outside the range where nothing was in force, so a header with no "
+ + "digest must still stop this node; that is what a NEW lapse looks like",
+ height)
+ .isFalse();
+
+ final BlockHeader honest = honestBlock(height, parent, List.of(0, 1, 2));
+ assertThat(r1.validate(honest, parent))
+ .describedAs("an honest header at height %d is still accepted", height)
+ .isTrue();
+ }
+ }
+
+ @Test
+ public void outsideBothRangesTheSameShapeIsStillRefusedByR2() {
+ for (final long height : List.of(BEFORE, LOW_FIRST, AFTER)) {
+ final BlockHeader parent = parentHeader(height - 1L);
+ final ProtocolContext context = contextWith(VALIDATORS);
+ final BlockHeader block = unenforcedHeader(height, parent, ARRIVAL_ORDER);
+ assertThat(r2.validate(block, parent, context))
+ .describedAs("height %d is outside the disarmed range, so unsorted indices are refused", height)
+ .isFalse();
+
+ final BlockHeader honest = honestBlock(height, parent, List.of(0, 1, 2));
+ assertThat(r2.validate(honest, parent, context))
+ .describedAs("an honest header at height %d is still accepted", height)
+ .isTrue();
+ }
+ }
+
+ @Test
+ public void afterBothRangesTheFullThresholdIsBack() {
+ // One anchor step past the end of the lowered range the schedule applies again, unchanged.
+ // This is the assertion that stops the lowered threshold from becoming permanent.
+ final BlockHeader parent = parentHeader(AFTER - 1L);
+ final ProtocolContext context = contextWith(VALIDATORS);
+ assertThat(live.minSealsAt(AFTER)).isEqualTo(3);
+ assertThat(r2.validate(honestBlock(AFTER, parent, List.of(0, 1)), parent, context)).isFalse();
+ assertThat(r2.validate(honestBlock(AFTER, parent, List.of(0, 1, 2)), parent, context)).isTrue();
+ }
+
+ @Test
+ public void wellBeyondTheRangesNothingIsRelaxed() {
+ final long far = 14_077_008L;
+ assertThat(live.anchorAppliesAt(far)).isTrue();
+ final BlockHeader parent = parentHeader(far - 1L);
+ final ProtocolContext context = contextWith(VALIDATORS);
+ assertThat(r1.validate(unenforcedHeader(far, parent, ARRIVAL_ORDER), parent)).isFalse();
+ assertThat(r2.validate(honestBlock(far, parent, List.of(0, 1)), parent, context)).isFalse();
+ assertThat(r2.validate(honestBlock(far, parent, List.of(0, 1, 2)), parent, context)).isTrue();
+ }
+
+ // -----------------------------------------------------------------------------------------------
+ // The bounds are exact, to one anchor step and to one block.
+ // -----------------------------------------------------------------------------------------------
+
+ @Test
+ public void theBoundsAreExactToOneAnchorStep() {
+ assertThat(BEFORE + INTERVAL).isEqualTo(OFF_FIRST);
+ assertThat(OFF_LAST + INTERVAL).isEqualTo(LOW_FIRST);
+ assertThat(LOW_LAST + INTERVAL).isEqualTo(AFTER);
+
+ final BlockHeader beforeParent = parentHeader(BEFORE - 1L);
+ assertThat(r1.validate(unenforcedHeader(BEFORE, beforeParent, ARRIVAL_ORDER), beforeParent))
+ .isFalse();
+
+ final BlockHeader firstParent = parentHeader(OFF_FIRST - 1L);
+ assertThat(r1.validate(unenforcedHeader(OFF_FIRST, firstParent, ARRIVAL_ORDER), firstParent))
+ .isTrue();
+
+ final BlockHeader lastParent = parentHeader(OFF_LAST - 1L);
+ assertThat(r1.validate(unenforcedHeader(OFF_LAST, lastParent, ARRIVAL_ORDER), lastParent))
+ .isTrue();
+
+ final BlockHeader lowParent = parentHeader(LOW_FIRST - 1L);
+ assertThat(r1.validate(unenforcedHeader(LOW_FIRST, lowParent, ARRIVAL_ORDER), lowParent))
+ .isFalse();
+
+ // And the far end of the lowered range, to one anchor step, on the threshold.
+ final BlockHeader lowLastParent = parentHeader(LOW_LAST - 1L);
+ final ProtocolContext context = contextWith(VALIDATORS);
+ assertThat(r2.validate(honestBlock(LOW_LAST, lowLastParent, List.of(0)), lowLastParent, context))
+ .isTrue();
+ final BlockHeader afterParent = parentHeader(AFTER - 1L);
+ assertThat(r2.validate(honestBlock(AFTER, afterParent, List.of(0)), afterParent, context))
+ .isFalse();
+ }
+
+ @Test
+ public void theBoundsAreExactToOneBlockOnBothRules() {
+ // The heights either side of the bounds are not anchor heights, so both rules stand down there
+ // for the ordinary reason. Asserted so that "accepted" at OFF_FIRST - 1 is not mistaken for the
+ // exception having leaked one block down.
+ assertThat(live.anchorAppliesAt(OFF_FIRST - 1L)).isFalse();
+ assertThat(live.anchorAppliesAt(OFF_LAST + 1L)).isFalse();
+ assertThat(PqAnchorLapse.isDisarmed(OFF_FIRST - 1L)).isFalse();
+ assertThat(PqAnchorLapse.isDisarmed(OFF_LAST + 1L)).isFalse();
+ assertThat(PqAnchorLapse.historicMinSeals(LOW_LAST + 1L)).isEmpty();
+ }
+
+ // -----------------------------------------------------------------------------------------------
+ // What the exception deliberately does NOT relax, at any height.
+ // -----------------------------------------------------------------------------------------------
+
+ @Test
+ public void insideTheFirstRangeARepeatedIndexIsStillRefusedByBothRules() {
+ // Sortedness fixes one accepted order for a given set; distinctness is what makes "repeat one
+ // seal to inflate the count" unrepresentable. Measured on every header of the range: distinct
+ // in all of them. So this refusal costs nothing and keeps the attack unrepresentable.
+ final BlockHeader parent = parentHeader(OFF_FIRST - 1L);
+ final BlockHeader repeated = unenforcedHeader(OFF_FIRST, parent, List.of(2, 6, 2));
+ assertThat(r1.validate(repeated, parent)).isFalse();
+ assertThat(r2.validate(repeated, parent, contextWith(VALIDATORS))).isFalse();
+
+ // Positive control: the same rule at the same height accepts the distinct version.
+ final BlockHeader distinct = unenforcedHeader(OFF_FIRST, parent, ARRIVAL_ORDER);
+ assertThat(r1.validate(distinct, parent)).isTrue();
+ assertThat(r2.validate(distinct, parent, contextWith(VALIDATORS))).isTrue();
+ }
+
+ @Test
+ public void insideTheFirstRangeAnUndecodableHeaderIsStillRefused() {
+ final BlockHeader parent = parentHeader(OFF_FIRST - 1L);
+ final BlockHeader garbage =
+ header(OFF_FIRST, parent.getHash(), Bytes.fromHexString("0xdeadbeef"));
+ assertThat(r1.validate(garbage, parent)).isFalse();
+ assertThat(r2.validate(garbage, parent, contextWith(VALIDATORS))).isFalse();
+ }
+
+ @Test
+ public void belowTheActivationHeightNothingIsJudgedAtAll() {
+ // The ranges sit far above H, so this only restates the height gate; it is here because a
+ // future edit that moved the range gates ABOVE the height gate would make the rules decode
+ // headers on the whole existing chain, which is the property that lets this binary be warmed.
+ final BlockHeader parent = parentHeader(H_LIVE - 2L);
+ final BlockHeader block = unenforcedHeader(H_LIVE - 1L, parent, ARRIVAL_ORDER);
+ assertThat(r1.validate(block, parent)).isTrue();
+ assertThat(r2.validate(block, parent, contextWith(VALIDATORS))).isTrue();
+ }
+
+ // -----------------------------------------------------------------------------------------------
+ // Helpers.
+ // -----------------------------------------------------------------------------------------------
+
+ /**
+ * A header of the shape the first range holds: the client version string in vanityData instead of
+ * a digest, and the certificate written in the order the commits arrived.
+ */
+ private BlockHeader unenforcedHeader(
+ final long number, final BlockHeader parent, final List<Integer> indicesInArrivalOrder) {
+ return header(
+ number, parent.getHash(), extraData(CLIENT_VANITY, sealsFor(parent, indicesInArrivalOrder)));
+ }
+
+ /** A header whose digest is correctly bound but whose indices are left in arrival order. */
+ private BlockHeader digestBoundButUnsorted(
+ final long number, final BlockHeader parent, final List<Integer> indicesInArrivalOrder) {
+ final List<FalconSeal> seals = sealsFor(parent, indicesInArrivalOrder);
+ final Bytes32 digest =
+ PqAnchor.anchorDigest(CHAIN_ID, parent.getNumber(), parent.getHash().getBytes(), seals);
+ return header(number, parent.getHash(), extraData(digest, seals));
+ }
+
+ /** A header an honest proposer under the armed rules writes: digest bound, indices sorted. */
+ private BlockHeader honestBlock(
+ final long number, final BlockHeader parent, final List<Integer> indices) {
+ final List<FalconSeal> sorted = PqAnchor.sortedByIndex(sealsFor(parent, indices));
+ final Bytes32 digest =
+ PqAnchor.anchorDigest(CHAIN_ID, parent.getNumber(), parent.getHash().getBytes(), sorted);
+ return header(number, parent.getHash(), extraData(digest, sorted));
+ }
+
+ private List<FalconSeal> sealsFor(final BlockHeader parent, final List<Integer> indices) {
+ // One return, one mutability. An early return of an immutable empty list here is what
+ // errorprone's MixedMutabilityReturnType refuses, and it is refusing something real: the empty
+ // case is not special, it is the case where the loop runs zero times.
+ final Bytes32 message =
+ PqAnchor.commitMessage(CHAIN_ID, parent.getNumber(), parent.getHash().getBytes());
+ final List<FalconSeal> seals = new ArrayList<>();
+ for (final int index : indices) {
+ seals.add(new FalconSeal(index, LocalRegistry.sign(index, message)));
+ }
+ return seals;
+ }
+
+ private ProtocolContext contextWith(final Collection<Address> parentValidators) {
+ final ValidatorProvider validatorProvider =
+ mock(ValidatorProvider.class, withSettings().strictness(Strictness.LENIENT));
+ when(validatorProvider.getValidatorsForBlock(any())).thenReturn(parentValidators);
+ final BftContext bftContext =
+ mock(BftContext.class, withSettings().strictness(Strictness.LENIENT));
+ when(bftContext.getValidatorProvider()).thenReturn(validatorProvider);
+ when(bftContext.as(any())).thenReturn(bftContext);
+ return new ProtocolContext.Builder().withConsensusContext(bftContext).build();
+ }
+
+ /**
+ * A registry of the same shape as the Falcon one, with a signature that is a deterministic
+ * function of the index AND the message, so a seal replayed at another height fails exactly as a
+ * real verification would. It exists so that the positive controls are real acceptances rather
+ * than acceptances bought by a registry that agrees to everything.
+ */
+ private static final class LocalRegistry implements PqSignerRegistry {
+
+ private final Map<Integer, Address> binding = new HashMap<>();
+
+ private LocalRegistry() {
+ for (int i = 0; i < VALIDATORS.size(); i++) {
+ binding.put(i, VALIDATORS.get(i));
+ }
+ }
+
+ static Bytes sign(final int index, final Bytes message) {
+ final byte[] out = new byte[655];
+ out[0] = (byte) index;
+ for (int i = 0; i < message.size() && i < 32; i++) {
+ out[1 + i] = message.get(i);
+ }
+ for (int i = 33; i < out.length; i++) {
+ out[i] = (byte) ((i * (index + 3) + 7) & 0xFF);
+ }
+ return Bytes.wrap(out);
+ }
+
+ @Override
+ public Address addressForIndexAtHistoric(final long blockNumber, final int validatorIndex) {
+ return binding.get(validatorIndex);
+ }
+
+ @Override
+ public boolean verifyAtHistoric(
+ final long blockNumber,
+ final int validatorIndex,
+ final Bytes message,
+ final Bytes signature) {
+ return signature != null && signature.equals(sign(validatorIndex, message));
+ }
+
+ @Override
+ public Address addressForIndexAtOwnHead(final long blockNumber, final int validatorIndex) {
+ return addressForIndexAtHistoric(blockNumber, validatorIndex);
+ }
+
+ @Override
+ public boolean verifyAtOwnHead(
+ final long blockNumber,
+ final int validatorIndex,
+ final Bytes message,
+ final Bytes signature) {
+ return verifyAtHistoric(blockNumber, validatorIndex, message, signature);
+ }
+
+ @Override
+ public String toString() {
+ return "LocalRegistry";
+ }
+ }
+}
diff --git a/consensus/qbft/src/test/java/org/hyperledger/besu/consensus/qbft/headervalidationrules/PqAnchorSealsRuleTest.java b/consensus/qbft/src/test/java/org/hyperledger/besu/consensus/qbft/headervalidationrules/PqAnchorSealsRuleTest.java
new file mode 100755
index 000000000..385abfb1f
--- /dev/null
+++ b/consensus/qbft/src/test/java/org/hyperledger/besu/consensus/qbft/headervalidationrules/PqAnchorSealsRuleTest.java
@@ -0,0 +1,691 @@
+/*
+ * Copyright contributors to Besu / AERE Network.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.qbft.headervalidationrules;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.hyperledger.besu.consensus.qbft.headervalidationrules.PqAnchorTestSupport.CHAIN_ID;
+import static org.hyperledger.besu.consensus.qbft.headervalidationrules.PqAnchorTestSupport.H;
+import static org.hyperledger.besu.consensus.qbft.headervalidationrules.PqAnchorTestSupport.VALIDATORS;
+import static org.hyperledger.besu.consensus.qbft.headervalidationrules.PqAnchorTestSupport.extraData;
+import static org.hyperledger.besu.consensus.qbft.headervalidationrules.PqAnchorTestSupport.header;
+import static org.hyperledger.besu.consensus.qbft.headervalidationrules.PqAnchorTestSupport.parentHeader;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+import static org.mockito.Mockito.withSettings;
+
+import org.hyperledger.besu.consensus.common.bft.BftContext;
+import org.hyperledger.besu.consensus.common.bft.FalconSeal;
+import org.hyperledger.besu.consensus.common.bft.PqAnchor;
+import org.hyperledger.besu.consensus.common.bft.PqAnchorConfig;
+import org.hyperledger.besu.consensus.common.bft.PqSignerRegistry;
+import org.hyperledger.besu.consensus.common.validator.ValidatorProvider;
+import org.hyperledger.besu.datatypes.Address;
+import org.hyperledger.besu.ethereum.ProtocolContext;
+import org.hyperledger.besu.ethereum.core.BlockHeader;
+import org.hyperledger.besu.ethereum.mainnet.BlockHeaderValidator;
+import org.hyperledger.besu.ethereum.mainnet.HeaderValidationMode;
+
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.NavigableMap;
+import java.util.OptionalInt;
+import java.util.TreeMap;
+
+import org.apache.tuweni.bytes.Bytes;
+import org.apache.tuweni.bytes.Bytes32;
+import org.junit.jupiter.api.Test;
+import org.mockito.quality.Strictness;
+
+/**
+ * R2, the anchor seals rule.
+ *
+ * <p>The registry is injected rather than taken from the Falcon singleton, so these tests exercise
+ * the RULE: threshold, ordering, eligibility against the parent's validator set, message binding and
+ * per-seal verification. Whether BouncyCastle's Falcon implementation verifies correctly is
+ * FalconSealSupport's own surface, and is deliberately not re-tested here.
+ *
+ * <p>The most important test in this file is {@link
+ * #acceptsAValidCertificateOverASubsetThisNodeNeverHeard()}. It is the one that proves the rule does
+ * not do the thing that killed the previous design.
+ */
+public class PqAnchorSealsRuleTest {
+
+ private static final long K_AT = H + 100L;
+
+ private final PqAnchorConfig armed =
+ new PqAnchorConfig(CHAIN_ID, H, Map.of(H, 0, K_AT, 5), OptionalInt.empty(), false);
+ private final FakeRegistry registry = new FakeRegistry();
+ private final PqAnchorSealsRule rule = new PqAnchorSealsRule(armed, registry);
+
+ // ---------------------------------------------------------------------------------------------
+ // Inert below H.
+ // ---------------------------------------------------------------------------------------------
+
+ @Test
+ public void belowHTheRuleIsInert() {
+ final BlockHeader parent = parentHeader(H - 2L);
+ final BlockHeader nonsense =
+ header(
+ H - 1L,
+ parent.getHash(),
+ extraData(Bytes32.random(), List.of(new FalconSeal(99, Bytes.of(1, 2, 3)))));
+ assertThat(rule.validate(nonsense, parent, contextWith(VALIDATORS))).isTrue();
+ }
+
+ @Test
+ public void anUnconfiguredAnchorIsInertAtEveryHeight() {
+ final PqAnchorSealsRule inert =
+ new PqAnchorSealsRule(PqAnchorConfig.never(CHAIN_ID), registry);
+ final BlockHeader parent = parentHeader(K_AT + 4L);
+ final BlockHeader nonsense =
+ header(
+ K_AT + 5L,
+ parent.getHash(),
+ extraData(Bytes32.random(), List.of(new FalconSeal(99, Bytes.of(1, 2, 3)))));
+ assertThat(inert.validate(nonsense, parent, contextWith(VALIDATORS))).isTrue();
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // Honest certificates.
+ // ---------------------------------------------------------------------------------------------
+
+ @Test
+ public void acceptsAQuorumCertificateOverTheParent() {
+ final BlockHeader parent = parentHeader(K_AT + 9L);
+ final BlockHeader block = blockWithSigners(K_AT + 10L, parent, List.of(0, 1, 2, 3, 4));
+ assertThat(rule.validate(block, parent, contextWith(VALIDATORS))).isTrue();
+ }
+
+ @Test
+ public void acceptsAValidCertificateOverASubsetThisNodeNeverHeard() {
+ // A5, the attack that killed Option V, and the reason V2 exists. Measured on 200 consecutive
+ // live headers read from two of our own nodes with identical block hashes: the seal SET differed
+ // on 11 of them. A rule that compared the carried certificate with the local view would reject
+ // roughly one header in eighteen with no attacker present. This rule never consults a local
+ // view, so every well formed subset of eligible signers is accepted on its own merits.
+ final BlockHeader parent = parentHeader(K_AT + 9L);
+ final ProtocolContext context = contextWith(VALIDATORS);
+ for (final List<Integer> subset :
+ List.of(
+ List.of(0, 1, 2, 3, 4),
+ List.of(0, 1, 2, 3, 5),
+ List.of(2, 3, 4, 5, 6),
+ List.of(0, 2, 4, 5, 6))) {
+ final BlockHeader block = blockWithSigners(K_AT + 10L, parent, subset);
+ assertThat(rule.validate(block, parent, context))
+ .withFailMessage("subset %s should be accepted on its own merits", subset)
+ .isTrue();
+ }
+ }
+
+ @Test
+ public void acceptsMoreThanTheThreshold() {
+ final BlockHeader parent = parentHeader(K_AT + 9L);
+ final BlockHeader block = blockWithSigners(K_AT + 10L, parent, List.of(0, 1, 2, 3, 4, 5, 6));
+ assertThat(rule.validate(block, parent, contextWith(VALIDATORS))).isTrue();
+ }
+
+ @Test
+ public void acceptsAnEmptyCertificateWhileTheThresholdIsZero() {
+ final BlockHeader parent = parentHeader(H - 1L);
+ final BlockHeader block = blockWithSigners(H, parent, List.of());
+ assertThat(rule.validate(block, parent, contextWith(VALIDATORS))).isTrue();
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // The four checks.
+ // ---------------------------------------------------------------------------------------------
+
+ @Test
+ public void rejectsACertificateBelowTheThresholdInForce() {
+ final BlockHeader parent = parentHeader(K_AT + 9L);
+ final BlockHeader block = blockWithSigners(K_AT + 10L, parent, List.of(0, 1, 2, 3));
+ assertThat(rule.validate(block, parent, contextWith(VALIDATORS))).isFalse();
+ }
+
+ @Test
+ public void rejectsAnEmptyCertificateOnceTheThresholdIsAboveZero() {
+ final BlockHeader parent = parentHeader(K_AT + 9L);
+ final BlockHeader block = blockWithSigners(K_AT + 10L, parent, List.of());
+ assertThat(rule.validate(block, parent, contextWith(VALIDATORS))).isFalse();
+ }
+
+ @Test
+ public void rejectsIndicesThatAreNotStrictlyIncreasing() {
+ final BlockHeader parent = parentHeader(K_AT + 9L);
+ final List<FalconSeal> reordered =
+ new ArrayList<>(sealsFor(parent, List.of(0, 1, 2, 3, 4)));
+ Collections.reverse(reordered);
+ final BlockHeader block =
+ header(K_AT + 10L, parent.getHash(), extraData(Bytes32.random(), reordered));
+ assertThat(rule.validate(block, parent, contextWith(VALIDATORS))).isFalse();
+ }
+
+ @Test
+ public void rejectsAnIndexTheRegistryDoesNotBindToAnAddress() {
+ final BlockHeader parent = parentHeader(K_AT + 9L);
+ final List<FalconSeal> seals = new ArrayList<>(sealsFor(parent, List.of(0, 1, 2, 3)));
+ final Bytes32 message = PqAnchor.commitMessage(CHAIN_ID, parent.getNumber(), parent.getHash().getBytes());
+ seals.add(new FalconSeal(42, FakeRegistry.sign(42, message)));
+ final BlockHeader block =
+ header(K_AT + 10L, parent.getHash(), extraData(Bytes32.random(), seals));
+ assertThat(rule.validate(block, parent, contextWith(VALIDATORS))).isFalse();
+ }
+
+ @Test
+ public void rejectsASignerThatWasNotAValidatorOfTheParent() {
+ // Removal safety: a validator dropped before the parent no longer counts, even though its key is
+ // still in the registry.
+ final BlockHeader parent = parentHeader(K_AT + 9L);
+ final BlockHeader block = blockWithSigners(K_AT + 10L, parent, List.of(0, 1, 2, 3, 6));
+ final List<Address> shrunk = VALIDATORS.subList(0, 6);
+ assertThat(rule.validate(block, parent, contextWith(shrunk))).isFalse();
+ // and the same certificate over the full parent set is fine, so the refusal is about
+ // eligibility and nothing else.
+ assertThat(rule.validate(block, parent, contextWith(VALIDATORS))).isTrue();
+ }
+
+ @Test
+ public void rejectsASignatureThatDoesNotVerify() {
+ final BlockHeader parent = parentHeader(K_AT + 9L);
+ final List<FalconSeal> seals = new ArrayList<>(sealsFor(parent, List.of(0, 1, 2, 3)));
+ seals.add(new FalconSeal(4, Bytes.repeat((byte) 0x5a, 655)));
+ final BlockHeader block =
+ header(K_AT + 10L, parent.getHash(), extraData(Bytes32.random(), seals));
+ assertThat(rule.validate(block, parent, contextWith(VALIDATORS))).isFalse();
+ }
+
+ @Test
+ public void rejectsSealsReplayedFromAnotherHeight() {
+ // A6, first half: M binds the chain id, the block number and the block hash, so a certificate
+ // that is genuine over a different parent is not material here.
+ final BlockHeader parent = parentHeader(K_AT + 9L);
+ final BlockHeader otherParent = parentHeader(K_AT + 8L);
+ final List<FalconSeal> foreign = sealsFor(otherParent, List.of(0, 1, 2, 3, 4));
+ final BlockHeader block =
+ header(K_AT + 10L, parent.getHash(), extraData(Bytes32.random(), foreign));
+ assertThat(rule.validate(block, parent, contextWith(VALIDATORS))).isFalse();
+ }
+
+ @Test
+ public void rejectsSealsReplayedFromAnotherChain() {
+ // A6, second half: the 442807 proving chain runs the same binaries and can run the same keys.
+ final BlockHeader parent = parentHeader(K_AT + 9L);
+ final Bytes32 foreignMessage =
+ PqAnchor.commitMessage(442807L, parent.getNumber(), parent.getHash().getBytes());
+ final List<FalconSeal> foreign = new ArrayList<>();
+ for (final int index : List.of(0, 1, 2, 3, 4)) {
+ foreign.add(new FalconSeal(index, FakeRegistry.sign(index, foreignMessage)));
+ }
+ final BlockHeader block =
+ header(K_AT + 10L, parent.getHash(), extraData(Bytes32.random(), foreign));
+ assertThat(rule.validate(block, parent, contextWith(VALIDATORS))).isFalse();
+ }
+
+ @Test
+ public void rejectsTwoIndicesThatResolveToOneValidator() {
+ // Strictly increasing indices stop a repeated INDEX. A malformed registry could still map two
+ // distinct indices onto one address, which would let one validator be counted twice.
+ final BlockHeader parent = parentHeader(K_AT + 9L);
+ registry.bind(7, VALIDATORS.get(0));
+ final BlockHeader block = blockWithSigners(K_AT + 10L, parent, List.of(0, 1, 2, 3, 7));
+ assertThat(rule.validate(block, parent, contextWith(VALIDATORS))).isFalse();
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // D2, the adversarial review of 2026-08-02, reproduced against R2 itself.
+ //
+ // The dossier's T2, in its own words: "a header that passes both rules today is REJECTED the
+ // moment index 0's Falcon key is rotated. Nothing else changes: same header, same parent, same
+ // validator set." T3: "if the index is rebound to ANOTHER validator who is still in the current
+ // set, the rule sees nothing."
+ //
+ // These two tests could not have been written before 2026-08-06. PqSignerRegistry carried a
+ // height-less pair plus a default that forwarded the height-aware form to it, so every test
+ // double in the tree - including the D2 harness's own RuleProbe - silently threw the height away
+ // and answered from ONE key set. A fake with one key set cannot express a rotation, so it cannot
+ // fail on one. The compiler now refuses that fake.
+ // ---------------------------------------------------------------------------------------------
+
+ @Test
+ public void d2t2AHeaderBelowARotationIsStillVerifiedUnderTheKEYSETITWASSEALEDUNDER() {
+ // The T2 measurement, stated as a property rather than a scenario: an honest certificate over
+ // parent P must still verify after the chain rotates index 0's key at a LATER height. The seals
+ // are produced under generation 0, which is what was in force at P.
+ final long rotationHeight = K_AT + 5_000L;
+ final BlockHeader parent = parentHeader(K_AT + 9L);
+ final BlockHeader block = blockWithSigners(K_AT + 10L, parent, List.of(0, 1, 2, 3, 4));
+ final ProtocolContext context = contextWith(VALIDATORS);
+
+ assertThat(rule.validate(block, parent, context))
+ .describedAs("baseline: the certificate is honest before any rotation")
+ .isTrue();
+
+ registry.rotateKeyFrom(rotationHeight, 0, 1);
+
+ assertThat(rule.validate(block, parent, context))
+ .describedAs(
+ "D2/T2: the SAME header, the SAME parent and the SAME validator set, after a key "
+ + "rotation at a height ABOVE it. R2 must resolve keys at the parent's height. If "
+ + "this is false the chain is unjoinable for every node that syncs after a rotation")
+ .isTrue();
+ }
+
+ @Test
+ public void d2t2ASealFromTheOLDKeyIsRefusedABOVETheRotation() {
+ // The other side of the same coin, and the reason the test above is not satisfied by a rule
+ // that ignores rotations entirely. Above the rotation height the old key must NOT verify -
+ // otherwise "rotation" would mean nothing and a revoked key would keep signing forever.
+ final long rotationHeight = K_AT + 5_000L;
+ registry.rotateKeyFrom(rotationHeight, 0, 1);
+
+ final BlockHeader parent = parentHeader(rotationHeight + 9L);
+ final Bytes32 message =
+ PqAnchor.commitMessage(CHAIN_ID, parent.getNumber(), parent.getHash().getBytes());
+ final List<FalconSeal> seals = new ArrayList<>();
+ // index 0 signs with the RETIRED generation; the other four are honest.
+ seals.add(new FalconSeal(0, FakeRegistry.sign(0, 0, message)));
+ for (final int index : List.of(1, 2, 3, 4)) {
+ seals.add(new FalconSeal(index, FakeRegistry.sign(index, message)));
+ }
+ final BlockHeader block =
+ header(rotationHeight + 10L, parent.getHash(), extraData(Bytes32.random(), seals));
+
+ assertThat(rule.validate(block, parent, contextWith(VALIDATORS)))
+ .describedAs("a seal from the key the chain retired must not count above the rotation")
+ .isFalse();
+ }
+
+ @Test
+ public void d2t3ARebindingOfAnIndexToAnotherCURRENTValidatorIsNotSeenByR2() {
+ // T3, and this test is here to keep an OPEN finding open rather than to prove a repair.
+ //
+ // Measured, not argued: PqAnchorSealsRule credits a seal to whatever address the registry hands
+ // back for its index, checks that address against the parent's validator set, and never asks
+ // which KEY signed. So rebinding index 0 to validator 5 - who is in the set - is invisible: the
+ // seal was produced by index 0's key and is credited to validator 5.
+ //
+ // The height-indexed registry NARROWS this: a rebinding changes the registry's canonical hash
+ // (PqRegistryHash.java:274-277 puts the address in the pre-image), so it cannot happen without
+ // a new scheduled epoch that every node must be given. It does not CLOSE it: whoever writes
+ // that epoch can write the rebinding into it and the whole fleet will accept it. Closing it
+ // needs eligibility DERIVED from the Falcon key rather than bound to it by configuration.
+ final long rebindHeight = K_AT + 5_000L;
+ final BlockHeader parent = parentHeader(rebindHeight + 9L);
+ // Validator 5 does not sign; index 0's key does. After the rebinding the seal is credited to 5.
+ registry.rebindFrom(rebindHeight, 0, VALIDATORS.get(5));
+
+ final Bytes32 message =
+ PqAnchor.commitMessage(CHAIN_ID, parent.getNumber(), parent.getHash().getBytes());
+ final List<FalconSeal> seals = new ArrayList<>();
+ for (final int index : List.of(0, 1, 2, 3, 4)) {
+ seals.add(new FalconSeal(index, FakeRegistry.sign(index, message)));
+ }
+ final BlockHeader block =
+ header(rebindHeight + 10L, parent.getHash(), extraData(Bytes32.random(), seals));
+
+ assertThat(rule.validate(block, parent, contextWith(VALIDATORS)))
+ .describedAs(
+ "D2/T3 IS STILL OPEN: R2 accepts a certificate in which index 0's key is credited to "
+ + "validator 5. When this assertion has to be flipped to isFalse(), T3 has been "
+ + "closed and this comment is the record of when it was not")
+ .isTrue();
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // Fail-closed on everything else.
+ // ---------------------------------------------------------------------------------------------
+
+ @Test
+ public void rejectsWhenTheParentIsMissingOrIsNotTheNamedParent() {
+ final BlockHeader parent = parentHeader(K_AT + 9L);
+ final BlockHeader block = blockWithSigners(K_AT + 10L, parent, List.of(0, 1, 2, 3, 4));
+ final ProtocolContext context = contextWith(VALIDATORS);
+ assertThat(rule.validate(block, null, context)).isFalse();
+ assertThat(rule.validate(block, parentHeader(K_AT + 8L), context)).isFalse();
+ }
+
+ @Test
+ public void rejectsWhenTheParentValidatorSetCannotBeResolved() {
+ final BlockHeader parent = parentHeader(K_AT + 9L);
+ final BlockHeader block = blockWithSigners(K_AT + 10L, parent, List.of(0, 1, 2, 3, 4));
+ assertThat(rule.validate(block, parent, contextWith(Collections.emptyList()))).isFalse();
+ assertThat(rule.validate(block, parent, contextWith(null))).isFalse();
+ }
+
+ @Test
+ public void rejectsUndecodableExtraData() {
+ final BlockHeader parent = parentHeader(K_AT + 9L);
+ final BlockHeader broken =
+ header(K_AT + 10L, parent.getHash(), Bytes.fromHexString("0xdeadbeef"));
+ assertThat(rule.validate(broken, parent, contextWith(VALIDATORS))).isFalse();
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // Where it runs.
+ // ---------------------------------------------------------------------------------------------
+
+ @Test
+ public void includeInLightValidationIsFalseAndTheRuleIsSkippedThere() {
+ assertThat(rule.includeInLightValidation()).isFalse();
+ final BlockHeader parent = parentHeader(K_AT + 9L);
+ final BlockHeader tooFew = blockWithSigners(K_AT + 10L, parent, List.of(0, 1));
+ final ProtocolContext context = contextWith(VALIDATORS);
+ final BlockHeaderValidator validator =
+ new BlockHeaderValidator.Builder().addRule(rule).build();
+ // Skipped in every light mode: this is the expensive half, and R1 already carries the binding
+ // into light validation.
+ assertThat(validator.validateHeader(tooFew, parent, context, HeaderValidationMode.LIGHT))
+ .isTrue();
+ assertThat(
+ validator.validateHeader(
+ tooFew, parent, context, HeaderValidationMode.LIGHT_SKIP_DETACHED))
+ .isTrue();
+ // And decisive in full validation.
+ assertThat(validator.validateHeader(tooFew, parent, context, HeaderValidationMode.FULL))
+ .isFalse();
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // Helpers.
+ // ---------------------------------------------------------------------------------------------
+
+ private List<FalconSeal> sealsFor(final BlockHeader parent, final List<Integer> indices) {
+ final Bytes32 message = PqAnchor.commitMessage(CHAIN_ID, parent.getNumber(), parent.getHash().getBytes());
+ final List<FalconSeal> seals = new ArrayList<>();
+ for (final int index : indices) {
+ seals.add(new FalconSeal(index, FakeRegistry.sign(index, message)));
+ }
+ return PqAnchor.sortedByIndex(seals);
+ }
+
+ /**
+ * A header carrying an honest certificate from the given signers. vanityData is set to the correct
+ * anchor digest so that a header built here would also satisfy R1; R2 does not read it.
+ */
+ private BlockHeader blockWithSigners(
+ final long number, final BlockHeader parent, final List<Integer> indices) {
+ final List<FalconSeal> seals = sealsFor(parent, indices);
+ final Bytes32 digest =
+ PqAnchor.anchorDigest(CHAIN_ID, parent.getNumber(), parent.getHash().getBytes(), seals);
+ return header(number, parent.getHash(), extraData(digest, seals));
+ }
+
+ private ProtocolContext contextWith(final Collection<Address> parentValidators) {
+ final ValidatorProvider validatorProvider =
+ mock(ValidatorProvider.class, withSettings().strictness(Strictness.LENIENT));
+ when(validatorProvider.getValidatorsForBlock(any())).thenReturn(parentValidators);
+ final BftContext bftContext =
+ mock(BftContext.class, withSettings().strictness(Strictness.LENIENT));
+ when(bftContext.getValidatorProvider()).thenReturn(validatorProvider);
+ when(bftContext.as(any())).thenReturn(bftContext);
+ return new ProtocolContext.Builder().withConsensusContext(bftContext).build();
+ }
+
+ /**
+ * A registry with the same shape as the Falcon one: index to address, plus a verifier. The fake
+ * signature is a deterministic function of the index AND the message, so replaying a genuine seal
+ * at another height or on another chain fails exactly as a real Falcon verification would.
+ */
+ private static final class FakeRegistry implements PqSignerRegistry {
+
+ /** Epoch start height to the index-to-address binding in force from there. */
+ private final NavigableMap<Long, Map<Integer, Address>> epochs = new TreeMap<>();
+
+ /**
+ * Epoch start height to the KEY GENERATION in force from there. The fake signature is a
+ * function of the generation, so "rotate index 0's key" and "rebind index 0 to another
+ * validator" are two DIFFERENT edits here, exactly as they are on the wire. T2 is the first,
+ * T3 the second.
+ */
+ private final NavigableMap<Long, Integer> generations = new TreeMap<>();
+
+ private FakeRegistry() {
+ final Map<Integer, Address> genesisEpoch = new HashMap<>();
+ for (int i = 0; i < VALIDATORS.size(); i++) {
+ genesisEpoch.put(i, VALIDATORS.get(i));
+ }
+ epochs.put(0L, genesisEpoch);
+ generations.put(0L, 0);
+ }
+
+ void bind(final int index, final Address address) {
+ epochs.get(epochs.firstKey()).put(index, address);
+ }
+
+ /**
+ * D2/T2. From {@code from}, index {@code index} answers to a NEW key generation. Everything
+ * else - the address binding, the validator set, the parent - is untouched, which is the whole
+ * point of the T2 measurement: a header that verified yesterday must still verify today.
+ */
+ void rotateKeyFrom(final long from, final int index, final int generation) {
+ final Map<Integer, Address> carried = new HashMap<>(epochs.floorEntry(from).getValue());
+ epochs.put(from, carried);
+ generations.put(from, generation);
+ rotatedIndex = index;
+ }
+
+ /**
+ * D2/T3. From {@code from}, index {@code index} answers to a DIFFERENT validator address, keys
+ * untouched. The seal is then credited to a validator that did not sign it.
+ */
+ void rebindFrom(final long from, final int index, final Address address) {
+ final Map<Integer, Address> carried = new HashMap<>(epochs.floorEntry(from).getValue());
+ carried.put(index, address);
+ epochs.put(from, carried);
+ generations.put(from, generations.floorEntry(from).getValue());
+ }
+
+ private int rotatedIndex = -1;
+
+ static Bytes sign(final int index, final Bytes message) {
+ return sign(index, 0, message);
+ }
+
+ static Bytes sign(final int index, final int generation, final Bytes message) {
+ final byte[] out = new byte[655];
+ out[0] = (byte) index;
+ for (int i = 0; i < message.size() && i < 32; i++) {
+ out[1 + i] = message.get(i);
+ }
+ for (int i = 33; i < out.length; i++) {
+ out[i] = (byte) ((i * (index + 3) + 7 + generation * 31) & 0xFF);
+ }
+ return Bytes.wrap(out);
+ }
+
+ private int generationAt(final long blockNumber, final int validatorIndex) {
+ final Integer g = generations.floorEntry(blockNumber).getValue();
+ // Only the rotated index changes generation; every other index keeps generation 0.
+ return (rotatedIndex < 0 || validatorIndex == rotatedIndex) ? g : 0;
+ }
+
+ // D2 HARDENING (a), 2026-08-06: the height-less pair is gone from PqSignerRegistry, so this
+ // double can no longer inherit a default that throws the height away. That default is why the
+ // original D2 harness (RuleProbe.java:115-131) returned the same verdict on repaired and
+ // unrepaired code; a fake that cannot express a rotation cannot prove one is handled.
+ @Override
+ public Address addressForIndexAtOwnHead(final long blockNumber, final int validatorIndex) {
+ return addressForIndexAtHistoric(blockNumber, validatorIndex);
+ }
+
+ @Override
+ public boolean verifyAtOwnHead(
+ final long blockNumber,
+ final int validatorIndex,
+ final Bytes message,
+ final Bytes signature) {
+ return verifyAtHistoric(blockNumber, validatorIndex, message, signature);
+ }
+
+ @Override
+ public Address addressForIndexAtHistoric(final long blockNumber, final int validatorIndex) {
+ return epochs.floorEntry(blockNumber).getValue().get(validatorIndex);
+ }
+
+ @Override
+ public boolean verifyAtHistoric(
+ final long blockNumber,
+ final int validatorIndex,
+ final Bytes message,
+ final Bytes signature) {
+ return signature != null
+ && signature.equals(sign(validatorIndex, generationAt(blockNumber, validatorIndex), message));
+ }
+
+ @Override
+ public String toString() {
+ return "FakeRegistry";
+ }
+ }
+
+ // ---------------------------------------------------------------------------------------------
+ // D2 HARDENING (b-v2), 2026-08-06. WHICH DOOR R2 GOES THROUGH, measured by behaviour, not by
+ // name.
+ //
+ // The shape chosen here admits its own weakness: the compiler forces you to CHOOSE between
+ // addressForIndexAtHistoric and addressForIndexAtOwnHead, but it does not force you to choose
+ // CORRECTLY. Both have the same type and both are total, so a future patch that moves this call
+ // onto the OWN-HEAD door reopens D2 without anything going red, because the OWN-HEAD door is
+ // precisely the one that always answers.
+ //
+ // The two assertions below are the lock. The registry they run against answers DIFFERENTLY on
+ // the two doors, which no real registry does; that is exactly why it can say which door was
+ // opened. The pair also carries its positive control built in: if R2 called NEITHER door, the
+ // first assertion would pass and the second would fail.
+ // ---------------------------------------------------------------------------------------------
+
+ @Test
+ public void r2GoesThroughTheHISTORYDoorAndThroughNothingElse() {
+ final BlockHeader parent = parentHeader(K_AT + 9L);
+ final BlockHeader block = blockWithSigners(K_AT + 10L, parent, List.of(0, 1, 2, 3, 4));
+ final ProtocolContext context = contextWith(VALIDATORS);
+
+ assertThat(rule.validate(block, parent, context))
+ .describedAs("baseline: the same header is accepted by the ordinary registry")
+ .isTrue();
+
+ final PqAnchorSealsRule peUsaIstorie =
+ new PqAnchorSealsRule(armed, new OneDoorRegistry(registry, false));
+ assertThat(peUsaIstorie.validate(block, parent, context))
+ .describedAs(
+ "the HISTORY door refuses everything and the OWN-HEAD door answers everything. R2 must "
+ + "REJECT. If this is true, R2 is reading the own-head door, which means it would "
+ + "answer a header it received from the registry in force at this node's head - "
+ + "and that is D2 verbatim")
+ .isFalse();
+
+ final PqAnchorSealsRule peUsaCap =
+ new PqAnchorSealsRule(armed, new OneDoorRegistry(registry, true));
+ assertThat(peUsaCap.validate(block, parent, context))
+ .describedAs(
+ "and the mirror image: the HISTORY door answers, the OWN-HEAD door refuses, and R2 "
+ + "ACCEPTS. Without this second half the first could pass on a rule that calls "
+ + "neither door at all")
+ .isTrue();
+ }
+
+ /**
+ * A registry that answers on exactly ONE of the two doors and refuses on the other. No real
+ * registry behaves like this; that is the point - it is an instrument for asking which door a
+ * caller opened, and it is the only kind of double that can catch a call site moved to the wrong
+ * one.
+ */
+ private static final class OneDoorRegistry implements PqSignerRegistry {
+ private final PqSignerRegistry delegate;
+ private final boolean historyAnswers;
+
+ private OneDoorRegistry(final PqSignerRegistry delegate, final boolean historyAnswers) {
+ this.delegate = delegate;
+ this.historyAnswers = historyAnswers;
+ }
+
+ @Override
+ public Address addressForIndexAtHistoric(final long blockNumber, final int validatorIndex) {
+ return historyAnswers ? delegate.addressForIndexAtHistoric(blockNumber, validatorIndex) : null;
+ }
+
+ @Override
+ public boolean verifyAtHistoric(
+ final long blockNumber,
+ final int validatorIndex,
+ final Bytes message,
+ final Bytes signature) {
+ return historyAnswers
+ && delegate.verifyAtHistoric(blockNumber, validatorIndex, message, signature);
+ }
+
+ @Override
+ public Address addressForIndexAtOwnHead(final long blockNumber, final int validatorIndex) {
+ return historyAnswers ? null : delegate.addressForIndexAtOwnHead(blockNumber, validatorIndex);
+ }
+
+ @Override
+ public boolean verifyAtOwnHead(
+ final long blockNumber,
+ final int validatorIndex,
+ final Bytes message,
+ final Bytes signature) {
+ return !historyAnswers
+ && delegate.verifyAtOwnHead(blockNumber, validatorIndex, message, signature);
+ }
+
+ @Override
+ public String toString() {
+ return "OneDoorRegistry{historyAnswers=" + historyAnswers + "}";
+ }
+ }
+
+ @Test
+ public void rejectsAnInvalidSignatureInEVERYPositionOfTheCertificate() {
+ // Added 2026-08-02 after a planted defect proved this was missing.
+ //
+ // The three signature tests above are all satisfied by a rule that skips the verification of
+ // ONE chosen position: rejectsASignatureThatDoesNotVerify puts its bad seal LAST, and the two
+ // replay tests make EVERY seal bad, so any one of them still fails on some other seal. A rule
+ // mutated to skip exactly the first seal's verification left all 187 tests of consensus:qbft
+ // green. An off-by-one in this loop, a stray continue, or a short-circuit on the first element
+ // is exactly that shape of bug, and it would have shipped.
+ //
+ // This test walks the bad signature through every position, so no per-position skip survives.
+ final BlockHeader parent = parentHeader(K_AT + 9L);
+ final List<Integer> signers = List.of(0, 1, 2, 3, 4);
+ for (int position = 0; position < signers.size(); position++) {
+ final List<FalconSeal> seals = new ArrayList<>(sealsFor(parent, signers));
+ final FalconSeal good = seals.get(position);
+ seals.set(
+ position, new FalconSeal(good.getValidatorIndex(), Bytes.repeat((byte) 0x5a, 655)));
+ final BlockHeader block =
+ header(K_AT + 10L, parent.getHash(), extraData(Bytes32.random(), seals));
+ assertThat(rule.validate(block, parent, contextWith(VALIDATORS)))
+ .describedAs("certificate with the only invalid signature at position %d", position)
+ .isFalse();
+ }
+ }
+
+ @Test
+ public void acceptsTheSameCertificateWhenEveryPositionIsHonest() {
+ // The negative control for the test above: without it, a rule that rejected EVERYTHING would
+ // pass the per-position walk and prove nothing at all.
+ final BlockHeader parent = parentHeader(K_AT + 9L);
+ final BlockHeader block = blockWithSigners(K_AT + 10L, parent, List.of(0, 1, 2, 3, 4));
+ assertThat(rule.validate(block, parent, contextWith(VALIDATORS))).isTrue();
+ }
+}
diff --git a/consensus/qbft/src/test/java/org/hyperledger/besu/consensus/qbft/headervalidationrules/PqAnchorTestSupport.java b/consensus/qbft/src/test/java/org/hyperledger/besu/consensus/qbft/headervalidationrules/PqAnchorTestSupport.java
new file mode 100755
index 000000000..f7961bcd3
--- /dev/null
+++ b/consensus/qbft/src/test/java/org/hyperledger/besu/consensus/qbft/headervalidationrules/PqAnchorTestSupport.java
@@ -0,0 +1,144 @@
+/*
+ * Copyright contributors to Besu / AERE Network.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.qbft.headervalidationrules;
+
+import org.hyperledger.besu.consensus.common.bft.BftExtraData;
+import org.hyperledger.besu.consensus.common.bft.FalconSeal;
+import org.hyperledger.besu.consensus.common.bft.PqAnchor;
+import org.hyperledger.besu.consensus.qbft.QbftExtraDataCodec;
+import org.hyperledger.besu.datatypes.Address;
+import org.hyperledger.besu.datatypes.Hash;
+import org.hyperledger.besu.ethereum.core.BlockHeader;
+import org.hyperledger.besu.ethereum.core.BlockHeaderTestFixture;
+
+import java.util.Collection;
+import java.util.Collections;
+import java.util.List;
+import java.util.Optional;
+
+import org.apache.tuweni.bytes.Bytes;
+import org.apache.tuweni.bytes.Bytes32;
+
+/** Header construction shared by the two anchor rule test classes. */
+public final class PqAnchorTestSupport {
+
+ /** The chain the rules under test are configured for. */
+ public static final long CHAIN_ID = 2800L;
+
+ /** The activation height H used throughout these tests. */
+ public static final long H = 1_000L;
+
+ /** The QBFT validator addresses used as the parent's validator set. */
+ public static final List<Address> VALIDATORS =
+ List.of(
+ Address.fromHexString("0x0000000000000000000000000000000000000a01"),
+ Address.fromHexString("0x0000000000000000000000000000000000000a02"),
+ Address.fromHexString("0x0000000000000000000000000000000000000a03"),
+ Address.fromHexString("0x0000000000000000000000000000000000000a04"),
+ Address.fromHexString("0x0000000000000000000000000000000000000a05"),
+ Address.fromHexString("0x0000000000000000000000000000000000000a06"),
+ Address.fromHexString("0x0000000000000000000000000000000000000a07"));
+
+ private static final QbftExtraDataCodec CODEC = new QbftExtraDataCodec();
+
+ private PqAnchorTestSupport() {}
+
+ /**
+ * A deterministic stand-in for a Falcon-512 signature. {@code variant} lets a test produce a
+ * DIFFERENT but equally well formed signature under the same index, which is what an "equally
+ * valid certificate, different bytes" substitution looks like on the wire.
+ *
+ * @param index the validator index the signature belongs to
+ * @param variant a discriminator so two signatures for one index differ
+ * @return 655 deterministic bytes, the measured mean Falcon-512 signature length
+ */
+ public static Bytes signature(final int index, final int variant) {
+ final byte[] bytes = new byte[655];
+ for (int i = 0; i < bytes.length; i++) {
+ bytes[i] = (byte) ((i * 31 + index * 7 + variant * 101) & 0xFF);
+ }
+ return Bytes.wrap(bytes);
+ }
+
+ /**
+ * A seal for a validator index.
+ *
+ * @param index the validator index
+ * @return the seal
+ */
+ public static FalconSeal seal(final int index) {
+ return new FalconSeal(index, signature(index, 0));
+ }
+
+ /**
+ * Build the extraData bytes of a header carrying a given certificate and a given vanity field.
+ *
+ * @param vanity the 32-byte vanity field, which from H is the anchor digest D
+ * @param certificate the carried certificate C, in the order it is to be written
+ * @return canonical extraData bytes
+ */
+ public static Bytes extraData(final Bytes vanity, final Collection<FalconSeal> certificate) {
+ return CODEC.encode(
+ new BftExtraData(
+ vanity, Collections.emptyList(), Optional.empty(), 0, VALIDATORS, certificate));
+ }
+
+ /**
+ * Build a header at a height, over a parent hash, carrying a certificate whose anchor digest is
+ * written into vanityData. This is what an HONEST proposer produces.
+ *
+ * @param number the height of the header
+ * @param parentHash the parent hash the header names
+ * @param certificate the certificate over the parent
+ * @return the header
+ */
+ public static BlockHeader honestHeader(
+ final long number, final Hash parentHash, final List<FalconSeal> certificate) {
+ final List<FalconSeal> sorted = PqAnchor.sortedByIndex(certificate);
+ final Bytes32 digest = PqAnchor.anchorDigest(CHAIN_ID, number - 1L, parentHash.getBytes(), sorted);
+ return header(number, parentHash, extraData(digest, sorted));
+ }
+
+ /**
+ * Build a header with explicit extraData bytes, so a test can tamper with the certificate while
+ * leaving vanityData as the honest proposer wrote it.
+ *
+ * @param number the height of the header
+ * @param parentHash the parent hash the header names
+ * @param extraData the exact extraData bytes
+ * @return the header
+ */
+ public static BlockHeader header(
+ final long number, final Hash parentHash, final Bytes extraData) {
+ return new BlockHeaderTestFixture()
+ .number(number)
+ .parentHash(parentHash)
+ .extraData(extraData)
+ .buildHeader();
+ }
+
+ /**
+ * The parent header a test uses, whose hash is what the child names.
+ *
+ * @param number the parent's height
+ * @return the parent header
+ */
+ public static BlockHeader parentHeader(final long number) {
+ return new BlockHeaderTestFixture()
+ .number(number)
+ .extraData(extraData(Bytes32.ZERO, Collections.emptyList()))
+ .buildHeader();
+ }
+}
diff --git a/consensus/qbft/src/test/java/org/hyperledger/besu/consensus/qbft/headervalidationrules/PqAnchorV2RulesTest.java b/consensus/qbft/src/test/java/org/hyperledger/besu/consensus/qbft/headervalidationrules/PqAnchorV2RulesTest.java
new file mode 100755
index 000000000..4c542fe87
--- /dev/null
+++ b/consensus/qbft/src/test/java/org/hyperledger/besu/consensus/qbft/headervalidationrules/PqAnchorV2RulesTest.java
@@ -0,0 +1,361 @@
+/*
+ * Copyright contributors to Aere Network.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.qbft.headervalidationrules;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+import static org.hyperledger.besu.consensus.qbft.headervalidationrules.PqAnchorTestSupport.CHAIN_ID;
+import static org.hyperledger.besu.consensus.qbft.headervalidationrules.PqAnchorTestSupport.H;
+import static org.hyperledger.besu.consensus.qbft.headervalidationrules.PqAnchorTestSupport.VALIDATORS;
+import static org.hyperledger.besu.consensus.qbft.headervalidationrules.PqAnchorTestSupport.header;
+import static org.hyperledger.besu.consensus.qbft.headervalidationrules.PqAnchorTestSupport.parentHeader;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+import static org.mockito.Mockito.withSettings;
+
+import org.hyperledger.besu.consensus.common.bft.BftContext;
+import org.hyperledger.besu.consensus.common.bft.BftExtraData;
+import org.hyperledger.besu.consensus.common.bft.FalconSeal;
+import org.hyperledger.besu.consensus.common.bft.HybridSealSupport;
+import org.hyperledger.besu.consensus.common.bft.PqAnchor;
+import org.hyperledger.besu.consensus.common.bft.PqAnchorConfig;
+import org.hyperledger.besu.consensus.common.bft.PqAnchorV2;
+import org.hyperledger.besu.consensus.common.bft.PqSignerRegistry;
+import org.hyperledger.besu.consensus.common.bft.SchemeSeal;
+import org.hyperledger.besu.consensus.common.bft.SealScheme;
+import org.hyperledger.besu.consensus.common.bft.SealSchemes;
+import org.hyperledger.besu.consensus.common.validator.ValidatorProvider;
+import org.hyperledger.besu.consensus.qbft.QbftExtraDataCodec;
+import org.hyperledger.besu.crypto.SecureRandomProvider;
+import org.hyperledger.besu.datatypes.Address;
+import org.hyperledger.besu.ethereum.ProtocolContext;
+import org.hyperledger.besu.ethereum.core.BlockHeader;
+import org.hyperledger.besu.ethereum.rlp.RLPException;
+
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.security.SecureRandom;
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.Collections;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.OptionalInt;
+
+import org.apache.tuweni.bytes.Bytes;
+import org.apache.tuweni.bytes.Bytes32;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+import org.mockito.quality.Strictness;
+
+/**
+ * AERE ANCHOR V2 (2026-09-03): the two header rules judge the SCHEME-TAGGED certificate, and the codec
+ * carries it in the sixth extraData element beside the v1 form.
+ *
+ * <p>Falcon seals come from a fake registry (a seal is valid iff it is exactly what the fake signs for
+ * that index over M(parent)); SLH-DSA seals are REAL, from probe keys generated here and published in
+ * a hybrid-1 registry loaded through the real system-configuration path.
+ *
+ * <p>Proven, each with its pair: R1 accepts the honest v2 header and refuses a stripped certificate
+ * (digest mismatch), a v2 certificate below the v2 height, and a v1 certificate at the v2 height; R2
+ * accepts the honest v2 header and refuses an SLH-DSA seal from an index without a Falcon seal, a
+ * certificate short of one scheme, a tampered SLH-DSA signature, and a scheme the schedule does not
+ * name; the codec round-trips both forms and refuses a non-canonical v2 certificate.
+ */
+public class PqAnchorV2RulesTest {
+
+ private static final long V2 = H + 100L;
+ private static final int K = 3;
+ private static final String SLH = "slh-dsa-sha2-128s";
+ private static final QbftExtraDataCodec CODEC = new QbftExtraDataCodec();
+
+ @TempDir Path tmp;
+
+ private final SecureRandom random = SecureRandomProvider.createSecureRandom();
+ private final List<SealScheme.GeneratedPair> slhKeys = new ArrayList<>();
+ private final FakeFalconRegistry falcon = new FakeFalconRegistry();
+
+ private PqAnchorConfig armedV2;
+ private PqAnchorDigestRule r1;
+ private PqAnchorSealsRule r2;
+
+ @BeforeEach
+ void setUp() throws Exception {
+ for (int i = 0; i < VALIDATORS.size(); i++) {
+ slhKeys.add(SealSchemes.SLH_DSA_128S.generate(random));
+ }
+ armHybrid("0:falcon-512+" + SLH);
+ armedV2 = new PqAnchorConfig(
+ CHAIN_ID, H, Map.of(H, 0, V2, K), OptionalInt.empty(), false, OptionalInt.empty(),
+ OptionalInt.empty(), V2);
+ r1 = new PqAnchorDigestRule(armedV2);
+ r2 = new PqAnchorSealsRule(armedV2, falcon);
+ }
+
+ @AfterEach
+ void tearDown() {
+ System.clearProperty(HybridSealSupport.PROPERTY_SCHEDULE);
+ System.clearProperty(HybridSealSupport.PROPERTY_REGISTRY);
+ HybridSealSupport.resetForTesting();
+ }
+
+ private void armHybrid(final String schedule) throws Exception {
+ final StringBuilder p = new StringBuilder();
+ p.append("formatVersion=hybrid-1\nchainId=").append(CHAIN_ID).append("\ncount=")
+ .append(VALIDATORS.size()).append('\n');
+ for (int i = 0; i < VALIDATORS.size(); i++) {
+ p.append(i).append(".addr=").append(VALIDATORS.get(i).toHexString()).append('\n');
+ p.append(i).append(".key.").append(SLH).append('=')
+ .append(Bytes.wrap(slhKeys.get(i).publicRegistryForm()).toHexString()).append('\n');
+ }
+ final Path reg = tmp.resolve("hybrid-" + schedule.replaceAll("[^a-z0-9]", "-") + ".properties");
+ Files.writeString(reg, p.toString());
+ System.setProperty(HybridSealSupport.PROPERTY_SCHEDULE, schedule);
+ System.setProperty(HybridSealSupport.PROPERTY_REGISTRY, reg.toAbsolutePath().toString());
+ HybridSealSupport.resetForTesting();
+ assertThat(HybridSealSupport.instance().registry()).isPresent();
+ }
+
+ // ------------------------------------------------------------------------------ certificates
+
+ /** Falcon seals for indices 0..falconCount-1 and SLH-DSA seals for 0..slhCount-1, canonical. */
+ private List<SchemeSeal> certificate(final BlockHeader parent, final int falconCount, final int slhCount) {
+ final Bytes32 m = PqAnchor.commitMessage(CHAIN_ID, parent.getNumber(), parent.getHash().getBytes());
+ final List<SchemeSeal> out = new ArrayList<>();
+ for (int i = 0; i < falconCount; i++) {
+ out.add(new SchemeSeal(SealSchemes.FALCON_512.wireId(), i, FakeFalconRegistry.sign(i, m)));
+ }
+ for (int i = 0; i < slhCount; i++) {
+ out.add(new SchemeSeal(SealSchemes.SLH_DSA_128S.wireId(), i,
+ Bytes.wrap(SealSchemes.SLH_DSA_128S.sign(slhKeys.get(i).privateKey(), m.toArray()).orElseThrow())));
+ }
+ out.sort(PqAnchorV2.CANONICAL);
+ return out;
+ }
+
+ private static Bytes extraDataV2(final Bytes vanity, final List<SchemeSeal> tagged) {
+ return CODEC.encode(new BftExtraData(
+ vanity, Collections.emptyList(), Optional.empty(), 0, VALIDATORS, Collections.emptyList(), tagged));
+ }
+
+ private static BlockHeader honestV2(final long number, final BlockHeader parent, final List<SchemeSeal> tagged) {
+ final Bytes32 d = PqAnchorV2.anchorDigestV2(CHAIN_ID, number - 1L, parent.getHash().getBytes(), tagged);
+ return header(number, parent.getHash(), extraDataV2(d, tagged));
+ }
+
+ // --------------------------------------------------------------------------------------- R1
+
+ @Test
+ public void r1AcceptsTheHonestV2HeaderAndRefusesAStrippedCertificate() {
+ final BlockHeader parent = parentHeader(V2 + 4L);
+ final List<SchemeSeal> tagged = certificate(parent, 5, 5);
+ final BlockHeader honest = honestV2(V2 + 5L, parent, tagged);
+ assertThat(r1.validate(honest, parent)).isTrue();
+ // one SLH-DSA seal stripped under the ORIGINAL digest
+ final List<SchemeSeal> stripped = new ArrayList<>(tagged);
+ stripped.removeIf(s -> s.getSchemeWireId() == SealSchemes.SLH_DSA_128S.wireId() && s.getValidatorIndex() == 4);
+ final BftExtraData decoded = CODEC.decodeRaw(honest.getExtraData());
+ final BlockHeader strippedHeader =
+ header(V2 + 5L, parent.getHash(), extraDataV2(decoded.getVanityData(), stripped));
+ assertThat(r1.validate(strippedHeader, parent)).isFalse();
+ }
+
+ @Test
+ public void r1RefusesAV2CertificateBelowTheV2HeightAndAV1CertificateAtIt() {
+ // v2 below V2: the anchor height V2-1 (interval absent => every height from H is an anchor height)
+ final BlockHeader parentBelow = parentHeader(V2 - 2L);
+ final BlockHeader v2Early = honestV2(V2 - 1L, parentBelow, certificate(parentBelow, 5, 5));
+ assertThat(r1.validate(v2Early, parentBelow)).isFalse();
+ // v1 at V2: an honest v1 header (correct v1 digest) is still refused, the form is wrong
+ final BlockHeader parent = parentHeader(V2 + 4L);
+ final BlockHeader v1Late = PqAnchorTestSupport.honestHeader(V2 + 5L, parent.getHash(),
+ List.of(PqAnchorTestSupport.seal(0), PqAnchorTestSupport.seal(1), PqAnchorTestSupport.seal(2)));
+ assertThat(r1.validate(v1Late, parent)).isFalse();
+ // control: the same v1 header is accepted by a rule whose V2 lies in the future
+ final PqAnchorConfig v1World = new PqAnchorConfig(
+ CHAIN_ID, H, Map.of(H, 0, V2, K), OptionalInt.empty(), false, OptionalInt.empty(),
+ OptionalInt.empty(), V2 + 1_000L);
+ assertThat(new PqAnchorDigestRule(v1World).validate(v1Late, parent)).isTrue();
+ }
+
+ // --------------------------------------------------------------------------------------- R2
+
+ @Test
+ public void r2AcceptsTheHonestV2HeaderWithKSealsPerScheme() {
+ final BlockHeader parent = parentHeader(V2 + 4L);
+ assertThat(r2.validate(honestV2(V2 + 5L, parent, certificate(parent, K, K)), parent, context())).isTrue();
+ // more than K of each is fine too: K is a floor
+ assertThat(r2.validate(honestV2(V2 + 5L, parent, certificate(parent, 5, 5)), parent, context())).isTrue();
+ }
+
+ @Test
+ public void r2RefusesAnSlhDsaSealFromAnIndexWithoutAFalconSeal() {
+ final BlockHeader parent = parentHeader(V2 + 4L);
+ final List<SchemeSeal> tagged = certificate(parent, K, K + 1); // SLH-DSA from index K has no Falcon
+ assertThat(r2.validate(honestV2(V2 + 5L, parent, tagged), parent, context())).isFalse();
+ }
+
+ @Test
+ public void r2RefusesACertificateShortOfOneScheme() {
+ final BlockHeader parent = parentHeader(V2 + 4L);
+ assertThat(r2.validate(honestV2(V2 + 5L, parent, certificate(parent, 5, K - 1)), parent, context()))
+ .describedAs("K Falcon seals and only K-1 SLH-DSA: the schedule demands K of EVERY scheme")
+ .isFalse();
+ assertThat(r2.validate(honestV2(V2 + 5L, parent, certificate(parent, K - 1, K - 1)), parent, context()))
+ .describedAs("short of Falcon as well")
+ .isFalse();
+ }
+
+ @Test
+ public void r2RefusesATamperedSlhDsaSignature() {
+ final BlockHeader parent = parentHeader(V2 + 4L);
+ final List<SchemeSeal> tagged = new ArrayList<>(certificate(parent, K, K));
+ for (int i = 0; i < tagged.size(); i++) {
+ final SchemeSeal s = tagged.get(i);
+ if (s.getSchemeWireId() == SealSchemes.SLH_DSA_128S.wireId() && s.getValidatorIndex() == 1) {
+ final byte[] sig = s.getSignature().toArray();
+ sig[sig.length / 2] ^= 0x01;
+ tagged.set(i, new SchemeSeal(s.getSchemeWireId(), s.getValidatorIndex(), Bytes.wrap(sig)));
+ }
+ }
+ assertThat(r2.validate(honestV2(V2 + 5L, parent, tagged), parent, context())).isFalse();
+ }
+
+ @Test
+ public void r2RefusesASchemeTheScheduleDoesNotName() throws Exception {
+ armHybrid("0:falcon-512");
+ final BlockHeader parent = parentHeader(V2 + 4L);
+ assertThat(r2.validate(honestV2(V2 + 5L, parent, certificate(parent, K, K)), parent, context()))
+ .describedAs("SLH-DSA seals carried while the schedule names Falcon only")
+ .isFalse();
+ assertThat(r2.validate(honestV2(V2 + 5L, parent, certificate(parent, K, 0)), parent, context()))
+ .describedAs("control: a Falcon-only v2 certificate under a Falcon-only schedule")
+ .isTrue();
+ }
+
+ // ------------------------------------------------------------------------------------ codec
+
+ @Test
+ public void theCodecRoundTripsBothFormsAndRefusesANonCanonicalV2Certificate() {
+ final BlockHeader parent = parentHeader(V2 + 4L);
+ final List<SchemeSeal> tagged = certificate(parent, 2, 2);
+ final Bytes v2 = extraDataV2(Bytes32.ZERO, tagged);
+ final BftExtraData back = CODEC.decodeRaw(v2);
+ assertThat(back.getHybridSeals()).isEqualTo(tagged);
+ assertThat(back.getFalconSeals()).isEmpty();
+ // the v1 form still round-trips through the same slot
+ final List<FalconSeal> v1 = List.of(PqAnchorTestSupport.seal(0), PqAnchorTestSupport.seal(1));
+ final BftExtraData backV1 = CODEC.decodeRaw(PqAnchorTestSupport.extraData(Bytes32.ZERO, v1));
+ assertThat(backV1.getFalconSeals()).containsExactlyElementsOf(v1);
+ assertThat(backV1.getHybridSeals()).isEmpty();
+ // a v2 certificate written out of canonical order is refused at decode, not silently reordered
+ final List<SchemeSeal> unsorted = new ArrayList<>(tagged);
+ Collections.reverse(unsorted);
+ // the holder accepts any list; it is the ENCODER that refuses, so no header can carry it
+ assertThatThrownBy(() -> CODEC.encode(new BftExtraData(
+ Bytes32.ZERO, Collections.emptyList(), Optional.empty(), 0, VALIDATORS,
+ Collections.emptyList(), unsorted)))
+ .isInstanceOf(RuntimeException.class);
+ // hand-built non-canonical bytes: the same seals, encoded by hand out of order, do not decode
+ final Bytes canonical = PqAnchorV2.encode(tagged);
+ final BftExtraData holder = new BftExtraData(
+ Bytes32.ZERO, Collections.emptyList(), Optional.empty(), 0, VALIDATORS, Collections.emptyList(), tagged);
+ final Bytes good = CODEC.encode(holder);
+ assertThat(good.toHexString()).contains(canonical.toUnprefixedHexString());
+ final Bytes swapped = Bytes.fromHexString(good.toHexString().replace(
+ canonical.toUnprefixedHexString(), PqAnchorV2.encode(List.of(tagged.get(0))).toUnprefixedHexString()));
+ assertThatThrownBy(() -> CODEC.decodeRaw(swapped)).isInstanceOf(RLPException.class);
+ }
+
+ // ------------------------------------------------------------------- D-328: the round substitution
+
+ @Test
+ public void replacingTheRoundInABlockKeepsTheV2Certificate() {
+ // 2026-09-03, testnet 28001: every sealed v2 header lost its certificate at replaceRoundInBlock,
+ // because that copy went through the v1 constructor; R1 then refused block 168032 for 3 hours.
+ final BlockHeader parent = parentHeader(V2 + 4L);
+ final List<SchemeSeal> tagged = certificate(parent, K, K);
+ final BlockHeader honest = honestV2(V2 + 5L, parent, tagged);
+ final org.hyperledger.besu.ethereum.core.Block block =
+ new org.hyperledger.besu.ethereum.core.Block(honest, org.hyperledger.besu.ethereum.core.BlockBody.empty());
+ final org.hyperledger.besu.ethereum.core.Block substituted =
+ new org.hyperledger.besu.consensus.common.bft.BftBlockInterface(CODEC)
+ .replaceRoundInBlock(block, 7, org.hyperledger.besu.consensus.common.bft.BftBlockHeaderFunctions.forCommittedSeal(CODEC));
+ final BftExtraData after = CODEC.decodeRaw(substituted.getHeader().getExtraData());
+ assertThat(after.getRound()).isEqualTo(7);
+ assertThat(after.getHybridSeals()).describedAs("the v2 certificate survives the round substitution").isEqualTo(tagged);
+ assertThat(after.getFalconSeals()).isEmpty();
+ assertThat(r1.validate(substituted.getHeader(), parent)).describedAs("R1 still binds it").isTrue();
+ }
+
+ // ---------------------------------------------------------------------------------- helpers
+
+ private static ProtocolContext context() {
+ return contextWith(VALIDATORS);
+ }
+
+ private static ProtocolContext contextWith(final Collection<Address> vs) {
+ final ValidatorProvider validatorProvider =
+ mock(ValidatorProvider.class, withSettings().strictness(Strictness.LENIENT));
+ when(validatorProvider.getValidatorsForBlock(any())).thenReturn(vs);
+ when(validatorProvider.getValidatorsAfterBlock(any())).thenReturn(vs);
+ final BftContext bftContext = mock(BftContext.class, withSettings().strictness(Strictness.LENIENT));
+ when(bftContext.getValidatorProvider()).thenReturn(validatorProvider);
+ when(bftContext.as(any())).thenReturn(bftContext);
+ return new ProtocolContext.Builder().withConsensusContext(bftContext).build();
+ }
+
+ /** Index i is VALIDATORS.get(i); a seal is valid iff it is exactly what {@link #sign} produces. */
+ private static final class FakeFalconRegistry implements PqSignerRegistry {
+ static Bytes sign(final int index, final Bytes32 message) {
+ final byte[] out = new byte[655];
+ out[0] = (byte) index;
+ for (int i = 0; i < 32; i++) {
+ out[1 + i] = message.get(i);
+ }
+ for (int i = 33; i < out.length; i++) {
+ out[i] = (byte) ((i * (index + 3) + 7) & 0xFF);
+ }
+ return Bytes.wrap(out);
+ }
+
+ @Override
+ public Address addressForIndexAtHistoric(final long blockNumber, final int validatorIndex) {
+ return validatorIndex >= 0 && validatorIndex < VALIDATORS.size() ? VALIDATORS.get(validatorIndex) : null;
+ }
+
+ @Override
+ public Address addressForIndexAtOwnHead(final long blockNumber, final int validatorIndex) {
+ return addressForIndexAtHistoric(blockNumber, validatorIndex);
+ }
+
+ @Override
+ public boolean verifyAtHistoric(
+ final long blockNumber, final int validatorIndex, final Bytes message, final Bytes signature) {
+ return message.size() == 32 && sign(validatorIndex, Bytes32.wrap(message)).equals(signature);
+ }
+
+ @Override
+ public boolean verifyAtOwnHead(
+ final long blockNumber, final int validatorIndex, final Bytes message, final Bytes signature) {
+ return verifyAtHistoric(blockNumber, validatorIndex, message, signature);
+ }
+ }
+}
diff --git a/consensus/qbft/src/test/java/org/hyperledger/besu/consensus/qbft/headervalidationrules/PqArmedWithoutRegistryTest.java b/consensus/qbft/src/test/java/org/hyperledger/besu/consensus/qbft/headervalidationrules/PqArmedWithoutRegistryTest.java
new file mode 100755
index 000000000..ec110ed67
--- /dev/null
+++ b/consensus/qbft/src/test/java/org/hyperledger/besu/consensus/qbft/headervalidationrules/PqArmedWithoutRegistryTest.java
@@ -0,0 +1,185 @@
+/*
+ * Copyright contributors to Besu / AERE Network.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.qbft.headervalidationrules;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.hyperledger.besu.consensus.qbft.headervalidationrules.PqAnchorTestSupport.VALIDATORS;
+import static org.hyperledger.besu.consensus.qbft.headervalidationrules.PqAnchorTestSupport.parentHeader;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+import static org.mockito.Mockito.withSettings;
+
+import org.hyperledger.besu.consensus.common.bft.BftContext;
+import org.hyperledger.besu.consensus.common.bft.FalconSealSupport;
+import org.hyperledger.besu.consensus.common.bft.PqV2Fixture;
+import org.hyperledger.besu.consensus.common.validator.ValidatorProvider;
+import org.hyperledger.besu.datatypes.Address;
+import org.hyperledger.besu.ethereum.ProtocolContext;
+import org.hyperledger.besu.ethereum.core.BlockHeader;
+
+import java.lang.reflect.Field;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.Collection;
+
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+import org.mockito.quality.Strictness;
+
+/**
+ * D-079, THE RESIDUAL: the accident the configuration guard cannot refuse.
+ *
+ * <p>{@code FalconSealSupport.validateAnchorObservationHeightOrAbort} refuses to start a node whose
+ * blocking height is armed at or before the height at which its registry can become active. That
+ * closes the misconfiguration. It cannot close the ACCIDENT: an operator declares the observation
+ * height correctly, the anchor-deploy transaction does not land, and the blocking height arrives
+ * over an empty registry anyway.
+ *
+ * <p>{@link FalconSealValidationRule} answers that by staying LOG-ONLY, and that answer is right -
+ * blocking over an empty registry buys no safety and costs the chain. It is also exactly how the
+ * condition used to disappear: the node was configured to enforce a post-quantum quorum, enforced
+ * nothing, and said so in a warning that nothing reads and no command can exit on.
+ *
+ * <p>These three tests measure the mark it now leaves, in both directions.
+ */
+// The D-079 label is our internal finding id. It names a fact about this
+// code, not anything outside it.
+public class PqArmedWithoutRegistryTest {
+
+ private static final int N = 9;
+
+ private static final long OBSERVE = 5_000L;
+
+ private static final long ATTACH = 6_000L;
+
+ private static final long FORK = 7_000L;
+
+ private static final String ANCHOR_ADDRESS = "0x0000000000000000000000000000000000000fa1";
+
+ /** AERE D-146: the chain this fixture's registry is BOUND to. Inside every proof, so stated. */
+ private static final long CHAIN_ID = 2_800L;
+
+ @TempDir private Path tmp;
+
+ @BeforeEach
+ public void setUp() throws Exception {
+ // AERE D-146 (2026-08-06): v2, proof-bound, bound at FORK. This manifest used to spell its
+ // addresses 0xC00+i; no secp256k1 key produces those, so once AERE-PQC-REG-ARM-02 was wired
+ // this armed fixture could not start at all. PqV2Fixture lives in consensus:common's test
+ // source set and reaches here through the testArtifacts dependency this module already had.
+ final StringBuilder m = new StringBuilder("{");
+ m.append(PqV2Fixture.manifestHeader(N, CHAIN_ID, FORK));
+ for (int i = 0; i < N; i++) {
+ m.append(',').append(PqV2Fixture.manifestEntry(i, N, CHAIN_ID, FORK));
+ }
+ m.append("}");
+ final Path manifest = tmp.resolve("falcon-late-manifest.json");
+ Files.writeString(manifest, m.toString());
+
+ System.setProperty("aere.falcon.manifest", manifest.toAbsolutePath().toString());
+ System.setProperty("aere.falcon.anchor.address", ANCHOR_ADDRESS);
+ System.setProperty("aere.falcon.anchor.block", Long.toString(OBSERVE));
+ System.setProperty("aere.falcon.attachBlock", Long.toString(ATTACH));
+ System.setProperty("aere.falcon.forkBlock", Long.toString(FORK));
+ System.setProperty("aere.falcon.validatorCount", Integer.toString(N));
+ forgetFalconSingleton();
+ }
+
+ @AfterEach
+ public void tearDown() throws Exception {
+ for (final String p :
+ new String[] {
+ "aere.falcon.manifest",
+ "aere.falcon.anchor.address",
+ "aere.falcon.anchor.block",
+ "aere.falcon.attachBlock",
+ "aere.falcon.forkBlock",
+ "aere.falcon.validatorCount"
+ }) {
+ System.clearProperty(p);
+ }
+ forgetFalconSingleton();
+ }
+
+ @Test
+ public void belowTheBlockingHeightNothingIsRecorded() {
+ // The negative control. A counter that were set unconditionally would pass the test below and
+ // mean nothing at all.
+ final FalconSealValidationRule rule = new FalconSealValidationRule(Long.MAX_VALUE);
+ final BlockHeader parent = parentHeader(FORK - 2L);
+ final BlockHeader block = parentHeader(FORK - 1L);
+
+ assertThat(rule.validate(block, parent, contextWith(VALIDATORS))).isTrue();
+ assertThat(FalconSealSupport.instance().blockingArmedWithoutRegistrySince())
+ .describedAs("below the blocking height there is nothing inert about being log-only")
+ .isEqualTo(-1L);
+ }
+
+ @Test
+ public void atTheBlockingHeightWithNoActiveRegistryTheHeightIsRecorded() {
+ final FalconSealValidationRule rule = new FalconSealValidationRule(Long.MAX_VALUE);
+ final BlockHeader parent = parentHeader(FORK - 1L);
+ final BlockHeader block = parentHeader(FORK);
+
+ assertThat(FalconSealSupport.instance().blockingArmedWithoutRegistrySince()).isEqualTo(-1L);
+ assertThat(rule.validate(block, parent, contextWith(VALIDATORS)))
+ .describedAs(
+ "the rule must still ACCEPT: blocking over an empty registry is a halt, not a safeguard")
+ .isTrue();
+ assertThat(FalconSealSupport.instance().blockingArmedWithoutRegistrySince())
+ .describedAs(
+ "the node is configured to enforce a Falcon quorum at %d and is enforcing nothing. That "
+ + "must be a value something can read, not a line in a file.",
+ FORK)
+ .isEqualTo(FORK);
+ assertThat(FalconSealSupport.instance().anchorObserveBlock())
+ .describedAs("and the declared height it was measured against must be readable too")
+ .isEqualTo(OBSERVE);
+ }
+
+ @Test
+ public void theRecordedHeightIsTheFirstOneAndDoesNotMoveWithTheChain() {
+ final FalconSealValidationRule rule = new FalconSealValidationRule(Long.MAX_VALUE);
+ rule.validate(parentHeader(FORK), parentHeader(FORK - 1L), contextWith(VALIDATORS));
+ rule.validate(parentHeader(FORK + 40L), parentHeader(FORK + 39L), contextWith(VALIDATORS));
+
+ assertThat(FalconSealSupport.instance().blockingArmedWithoutRegistrySince())
+ .describedAs(
+ "the value answers 'since when', so a later block must not overwrite it; if it tracked "
+ + "the head it would report a fresh problem forever and never a duration")
+ .isEqualTo(FORK);
+ }
+
+ private static ProtocolContext contextWith(final Collection<Address> validators) {
+ final ValidatorProvider validatorProvider =
+ mock(ValidatorProvider.class, withSettings().strictness(Strictness.LENIENT));
+ when(validatorProvider.getValidatorsForBlock(any())).thenReturn(validators);
+ when(validatorProvider.getValidatorsAfterBlock(any())).thenReturn(validators);
+ final BftContext bftContext =
+ mock(BftContext.class, withSettings().strictness(Strictness.LENIENT));
+ when(bftContext.getValidatorProvider()).thenReturn(validatorProvider);
+ when(bftContext.as(any())).thenReturn(bftContext);
+ return new ProtocolContext.Builder().withConsensusContext(bftContext).build();
+ }
+
+ private static void forgetFalconSingleton() throws Exception {
+ final Field f = FalconSealSupport.class.getDeclaredField("instance");
+ f.setAccessible(true);
+ f.set(null, null);
+ }
+}
diff --git a/consensus/qbft/src/test/java/org/hyperledger/besu/consensus/qbft/headervalidationrules/PqEmergencyShoutRuleTest.java b/consensus/qbft/src/test/java/org/hyperledger/besu/consensus/qbft/headervalidationrules/PqEmergencyShoutRuleTest.java
new file mode 100755
index 000000000..17d4dbc61
--- /dev/null
+++ b/consensus/qbft/src/test/java/org/hyperledger/besu/consensus/qbft/headervalidationrules/PqEmergencyShoutRuleTest.java
@@ -0,0 +1,78 @@
+/*
+ * Copyright contributors to Besu / AERE Network.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.qbft.headervalidationrules;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.hyperledger.besu.consensus.qbft.headervalidationrules.PqAnchorTestSupport.CHAIN_ID;
+import static org.hyperledger.besu.consensus.qbft.headervalidationrules.PqAnchorTestSupport.H;
+import static org.hyperledger.besu.consensus.qbft.headervalidationrules.PqAnchorTestSupport.parentHeader;
+
+import org.hyperledger.besu.consensus.common.bft.PqAnchorConfig;
+import org.hyperledger.besu.ethereum.core.BlockHeader;
+
+import java.util.Map;
+import java.util.OptionalInt;
+
+import org.junit.jupiter.api.Test;
+
+/**
+ * AERE OPTIUNI-URGENTA: the rule whose entire job is to be impossible to ignore.
+ *
+ * <p>The one property that must hold on every path is that it CANNOT REJECT. It is placed first in
+ * the QBFT header ruleset precisely because a rule that always returns true cannot change the
+ * verdict of a conjunction, and that claim has to be asserted rather than assumed, including for a
+ * header it has never seen before and for a null parent.
+ */
+class PqEmergencyShoutRuleTest {
+
+ private PqEmergencyShoutRule rule(final boolean disabled, final OptionalInt ceiling) {
+ return new PqEmergencyShoutRule(
+ new PqAnchorConfig(CHAIN_ID, H, Map.of(H, 0, H + 100L, 5), ceiling, disabled));
+ }
+
+ @Test
+ void acceptsEveryHeaderWhenNothingIsOverridden() {
+ final PqEmergencyShoutRule r = rule(false, OptionalInt.empty());
+ for (final long n : new long[] {0L, 1L, H - 1L, H, H + 100L, H + 1_000_000L}) {
+ final BlockHeader header = parentHeader(n);
+ assertThat(r.validate(header, parentHeader(Math.max(0L, n - 1L)))).isTrue();
+ }
+ }
+
+ @Test
+ void acceptsEveryHeaderWhenTheAnchorIsDisarmed() {
+ final PqEmergencyShoutRule r = rule(true, OptionalInt.empty());
+ assertThat(r.validate(parentHeader(H + 5L), parentHeader(H + 4L))).isTrue();
+ // Twice at the same height: the second call is the bounded one, and it must still accept.
+ assertThat(r.validate(parentHeader(H + 5L), parentHeader(H + 4L))).isTrue();
+ }
+
+ @Test
+ void acceptsEveryHeaderWhenTheThresholdIsCapped() {
+ final PqEmergencyShoutRule r = rule(false, OptionalInt.of(1));
+ assertThat(r.validate(parentHeader(H + 150L), parentHeader(H + 149L))).isTrue();
+ }
+
+ @Test
+ void acceptsEvenWithoutAParent() {
+ final PqEmergencyShoutRule r = rule(true, OptionalInt.of(0));
+ assertThat(r.validate(parentHeader(H + 150L), null)).isTrue();
+ }
+
+ @Test
+ void isPartOfLightValidationSoTheAnnouncementIsHeardOnEveryPath() {
+ assertThat(rule(true, OptionalInt.empty()).includeInLightValidation()).isTrue();
+ }
+}
diff --git a/consensus/qbft/src/test/java/org/hyperledger/besu/consensus/qbft/headervalidationrules/PqForkGateFeedTest.java b/consensus/qbft/src/test/java/org/hyperledger/besu/consensus/qbft/headervalidationrules/PqForkGateFeedTest.java
new file mode 100755
index 000000000..3b9813371
--- /dev/null
+++ b/consensus/qbft/src/test/java/org/hyperledger/besu/consensus/qbft/headervalidationrules/PqForkGateFeedTest.java
@@ -0,0 +1,191 @@
+/*
+ * Copyright contributors to Besu / AERE Network.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.consensus.qbft.headervalidationrules;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.hyperledger.besu.consensus.qbft.headervalidationrules.PqAnchorTestSupport.CHAIN_ID;
+import static org.hyperledger.besu.consensus.qbft.headervalidationrules.PqAnchorTestSupport.H;
+import static org.hyperledger.besu.consensus.qbft.headervalidationrules.PqAnchorTestSupport.VALIDATORS;
+import static org.hyperledger.besu.consensus.qbft.headervalidationrules.PqAnchorTestSupport.parentHeader;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+import static org.mockito.Mockito.withSettings;
+
+import org.hyperledger.besu.consensus.common.bft.BftContext;
+import org.hyperledger.besu.consensus.common.bft.FalconSealSupport;
+import org.hyperledger.besu.consensus.common.bft.PqAnchorConfig;
+import org.hyperledger.besu.consensus.common.validator.ValidatorProvider;
+import org.hyperledger.besu.datatypes.Address;
+import org.hyperledger.besu.ethereum.ProtocolContext;
+import org.hyperledger.besu.ethereum.core.BlockHeader;
+
+import java.lang.reflect.Field;
+import java.util.Collection;
+import java.util.List;
+import java.util.Map;
+import java.util.OptionalInt;
+
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.mockito.quality.Strictness;
+
+/**
+ * D-078, THE OTHER HALF: who feeds the seal-attachment gate above the anchor height.
+ *
+ * <p>The gate's registry-coverage report reads a validator set recorded by {@code
+ * FalconSealSupport.observeValidators}. Until 2026-08-02 the ONLY caller of that method was {@link
+ * FalconSealValidationRule}, and {@link PqAnchorConfig#legacyFalconRuleRetirementBlock()} stands
+ * that rule down at exactly the anchor height H. So from H upward nothing fed it: the recorded set
+ * was either frozen at a height below H, or - on any node whose process started above H - never
+ * recorded at all. The old gate answered "never recorded" by switching seal attachment off, which
+ * is one restart away from a chain that cannot propose.
+ *
+ * <p>This class measures the WIRING, in both directions, and it is the only thing that separates the
+ * repair from a claim about it:
+ *
+ * <ul>
+ * <li>the legacy rule really does stand down at H, so it really cannot be the feed above H;
+ * <li>{@link PqAnchorSealsRule}, which runs at every height from H, really does feed it.
+ * </ul>
+ */
+// The D-078 label is our internal finding id. It names a fact about this
+// code, not anything outside it.
+public class PqForkGateFeedTest {
+
+ private static final PqAnchorConfig ARMED =
+ new PqAnchorConfig(CHAIN_ID, H, Map.of(H, 0), OptionalInt.empty(), false);
+
+ @BeforeEach
+ public void resetSingleton() throws Exception {
+ forgetFalconSingleton();
+ }
+
+ @AfterEach
+ public void resetSingletonAfter() throws Exception {
+ forgetFalconSingleton();
+ }
+
+ @Test
+ public void theLegacyRuleStandsDownAtTheAnchorHeightSoItCannotBeTheFeed() {
+ assertThat(ARMED.legacyFalconRuleRetirementBlock())
+ .describedAs("the legacy Falcon rule retires at exactly the anchor height")
+ .isEqualTo(H);
+
+ final FalconSealValidationRule legacy =
+ new FalconSealValidationRule(ARMED.legacyFalconRuleRetirementBlock());
+ final BlockHeader parent = parentHeader(H - 1L);
+ final BlockHeader atH = parentHeader(H);
+
+ assertThat(legacy.validate(atH, parent, contextWith(VALIDATORS)))
+ .describedAs("retired, so it accepts without doing anything")
+ .isTrue();
+ assertThat(FalconSealSupport.instance().observedValidatorsHeight())
+ .describedAs(
+ "at and above the anchor height the legacy rule records NOTHING. That is correct for the "
+ + "rule and fatal for anything that depended on it as its only source.")
+ .isEqualTo(-1L);
+ }
+
+ @Test
+ public void theAnchorSealsRuleFeedsTheGateAtEveryHeightFromH() {
+ final PqAnchorSealsRule rule = new PqAnchorSealsRule(ARMED, new NoRegistry());
+ final BlockHeader parent = parentHeader(H + 40L);
+ final BlockHeader block = PqAnchorTestSupport.honestHeader(H + 41L, parent.getHash(), List.of());
+
+ assertThat(FalconSealSupport.instance().observedValidatorsHeight()).isEqualTo(-1L);
+ assertThat(rule.validate(block, parent, contextWith(VALIDATORS)))
+ .describedAs("K is 0 at this height, so an empty certificate is legitimate")
+ .isTrue();
+ assertThat(FalconSealSupport.instance().observedValidatorsHeight())
+ .describedAs(
+ "the rule that takes over at H must also take over feeding the coverage report, or the "
+ + "report is about a height the chain left behind")
+ .isEqualTo(parent.getNumber());
+ }
+
+ @Test
+ public void belowTheAnchorHeightTheSealsRuleRecordsNothing() {
+ // The negative control for the test above: a rule that recorded unconditionally would pass it
+ // while breaking the height gate that keeps the whole scheme inert below H.
+ final PqAnchorSealsRule rule = new PqAnchorSealsRule(ARMED, new NoRegistry());
+ final BlockHeader parent = parentHeader(H - 3L);
+ final BlockHeader block = PqAnchorTestSupport.honestHeader(H - 2L, parent.getHash(), List.of());
+
+ assertThat(rule.validate(block, parent, contextWith(VALIDATORS))).isTrue();
+ assertThat(FalconSealSupport.instance().observedValidatorsHeight())
+ .describedAs("below H this rule does nothing at all, recording included")
+ .isEqualTo(-1L);
+ }
+
+ private static ProtocolContext contextWith(final Collection<Address> validators) {
+ final ValidatorProvider validatorProvider =
+ mock(ValidatorProvider.class, withSettings().strictness(Strictness.LENIENT));
+ when(validatorProvider.getValidatorsForBlock(any())).thenReturn(validators);
+ when(validatorProvider.getValidatorsAfterBlock(any())).thenReturn(validators);
+ final BftContext bftContext =
+ mock(BftContext.class, withSettings().strictness(Strictness.LENIENT));
+ when(bftContext.getValidatorProvider()).thenReturn(validatorProvider);
+ when(bftContext.as(any())).thenReturn(bftContext);
+ return new ProtocolContext.Builder().withConsensusContext(bftContext).build();
+ }
+
+ private static void forgetFalconSingleton() throws Exception {
+ final Field f = FalconSealSupport.class.getDeclaredField("instance");
+ f.setAccessible(true);
+ f.set(null, null);
+ }
+
+ /** A registry that binds nothing: this file measures the feed, never the verification. */
+ private static final class NoRegistry
+ implements org.hyperledger.besu.consensus.common.bft.PqSignerRegistry {
+
+ // D2 (2026-08-06): the height-less pair was deleted from PqSignerRegistry, so this double now
+ // has to answer "at which height" like everything else. It still binds nothing.
+ @Override
+ public Address addressForIndexAtOwnHead(final long blockNumber, final int validatorIndex) {
+ return addressForIndexAtHistoric(blockNumber, validatorIndex);
+ }
+
+ @Override
+ public boolean verifyAtOwnHead(
+ final long blockNumber,
+ final int validatorIndex,
+ final org.apache.tuweni.bytes.Bytes message,
+ final org.apache.tuweni.bytes.Bytes signature) {
+ return verifyAtHistoric(blockNumber, validatorIndex, message, signature);
+ }
+
+ @Override
+ public Address addressForIndexAtHistoric(final long blockNumber, final int validatorIndex) {
+ return null;
+ }
+
+ @Override
+ public boolean verifyAtHistoric(
+ final long blockNumber,
+ final int validatorIndex,
+ final org.apache.tuweni.bytes.Bytes message,
+ final org.apache.tuweni.bytes.Bytes signature) {
+ return false;
+ }
+
+ @Override
+ public String toString() {
+ return "NoRegistry";
+ }
+ }
+}
diff --git a/ethereum/eth/src/main/java/org/hyperledger/besu/ethereum/eth/sync/DownloadHeadersStep.java b/ethereum/eth/src/main/java/org/hyperledger/besu/ethereum/eth/sync/DownloadHeadersStep.java
index c8eb53639..76c435677 100644
--- a/ethereum/eth/src/main/java/org/hyperledger/besu/ethereum/eth/sync/DownloadHeadersStep.java
+++ b/ethereum/eth/src/main/java/org/hyperledger/besu/ethereum/eth/sync/DownloadHeadersStep.java
@@ -11,6 +11,12 @@
* specific language governing permissions and limitations under the License.
*
* SPDX-License-Identifier: Apache-2.0
+ *
+ * Modifications Copyright contributors to the Aere Network.
+ *
+ * This file was modified by contributors to the Aere Network, as required by section 4(b) of the
+ * Apache License 2.0. The copyright header above is the upstream one and is left exactly as it was
+ * found, as section 4(c) requires. The change itself is in patches/0003-aere-pq-anchor.patch.
*/
package org.hyperledger.besu.ethereum.eth.sync;
@@ -26,7 +32,10 @@ import org.hyperledger.besu.ethereum.eth.manager.peertask.task.GetHeadersFromPee
import org.hyperledger.besu.ethereum.eth.sync.range.RangeHeaders;
import org.hyperledger.besu.ethereum.eth.sync.range.SyncTargetRange;
import org.hyperledger.besu.ethereum.eth.sync.tasks.DownloadHeaderSequenceTask;
+import org.hyperledger.besu.ethereum.eth.sync.tasks.exceptions.InvalidBlockException;
+import org.hyperledger.besu.ethereum.mainnet.HeaderValidationMode;
import org.hyperledger.besu.ethereum.mainnet.ProtocolSchedule;
+import org.hyperledger.besu.ethereum.mainnet.ProtocolSpec;
import org.hyperledger.besu.plugin.services.MetricsSystem;
import org.hyperledger.besu.util.FutureUtils;
@@ -112,11 +121,103 @@ public class DownloadHeadersStep
return CompletableFuture.failedFuture(
new RuntimeException("Unable to download headers for range " + range));
}
- return CompletableFuture.completedFuture(taskResult.result().get());
+ final List<BlockHeader> downloaded = taskResult.result().get();
+ // AERE SINCRONIZARE (2026-08-02): validate the OPEN-ENDED range too.
+ try {
+ validateOpenEndedRange(range, downloaded);
+ } catch (final RuntimeException e) {
+ return CompletableFuture.failedFuture(e);
+ }
+ return CompletableFuture.completedFuture(downloaded);
});
}
}
+ /**
+ * AERE SINCRONIZARE (2026-08-02). Apply the SAME validation policy to the open-ended range that
+ * the closed ranges already get.
+ *
+ * <p>The defect, read in this file and then measured on a running network. {@link
+ * #downloadHeaders} has two branches and the choice between them is not "syncing or not", it is
+ * {@link SyncTargetRange#hasEnd()}. A closed range goes to {@code
+ * DownloadHeaderSequenceTask.endingAtHeader}, which validates every header it accepts under
+ * {@code validationPolicy}. The open-ended range - the one at the tip, when the range source
+ * could not obtain a further range boundary from the peer - went to a bare {@code
+ * GetHeadersFromPeerTask} and was handed onward with nothing checked but the hash chaining that
+ * {@code RangeHeadersValidationStep} does at the join. With the default header request size of
+ * 200 that is the last 199 blocks of every catch-up, which is the whole of a short one.
+ *
+ * <p>The consequence for the certificate anchor was measured: an honest node with its data
+ * directory deleted imported headers whose certificate had been tampered with, in silence,
+ * because the only rule that binds the certificate to the block hash is detached and detached
+ * rules run in exactly the branch this range does not take. The attached copy of that rule now
+ * catches such a header at import in any case; this method makes it fail one pipeline stage
+ * earlier, before bodies are fetched for a range that is going to be thrown away, and restores
+ * the property that the tail of a sync is checked exactly like the rest of it.
+ *
+ * <p>Fail closed on every path: a range whose headers do not form a chain from {@code
+ * range.getStart()} is rejected here rather than trimmed or accepted.
+ *
+ * @param range the open-ended range these headers were requested for
+ * @param headers the headers as the peer returned them, ascending from {@code range.getStart()}
+ */
+ private void validateOpenEndedRange(
+ final SyncTargetRange range, final List<BlockHeader> headers) {
+ if (headers.isEmpty()) {
+ return;
+ }
+ final BlockHeader start = range.getStart();
+ BlockHeader parent;
+ int index;
+ if (headers.getFirst().equals(start)) {
+ // The usual shape: the peer echoes the header we asked to start from.
+ parent = start;
+ index = 1;
+ } else if (headers.getFirst().getParentHash().equals(start.getHash())) {
+ parent = start;
+ index = 0;
+ } else {
+ throw InvalidBlockException.fromInvalidBlock(
+ String.format(
+ "AERE-SYNC-TAIL-01: open-ended range starting at #%d (%s) came back beginning at #%d "
+ + "(%s), which neither is that header nor descends from it",
+ start.getNumber(),
+ start.getHash(),
+ headers.getFirst().getNumber(),
+ headers.getFirst().getHash()),
+ headers.getFirst());
+ }
+
+ final HeaderValidationMode mode = validationPolicy.getValidationModeForNextBlock();
+ for (int i = index; i < headers.size(); i++) {
+ final BlockHeader header = headers.get(i);
+ if (!header.getParentHash().equals(parent.getHash())
+ || header.getNumber() != parent.getNumber() + 1L) {
+ throw InvalidBlockException.fromInvalidBlock(
+ String.format(
+ "AERE-SYNC-TAIL-01: open-ended range does not form a chain at #%d (%s); previous "
+ + "header was #%d (%s)",
+ header.getNumber(), header.getHash(), parent.getNumber(), parent.getHash()),
+ header);
+ }
+ final ProtocolSpec protocolSpec = protocolSchedule.getByBlockHeader(header);
+ if (!protocolSpec
+ .getBlockHeaderValidator()
+ .validateHeader(header, parent, protocolContext, mode)) {
+ LOG.warn(
+ "AERE-SYNC-TAIL-01: header #{} ({}) of the OPEN-ENDED range failed {} validation. This "
+ + "is the branch that used to accept the last {} headers of every recovery without "
+ + "running a single header rule.",
+ header.getNumber(),
+ header.getHash(),
+ mode,
+ headerRequestSize - 1);
+ throw InvalidBlockException.fromInvalidBlock(header);
+ }
+ parent = header;
+ }
+ }
+
private RangeHeaders processHeaders(
final SyncTargetRange checkpointRange, final List<BlockHeader> headers) {
if (checkpointRange.hasEnd()) {
Reference in New Issue View Git Blame Copy Permalink